On 22.09.14 12:34, andy pugh wrote: > On 22 September 2014 12:22, Gene Heskett <[email protected]> wrote: > > IMO an > > example usage stanza should be shown. > > Most of the component manpages are auto-generated by "comp", but in > many cases it is hard for comp to auto-generate a valid usage example.
A commonly used tool for auto-generating documentation from code is: http://en.wikipedia.org/wiki/Doxygen If that is already what is being used, then all that is required for the insertion of examples is a suitable comment in the code. Now everyone wins: The coder does not have precious tweaked documentation overwritten by auto-generation (since the tweaks come from the extra code comments); the user has examples (or whatever other goodies are added) in the manpage; and the coder also has them in the code, to serve as a reminder of the code's documented requirements. There may be other tools, but this one seems to be the frontrunner is FOSS circles. If a bit of awk were needed, to massage the doxygen output to manpage layout, then that'd be no biggy. (I'm thinking of auto-insertion of groff formatting gumpf, a la "man 7 man", as an example.) Mind you, according to: http://en.wikipedia.org/wiki/Comparison_of_documentation_generators it'll generate manpages and html directly. Erik -- "You have seven to eight million people entering the workforce in China every single year, so you have to give them something to do in order to retain the legitimacy of the government," says Doran. "Maybe 10 or 15 years ago they were doing things that made sense - roads, rail, power stations etc - but now it's investment for investment's sake." - http://www.bbc.com/news/magazine-19049254 ------------------------------------------------------------------------------ Meet PCI DSS 3.0 Compliance Requirements with EventLog Analyzer Achieve PCI DSS 3.0 Compliant Status with Out-of-the-box PCI DSS Reports Are you Audit-Ready for PCI DSS 3.0 Compliance? Download White paper Comply to PCI DSS 3.0 Requirement 10 and 11.5 with EventLog Analyzer http://pubads.g.doubleclick.net/gampad/clk?id=154622311&iu=/4140/ostg.clktrk _______________________________________________ Emc-users mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/emc-users
