On 11/16/14 16:09, Stuart Henderson wrote: > On 2014-11-16, Daniel Jakots <vigdis+o...@chown.me> wrote: >> Hi, >> >> I wanted to add some content to FAQ14 but I saw some errors there, so >> first I corrected them. >> >> The problems are >> - No 14.13 >> - No 20.2 > > That's intentional, we don't generally do a bulk renumbering if a section > is removed.
yes...for a number of reasons...not just that I'm a lazy bum. A lot of sections I think of by number, not just by name....and sometimes it is nice to be able to insert a new section near where other sections are already in place without renumbering everything else. I do not want the renumber at this time...when I do, you will know (because I'll have done it. :) >> - 14.5.*, 14.17.* and 14.20.* are not linked in the "Table of Contents" > > It's probably worth splitting that out to a separate diff, I'm not > sure what Nick@ will think but that seems reasonable to me. > >> Also what's the policy about giving numbers (like 14.5.1)? Because they >> are assigned to "h3" heading tags, but not all "h3" are numbered. > > I'm not sure about that. For both the TOC and section numbers, no firm rule...the question is mostly one of "stand-alone-ability" -- If someone might be interested in the subsection without recognizing it as part of the parent section, then yes, it should definitely be broken out. If subsections are entirely dependent upon the parent section, probably not. And the TOC at the top of the page shouldn't be overly large, but should be useful. However, look at this kind of work just like coders look at KNF (style(9)) work. Coders do KNF as part of READING THE CODE looking for problems...and they find formatting errors and fix them to make the code easier to read. KNF for the sake of KNF does nothing for anyone...and in fact, may discourage the constructive reading/auditing of code. Adjusting the TOC and section numbers will generally not improve the FAQ experience for readers; if while looking for bigger issues the worst you can find is missing section numbers, great. But in this case, if that's even the biggest /formatting/ issue you have found, you need glasses. :) Nick.
