[doctools] New 'chapter-links-' mechanism

Replaces {osh,oil}-help-topics

doc/osh-help-topics.md

@@ -41,7 +41,7 @@ feature is **unimplemented**.
   Overview (<a class="group-link" href="osh-help.html#overview">overview</a>)
 </h2>
 
-```osh-help-topics
+```chapter-links-osh
   [Usage]         osh-usage   config   startup   line-editing   prompt
   [Lexing]        comment #   line-continuation \
 ```
@@ -50,7 +50,7 @@ feature is **unimplemented**.
   Command Language (<a class="group-link" href="osh-help.html#command-lang">command-lang</a>)
 </h2>
 
-```osh-help-topics
+```chapter-links-osh
   [Commands]      simple-command   semicolon ;
   [Conditional]   case   if   true   false   colon :
                   bang !   and &&   or ||   dbracket [[
@@ -69,7 +69,7 @@ feature is **unimplemented**.
   Assignments and Expressions (<a class="group-link" href="osh-help.html#assign">assign</a>)
 </h2>
 
-```osh-help-topics
+```chapter-links-osh
   [Literals]      sh-array      array=(a b c)   array[1]=B   "${a[@]}"
                   sh-assoc      assoc=(['a']=1 ['b']=2)   assoc['x']=b
   [Operators]     sh-assign     str='xyz'
@@ -82,7 +82,7 @@ feature is **unimplemented**.
   Word Language (<a class="group-link" href="osh-help.html#word-lang">word-lang</a>)
 </h2>
 
-```osh-help-topics
+```chapter-links-osh
   [Quotes]        quotes        'abc'  $'\n'  "$var"
   [Substitutions] com-sub       $(command)   `command`   @(split command)
                   var-sub       ${var}   $0   $9   
@@ -101,7 +101,7 @@ feature is **unimplemented**.
   Other Shell Sublanguages (<a class="group-link" href="osh-help.html#sublang">sublang</a>)
 </h2>
 
-```osh-help-topics
+```chapter-links-osh
   [Arithmetic]    arith-context Where legacy arithmetic is allowed
                   sh-numbers    0xFF  0755  etc.
                   sh-arith      1 + 2*3   a *= 2
@@ -126,7 +126,7 @@ feature is **unimplemented**.
   Builtin Commands (<a class="group-link" href="osh-help.html#builtins">builtins</a>)
 </h2>
 
-```osh-help-topics
+```chapter-links-osh
   [I/O]           read   echo   printf
                   readarray   mapfile
   [Run Code]      source .   eval   trap
@@ -148,7 +148,7 @@ X [Unsupported]   enable
   Shell Options (<a class="group-link" href="osh-help.html#option">option</a>)
 </h2>
 
-```osh-help-topics
+```chapter-links-osh
   [Errors]        nounset   pipefail   errexit   inherit_errexit
   [Globbing]      noglob   nullglob   failglob   dashglob
   [Debugging]     xtrace   X verbose   X extdebug
@@ -160,7 +160,7 @@ X [Unsupported]   enable
   Environment Variables (<a class="group-link" href="osh-help.html#env">env</a>)
 </h2>
 
-```osh-help-topics
+```chapter-links-osh
   [Shell Options] SHELLOPTS   X BASHOPTS
   [Other Env]     HOME   PATH
 ```
@@ -170,7 +170,7 @@ X [Unsupported]   enable
   Special Variables (<a class="group-link" href="osh-help.html#special">special</a>)
 </h2>
 
-```osh-help-topics
+```chapter-links-osh
   [POSIX Special] $@  $*  $#     $?  $-     $$  $!   $0  $9
   [Other Special] BASH_REMATCH   @PIPESTATUS
   [Platform]      HOSTNAME   OSTYPE
@@ -195,7 +195,7 @@ X [Shell State]   BASH_CMDS   @DIRSTACK
   Plugins and Hooks (<a class="group-link" href="osh-help.html#plugin">plugin</a>)
 </h2>
 
-```osh-help-topics
+```chapter-links-osh
   [Signals]       SIGTERM   X SIGINT   X SIGABRT   SIG...
   [Traps]         EXIT   X ERR   X DEBUG   X RETURN
   [Words]         PS1   X PS2   X PS3   PS4

doc/ref/osh.txt

@@ -13,3 +13,6 @@ Chapters:
     special
     plugin
 
+To see topics in a chapter:
+
+    help osh-$chapter

doc/ref/ysh.txt

@@ -11,3 +11,7 @@ Chapters:
     env
     special
     lib
+
+To see topics in a chapter:
+
+    help ysh-$chapter

doc/ysh-help-topics.md

@@ -29,7 +29,7 @@ feature is **unimplemented**.
   Overview (<a class="group-link" href="ysh-help.html#overview">overview</a>)
 </h2>
 
