Improving Documentation of support scripts

[David G <..hidden..>]

Hi,

A while ago Erik and I were discussing the need to better document the
various scripts and files that are not directly part of the LedgerSMB code.
These scripts are found in directories like
    * tools
    * utils
    * dists

At the moment there is essentially no documentation for any of these
scripts.
We discussed the possibility of using our existing perldoc tool to
extract documentation from comments in these files, but that may get a
little tricky as the format that perldoc expects is not compatible with
all script comment formats.

An alternative would be to require every script to provide a number of
command line options.
When we want to build the docs, (at release for example) a simple script
can run all of the other scripts with the correct arguments allowing the
docs to be generated.

Keeping the documentation inside each script makes it easier to maintain
(a single file to edit) and less likely that the documentation falls out
of date.

The arguments I propose all executables (scripts and binaries) support are

     * --help 	  displays a Usage Summary followed by more detail if required.
     * --readme   displays a markdown formatted chunck containing script description an usage summary
     * --version  reports the script version in "scriptname v1.0.0" format


By requiring the --readme argument to output markdown formatted text we
can just combine the output from all executables in a directory into a
single README.md that will be nicely formatted by github and other tools.
This README.md can also be easily read by a normal text editor and
trivially converted to HTML for viewing in a browser.

We could also have a readme.header that is included at the top of the
auto generated README.md so hand generated information can be added.

I would be happy to implement the required changes to implement this but
thought the community may have some thoughts to contribute.

Regards
David G

------------------------------------------------------------------------------
_______________________________________________
Ledger-smb-devel mailing list
..hidden..
https://lists.sourceforge.net/lists/listinfo/ledger-smb-devel