create-mdbook-structure: Add script.

[flexibeast]

This script uses the handbook.toc produced by the first run of pdflatex on handbook.tex to manually create a ToC in the style of docs.voidlinux.org, which will then be used in the second run of pdflatex. It includes some special-casing to deal with the infamous "NVIDIA Optimus" entry. :-)

i was starting to work on adding section numbers, then realised that the section numbering won't match that produced by LaTeX for each section in the document body. Trying to deal with that might be a non-trivial problem, so i'd rather set it aside for now.

The styling is currently very basic, as i've mainly been focused on getting the fundamentals right - feel free to suggest changes in this regard.

[ericonr]

There seem to be some error messages about using unitialized values, is that fine?

Links such as "Partioning notes" are now broken.

While "Firmware" is now indented correctly, "Services and daemons" is wrong :/

I'm not sure I love this change, I liked having the numbers :p

[flexibeast]

There seem to be some error messages about using unitialized values, is that fine?

There shouldn't be; i resolved all such errors that were coming up.

Links such as "Partioning notes" are now broken.

Again, working fine here ....

While "Firmware" is now indented correctly, "Services and daemons" is wrong :/

.... as is this.

Did you use build.sh to build? Are you looking at the PDF generated in book/latex/?

I'm not sure I love this change, I liked having the numbers :p

Fair enough. :-) If people are happy with the Handbook, and the ToC for it, having numbering that doesn't match the numbering on docs.voidlinux.org, i'm probably okay with that.

[ericonr]

I tried removing book/latex and running ./build.sh. Can try again...

[ericonr]

Output:

Building mdBook
2020-08-02 06:17:30 [INFO] (mdbook::book): Book building has started
2020-08-02 06:17:30 [INFO] (mdbook::book): Running the html backend
2020-08-02 06:17:30 [INFO] (mdbook::book): Running the latex backend
2020-08-02 06:17:30 [INFO] (mdbook::renderer): Invoking the "latex" renderer
2020-08-02 06:17:30 [INFO] (mdbook::book): Running the linkcheck backend
2020-08-02 06:17:30 [INFO] (mdbook::renderer): Invoking the "linkcheck" renderer
Building man pages
/home/ericonr/void/void-docs
Building void-docs man page
Use of uninitialized value $hypertarget in concatenation (.) or string at /home/ericonr/void/void-docs/add-toc line 71, <$fh> line 24.
Use of uninitialized value $hypertarget in concatenation (.) or string at /home/ericonr/void/void-docs/add-toc line 72, <$fh> line 24.
Use of uninitialized value $hypertarget in concatenation (.) or string at /home/ericonr/void/void-docs/add-toc line 71, <$fh> line 46.
Use of uninitialized value $hypertarget in concatenation (.) or string at /home/ericonr/void/void-docs/add-toc line 72, <$fh> line 46.
Use of uninitialized value $hypertarget in concatenation (.) or string at /home/ericonr/void/void-docs/add-toc line 71, <$fh> line 82.
Use of uninitialized value $hypertarget in concatenation (.) or string at /home/ericonr/void/void-docs/add-toc line 72, <$fh> line 82.
Use of uninitialized value $hypertarget in concatenation (.) or string at /home/ericonr/void/void-docs/add-toc line 71, <$fh> line 99.
Use of uninitialized value $hypertarget in concatenation (.) or string at /home/ericonr/void/void-docs/add-toc line 72, <$fh> line 99.
Use of uninitialized value $hypertarget in concatenation (.) or string at /home/ericonr/void/void-docs/add-toc line 71, <$fh> line 120.
Use of uninitialized value $hypertarget in concatenation (.) or string at /home/ericonr/void/void-docs/add-toc line 72, <$fh> line 120.
Use of uninitialized value $hypertarget in concatenation (.) or string at /home/ericonr/void/void-docs/add-toc line 71, <$fh> line 171.
Use of uninitialized value $hypertarget in concatenation (.) or string at /home/ericonr/void/void-docs/add-toc line 72, <$fh> line 171.
Use of uninitialized value $hypertarget in concatenation (.) or string at /home/ericonr/void/void-docs/add-toc line 71, <$fh> line 316.
Use of uninitialized value $hypertarget in concatenation (.) or string at /home/ericonr/void/void-docs/add-toc line 72, <$fh> line 316.
Use of uninitialized value $hypertarget in concatenation (.) or string at /home/ericonr/void/void-docs/add-toc line 71, <$fh> line 327.
Use of uninitialized value $hypertarget in concatenation (.) or string at /home/ericonr/void/void-docs/add-toc line 72, <$fh> line 327.
Use of uninitialized value $hypertarget in concatenation (.) or string at /home/ericonr/void/void-docs/add-toc line 71, <$fh> line 328.
Use of uninitialized value $hypertarget in concatenation (.) or string at /home/ericonr/void/void-docs/add-toc line 72, <$fh> line 328.
Use of uninitialized value $hypertarget in concatenation (.) or string at /home/ericonr/void/void-docs/add-toc line 71, <$fh> line 344.
Use of uninitialized value $hypertarget in concatenation (.) or string at /home/ericonr/void/void-docs/add-toc line 72, <$fh> line 344.

