[documentation]: Fix links

[fernape]

Summary

Use the crossref: macro all documentation internal links except for inter-book links.
This will produce the correct link in Single HTML, Splitted HTML and PDF.

Rework the macro to include the PDF special render.
Apply the changes where apply (basically convert the xref shortcut to crossref)

While here briefly document macros

PR: 266107
Should obsolete:

• https://reviews.freebsd.org/D46265
• https://reviews.freebsd.org/D46264
• https://reviews.freebsd.org/D46263
• https://reviews.freebsd.org/D46262
• https://reviews.freebsd.org/D46261
• https://reviews.freebsd.org/D46260
• https://reviews.freebsd.org/D46258

Dear reviewer: as you can imagine I did not check all links in the documentation, but check a fairly amount of them :-)
I'm not worried about possible mistakes now that we have a working solution.
If I accidentally broke a link, I can fix it later.

Test Plan

Check the behavior before the patch:

cd documentation && make run
Access to http://localhost:1313/ and check that the same links work in both
Split HTML and Single HTML.

Then do

cd documentation && make pdf
Go to Chapter 8 Desktops Environments.
Check the broken links in 8.1 Synopsis.

After applying the patch, do the same tests to check the links work in the three
different output formats.

Once this is in the tree I will commit another change clarifying the usage of
the link macros.

[fernape]

• Fix a couple of links

[concussious.bugzilla_runbox.com]

I am so excited to test this after I get off work!

[concussious.bugzilla_runbox.com]

Tested chapter 8.1 wayland link on single pdf, doesn't work on mupdf or cellphone, opens up a web browser attempting to go to http://./#wayland.

[fernape]

In D46480#1059960, @concussious.bugzilla_runbox.com wrote:

Tested chapter 8.1 wayland link on single pdf, doesn't work on mupdf or cellphone, opens up a web browser attempting to go to http://./#wayland.

Do you mean "single HTML"?
I tested PDF. Go to page 169 ("Wayland on FreeBSD") and clicked on:

• Know how to install <<additional third-party software>>.
• How to identify and configure <<drivers for your graphics hardware>>.

Both links work.

I also tested the HTML version in split and single HTML and also both links work.
If you are testing with "make run" all links should be pointing to localhost, not to https//... whatever.

[concussious.bugzilla_runbox.com]

Tried with "make -j20" and "make run". "make run" worked as expected when connected to localhost instance as you described, but the PDF (handbook_en.pdf) did not work in mupdf on current or when I sent it to my phone.

[fernape]

In D46480#1060009, @concussious.bugzilla_runbox.com wrote:

Tried with "make -j20" and "make run". "make run" worked as expected when connected to localhost instance as you described, but the PDF (handbook_en.pdf) did not work in mupdf on current or when I sent it to my phone.

Are you using the handbook_en.pdf?
I will try and install mupdf. Can you try with xpdf?

[fernape]

In D46480#1060009, @concussious.bugzilla_runbox.com wrote:

Tried with "make -j20" and "make run". "make run" worked as expected when connected to localhost instance as you described, but the PDF (handbook_en.pdf) did not work in mupdf on current or when I sent it to my phone.

In D46480#1060010, @fernape wrote:

In D46480#1060009, @concussious.bugzilla_runbox.com wrote:

Tried with "make -j20" and "make run". "make run" worked as expected when connected to localhost instance as you described, but the PDF (handbook_en.pdf) did not work in mupdf on current or when I sent it to my phone.

Are you using the handbook_en.pdf?
I will try and install mupdf. Can you try with xpdf?

I installed mupdf, regenerate the PDF with make pdf and opened handbook_en.pdf with mupdf. Links work for me.

[concussious.bugzilla_runbox.com]

Yes, confirmed this works!!! Awesome! I will close all my attempts.

Eventually, I discovered that I had to git clean -dfx (is there a better way?) in order to delete the ignored files, or they weren't getting overwritten. Even though I was making, it wasn't happening. Worked in mupdf, xpdf, on my cellphone pdf reader, and htmls with firefox.

[concussious.bugzilla_runbox.com]

Yes, confirmed this works!!! Awesome! I will close all my attempts.

Eventually, I discovered that I had to git clean -dfx (is there a better way?) in order to delete the ignored files, or they weren't getting overwritten. Additionally, hugo doesn't seem to paralelize anything when passed the -j flag of make.

Tested on CURRENT with mupdf, xpdf, my cellphone pdf reader, and htmls with firefox.

[fernape]

In D46480#1060139, @concussious.bugzilla_runbox.com wrote:

Yes, confirmed this works!!! Awesome! I will close all my attempts.

Eventually, I discovered that I had to git clean -dfx (is there a better way?) in order to delete the ignored files, or they weren't getting overwritten. Additionally, hugo doesn't seem to paralelize anything when passed the -j flag of make.

make clean should clean up all the generated artifacts.

Tested on CURRENT with mupdf, xpdf, my cellphone pdf reader, and htmls with firefox.

Terrific, thanks a lot!

[concussious.bugzilla_runbox.com]

Teriffic, thanks a lot!

Thank you! This is so exciting and informative!

[bcr]

Looks good to me. I think we should try to use some automated link checker that reports when there is a broken link in our docs. But that's beside this review, so go ahead. Thank you for the work!

[dbaio]

I did some tests, and the links look good. Thanks for working on this improvement @fernape

[fernape]

Landed in https://cgit.freebsd.org/doc/commit/?id=557464e66e059e785c3d83036ed2168df224198f

Thank you all for the reviews.