manpage writing [rst, asciidoc, pod] was [Re: What should Python apps do when asked to show help?]

[Rustom Mody]

On Saturday, April 30, 2016 at 7:55:47 AM UTC+5:30, Ben Finney wrote:
> "Martin A. Brown"  writes:
> 
> > Hello [Steven D'Aprano],
> >
> > >What is a good place where I can find out more about writing manpage?
> 
> Writing them directly in GNU troff markup is easy enough
> <URL:http://liw.fi/manpages/>.
> 
> For writing manual pages programmatically via Python code, I am working
> on a 'manpage' library. It is not yet at PyPI, but Steven may find
> the existing library <URL:https://notabug.org/bignose/python-manpage>
> useful. It's free software under the GNU GPL v3 or later.
> 
> Steven, if you want to use that library for making manual pages, I'd
> love to get feedback. Currently it works on an ArgumentParser instance
> (to get the program's name and option help), and a Distutils
> distribution (to get the boader metadata about the package).
> 
> What 'manpage' doesn't yet have is a more generic way to specify the
> metadata of a manual page. Everything is done by directly modifying a
> Document instance. I have yet to decide a data format for the data which
> specifies a manual page.
> 
> Getting several more code bases using this library would make it clearer
> what use cases are important, and thereby inform a data format for the
> specification. Please experiment!

Some general thoughts and comments:
Documentation in linux is a train-wreck in slow motion -- 30 years of slow motion!!

tl;dr
If you want to be helpful to the community please dont create a new format
Instead try to make existing formats interoperate/work better with each other

In more detail:
First there was man
Then gnu/rms created info to better man with hypertext capabilities
However another hypertext standard beat the gnu standard -- html
[No I am not talking of quality just general acceptance]
As with all things rms, its taking him decades to realize this defeat
[Latest makeinfo is 18 times slower than previous version!!
https://lists.gnu.org/archive/html/bug-texinfo/2013-01/msg00012.html
]

In the meantime the so called lightweight formats have multiplied:
rst, textile, markdown, asciidoc etc
with their own 'stacks'
Alongside siloed, incompatible help systems:
manpages, infodocs, yelp...