HelpSource/Classes/SCDocHTMLRenderer.schelp

   1 class:: SCDocHTMLRenderer
   2 summary:: Render SCDoc markup text to HTML
   3 categories:: HelpSystem
   4 related:: Classes/SCDoc, Classes/SCDocParser, Guides/WritingHelp, Reference/SCDocSyntax
   5
   6 description::
   7 This class is part of the SCDoc help system, and handles the rendering of the parsed document tree into HTML output.
   8
   9 In normal cases you won't need to use this class directly, link::Classes/SCDoc:: uses this class to parse and render all help files.
  10
  11 classmethods::
  12 method::new
  13 Create a renderer instance.
  14
  15 method::enableClassLinksInCode
  16 Set this to false to disable generation of hypertext links for class names in example code.
  17
  18 method::simplifyName
  19 Simplify a textstring by replacing spaces with underscores and making it all lowercase. Used to convert section names to anchor names.
  20 argument::txt
  21 The textstring to simplify.
  22 returns:: the simplified string.
  23
  24 method:: checkBrokenLinks
  25 Scans the entire help tree for broken links
  26
  27 method:: makeArgString
  28 Used internally.
  29 Returns:: A link::Classes/String:: representing the arguments (with defaults) for a link::Classes/Method::.
  30
  31 instancemethods::
  32
  33 private:: addUndocumentedMethods, renderFootNotes, renderTOC, escapeSpecialChars, renderHTMLSubTree, renderHTMLHeader, autoLinkClasses, renderClassTree
  34
  35 method:: render
  36 Render the tree contained in the code::parser:: instance variable to HTML file.
  37 argument:: p
  38 An instance of link::Classes/SCDocParser:: holding a parsed document tree in code::.root::, which are to be rendered.
  39 argument:: filename
  40 The full path for the output filename.
  41 argument:: folder
  42 The directory part relative to the base directory of the help directory tree, like "Classes" or "Reference". This is used as a simple organization for document "kind".
  43 argument:: toc
  44 if true, create a table-of-contents.
  45
  46 method:: findHelpFile
  47 returns:: the URL for help on given string
  48 discussion::
  49 If the string is empty or nil, return the home help page URL. If string is a class, return the URL for the helpfile for that class. If the string starts with uppercase but is not an existing class, then the Search page with this string. If the string starts with lowercase, then the Methods page for this method. (This page will redirect to Search if the method was not found)
  50
  51 section:: CSS styling
  52 The rendered HTML reads the global style from teletype::scdoc.css::, but also reads teletype::frontend.css:: and teletype::custom.css:: (in that order) if available, to enable specific frontends and users to override the CSS.
  53
  54 So to customise the CSS, the user can create a teletype::custom.css:: in their link::Classes/SCDoc#*helpTargetDir:: or at the root of any HelpSource directory (for example in teletype::YourExtension/HelpSource/custom.css:: ).
  55
  56 examples::
  57 code::
  58 p = SCDocParser.new;
  59 r = SCDocHTMLRenderer.new;
  60
  61 p.parseFile("/path/to/HelpSource/Classes/Array.schelp");
  62 r.render(p,"/path/to/Help/Classes/Array.html","Classes");
  63 ::
  64