TODO
----
* Adjust or deprecate all old classes and methods related to help:

Classes:

    AutoClassHelper
    HelpSearchResult
    UGenHelper
    AutoClassHelperTest
    TopicHelper
    Help
    ClassHelper
    Helper

Methods todo:
    *Platform, Platform : helpDir - deprecate in favor of SCDoc.helpTargetDir ?
    PathName : helpFilesDo
    Help, *Help : findHelpFile - Used by SCDoc to get old help, fix this when all old help is converted
    Help : findHelpFileOrElse
    Class, Method : hasHelpFile - in SCDoc all classes has a helpfile - even if it's an autogenerated stub

Methods to deprecate?
    AutoClassHelper, ClassHelper, *Help, TopicHelper, UGenHelper : makeHelp
    Helper : initHelper
    TopicHelper : initTopicHelper
    UGenHelper : initUGenHelper
    *Quarks, Quarks : help
    *Help : makeAutoHelp
    Integer : isHelp
    AutoClassHelper, ClassHelper : initClassHelper

Methods done but could be improved:
    // Class : helpFileForMethod  - FIXME: should jump to method anchor
    // Method : openHelpFile - FIXME: should jump to method anchor

Methods done:
    // Main-showHelpSearch
    // Main-showHelpBrowser
    // Process-showHelp
    // Process-helpGui
    // Class-helpFilePath
    // String-findHelpFileOrElse
    // String-findHelpFile
    // Class-openHelpFile
    // String-openHelpFile

Also deprecate class.categories since this is now in the helpfiles instead?
(categories can still be reached run-time from SCDoc.docMap and SCDoc.makeCategoryMap)

* cross-platform: check all uses of systemCmd. move to Platform class? Some stuff are not possible on windows, use cygwin or similar?

* plain HTML in HelpSource
Some files might be kept as plain HTML instead of converting to .schelp, for example License.html but perhaps even some tutorials?
But then we need a way to add these to the doc_map. For example a directory.scdoc file in these folders that contains a list of doc_map Event's:
[(title: "License", summary: "SC license note", categories: "Licensing", file: "License.html"),
...]
'path' is set automagically.
perhaps we need also a flag to tell if it's a original html with no schelp source, for example we should not delete these entries from cache in getAllMetaData, and  prepareHelpForURL doesn't need to check for a schelp source file.

* Docs using the classtree:: tag should re-render once every session, since the class tree might have changed.
How do we force this? perhaps by setting doc.mtime = 0 for these docs in doc_map? Or use "touch -d DATE" to set the html to a very old date?

PARSER BUGS
-----------
* this doesn't work as it should:

    modalrangetag:: blah blah blah
    blah blah blah blah blah
    blah blah ::

* tags after each other doesn't work, like returns::link::hello::
you need to write returns:: link::hello::
perhaps hard to fix without taking into account if the tag needs closing or not?
for example, what does this mean: code::foo::link::bar::

VALIDATION
----------
* better error handling in parser on bogus input, etc..

* Some tags should only be allowed once. like class, title, related, categories, summary, description, examples..
Also, they should only occur in the root node.

* private:: must come before any other method

* check method argument names (and order?). it's ok to skip arguments though..

* warn on nameless sections, subsections and methods

* warn on subsection with no parent section (including description/classmethods/etc.)

* warn on text before first section in classdocumentation?

* make sure ## and || only happens inside lists/tables

* warn if argstring is given to method under instancemethods/classmethods?
we don't seem to use this anyway. should we allow force replacement of argstring? probably not.

IDEAS AND IMPROVEMENTS
----------------------
* Improve the parser,
clean up and write better regexps. For example, code::foo::/code::bar:: does not currently work.
Use Array instead of List where possible? (note: l=l.add(x), and add everything before we put the array in some other container like node.children, etc).
Rewrite the parser in C or some fast external script?

* Improve the regexp primitives? Perhaps like in JS where we can first compile regexp objects and the re-use them. Also, use a callback instead of returning a list of matches?

* Try to make the renderer faster.

* description for categories? HelpSource/category_descriptions, example:
  Server>Abstractions: Client-side classes representing server-side stuff
  show in header and category browser/overview..
  extensions should be able to add such descriptions too, but not overwrite existing descriptions?

* handle formula:: tag. generate a hash hexstring for use as filename, HelpSource/formulas/xxxxxxxx.png
The renderer would render formula:: by displaying that image if it exists, if not and if LaTeX is installed, convert formula to image first. if LaTeX not installed and image don't exist, show the latex code. (use img alt text?)

* comments (* like this? *)

* shortcuts for links to method in class? mlink::Node-set:: -> link::Classes/Node#-set::
or clink::Node#-set:: -> link::Classes/Node#-set:: ?

* render binary op methods differently? like ArrayedCollections ++
we don't want it to display as "++ (aCollection)" do we? rather "++ aCollection" or "this ++ that" or something..
binary ops only uses chars from this list: !@%&*-+=|<>?/

