Axel Naumann University of Nijmegen / NIKHEF, NL ROOT 2004 Users Workshop The Future of THtml Plans and Status of ROOT’s documentation facility

Axel Naumann University of Nijmegen / NIKHEF, NL ROOT 2004 Users Workshop 2 Why is THtml important? Obviously for ROOT – but there is more: Users combine different code packages, demand for (uniform) documentation ROOT is everywhere – THtml widely used for documentation of non-ROOT code Future: delivers content to ROOT’s online, context sensitive help system

Axel Naumann University of Nijmegen / NIKHEF, NL ROOT 2004 Users Workshop 3 Do We Need a New Implementation? THtml’s horizon “limited by CINT”, but code usually compiled with ACLiC ROOT allows “foreign” code – so should THtml Too many feature requests saying “my compiler understands it, why doesn’t THtml” Help system needs doc objects, but THtml generates HTML Answer: YES.

Axel Naumann University of Nijmegen / NIKHEF, NL ROOT 2004 Users Workshop 4 Can’t We Use Another Tool? Could be Doc++, Doxygen,... Don’t understand ROOT doc syntax No interface to ROOT’s RTTI No doc objects generated but text files No multiple, independent code packages No versioning O(10) slower (Doxygen takes >20mins) Answer: NO.

Axel Naumann University of Nijmegen / NIKHEF, NL ROOT 2004 Users Workshop 5 Goals Support for complete c++ syntax friend, operator, inline, typedef, template, struct,… C preprocessor and c++ parser Current THtml doesn’t parse c++ tokens but characters – slower & no way to integrate a code parser Need CPP to get valid c++ and to document CPP macros Fast (at least as fast as current) Small (only a few files, simple & clean interface – Rene would prefer 1 class with 10 lines of code) Source “beautifier” understanding c++ syntax e.g. count method calls to determine how important it is

Axel Naumann University of Nijmegen / NIKHEF, NL ROOT 2004 Users Workshop 6 Goals Documentation objects, independent of output Content for ROOT’s online help, doc objects in file Generate HTML doc from file – parse once, output many Versioned documentation Often doc is needed for older releases Allow for non-ROOT doc syntax Seamless linking of separate documentation sites Not only UserLib  ROOT, but also UserLib1  UserLib2 Need doc object file for UserLib2 to link doc against it

Axel Naumann University of Nijmegen / NIKHEF, NL ROOT 2004 Users Workshop 7 Design Linked tokens are passed through layer of parsers (CPP parser, type parser, doc extraction) Allows for easy maintenance & customization Nice OO structure with independent parsers Fast, parsers ignore classes of tokens (e.g. CPP) Tiny memory usage Cross-linked documentation objects for doc elements: packages, modules, files, namespaces, classes, methods…

Axel Naumann University of Nijmegen / NIKHEF, NL ROOT 2004 Users Workshop 8 Design - Customization Extensive customization abilities: split code into packages (ROOT, AliROOT,…) specifying versions split packages into modules (e.g. libraries) specifying source dirs (i.e. not relying on ClassImp) add doc elements of external packages for parsing

Axel Naumann University of Nijmegen / NIKHEF, NL ROOT 2004 Users Workshop 9 Design - Interfaces Most important: hide everything! same old (but lightweight) interface MakeAll, MakeClass, talking to doc manager, reads doc objects from file (using rlibmap to find file for class) or generates them THtmlNewROOT online help DocManager docfile.root Parser SourceBeautifyHtmlGenerator

Axel Naumann University of Nijmegen / NIKHEF, NL ROOT 2004 Users Workshop 10 Status Not usable yet :-( Not in ROOT’s cvs yet Concept seems to work 4500 lines of code in 7 header / source files Runs over all (i.e. Unix and WinNT) ROOT sources (1660 files) in 1 minute: tokenizing, CPP’ing and extracting all types & methods

Axel Naumann University of Nijmegen / NIKHEF, NL ROOT 2004 Users Workshop 11 Design of HTML Pages I need comments from you: What do you want a doc page to look like? Plain typewriter pages, or condensed “stylish” ones? Sorting methods by frequency of usage a good idea? To trigger discussion: peek on possible HTML layout Uses optional CSS2, Javascript and cookies Plain html files on server-side (no cgi/php/…) Works on IE6, Mozilla 1.6, NS4, Opera7

Axel Naumann University of Nijmegen / NIKHEF, NL ROOT 2004 Users Workshop 12 HTML Output Example

Axel Naumann University of Nijmegen / NIKHEF, NL ROOT 2004 Users Workshop 13 HTML Output Example Modules (or alphabetical list)

Axel Naumann University of Nijmegen / NIKHEF, NL ROOT 2004 Users Workshop 14 Page header with location (package, version, module, type) and basic type properties (include file, library, ClassDef’ed) HTML Output Example

Axel Naumann University of Nijmegen / NIKHEF, NL ROOT 2004 Users Workshop 15 Member overview – expand to see documentation HTML Output Example

Axel Naumann University of Nijmegen / NIKHEF, NL ROOT 2004 Users Workshop 16 HTML Output Example (Method) Documentation shown by clicking method name

Axel Naumann University of Nijmegen / NIKHEF, NL ROOT 2004 Users Workshop 17 HTML Output Example (Go to Class) Switch to different class using menu

Axel Naumann University of Nijmegen / NIKHEF, NL ROOT 2004 Users Workshop 18 HTML Output Example (Go to Class)...or “JumpTo” box

Axel Naumann University of Nijmegen / NIKHEF, NL ROOT 2004 Users Workshop 19 Example Only showing TExMap’s local methods Click “Show Derived” and...

Axel Naumann University of Nijmegen / NIKHEF, NL ROOT 2004 Users Workshop 20 Example...TObject’s methods will be added

Axel Naumann University of Nijmegen / NIKHEF, NL ROOT 2004 Users Workshop 21 Example

Axel Naumann University of Nijmegen / NIKHEF, NL ROOT 2004 Users Workshop 22 Is Help In Reach?

Axel Naumann University of Nijmegen / NIKHEF, NL ROOT 2004 Users Workshop 23 Is Help In Reach? Parser 70% done tokenizer, CPP, templates & most types done Manager 70% done (missing: doc file) Generate on-demand, manage doc elements, packages & modules, parsing by source dirs Doc elements 90% done Output generator 0% done

Axel Naumann University of Nijmegen / NIKHEF, NL ROOT 2004 Users Workshop 24 Is Help In Reach? Needs about 3 months of continuous work for basic version Available for 6 months starting October ’04 – need bread & water, though... First version by end of the year!