I would prefer that we maintain 1 document that we can build man pages from, especially since the man pages are very neglected. Having said that I totally see the need for a narrower man page that tells people how to get up and running. Guess that is not a bunch of help. Does anyone even use the man pages? donald On Wed, Jan 31, 2018 at 12:33 PM, Quentin Young <qlyoung@cumulusnetworks.com> wrote:
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 (common-options.rst) 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?
_______________________________________________ dev mailing list dev@lists.frrouting.org https://lists.frrouting.org/listinfo/dev