On 21 June 2010 19:54, Chris Morley <c.mor...@gaseq.co.uk> wrote: > `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?
Can you write up the description of the -L option on the wiki? I'm thinking that maybe it's time to stop listing all 100 formats under babel -H. This prevents the user acutally seeing all of the available options. How about babel -H ending with the number of plugins loaded and prompting the user to use -L to get a list of plugin names? For example: """ Plugins available: 100 formats, 5 operations, 3 fingerprints. For a list of available plugin names, use "babel -L <plugintype>". For example, "babel -L formats" to list all available formats. See "-L" option above. For information on a particular format, you can also use "babel -H<formatname>". For example "babel -Hsdf". """ > 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. I agree. > 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. Sounds good. > 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 > ------------------------------------------------------------------------------ This SF.net email is sponsored by Sprint What will you do first with EVO, the first 4G phone? Visit sprint.com/first -- http://p.sf.net/sfu/sprint-com-first _______________________________________________ OpenBabel-Devel mailing list OpenBabel-Devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/openbabel-devel
