Restructuring for PDF/HTML compatibility and numbering #367
Conversation
same functions as toctree, but no potential problems in PDF
prev. figures were needlessly placed in the middle of otherwise empty pages, or too far after the text they applied to
This change gives a detailed toctree down to subsection level and a sidebar navigation that mirrors that of the books index page.
this is to reduce mismatch between html and pdf numbering
- rely on chapter level toctrees for the basics chapters and combine the basics into a single toctree. This has two advantages: shows the Basics in html as one consecutive part, and leads to 'basics' being a single part in the PDF (instead of 10 different parts) - insert small figures with additional captions to make the distinction between the book parts more clear - Set the toctree depth to 2 to show chapters (e.g. DataLad, Runand sections (e.g., Keep track)
This allows that the Basics are a single part and to reference chapters (instead of only sections). The toctrees are hidden in the PDF, and chapters start with an illustration
|
FTR: If this PR is merged, I think the only severe deficiency of the PDF version of the book is that findoutmores are not distinguishable from the main text. |
|
Note that for across docs referencing we can insert reference handles at any point in the rst documents. An example is http://handbook.datalad.org/en/latest/basics/101-136-filesystem.html#removing-annexed-content-entirely. With the numbering, we can refer to this paragraph with "Chapter VIII, 2.7.2") |
|
@mih, let me know whether you're okay with this PR. There's left-over TODOs (we talked about custom numbering in Latex table of contents, numerals types are still subject to discussion), but if possible, I'd like to have the general restructuring in master soon-ish to sort the new usecases in. :) |
|
Sure, go ahead. I might come back to this at a later point in time. Thx! |
This PR restructures the table of contents in the HTML and PDF version of the handbook. This is done to reduce the significant mismatches between HTML and PDF version (see #38 (comment) for an overview of problems I have identified), and to create a handbook toctree that is allows easy navigation based on Chapter or usecase numbers.
In particular, this PR: