[doc] Move help text to ref/chap-front-end.md

Add CSS color to show the difference between OSH and YSH help topics.
oilshell · Aug 5, 2023 · bf37374 · bf37374
1 parent 0db73c1
commit bf37374
Show file tree

Hide file tree

Showing 11 changed files with 175 additions and 143 deletions.
diff --git a/build/doc.sh b/build/doc.sh
@@ -444,6 +444,9 @@ all-help() {
   cp -v doc/ref/osh.txt $TEXT_DIR/osh
   cp -v doc/ref/ysh.txt $TEXT_DIR/ysh
 
+  all-ref
+
+
   # Better sorting
   #LANG=C ls -l $TEXT_DIR
 }

diff --git a/doc/osh-help-topics.md b/doc/osh-help-topics.md
@@ -37,11 +37,11 @@ feature is **unimplemented**.
 
 &nbsp;
 
-<h2 id="overview">
-  Overview (<a class="group-link" href="osh-help.html#overview">overview</a>)
+<h2 id="front-end">
+  Front End (<a class="group-link" href="ref/chap-front-end.html">front-end</a>)
 </h2>
 
-```chapter-links-osh
+```chapter-links-front-end
   [Usage]         osh-usage   config   startup   line-editing   prompt
   [Lexing]        comment #   line-continuation \
 ```

diff --git a/doc/osh-help.md b/doc/osh-help.md
@@ -21,70 +21,6 @@ It generates both HTML and text for the 'help' builtin.
 <div id="toc">
 </div>
 
-<h2 id="overview">Overview</h2>
-
-### Usage
-
-<h4 id="osh-usage"><code>bin/osh</code> Usage</h4>
-
-    Usage: osh [OPTION]... SCRIPT [ARG]...
-           osh [OPTION]... -c COMMAND [ARG]...
-
-The command line accepted by `bin/osh` is compatible with `/bin/sh` and `bash`.
-
-    osh -c 'echo hi'
-    osh myscript.sh
-    echo 'echo hi' | osh
-
-It also has a few enhancements:
-
-    osh -n -c 'hello'                    # pretty-print the AST
-    osh --ast-format text -n -c 'hello'  # print it full
-
-osh accepts POSIX sh flags, with these additions:
-
-  -n             parse the program but don't execute it.  Print the AST.
-  --ast-format   what format the AST should be in
-
-<h4 id="config">Configuring the Shell</h4>
-
-If the --rcfile flag is specified, that file will be executed on startup.
-Otherwise:
-
-- `bin/osh` runs `~/.config/oils/oshrc`
-- `bin/ysh` runs `~/.config/oils/yshrc`
-
-Pass --rcfile /dev/null or --norc to disable the startup file.
-
-If the --rcdir flag is specified, files in that folder will be executed on
-startup.
-Otherwise:
-
-- `bin/osh` runs everything in `~/.config/oils/oshrc.d/`
-- `bin/ysh` runs everything in `~/.config/oils/yshrc.d/`
-
-Pass --norc to disable the startup directory.
-
-<h4 id="startup">Startup Files</h4>
-
-History is read?
-
-### Lexing
-
-#### comment
-
-A comment starts with `#` and goes until the end of the line.
-
-    echo hi  # print a greeting
-
-#### line-continuation
-
-A backslash `\` at the end of a line continues the line without executing it:
-
-    ls /usr/bin \
-       /usr/lib \
-       ~/src        # A single command split over three lines
-
 <h2 id="command-lang">Command Language</h2>
 
 ### Commands

diff --git a/doc/ref/y-notation.md → doc/ref/chap-data-lang.md b/doc/ref/y-notation.md → doc/ref/chap-data-lang.md
diff --git a/doc/ref/chap-front-end.md b/doc/ref/chap-front-end.md
@@ -0,0 +1,137 @@
+---
+in_progress: yes
+css_files: ../../web/base.css ../../web/manual.css ../../web/help.css ../../web/toc.css
+body_css_class: width40 help-body
+default_highlighter: oil-sh
+---
+
+Oils Reference: Front End
+===
+
+<div id="toc">
+</div>
+
+## Usage
+
+<h3 id="bundle-usage" class="osh-ysh-topic">App Bundle Usage</h3>
+
+    Usage: oils-for-unix MAIN_NAME [ARG]...
+           MAIN_NAME [ARG]...
+
+oils-for-unix behaves like busybox.  If it's invoked through a symlink, e.g. 'osh',
+then it behaves like that binary.  Otherwise, the binary name can be passed as
+the first argument, e.g.:
+
+    oils-for-unix osh -c 'echo hi'
+
+<h3 id="osh-usage" class="osh-topic"><code>bin/osh</code> Usage</h3>
+
+    Usage: osh [OPTION]... SCRIPT [ARG]...
+           osh [OPTION]... -c COMMAND [ARG]...
+
+The command line accepted by `bin/osh` is compatible with `/bin/sh` and `bash`.
+
+    osh -c 'echo hi'
+    osh myscript.sh
+    echo 'echo hi' | osh
+
+It also has a few enhancements:
+
+    osh -n -c 'hello'                    # pretty-print the AST
+    osh --ast-format text -n -c 'hello'  # print it full
+
+osh accepts POSIX sh flags, with these additions:
+
+  -n             parse the program but don't execute it.  Print the AST.
+  --ast-format   what format the AST should be in
+
+<h3 id="ysh-usage" class="ysh-topic"><code>bin/ysh</code> Usage</h3>
+
+    Usage: ysh [OPTION]... SCRIPT [ARG]...
+           ysh [OPTION]... -c COMMAND [ARG]...
+
+`bin/ysh` is the same as `bin/osh` with a the `ysh:all` option group set.  So
+`bin/ysh` also accepts shell flags.
+
+    ysh -c 'echo hi'
+    ysh myscript.ysh
+    echo 'echo hi' | ysh
+
+
+<h3 id="config" class="osh-ysh-topic">Configuring the Shell</h3>
+
+If the --rcfile flag is specified, that file will be executed on startup.
+Otherwise:
+
+- `bin/osh` runs `~/.config/oils/oshrc`
+- `bin/ysh` runs `~/.config/oils/yshrc`
+
+Pass --rcfile /dev/null or --norc to disable the startup file.
+
+If the --rcdir flag is specified, files in that folder will be executed on
+startup.
+Otherwise:
+
+- `bin/osh` runs everything in `~/.config/oils/oshrc.d/`
+- `bin/ysh` runs everything in `~/.config/oils/yshrc.d/`
+
+Pass --norc to disable the startup directory.
+
+<h3 id="startup" class="osh-ysh-topic">Startup Files</h3>
+
+History is read?
+
+## Lexing
+
+<h3 id="comment" class="osh-ysh-topic">Comments</h3>
+
+A comment starts with `#` and goes until the end of the line.
+
+    echo hi  # print a greeting
+
+<h3 id="line-continuation" class="osh-ysh-topic">Line Continuation</h3>
+
+A backslash `\` at the end of a line continues the line without executing it:
+
+    ls /usr/bin \
+       /usr/lib \
+       ~/src        # A single command split over three lines
+
+<h3 id="doc-comment" class="ysh-topic">Doc Comments</h3>
+
+Doc comments look like this:
+
+    proc deploy {   
+      ### Deploy the app
+      echo hi
+    }
+
+<h3 id="multiline-command" class="ysh-topic">Multi-Line Command</h3>
+
+The ... prefix starts a single command over multiple lines.  It allows writing
+long commands without \ continuation lines, and the resulting limitations on
+where you can put comments.
+
+Single command example:
+
+    ... chromium-browser
+        # comment on its own line
+        --no-proxy-server
+        --incognito  # comment to the right
+        ;
+
+Long pipelines and and-or chains:
+
+    ... find .
+        # exclude tests
+      | grep -v '_test.py'
+      | xargs wc -l
+      | sort -n
+      ;
+
+    ... ls /
+     && ls /bin
+     && ls /lib
+     || error "oops"
+     ;
+
diff --git a/doc/ysh-help-topics.md b/doc/ysh-help-topics.md
@@ -29,9 +29,9 @@ feature is **unimplemented**.
   Overview (<a class="group-link" href="ysh-help.html#overview">overview</a>)
 </h2>
 
-```chapter-links-ysh
+```chapter-links-front-end
   [Usage]         bundle-usage   ysh-usage
-  [Oil Lexing]    docstring ###   multiline-command ...
+  [Oil Lexing]    doc-comment ###   multiline-command ...
 ```
 
 <h2 id="command-lang">

