[doc/PDF] improvements to TOC style of the PDF manual

[inkydragon]

Override latex writeheader to use our custom preamble.

Changes:

• Show only "part&chapter" in TOC
• Use compact line spacing in TOC
• Increase the spacing between chapter numbers and chapter names

xref: #35495

• Present lesser levels of subchapters in the TOC (It is almost 20 pages right now)
• The spacing for chapter numbers in the TOC is not sufficient

Output

14p v.s. 3p

Output PDF: doc-pdf-toc+compact-style+efac0d7794.pdf

fast PDF build

These changes affect only the TOC.
So you can compile only the TOC and ignore the rest of the document, which will speed up the compilation significantly!

Clone my en-toc branch, and build.

[ViralBShah]

@fredrikekre Does this look good to you?

[fredrikekre]

Can this be incorporated in Documenter instead?

[inkydragon]

It is definitely possible. But I doubt that this custom style will work for all documents that use Documenter.
Later, I'll also add a custom cover for Julia's document, which undoubtedly doesn't fit in Documenter.

Documenter may provide a more flexible way to customize the preamble of a document.
Maybe Documenter could accept a keyword argument specifying the path to a custom preamble.tex and use its contents to replace the existing preamble.

[ViralBShah]

@fredrikekre Is adding this to Documenter significant effort? Since we have a PR that fixes known issues, would it be ok to merge this and then try to have Documenter implement these as convenient? Perhaps a Documenter issue should be opened up for necessary features.

[inkydragon]

Some new idea

function Documenter.Writers.LaTeXWriter.writeheader(io::IO, doc::Documenter.Documents.Document)
    custom = joinpath(doc.user.root, doc.user.source, "assets", "custom.sty")
    isfile(custom) ? cp(custom, "custom.sty"; force = true) : touch("custom.sty")
    custom = joinpath(doc.user.root, doc.user.source, "assets", "preamble.tex")
    isfile(custom) ? cp(custom, "preamble.tex"; force = true) : touch("preamble.tex") # TODO: Use the default preamble
    preamble =
        """
        \\newcommand{\\DocMainTitle}{$(doc.user.sitename)}
        \\newcommand{\\DocVersion}{$(get(ENV, "TRAVIS_TAG", ""))}
        \\newcommand{\\DocAuthors}{$(doc.user.authors)}

        % ---- Insert custom preamble
        \\input{preamble.tex}
        """
    _println(io, preamble)
end

This short preamble passed some variables to TeX, and insert the contents of preamble.tex into the tex file as a preamble.
Users can fully customize preamble by adding their own preamble.tex.

I'll clean up the writeheader implementation first, and then present the new custom preamble API proposal in JuliaDocs/Documenter.jl#1746 for discussion.

[inkydragon]

@ViralBShah Do we need a CI for building PDF? Something like: docs.julialang.org/PDFs.yml
The existing CI doctest_linux64 seems to test only the HTML build.

---

Note: If we turn off code highlighting and then build the PDF, we can save about 90% of build time.

• 5min: with \usepackage[draft=true]{minted}
• 55min: Normal

[fredrikekre]

I mean, since this PR just overrides functions in Documenter, why not move the overrides there?

[inkydragon]

Yes, this pr overrides the Documenter function, mainly to make some changes to TOC style.
I'm not quite sure if this change should be applied to the upstream Documenter, so that all Documenter-based documents are styled the same way.

What this pr actually does is customize the TeX document style generated by Documenter. Maybe this pr can be merged into Documenter, but not all customization changes are necessary to sync upstream.
I'm also going to add Julia's logo to the first page of the document next, so changes like that are no need to merge into Documenter as well.

The main issues here are that Documenter does not currently provide a way to customize the preamble.
The solution I propose is to use the contents of preamble.tex as a preamble if it exists.
I may open a separate pr in Documenter.jl later.

[fredrikekre]

I mean, it seems like these are improvements that would be useful for everyone building pdf docs with Documenter, no?

[inkydragon]

I'm not sure, julia manual is a little bit special.

The manual has so many chapters (116) that by showing only the chapter names, the TOC is as long as any other TOC that shows both chapter and section names.

I also reduced the line spacing of the TOC to further reduce the length of the TOC.
Normally, a typical manual would not have such a long table of contents.

For me, the only thing worth porting upstream is "Increasing the spacing between chapter numbers and chapter names".

Anyway, I opened new pr JuliaDocs/Documenter.jl#1750.

[jebej]

Agreed that this shouldn't go for all documents, and, for what it's worth, I prefer the old style despite the extreme length.

[inkydragon]

It looks like git rebase master messed up the commit log.

I'll open a new pr.

[inkydragon]

This pr will be replace by: (Merged) JuliaDocs/Documenter.jl#1750 + (Merged) JuliaDocs/Documenter.jl#1785 + JuliaDocs/Documenter.jl#1788