On 30 June 2010 22:49, Chris Morley <[email protected]> wrote: > 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).
I think we can all agree that having the documentation in one place (e.g. the .cpp code) and then generating the other versions is a good idea. The formatting and so forth can all be changed very easily once we get the mechanism in place to make this happen. I am making sure that none of the information on the wiki will be lost. > 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. Thanks for the feedback. I'll try to take these comments on board and regenerate the pages. Just to note that it's not quite like a wiki page where the appearance is essentially free-for-all; some elements of the design are out of my control as it uses some special formatting to indicate that these are options to a command line program (this has various advantages regarding indexing and so forth). In the HTML format it will format these one way, in the PDF version it will format them differently. The notes and so forth I can control though. > 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 > ------------------------------------------------------------------------------ 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
