Re: [brlcad-devel] Multiple options for same purpose: prohibit them?
Open Source Solid Modeling CAD
Brought to you by:
brlcad
From: Tom B. <tom...@gm...> - 2013-07-31 15:18:32
|
On Wed, Jul 31, 2013 at 8:04 AM, Christopher Sean Morrison <br...@ma...> wrote: > On Jul 31, 2013, at 8:35 AM, Tom Browder wrote: >> I am working on a proposal for DRY handling of binary program option descriptions ... > 2) we don't need duplicate options like -s/-S where they both describe a framebuffer size. ;) > A few more conventions I'd like to see codified: size options... My simple proposal doesn't go that far, but I think it's extendable in that direction. My general idea is to try to standardize some simple rules for adding tidbits of info to already-used semi-programming conventions so that selected program source can be parsed to generate a minimal docbook manpage that can be expanded as desired. Case statements for the bu_getopt block will provide the single-character option comments. Each option should be on one case line and be followed on the same line by a comment block (which can be continued on as many lines as needed) which will provide the info for the option description in the DocBook. That comment block is not started with a key word. Other inputs will be provided through several const char strings plus some mandatory and optional comment blocks headed by keywords (similar to Doxygen) like 'description:' (mandatory) and 'seealso:' (optional) which can be translated directly into DocBook man format. The bu_getopt arg string is easily parsed for single-character option handling, but other options I think could be handled by making a comment block with a leading key word such as 'opt:' followed by the option character or name followed by an optional list of square bracketed optional subargs, or something like that. Such things as BUGS, BUG REPORTS, and COPYRIGHT will be boiler plate unless such a comment block is provided. > Related effort in this area, Carl Moore has been working on options as well now I've been watching that and I applaud Carl for that faithful, slogging effort! > His work raises another potential exception to a multiple-character rule > (or at > least it's something worth discussing) where he's currently > making both -? and -h provide help/usage. Presently, they return the > same information, but the long-term intent is to make them return > *different* levels/types of help information. That's okay, but I would like to standardize on the execution of the program name, with no args, to return a short usage string. I guess a very few programs might not take to that convention (but I'll have to be convinced), but most (if not all) could be converted to do that. Best, -Tom |