-```oil-help-topics
+```chapter-links-ysh
   [Usage]         bundle-usage   ysh-usage
   [Oil Lexing]    docstring ###   multiline-command ...
 ```
@@ -38,7 +38,7 @@ feature is **unimplemented**.
   Command Language (<a class="group-link" href="ysh-help.html#command-lang">command-lang</a>)
 </h2>
 
-```oil-help-topics
+```chapter-links-ysh
                   proc-def      proc p (x, out Ref, @rest, e Expr, b Block) { c }
                   X func-def    func f(x; opt1, opt2) { return (x + 1) }
                   X ysh-return  return (myexpr)
@@ -56,7 +56,7 @@ feature is **unimplemented**.
   Expression Language and Assignments (<a class="group-link" href="ysh-help.html#expr-lang">expr-lang</a>)
 </h2>
 
-```oil-help-topics
+```chapter-links-ysh
   [Keywords]      const   var   setvar   setglobal   setref
   [Literals]      bool-literal  true   false   null
                   int-literal   42  65_536  0xFF  0o755  0b10
@@ -99,7 +99,7 @@ feature is **unimplemented**.
   Word Language (<a class="group-link" href="ysh-help.html#word-lang">word-lang</a>)
 </h2>
 
-```oil-help-topics
+```chapter-links-ysh
                   expr-sub      echo $[42 + a[i]]
                   expr-splice   echo @[split(x)]
                   var-splice    @myarray @ARGV
@@ -113,7 +113,7 @@ feature is **unimplemented**.
   Builtin Commands (<a class="group-link" href="ysh-help.html#builtins">builtins</a>)
 </h2>
 
-```oil-help-topics
+```chapter-links-ysh
   [Memory]        append                 Add elements to end of array
                   X argparse             getopts replacement, sets OPT
                   X setref               Builtin to replac ekeyword
@@ -155,7 +155,7 @@ X [External Lang] BEGIN   END   when (awk)
   Shell Options (<a class="group-link" href="ysh-help.html#option">option</a>)
 </h2>
 
-```oil-help-topics
+```chapter-links-ysh
   [Option Groups] strict:all   ysh:upgrade   ysh:all
   [Strictness]    ... More Runtime Errors
                   strict_argv            No empty argv
@@ -218,15 +218,15 @@ X [External Lang] BEGIN   END   when (awk)
   Environment Variables (<a class="group-link" href="ysh-help.html#env">env</a>)
 </h2>
 
-```oil-help-topics
+```chapter-links-ysh
   [Oil Paths]     ?builtins   ?completion_plugins   ?coprocesses
 ```
 
 <h2 id="special">
   Special Variables (<a class="group-link" href="ysh-help.html#special">special</a>)
 </h2>
 
-```oil-help-topics
+```chapter-links-ysh
   [History]       YSH_HISTFILE
   [Shell Vars]    ARGV   X ENV   X OPT
                   X _ESCAPE   _DIALECT
@@ -246,14 +246,14 @@ X [Types]         Null   Bool   Int   Float   Str   List   Dict
 
 Access silently mutated globals:
 
