SCClassLibrary/SCDoc/TODO

   1 TODO
   2 ----
   3 * Adjust or deprecate all old classes and methods related to help:
   4
   5 Classes:
   6
   7     AutoClassHelper
   8     HelpSearchResult
   9     UGenHelper
  10     AutoClassHelperTest
  11     TopicHelper
  12     Help
  13     ClassHelper
  14     Helper
  15
  16 Methods todo:
  17     *Platform, Platform : helpDir - deprecate in favor of SCDoc.helpTargetDir ?
  18     PathName : helpFilesDo
  19     Help, *Help : findHelpFile - Used by SCDoc to get old help, fix this when all old help is converted
  20     Help : findHelpFileOrElse
  21     Class, Method : hasHelpFile - in SCDoc all classes has a helpfile - even if it's an autogenerated stub
  22
  23 Methods to deprecate?
  24     AutoClassHelper, ClassHelper, *Help, TopicHelper, UGenHelper : makeHelp
  25     Helper : initHelper
  26     TopicHelper : initTopicHelper
  27     UGenHelper : initUGenHelper
  28     *Quarks, Quarks : help
  29     *Help : makeAutoHelp
  30     Integer : isHelp
  31     AutoClassHelper, ClassHelper : initClassHelper
  32
  33 Methods done but could be improved:
  34     // Class : helpFileForMethod  - FIXME: should jump to method anchor
  35     // Method : openHelpFile - FIXME: should jump to method anchor
  36
  37 Methods done:
  38     // Main-showHelpSearch
  39     // Main-showHelpBrowser
  40     // Process-showHelp
  41     // Process-helpGui
  42     // Class-helpFilePath
  43     // String-findHelpFileOrElse
  44     // String-findHelpFile
  45     // Class-openHelpFile
  46     // String-openHelpFile
  47
  48 Also deprecate class.categories since this is now in the helpfiles instead?
  49 (categories can still be reached run-time from SCDoc.docMap and SCDoc.makeCategoryMap)
  50
  51 * cross-platform: check all uses of systemCmd. move to Platform class? Some stuff are not possible on windows, use cygwin or similar?
  52
  53 * plain HTML in HelpSource
  54 Some files might be kept as plain HTML instead of converting to .schelp, for example License.html but perhaps even some tutorials?
  55 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:
  56 [(title: "License", summary: "SC license note", categories: "Licensing", file: "License.html"),
  57 ...]
  58 'path' is set automagically.
  59 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.
  60
  61 * Docs using the classtree:: tag should re-render once every session, since the class tree might have changed.
  62 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?
  63
  64 PARSER BUGS
  65 -----------
  66 * this doesn't work as it should:
  67
  68     modalrangetag:: blah blah blah
  69     blah blah blah blah blah
  70     blah blah ::
  71
  72 * this doesn't work as it should:
  73
  74     hello
  75
  76     strong::there:: is a bug
  77
  78 * tags after each other doesn't work, like returns::link::hello::
  79 perhaps hard to fix without taking into account if the tag needs closing or not?
  80 for example, what does this mean: code::foo::link::bar::
  81
  82 * using \::. doesn't work, needs a space: \:: .
  83 also sometimes non-letters after :: doesn't work as expected, like "(link::hello::)"
  84
  85 VALIDATION
  86 ----------
  87 * better error handling in parser on bogus input, etc..
  88
  89 * Some tags should only be allowed once. like class, title, related, categories, summary, description, examples..
  90 Also, they should only occur in the root node.
  91
  92 * private:: must come before any other method
  93
  94 * check method argument names (and order?). it's ok to skip arguments though..
  95
  96 * warn on nameless sections, subsections and methods
  97
  98 * warn on subsection with no parent section (including description/classmethods/etc.)
  99
 100 * warn on text before first section in classdocumentation?
 101
 102 * make sure ## and || only happens inside lists/tables
 103
 104 * warn if argstring is given to method under instancemethods/classmethods?
 105 we don't seem to use this anyway. should we allow force replacement of argstring? probably not.
 106
 107 IDEAS AND IMPROVEMENTS
 108 ----------------------
 109 * Improve the parser,
 110 clean up and write better regexps. For example, code::foo::/code::bar:: does not currently work.
 111 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).
 112 Rewrite the parser in C or some fast external script?
 113
 114 * 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?
 115
 116 * Try to make the renderer faster.
 117
 118 * description for categories? HelpSource/category_descriptions, example:
 119   Server>Abstractions: Client-side classes representing server-side stuff
 120   show in header and category browser/overview..
 121   extensions should be able to add such descriptions too, but not overwrite existing descriptions?
 122
 123 * handle formula:: tag. generate a hash hexstring for use as filename, HelpSource/formulas/xxxxxxxx.png
 124 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?)
 125
 126 * comments (* like this? *)
 127
 128 * shortcuts for links to method in class? mlink::Node-set:: -> link::Classes/Node#-set::
 129 or clink::Node#-set:: -> link::Classes/Node#-set:: ?
 130
 131 * render binary op methods differently? like ArrayedCollections ++
 132 we don't want it to display as "++ (aCollection)" do we? rather "++ aCollection" or "this ++ that" or something..
 133 binary ops only uses chars from this list: !@%&*-+=|<>?/
 134