[dev] Manpage content

[Quentin Young]

Hi folks,

As part of the work I’m doing to convert all of our docs to RST, I’ve now reached the point where I am converting over the manpages from groff and want some community input on content. As it stands the manpages have not been significantly updated since ~2004 and contain little more than a brief summary of option flags. Now that all of the user documentation is in RST, as far as I can see we have two options:

1. Keep the manpages separate, with their current minimal content. Example (converted) manpage source:
(bgpd.rst) http://ix.io/F0E <http://ix.io/F0E>
(common-options.rst) http://ix.io/F0G <http://ix.io/F0G>

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.

Thoughts?
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.frrouting.org/pipermail/dev/attachments/20180131/0fd605c2/attachment.html>