-```oil-help-topics
+```chapter-links-ysh
   [Pattern]       _match()   X _start()   X _end()
 X [Wok]           _field()
 ```
 
 Functions and Methods:
 
-```oil-help-topics
+```chapter-links-ysh
   [Collections]   len()
 X [String]        find(eggex)   replace(eggex, template)   join() 
                   split()             $IFS, awk algorithm, regex

doctools/cmark.py

@@ -271,26 +271,32 @@ def _ApplyInsertions(lines, insertions, out_file):
 
 
 def Render(opts, meta, in_file, out_file, use_fastlex=True):
+
+  # First convert to HTML
   html = md2html(in_file.read())
 
+  # Now process HTML with oil_doc
   if use_fastlex:
     # Note: extract code BEFORE doing the HTML highlighting.
     if opts.code_block_output:
       with open(opts.code_block_output, 'w') as f:
-        f.write('# %s: code blocks extracted from Markdown/HTML\n\n' % opts.code_block_output)
+        f.write('# %s: code blocks extracted from Markdown/HTML\n\n' %
+                opts.code_block_output)
         text = oil_doc.ExtractCode(html, f)
 
     html = oil_doc.RemoveComments(html)
 
-    # Hack for allowing tables without <p> in cells, which CommonMark seems to require?
+    # Hack for allowing tables without <p> in cells, which CommonMark seems to
+    # require?
     html = html.replace('<p><pstrip>', '')
     html = html.replace('</pstrip></p>', '')
 
-    # Stages of transformation.
+    # Expand $xref, etc.
     html = oil_doc.ExpandLinks(html)
 
-    if 1:
-      html = oil_doc.HighlightCode(html, meta.get('default_highlighter'))
+    # <code> blocks
+    # Including class=language-oil-help-topics
+    html = oil_doc.HighlightCode(html, meta.get('default_highlighter'))
 
   # h2 is the title.  h1 is unused.
   if opts.toc_tags:
@@ -310,7 +316,8 @@ def Render(opts, meta, in_file, out_file, use_fastlex=True):
     out_file.write(html)  # Pass through
     return
 
-  insertions = _MakeTocAndAnchors(opts, toc_tags, parser.headings, parser.toc_begin_line)
+  insertions = _MakeTocAndAnchors(opts, toc_tags, parser.headings,
+                                  parser.toc_begin_line)
 
   log('')
   log('*** Text Insertions:')
@@ -386,3 +393,5 @@ def main(argv):
 
 if __name__ == '__main__':
   main(sys.argv)
+
+# vim: sw=2

doctools/make_help.py

@@ -87,7 +87,7 @@ def _StringToHref(s):
 
 X_LEFT_SPAN = '<span style="color: darkred">'
 
-def HighlightLine(lang, line):
+def HighlightLine(chapter, line):
   """Convert a line of text to HTML.
 
   Topics are highlighted and X made red.
@@ -119,7 +119,7 @@ def HighlightLine(lang, line):
     href = _StringToHref(m.group(1))
 
     out.PrintUntil(m.start(1))
-    out.Print('<a href="%s-help.html#%s" class="level2">' % (lang, href))
+    out.Print('<a href="%s-help.html#%s" class="level2">' % (chapter, href))
     out.PrintUntil(m.end(1))  # anchor
     out.Print('</a>')
 
@@ -148,7 +148,7 @@ def HighlightLine(lang, line):
     topic = m.group(2)
 
     out.PrintUntil(m.start(2))
-    out.Print('<a href="%s-help.html#%s">' % (lang, topic))
+    out.Print('<a href="%s-help.html#%s">' % (chapter, topic))
     out.PrintUntil(m.end(2))
     out.Print('</a>')
 
@@ -346,8 +346,7 @@ def HelpTopics(s):
         # Now find the <code></code> span
         _, code_start_right = html.ReadUntilStartTag(it, tag_lexer, 'code')
         css_class = tag_lexer.GetAttr('class') 
-        assert css_class in ('language-oil-help-topics',
-                             'language-osh-help-topics'), tag_lexer.TagString()
+        assert css_class.startswith('language-chapter-links-'), tag_lexer.TagString()
 
         code_end_left, _ = html.ReadUntilEndTag(it, tag_lexer, 'code')
 

doctools/oil_doc.py

@@ -262,9 +262,9 @@ class HelpTopicsPlugin(_Plugin):
   """
   Highlight blocks of help-index.md.
   """
-  def __init__(self, s, start_pos, end_pos, lang):
+  def __init__(self, s, start_pos, end_pos, chapter):
     _Plugin.__init__(self, s, start_pos, end_pos)
-    self.lang = lang
+    self.chapter = chapter
 
   def PrintHighlighted(self, out):
     from doctools import make_help
@@ -275,7 +275,7 @@ def PrintHighlighted(self, out):
       # add tags and leave everything alone.
       line = self.s[pos : line_end]
 
-      html_line = make_help.HighlightLine(self.lang, line)
+      html_line = make_help.HighlightLine(self.chapter, line)
 
       if html_line is not None:
         out.PrintUntil(pos)
@@ -438,20 +438,15 @@ def HighlightCode(s, default_highlighter):
               # TODO: Write an Oil syntax highlighter.
               pass
 
-            elif css_class == 'language-osh-help-topics':
-              # TODO: Link to osh-help.html, instead of oil-help.html
-              out.PrintUntil(code_start_pos)
-
-              plugin = HelpTopicsPlugin(s, code_start_pos, slash_code_left, 'osh')
-              plugin.PrintHighlighted(out)
-
-              out.SkipTo(slash_code_left)
-
-            elif css_class == 'language-oil-help-topics':
+            elif css_class.startswith('language-chapter-links-'):
+              n = len('language-chapter-links-')
+              chapter = css_class[n:]
+              #log('chap %s', chapter)
 
+              # TODO: Link to osh-help.html, instead of oil-help.html
               out.PrintUntil(code_start_pos)
 
-              plugin = HelpTopicsPlugin(s, code_start_pos, slash_code_left, 'oil')
+              plugin = HelpTopicsPlugin(s, code_start_pos, slash_code_left, chapter)
               plugin.PrintHighlighted(out)
 
               out.SkipTo(slash_code_left)
@@ -616,3 +611,6 @@ def main(argv):
 
 if __name__ == '__main__':
   main(sys.argv)
+
+
+# vim: sw=2