On Aug 7, 2013, at 1:52 PM, Tom Browder wrote: > On Wed, Jul 31, 2013 at 8:04 AM, Christopher Sean Morrison > <[email protected]> wrote: > ... >> 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. > > Can we decide on that now?
Sure, but how about I pick people's mind for some usability feedback before making that declaration. There's a requirements issue that warrants consideration. > Let one option (or no options where feasible) be a one liner and one > be extended. Take, for example, the current usage in program > 'fix_polysolids' (with either '-h' or '-?' or no options): I had similar thoughts at first, but short usage and long usage seem to have minimal value. I don't know that I've ever experienced a usability concern with a long usage (e.g., svn help), but certainly have with short unhelpful usage messages (e.g., ls -?). If the user is intentionally asking for help, then I think long usage where options/defaults are described makes the most sense. Perhaps let no options still just give the one liner reminder, but default -h to full usage with each option described, for example.. That just begs what to do with the second option and three types of information come to mind: 1) Instruction. Instead us short/long usage, give them prose that explains what the tool is and what it does with maybe one example. This could even be the overview in the manual page. 2) Man page. Instead of just instruction, give the whole shebang. It would certainly improve documentation accessibility (no man/brlman awareness, no MANPATH issues, easily discovered/announced). 3) Programmatic schema. A primary goal of mine is to turn all of our commands into a massive plug-in system which means that our existing commands are going to need to declare their interface somewhere. This could be an outboard file or it could literally be embedded into the command itself. The output would describe (e.g., via xml or json) the program's I/O -- what data type(s) does the program read via stdin, stdout, stderr given particular option sets. With that information, the program could be auto-registered as a data processing interface and commands could be automatically chained together to get work done. This obviously wouldn't be an option documented to users. Merits to all three, but interested in hearing other's thoughts. Cheers! Sean ------------------------------------------------------------------------------ Get 100% visibility into Java/.NET code with AppDynamics Lite! It's a free troubleshooting tool designed for production. Get down to code-level detail for bottlenecks, with <2% overhead. Download for free and get started troubleshooting in minutes. http://pubads.g.doubleclick.net/gampad/clk?id=48897031&iu=/4140/ostg.clktrk _______________________________________________ BRL-CAD Developer mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/brlcad-devel
