#17 Compatibility with GNU help2man and other formalizations.

open
5
2005-08-29
2005-08-29
No

http://www.gnu.org/software/help2man/

help2man is a very useful utility that can be used to
generate
manpages based on optparse's --help and --version
output. With careful
use of optparse, one can create a pretty nice manpage.
This is an RFE
to make optparse more congruent with help2man and more
similar to
other GNU utilities' --help/--version dumps (eg: ls,
cat, diff, etc).
Doing so would enforce optparse output to be more
consistent and
prescribed.

Help
----
help2man expects certain sections (key words) in the
--help dump:
"Usage", ("Description" glarked), "Options",
"Examples", and "Report
bugs".

This begs for explicit __init__ args for OptionParser:
usage, description, examples, and bugsto. usage and
description as
currently implemented are fine. But it would be more
explicit to have
"examples" and "bugsto" in place of "epilog". [Sorry
for not having
these details when I submitted #988126.]

Version
-------
And further expectations from the --version dump:
Utilty name, Written
by, and Copyright.

This begs for replacing the "version" arg by breaking
it into some
explicit sub-version lines: utilname, package, version,
author, and
copyright.

Summary
-------
With all this in place the ideal OptionParser
instantiation would
change today's usage model from:

multiline_banner = 'foo (fooutils) 0.1\nWritten by
Micah.\n\nCopyright...'
examples_and_bugsto = ' foo --xxx # do
xxx\n\nReport bugs to...'
OptionParser(...,
version=multiline_banner,
epilog=examples_and_bugsto
...)

to this:

OptionParser(...,
usage='foo [OPTIONS] [FILES]',
description='Do some foo stuff...',
examples=' foo --xxx\n foo --yyy\n',
bugsto='Report bugs to: <micah@foo.com>,
utilname='foo',
package='fooutils',
version='0.1',
author='Micah Elliott',
copyright='Copyright (C) 2005 Micah
Elliott.',
)

And optparse could then do the work to produce
help2man-prescribed
formatting:

$ foo --help
Usage: foo [OPTIONS] [FILES]

Do some foo stuff...

Options:
--xxx do xxx
--yyy do yyy

Examples:
foo --xxx # do xxx

Report bugs to: <foo@bar.com>
$ foo --version
foo (fooutils) 0.1
Written by Micah Elliott

Discussion

Get latest updates about Open Source Projects, Conferences and News.

Sign up for the SourceForge newsletter:





No, thanks