PDF version of Handbook

[flexibeast]

Suggested by /u/YouNeverWalkAlone here.

i'm not sure what the best approach to this would be. Use pandoc to export to LaTeX, then use pdflatex to produce the PDF?

[ericonr]

We'd have to check the results, but now that we have texlive packages that might be a viable solution and we could even include in the package. I believe @abenson has some templates for markdown -> LaTeX stuff we could try to use.

[flexibeast]

#416 is now basically ready to be merged, modulo any feedback from @void-linux/pkg-committers. However, some things to follow up in the future:

• The ToC structure follows LaTeX conventions, rather than the Web site conventions. Some code could be added to create a ToC along the lines of the latter.
• Lines with filepaths are currently handled by using sloppypar for the entire document, which is a probably an overly-blunt tool.
• The Tor repo table is over-indented.

[ericonr]

handbook.pdf

If anyone wants to get their hands on it without building

[bobertlo]

I am not posting these in the PR because I don't view anything as blocking. I don't feel great about the paragraph indentation being non-uniform. The first paragraph of a section lacking indentation and then the following having it really sticks out to me. This is highlighted by the use of short single sentence paragraphs. Seeing it in this format makes this stick out more. The handbook feels more like a wiki and in that display format it seems natural.

Another thing is just that the paragraphs are single spaced from eachother while lists seem to be double-spaced between their elements and other paragraphs. I don't really know anything about latex, but that is the only other note I saw.

The short sentences and stub sections taking up whole pages I view as more a product of our writing than the PDF.

I do not think these things are blockers from publishing this, just more issues to consider in the future if we are going to do tagged releases. I am starting to have a lot more free time lately and will try to take a look at some of this stuff with you guys. I love this and keep up the good work!

[bobertlo]

If anything, I think in light of this we could merge InfraDocs into the section above as like a see also... just so it doesn't sit alone on the page, or could be expanded to elaborate more on the infrastructure of void in general (and maybe indirectly ease common questions about a former public figure?)

Also, I wonder if it would be worth moving the style guide into a markdown file in the root of the repository, and just pointing to it from the main corpus? It seems a little odd in PDF form. This seems like a very normal practice to me, but as just an mdBook I could have gone either way.

[bobertlo]

Also, I wonder if the contributing section could be worked around a little? If we move the style guide I think PopCorn and Contributing could just all fit in one page vs three (including the parent)

[flexibeast]

@bobertlo: Thanks for the feedback, and the suggestions. :-)

LaTeX provides defaults for each documentclass (such as article or book) that are considered "good typographic style" for that particular class, and i've generally not changed those defaults. But it's LaTeX, so there's a high probability of being able to change things to look exactly how we want. :-) (i recently read somewhere, can't find the source now, that vertical lines in tables are generally frowned upon in professional typesetting, so i'd like to remove them from our tables if people are amenable.)

Finally, i've been making some progress on a script to generate a ToC that looks more like the one on the Web site. One problem i've encountered is that there are numerous inconsistencies between section titles as per SUMMARY.md, and the actual titles of sections. i hope to open a bulk PR to address that sometime today.

[ericonr]

@ericonr: Any thoughts on deployment? i'm guessing some changes need to be made to mdbook_build.sh.j2 in the mdbook Ansible role?

Moving this here.

So, I would prefer to update the build.sh script to take an option so it could run just mdbook build and pdflatex for us, and still be used for the man page generation when building the void-docs package. What we'd need to update then is the part that copies the generated artifacts into the folders used for distributing them. We'd also have to add a few necessary packages to the role, in order to build the whole thing.

[ericonr]

Given the plans of a transition to Docker, we might have to wait a bit to run all this :p

[flexibeast]

Ah, so deploying the PDF will have to wait until after the Docker transition?

[ericonr]

Preferrably so, as I understand it.

[ericonr]

Regarding @flexibeast's comment here #403 (comment) , this is an issue we have to solve, because it appears when building the void-docs package. Output:

Before installing musl Void, please read \hyperlink{-builddir-void-docs-8f542434eea880cca04b688ee4aa5d28ea416a61-src-installation-musl}{the "musl" section} of this
Handbook, so that you are aware of software incompatibilities.

[flexibeast]

Indeed. i have a thought about how to address this, which i've not yet tested locally: on line 272 of mdbook-latex, change:

$base =~ s|^.+/void-docs/src/||;

to:

$base =~ s|^.+/src/||;

[ericonr]

Seemed to work, nice!

[flexibeast]

Okay, thanks - i'll create a PR including that change asap.