I noticed that pms-3.pdf has some broken references. In particular, section 9.2.4 has three references to itself. I assume that latex wasn't run often enough when generating this document. A revbump fixing this would be great.
OK, my error: the referenced information really follows later on in that same section. Still, referencing it by number is somewhat confusing. Better wording or different sectioning would be good. Not a compilation issue, though, but an editorial issue.
This should probably go upstream.
Also several times in section 12.3.3 "Ebuild-specific Commands". The problem is that subsubsections don't have numbers, therefore references to them appear as the number of the containing subsection.
(In reply to comment #3) > Also several times in section 12.3.3 "Ebuild-specific Commands". > > The problem is that subsubsections don't have numbers, therefore references to > them appear as the number of the containing subsection. We could enumerate subsubsections...Comments?
(In reply to comment #4) > We could enumerate subsubsections...Comments? Yes, we could increase secnumdepth from 2 to 3, but do we really want section numbers with four components? (I've no better idea though.)
One alternative would be page numbers instead or in addition to section numbers. Another would be restructuring the hierarchy to make do with less depth. Dunno. I don't mind deep section numbers in such technical documents, though. Makes referencing parts easier while representing complicated structures sensibly.
Created attachment 252791 [details, diff] suggested PMS patch We could increase secnumdepth to 3, but leave tocdepth at 2, in order not to clutter the table of contents too much. See attached patch. Or we could also increase tocdepth to 3. Resulting PDF files with tocdepth 2 and 3 are here: <http://dev.gentoo.org/~ulm/pms/pms-tocdepth-2.pdf> <http://dev.gentoo.org/~ulm/pms/pms-tocdepth-3.pdf> I'd prefer the first variant. Other opinions?
(In reply to comment #7) > We could increase secnumdepth to 3, but leave tocdepth at 2, in order not to > clutter the table of contents too much. See attached patch. Or we could also > increase tocdepth to 3. We can also have two table of contents with different verbosity levels, but for such a short document as PMS this is a bit overkill. I vote for tocdepth 2 and secnumdepth 3.
Nobody has objected, therefore pushed to master. Thank you for pointing this out.
In the mean time, subsection 11.3.3 "Ebuild-specific Commands" has grown to 14 pages. This is longer than any chapter (except for chapter 11, of course). Also, pointing to specific commands would have been useful more than once in the past. Any objections if I increase the tocdepth to 3, i.e. the same value as secnumdepth? It would add one page to the PDF file.
(In reply to Ulrich Müller from comment #10) > Any objections if I increase the tocdepth to 3, i.e. the same value as > secnumdepth? Seems not. Committed to master: https://gitweb.gentoo.org/proj/pms.git/commit/?id=1afb71f3cdeb145999c872c30e97a4a00ef6575b