The Future of THtml

1. The Future of THtml Plans and Status of ROOT’s documentation facility 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 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. 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. 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 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 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… 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 ROOT 2004 Users Workshop

9. SourceBeautify HtmlGenerator Parser docfile.root Parser Parser 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 ROOT online help THtmlNew DocManager 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 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 ROOT 2004 Users Workshop

12. HTML Output Example ROOT 2004 Users Workshop

13. Modules (or alphabetical list) HTML Output Example 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 ROOT 2004 Users Workshop

15. Member overview – expand to see documentation HTML Output Example ROOT 2004 Users Workshop

16. HTML Output Example (Method) Documentation shown by clicking method name ROOT 2004 Users Workshop

17. Switch to different class using menu HTML Output Example (Go to Class) ROOT 2004 Users Workshop

18. ...or “JumpTo” box HTML Output Example (Go to Class) ROOT 2004 Users Workshop

19. Only showing TExMap’s local methods Click “Show Derived” and... Example ROOT 2004 Users Workshop

20. ...TObject’s methods will be added Example ROOT 2004 Users Workshop

21. Example http://www-clued0.fnal.gov/~axel/example ROOT 2004 Users Workshop

22. Is Help In Reach? 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 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! ROOT 2004 Users Workshop