On 30/06/2010 12:24, Noel O'Boyle wrote:
> On 30 June 2010 12:16, Geoffrey Hutchison<[email protected]> wrote:
>>> It would be useful if people could add at least a few lines to each
>>> format saying what it is and what it might be used for. This is
>>> particular true of the utility formats, which I still don't
>>
>> We *have* format documentation in the wiki. In particular, I tried to
>> document many of the "utility" formats. No, not all, but there are bits here:
>> http://openbabel.org/wiki/Formats
>
> I guess these were automatically generated from the Descriptions also,
> right? I'll check for any modifications and then put that information
> back into the .cpp descriptions.
Geoff's pages are ok but would be better if
- there was more content in the Descriptions
- all the content including Additional Comments was there so that
everything could be accessed from the command-line
- there was a greater range of content type: examples etc. with
appropriate formatting
- it was easy to keep up to date.
Noel's formatting is smarter but can I make some comments on the
design? (Ref the SVGFormat description).
There is a school which thinks that the more white space there is, the
easier it is to understand. But I don't like very open layouts and
think the key is getting the grouping and the hierarchy of comments
right. So I would give a bigger emphasis to the first comment line,
and have it more closely associated with the the option letter.
The comment at the bottom about explicit hydrogen is what I would want
in a Note box - "you've had the basic information, but have you
thought about this?"
I think it would be better to put the examples (especially the one
near the end) in a different typeface and layout - like the wiki. The
kind of person who uses OB probably looks at examples first and then
reads the rest when he doesn't understand them. We should try too keep
the exposition logical, but make the examples stand out - so keeping
everybody happy.
Chris
------------------------------------------------------------------------------
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
[email protected]
https://lists.sourceforge.net/lists/listinfo/openbabel-devel
