Hi Anton , Damir and I hope the long list of documenters, I totally agree with your view about the online manual. >From an application running Root, one should be able to get (< 100 msec) a help window with the usual search techniques: - structured table of contents - search by keyword - help on class The help data base consisting of the "new user guide" and of the automatically generated reference manual from the classes. In addition it should point to references showing examples and courses. Concerning the automatic reference manual, I suggested the following idea at the Root workshop. With minor changes to the THtml class, it would be easy to generate an application_help.root file (eg root_help.root for root itself). This root file will contain as many directories than classes in the application. Each directory having a key for each member function. This will permit an extremely fast access to the documentation for any object (one could implement an object.Help() function also available from the context menu. The object.Help function will show a browsable window with the list of all functions (including the ones from the base classes). Clicking on one function will show the documentation for this function. We have not yet discussed the implementation for this browsable window. It must clearly be an html-like facility. The important point is that it must be fast. If the time to get a help is more than a few hundred milliseconds, it is useless. The root_help.root file would be distributed with the binary distributions and will always be in phase (by definition) with the functionality of the associated binary libraries. Concerning the users guide itself, I think that one must absolutely avoid the "Cathedral model". I do not care too much about the format for the time being. It is more important to have quickly a first draft and have reactions on this first draft, rather than wait 6 months or one year of a substantial effort and may be get something that will not correspond to the expectations. A simple text file would be perfect. Once we have a clear idea on the contents, we can start discussing the format. Because we do not want to have to maintain N different formats, one should be able to automatically generate from the selected native source format: - an html version. - a Latex version or equivalent - a Postscript version. - the relevant information for the application_help.root file. XML is currently gaining ground for this type of problem. From the XML DTDs, one should be able to generate the different versions above. XML is public domain, text file format with WYSIWYG editors coming. This is may be a crazy idea, but it should be investigated. Rene Brun On Sat, 12 Feb 2000, Anton Fokin wrote: > Hi there! > > I do not know if I am going to write my part of the manual :) but I would > like to suggest people who are really going to do it to look first how > _good_ manuals for _frameworks_ are written. I.e. I would like to see > something which stands close to Turbo Vision, ObjWindows, Delphi, C++ > Builder, Qt, (well, I think about 99% of you know those mans) or, perhaps, > Java. These are in some way _frameworks_ and the reader gets feeling about > how to understand and follow the framework (like, object model, event model > and handling, rtti, serialization, error and exception handling) rather than > how to use it as an object lib to open a file and build a histogram. > > Concerning the format, it doesn't matter, the only one thing to keep in > mind: it would be nice to be able to convert the manual to a somewhat > "standardized" on-line helper (i.e. a help window you get than you press F1 > or go to the "help" menu), so it ...perhaps... should have an > easy-to-convert cross-reference structure to create index, key search, etc > (well, look how mustdie95 helper works). Of course if you are going to write > a _book_, it might be different, but I am not sure that the first versions > would stay so far away from a kind of "on-line" manual. And ... it is much > more easier to write a help window object which can show a html page (by the > way why it is not done yet in ROOT?:) everybody has it and it is a _very_ > useful object)) than pdf or ms word ... > > Anton >
This archive was generated by hypermail 2b29 : Tue Jan 02 2001 - 11:50:18 MET