Follow-up from "WIP: Convert documentation from docbook to sphinx-doc syntax"
The following discussion from !1761 (merged) should be addressed:
- I notice
make docdoesn't generate PDFs, I had to
make allapparently includes a
make docstep, now, which seems unnecessary to me.
make allin a clean directory always seems to fail while building doc the first time, though it always seems to succeed on the second attempt. I haven't had time to dig in to what's causing this.
- Is the directory name
_builda requirement of sphinx? It's an admittedly minor quibble, but I wish the HTML still appeared in doc/arm, or at most one level down instead of two.
- Why do we have both
make doccleanboth fail to clean up generated documentation.
- The files in doc/arm/man appear to be generated from RST source, but are checked into git, whereas elsewhere you seem to have removed all the generated documentation; what's the purpose of having these checked in?
- Chapter numbering is very weird - what used to be section 3.4 on plugins is now a very short chapter by itself, and many the sections of chapter 4 seem to have been split out into separate chapters too. The result is what used to be 8 chapters and 4 appendices is now 19 chapters. The appendices are no longer at the end.
- (Not a regression, but it's also really weird to have the advanced DNS features turn up in the ARM before the basic configuration directions. We should reorder the chapters.)
Looking over the generated PDF's for the ARM and the release notes:
- The ISC logo has become kind of tiny now.
- Many of the grammars in the ARM display weirdly. They're enclosed in boxes but they spill out past the margins, and there are XML tags in them. The ones in the named.conf man page in chapter 19 are fine, but in the earlier parts of the ARM they're broken. I'm guessing this is a bug in the rst-zoneopt.pl and/or rst-grammars.pl scripts.
- Tables that fill a whole page look weird (see pages 50, 60 and 125 for examples). I don't think this is a regression, though.
- Odd formatting in a table on page 61 as well.
- Option definitions should probably have a line break after the option name. (See page 77 for examples of what I mean - the first line of the text describing the option flows right after the option name, and it looks to me like it should start on the line below.)
- The table defining rrset-order values is positioned incorrectly on page 93.
- Tables spill over the right margins on pages 127 and 135.
- Table appears to incorrectly contain another table on page 132.
- Table formatting error on page 137.
Looking over the generated HTML:
- The formatting here is generally very nice!
- The same problem also applies here with grammars - XML tags are visible.
- RFC references in chapter 17 are formatted oddly, with author names showing up as "VixieP" and "AndrewsM", commas missing.
- I notice