2. Add the standard SYNOPSIS, DESCRIPTION, OPTIONS etc. sections, as in the source above, to the top of each chapter in the user documentation that covers a daemon, and then generate manpages from the same source we use to generate the various other manuals (web, info, pdf, etc).
The only downside I see to option #2 is that some of the manpages have small novels written inside them (for example the 24 paragraph section on MED in the BGP chapter), which degrades their usefulness as the “quick reference” people tend to use them for these days. Whereas the upside is 13 less (albeit small) files to update when things change and a significant increase in the amount of overall information in the manpages.
After the other long note, in a nutshell, in reminding myself of all the options for writing route-maps with prefix-lists with permit / deny entries, I think I prefer the Cisco way (if I recall correctly) of putting everything into a longer page. It makes it easier to scroll up and down, comparing notes and options and relationships, and then to compose the specific rules I need from what I see on a larger page. I ended up copying commands from the various sub-pages into my own mini document so I could see all the bits I needed. Maybe that provides some vague perspective on usage from a casual user of many different sub-systems. -- This message has been scanned for viruses and dangerous content by MailScanner, and is believed to be clean.