diff --git a/doc/ysh-help.md b/doc/ysh-help.md
@@ -21,75 +21,6 @@ It generates both HTML and text for the 'help' builtin.
 <div id="toc">
 </div>
 
-<h2 id="overview">Overview</h2>
-
-### Usage
-
-This section describes how to use the Oil binary.
-
-<h4 id="ysh-usage"><code>bin/ysh</code> Usage</h4>
-
-    Usage: ysh [OPTION]... SCRIPT [ARG]...
-           ysh [OPTION]... -c COMMAND [ARG]...
-
-`bin/ysh` is the same as `bin/osh` with a the `ysh:all` option group set.  So
-`bin/ysh` also accepts shell flags.
-
-    ysh -c 'echo hi'
-    ysh myscript.ysh
-    echo 'echo hi' | ysh
-
-<h4 id="bundle-usage">App Bundle Usage</h4>
-
-    Usage: oils-for-unix MAIN_NAME [ARG]...
-           MAIN_NAME [ARG]...
-
-oils-for-unix behaves like busybox.  If it's invoked through a symlink, e.g. 'osh',
-then it behaves like that binary.  Otherwise, the binary name can be passed as
-the first argument, e.g.:
-
-    oils-for-unix osh -c 'echo hi'
-
-<h3>Oil Lexing</h3>
-
-#### docstring
-
-Docstrings look like this:
-
-    proc deploy {   
-      ### Deploy the app
-      echo hi
-    }
-
-#### multiline-command
-
-The ... prefix starts a single command over multiple lines.  It allows writing
-long commands without \ continuation lines, and the resulting limitations on
-where you can put comments.
-
-Single command example:
-
-    ... chromium-browser
-        # comment on its own line
-        --no-proxy-server
-        --incognito  # comment to the right
-        ;
-
-Long pipelines and and-or chains:
-
-    ... find .
-        # exclude tests
-      | grep -v '_test.py'
-      | xargs wc -l
-      | sort -n
-      ;
-
-    ... ls /
-     && ls /bin
-     && ls /lib
-     || error "oops"
-     ;
-
 <h2 id="command">Command Language</h2>
 
 #### proc