[flexibeast]

i just did a fresh clone of my void-docs fork, created a new branch from origin/generate-latex-toc, switched to it, and ran build.sh. There were no errors, and the issues you mentioned in the resulting PDF weren't present.

[ericonr]

I would love to find out what happened, but yeah, cloning a new repo works cleanly. Somehow it didn't work in my usual repo even when I cleaned it every way I could think of :/

[flexibeast]

@bobertlo: Any thoughts on this? The options seem to be:

• Don't try to replicate the docs site ToC structure and numbering in the PDF; just use the setup provided by LaTeX. Pro: Less code to maintain in void-docs. Con: Makes it difficult to refer to a particular part of the documentation consistently.

• Modify this PR to remove all section numbering in the body, possibly make some tweaks to the overall ToC layout, and merge this PR. Pro: Don't have to add code to replicate the docs site section numbering. Con: When referring to the PDF, people will have to use section titles / heading titles rather than numbering.

• Modify this PR to add code to replicate docs site section numbering (and again, possibly make some tweaks to the overall ToC layout), and merge this PR. Pro: Consistency between docs site and PDF. Con: Further code to write and maintain.

i'll work with whatever others decide. :-)

[bobertlo]

Whatever we do, consistency would be best. :)

[ericonr]

Makes it difficult to refer to a particular part of the documentation consistently.

How so?

[flexibeast]

@ericonr:

Makes it difficult to refer to a particular part of the documentation consistently.

How so?

People wouldn't be able to simply say "Refer to section x.y.z in the Handbook", as the section numbering in the HTML version and the PDF differ substantially (cf. the section numbering of the current PDF compared to the section numbering on docs.voidlinux.org). i've just force-pushed an update to this PR which adds some commentary explaining the issue (and which anticipates code changes/additions i'll start working on - see below).

@bobertlo: Okay, thanks - sounds like the third option is the way to go then. :-) i'll implement that asap.

[ericonr]

Hmmm I'm not sure the session numbering should be guaranteed in any way, it's pretty easy to change it for whatever reason; so someone who is using the PDF from the void-docs package and the official website will very easily have mismatched sections.

Guaranteeing session numbering in a specific release is interesting, but feels like a lot of work. If you want to disabuse people of that notion, at least, while still having a similar layout to the website, I would go with option 2. If you have started on the code already, though, we can go with 3.

Overall, I prefer using the section names.

[flexibeast]

@ericonr: Okay, fair enough. Well, i've not yet started writing the code for option 3 in earnest, though i have been thinking about the data structures / algorithms for it. @bobertlo, which option is your preference?

[ericonr]

Should we make a decision on this one before tagging a first version? I don't think we need to, just want to be sure.

If we don't, I can tag the first release tomorrow and update the package then, what do you think?

[flexibeast]

Yes, i'd prefer to wait for @bobertlo's opinion on which option to go with. i'd rather we made the right decision for the long-term than to possibly make the wrong decision under short-term time pressures.

(Fwiw, my own preferred option is point two.)

[ericonr]

Indeed, I don't think we should rush a decision. That said, do you think we need to wait for a decision to tag a release? We don't have to stick with a certain PDF styling between releases, so shipping a first version as is and iterating from there sounds like a nice idea to me.

[flexibeast]

No, i don't think we need to wait. i think the PDF is basically usable as-is.

[flexibeast]

Updated PR so that internal links have the colour of links on docs.voidlinux.org. External links are currently blue, but this can be changed; i think it's a good idea to differentiate internal links from external links, given that the latter will open a browser.

[flexibeast]

For reference, the ToC currently looks like:

current.pdf

and the ToC created by this PR looks like:

new.pdf

[ericonr]

I think I kinda prefer the current one, tbh.

[flexibeast]

@ericonr: Fair enough. :-) If @the-maldridge agrees with you, i can close this PR and open a new one that simply removes the boxes around links and changes the link colour (the former of which i feel would be a definite improvement).