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?
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
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?
Kind of a chicken and egg problem? No one uses them because they don't have current information? Many might use them with updated information? FRR may gain even more acceptance with more inclusive/documented details? Can some options and commands be automatically extracted from source code? I've had to go there to find interesting things. Would it be acceptable to maybe point to some reference cumulus pages for information? I've gone there as well for guidelines. If I had time, I would extract and write stuff, but time eludes me. Can't seem to figure out why. Long man pages are good if they have lots of juicy tidbits of information. Are links to blogs of useful value as a work around for lack of detail? Although ... blog entries tend to become out-dated as code/commands evolves.
On Wed, Jan 31, 2018 at 12:33 PM, Quentin Young <qlyoung@cumulusnetworks.com> wrote:
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”
Quick reference has its merits and detailed sections also have their merits. Unless there are links to off-site links which can provide the background. But detail should probably be local as there are typically FRR'isms in the interpretations which need to be mentioned. The MED page is a good example of where we could be in some version of the future: details followed by command specifics.
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.
If, at some point, when someone is able to add detail, there may be much more than just 13 (albeit small) files. How many sections might there be? BGP could get quite large due to all the various ways it is/could be used: EVPN, MPLS, VNC, maps, lists, .... Plus the various diagnostic commands which don't seem to be listed. Should there be some thought to the future as to how sections could be arranged, and make some sort of notification somewhere of where users can go to add their own bits to the overall documentation project? Wiki page or something? It is probably dead easy for someone already familiar, but sometimes we need to be hand-lead to where we need to be. -- This message has been scanned for viruses and dangerous content by MailScanner, and is believed to be clean.
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.
participants (3)
-
Donald Sharp -
Quentin Young -
Raymond Burkholder