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... -- https://mail.python.org/mailman/listinfo/python-list
