[dev] Manpage content

[Donald Sharp]

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 at 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 at lists.frrouting.org
> https://lists.frrouting.org/listinfo/dev
>