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 <[EMAIL PROTECTED]> To: gEDA developer mailing list <[email protected]> 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 _______________________________________________ geda-dev mailing list [email protected] http://www.seul.org/cgi-bin/mailman/listinfo/geda-dev
