`On 21/06/2010 11:13, Noel O'Boyle wrote: > I'd like to automatically generate documentation for the file formats > based on the OBFormat Description(). Currently this looks like: > =================== > MOPAC Cartesian format > Read Options e.g. -as > s Output single bonds only > b Disable bonding entirely > Write Options e.g. -xk > k "keywords" Use the specified keywords for input > f<file> Read the file specified for input keywords > u Write the crystallographic unit cell, if present. > =================== > > (Note that some formats say Input or Output instead of Read or Write. > I think I should go through and correct these.) > > I think that ideally each option should have one or more paragraphs > explaining the option in more depth, for example where it might be > useful or why it was added. Also it would be nice to have an example > using "babel". Now, I don't expect all of this to arrive magically > overnight but I think it might be a good idea for the future. Right > now, though, I would like to get some agreement on how this > documentation can fit into Description() without breaking the GUI > (which I know parses this text string) or "babel -H". > > Here's a possible solution; indent the option documentation with 4 > spaces (or whatever) and the example with 6. > > =================== > The MOPAC Cartesian format was designed by the Mopac community in > honour of Rene Descartes. It has > the unique ability to do x, y and z, and is widely regarded as great. > Read Options e.g. -as > s Output single bonds only > b Disable bonding entirely > This option should only be used by trained > professionals. The following example gets rid of bonding entirely in > a MOPAC Cartesian file: > babel whatever -ab > > Write Options e.g. -xk > ... > =================== > > Any thoughts?
Within the description of the options, I guess the parsing for the GUI could ignore lines with more than n leading spaces. AFAIR the GUI uses just the first line and the lines between "Read"/"Input"/"Write"/"Output"+"Options" and a blank line. So an extended discussion of a philosopher in every format is entirely possible. The babel -L option is more versatile than -H and can take an extra parameter. The default is to use only the first line, but you can also do babel -L formats input or babel -L formats verbose Maybe with more complex descriptions this could be expanded? I think having documentation available in some detail at run time is a good idea. Polished help files will tend to be forgotten about if they are external and we should aim for the commandline and the GUI being a tool at the user's fingertips. The -L option applies to all plugins, where the descriptions are arguably more important than for formats, so I would hope to see a new system developing it, rather than the historic -H. Chris ------------------------------------------------------------------------------ ThinkGeek and WIRED's GeekDad team up for the Ultimate GeekDad Father's Day Giveaway. ONE MASSIVE PRIZE to the lucky parental unit. See the prize list and enter to win: http://p.sf.net/sfu/thinkgeek-promo _______________________________________________ OpenBabel-Devel mailing list OpenBabel-Devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/openbabel-devel
