handbook/disks: fix internal xrefs

[ziaee]

Summary

Internal crossreferences in the FreeBSD handbook using crossref: are currently broken on PDF output. The official docs [0] say to xref with <<here-is-the-xref,it will optionally look like this>>. Most xrefs are already written in that notation, they are clean and work great. Update the rest of the remaining xrefs in this chapter to this notation.

[0] : https://docs.asciidoctor.org/asciidoc/latest/macros/xref/

Related bug : https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=266107

Similar fix for desktop : https://reviews.freebsd.org/D46265
Similar fix for cutting-edge : https://reviews.freebsd.org/D46264
Similar fix for boot : https://reviews.freebsd.org/D46263
Similar fix for bsdinstall : https://reviews.freebsd.org/D46262
Similar fix for audit : https://reviews.freebsd.org/D46261
Similar fix for basics : https://reviews.freebsd.org/D46260
Similar fix for advanced networking : https://reviews.freebsd.org/D46258

Test Plan

Built in en/{html,pdf}, and tested links.

[fernape]

documentation/content/en/books/handbook/disks/_index.adoc

72

This breaks the HTML links.
This link points to http://localhost:1313/en/books/handbook/disks/#kernelconfig and that anchor does not exist. The chapter is wrong, isn't it?

[ziaee]

documentation/content/en/books/handbook/disks/_index.adoc

72

That's very interesting. Testing again it works in single html, but not split html.

I don't see [[kernelconfig]] in disks/_index.adoc, but I do see it in kernelconfig/_index.adoc?

Link related is broken here (pg. 423): https://download.freebsd.org/doc/handbook/handbook_en.pdf

But currently works here: https://docs.freebsd.org/en/books/handbook/disks/

I'm not sure how to proceed forward. Thank you for checking this out.

[fernape]

documentation/content/en/books/handbook/disks/_index.adoc

72

Yes, we have a nice cross links mix here.

So we can create cross referenced links with:

• <<foo, description>> which is the asciidoc native macro. This works in HTML single page and PDF but fails in HTML splitted pages.
• crossref which is a custom macro we use to try to do different things depending on the context. Works in any HTML setup, but fails in PDF
• extref is another custom macro that I don't really know what does differently than the previous one.

[ziaee]

Fernape has fixed the internal macro in D46480, so I'm going to close this.