gEDA-dev: asciidoc

[Michael Stovenour]

asciidoc may be a good choice for c; I haven't studied documentation control for c and c++.

However as a fairly regular perl programmer, may I suggest the use of perldoc for the included perl scripts?  There is nothing easier IMHO than updating the command line help right in the source code while I'm updating the ...  code.  The make files can generate the man pages (and HTML, pdf, ...) for the perl scrips using perldoc.  It is easy to have two "help" options on a perldoc embedded perl script.  For example one option (--help, -?, -h) can give a terse output while (--man) produces much more information.  The make file simply specifies --man when building the man pages.  I generally include a 3rd "usage" grouping which is produced when the command line parser fails.  Then it is as simple as "parser failed" dumps just the usage headings, --help dumps the usage headings and the terse help headings, --man dumps the first two and also more of what you would expect in a man page.

Michael

----- Original Message ----
From: Peter TB Brett <peter at peter-b.co.uk>
To: gEDA developer mailing list <geda-dev at moria.seul.org>
Sent: Tuesday, December 18, 2007 3:09:55 PM
Subject: gEDA-dev: asciidoc

Hi,

There is a bug report on SourceForge.net complaining that the gEDA man
 pages 
are rather out of date.

  [1556064] man page version out of date

Man pages seem hard to write and maintain, and other applications seem
 to use 
tools such as pod and asciidoc to generate man pages from an easier
 syntax.

Are there any objections to adopting asciidoc for processing man pages?

                                   Peter



-- 
Peter Brett

Electronic Systems Engineer
Integral Informatics Ltd