diff --git a/doctools/make_help.py b/doctools/make_help.py
@@ -101,6 +101,11 @@ def HighlightLine(chapter, line):
   f = cStringIO.StringIO()
   out = html.Output(line, f)
 
+  if chapter in ('osh', 'ysh'):
+    html_page = '%s-help.html' % chapter
+  else:
+    html_page = 'ref/chap-%s.html' % chapter
+
   pos = 0 # position within line
 
   if line.startswith('X '):
@@ -119,7 +124,7 @@ def HighlightLine(chapter, line):
     href = _StringToHref(m.group(1))
 
     out.PrintUntil(m.start(1))
-    out.Print('<a href="%s-help.html#%s" class="level2">' % (chapter, href))
+    out.Print('<a href="%s#%s" class="level2">' % (html_page, href))
     out.PrintUntil(m.end(1))  # anchor
     out.Print('</a>')
 
@@ -148,7 +153,7 @@ def HighlightLine(chapter, line):
     topic = m.group(2)
 
     out.PrintUntil(m.start(2))
-    out.Print('<a href="%s-help.html#%s">' % (chapter, topic))
+    out.Print('<a href="%s#%s">' % (html_page, topic))
     out.PrintUntil(m.end(2))
     out.Print('</a>')
 

diff --git a/doctools/oil_doc.py b/doctools/oil_doc.py
@@ -443,7 +443,6 @@ def HighlightCode(s, default_highlighter):
               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, chapter)

diff --git a/web/help.css b/web/help.css
@@ -7,9 +7,13 @@
   font-size: 1em;
   /* margin-left: 2em; */
   padding: 1em; 
-  background-color: lavender;
+  /* background-color: lavender; */
+
+  color: black;  /* different than blog */
 }
 
+/* TODO: remove h4 */
+
 .help-body h4 {
   font-size: 1em;
 
@@ -19,3 +23,20 @@
 
   color: darkblue;  /* different than blog */
 }
+
+.osh-topic {
+  border-left: solid;
+  border-color: brown;
+}
+
+.osh-ysh-topic {
+  border-left: solid;
+  border-right: solid;
+  border-color: darkgreen;
+}
+
+.ysh-topic {
+  border-right: solid;
+  border-color: darkcyan;
+}
+