[dev] Manpage content

[Raymond Burkholder]

> > 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.