On 7/4/10 1:45 PM, Chris Morley wrote:
> On 04/07/2010 21:11, Noel O'Boyle wrote:
>> 2010/7/4 Konstantin Tokarev<[email protected]>:
>>>
>>>
>>> 04.07.10, 23:37, "Noel O'Boyle"<[email protected]>:
>>>
>>>> On 30 June 2010 22:49, Chris Morley wrote:
>>>> > On 30/06/2010 12:24, Noel O'Boyle wrote:
>>>> >> On 30 June 2010 12:16, Geoffrey Hutchison 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.
>>>>
>>>> How about now?
>>>> http://baoilleach.webfactional.com/site_media/ob-docs/FileFormats/SVG_depiction.html
>>>
>>> Looks cool! Is it all generated from source documentation?
>>
>> The file format pages are.
>>
>> There are a couple of things to do still, like add a few missing
>> formats, "Read only" info, the specification and so forth. I had to
>> add a minus sign in front of the option letters to make it format it
>> nicely. This is not ideal - I might have to hack a bit to sort this
>> out.
>
> It looks good!
> However I agree the '-' before the options is confusing because you
> have to use e.g. -xu
> One of the '-' has been removed from --gen2D.
> Could the<num> go on the same line as the option letter?
Do you mean it's now -gen2D? That's not right. The defacto standard for
UNIX/Linux is to use a single hyphen for single-letter options and double
hyphen for longer option names. For example, the ls(1) man page on Linux looks
like this:
-a, --all
do not ignore entries starting with .
-A, --almost-all
do not list implied . and ..
--author
with -l, print the author of each file
-b, --escape
print octal escapes for nongraphic characters
... and so forth. OpenBabel's options are already really screwed up. If it's
time to make changes, we should be moving towards defacto standards, not away.
We had a long discussion about this a year or two ago, about how the babel(1)
options have tricked a bunch of us who are experienced with Linux into
accidentally erasing files.
So PLEASE leave the option as "--gen2D", not "-gen2D".
Craig
------------------------------------------------------------------------------
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
