Better docs

Author: djha-skin

build-docs.ros

@@ -0,0 +1,26 @@
+#!/bin/sh
+#|-*- mode:lisp -*-|#
+#|
+exec ros -R +Q -- $0 "$@"
+|#
+(progn ;;init forms
+  (ros:ensure-asdf)
+  ;;; https://github.com/ocicl/ocicl.git
+  #-ocicl
+  (when (probe-file #P"./ocicl/ocicl-runtime.lisp")
+    (load #P"./ocicl/ocicl-runtime.lisp"))
+  (asdf:initialize-source-registry
+  `(:source-registry
+     :ignore-inherited-configuration
+     (:directory ,(uiop:getcwd))))
+  (asdf:load-system "codex")
+  )
+
+(defpackage :ros.script.build-docs.3943893088
+  (:use :cl))
+(in-package :ros.script.build-docs.3943893088)
+
+(defun main (&rest argv)
+  (declare (ignorable argv))
+  (codex:document "com.djha-skin.cliff"))
+;;; vim: set ft=lisp lisp:

docs/api-reference.html

@@ -42,7 +42,7 @@
   <h1 class="doc-title">CLIFF: Command Line Interface Functional Framework</h1>
   <article id="article" data-section="api-reference">
     <aside>
-      <ol class="toc"><li><a href="overview.html" data-node="overview">Overview</a></li><li><a href="tutorial.html" data-node="tutorial">Tutorial</a><ol><li><a href="tutorial.html#install" data-node="install">Install</a></li><li><a href="tutorial.html#up-and-running" data-node="up-and-running">Up and Running</a></li><li><a href="tutorial.html#open-world-configuration" data-node="open-world-configuration">Open World Configuration</a></li><li><a href="tutorial.html#the-option-tower" data-node="the-option-tower">The Option Tower</a></li><li><a href="tutorial.html#add-a-default-function" data-node="add-a-default-function">Add a Default Function</a></li><li><a href="tutorial.html#string-conversion" data-node="string-conversion">String Conversion</a></li><li><a href="tutorial.html#provide-command-line-aliases" data-node="provide-command-line-aliases">Provide Command-Line Aliases</a></li><li><a href="tutorial.html#override-default-output" data-node="override-default-output">Override Default Output</a></li><li><a href="tutorial.html#add-subcommands" data-node="add-subcommands">Add Subcommands</a></li><li><a href="tutorial.html#add-more-help-documentation" data-node="add-more-help-documentation">Add More Help Documentation</a></li><li><a href="tutorial.html#wrap-up" data-node="wrap-up">Wrap-up</a></li></ol></li><li><a href="api-reference.html" data-node="api-reference">API Reference</a><ol><li><a href="api-reference.html#com.djhaskin.cliff" data-node="com.djhaskin.cliff"><code>com.djhaskin.cliff</code></a><ol><li><a href="0-overview.html" data-node="0-overview">Overview</a></li><li><a href="the-options-tower.html" data-node="the-options-tower">The Options Tower</a><ol><li><a href="configuration-files.html" data-node="configuration-files">Configuration Files</a></li><li><a href="environment-variables.html" data-node="environment-variables">Environment Variables</a></li><li><a href="command-line-arguments.html" data-node="command-line-arguments">Command Line Arguments</a></li><li><a href="the-setup-function.html" data-node="the-setup-function">The Setup Function</a></li></ol></li><li><a href="determining-the-action-function.html" data-node="determining-the-action-function">Determining the Action Function</a></li><li><a href="the-help-page.html" data-node="the-help-page">The Help Page</a></li><li><a href="execution.html" data-node="execution">Execution</a></li><li><a href="error-handling.html" data-node="error-handling">Error Handling</a></li><li><a href="goals-and-discussion.html" data-node="goals-and-discussion">Goals and Discussion</a></li></ol></li><li><a href="api-reference.html#com.djhaskin.cliff-errors" data-node="com.djhaskin.cliff-errors"><code>com.djhaskin.cliff/errors</code></a></li></ol></li></ol>
+      <ol class="toc"><li><a href="overview.html" data-node="overview">Overview</a></li><li><a href="tutorial.html" data-node="tutorial">Tutorial</a><ol><li><a href="tutorial.html#install" data-node="install">Install</a></li><li><a href="tutorial.html#up-and-running" data-node="up-and-running">Up and Running</a></li><li><a href="tutorial.html#open-world-configuration" data-node="open-world-configuration">Open World Configuration</a></li><li><a href="tutorial.html#the-options-tower" data-node="the-options-tower">The Options Tower</a></li><li><a href="tutorial.html#add-a-default-function" data-node="add-a-default-function">Add a Default Function</a></li><li><a href="tutorial.html#string-conversion" data-node="string-conversion">String Conversion</a></li><li><a href="tutorial.html#provide-command-line-aliases" data-node="provide-command-line-aliases">Provide Command-Line Aliases</a></li><li><a href="tutorial.html#override-default-output" data-node="override-default-output">Override Default Output</a></li><li><a href="tutorial.html#add-subcommands" data-node="add-subcommands">Add Subcommands</a></li><li><a href="tutorial.html#add-more-help-documentation" data-node="add-more-help-documentation">Add More Help Documentation</a></li><li><a href="tutorial.html#wrap-up" data-node="wrap-up">Wrap-up</a></li></ol></li><li><a href="api-reference.html" data-node="api-reference">API Reference</a><ol><li><a href="api-reference.html#com.djhaskin.cliff" data-node="com.djhaskin.cliff"><code>com.djhaskin.cliff</code></a><ol><li><a href="0-overview.html" data-node="0-overview">Overview</a></li><li><a href="1-the-options-tower.html" data-node="1-the-options-tower">The Options Tower</a><ol><li><a href="configuration-files.html" data-node="configuration-files">Configuration Files</a></li><li><a href="environment-variables.html" data-node="environment-variables">Environment Variables</a></li><li><a href="command-line-arguments.html" data-node="command-line-arguments">Command Line Arguments</a></li><li><a href="the-setup-function.html" data-node="the-setup-function">The Setup Function</a></li></ol></li><li><a href="determining-the-action-function.html" data-node="determining-the-action-function">Determining the Action Function</a></li><li><a href="the-help-page.html" data-node="the-help-page">The Help Page</a></li><li><a href="execution.html" data-node="execution">Execution</a></li><li><a href="error-handling.html" data-node="error-handling">Error Handling</a></li><li><a href="discussion.html" data-node="discussion">Discussion</a></li></ol></li><li><a href="api-reference.html#com.djhaskin.cliff-errors" data-node="com.djhaskin.cliff-errors"><code>com.djhaskin.cliff/errors</code></a></li></ol></li></ol>
     </aside>
     <main class="codex-section">
       <header>
@@ -62,7 +62,7 @@ <h2 class="section-title">API Reference</h2>
   corresponding to the subcommand as given in <code class="codex-param">subcommand-functions</code>
   will be called. Expects that function to return a results map, with at least
   the <code>:status</code> key set to one of the values listed in the <code>*exit-codes*</code>
-  map.</p><p>  </p><p>  </p><h2 id="the-options-tower">The Options Tower</h2><p>  </p><h3 id="configuration-files">Configuration Files</h3><p>  The function first builds, in successive steps, the options table which will
+  map.</p><p>  </p><p>  </p><h2 id="1-the-options-tower">The Options Tower</h2><p>  </p><h3 id="configuration-files">Configuration Files</h3><p>  The function first builds, in successive steps, the options table which will
   be passed to the function in question.</p><p>  It starts with the options hash table given by the <code class="codex-param">defaults</code>
   parameter.</p><p>  The function next examines the given <code class="codex-param">environment-variables</code>,
   which should be given as an alist with keys as variable names and values as
@@ -196,7 +196,7 @@ <h2 class="section-title">API Reference</h2>
   <code class="codex-param">suppress-output</code> is given as <code>t</code>.</p><p>  <code>execute-program</code> then returns two values: the numeric exit code
   corresponding to the exit status computed as described above, and the newly
   constructed result map containing the error information.</p><p>  </p><p>
-  </p><h2 id="goals-and-discussion">Goals and Discussion</h2><p>  Command line tools necessarily need to do a lot of I/O. <code>execute-program</code>
+  </p><h2 id="discussion">Discussion</h2><p>  Command line tools necessarily need to do a lot of I/O. <code>execute-program</code>
   attempts to encapsulate much of this I/O while providing
   <a href="https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html">clean
   architecture</a> by default. Ideally, <code>execute-program</code> should enable an

docs/manual.scr

@@ -286,13 +286,12 @@ other programs.
 @end(section)
 
 @begin(section)
-@title(The Option Tower)
+@title(The Options Tower)
 
 CLIFF gathers options for the calling code tool (in this case @c(calc)) from
 configuration files, environment variables, and command-line flags. It merges
 what it finds from various sources into one single, nested hash table. The
-various sources comprise what we will call the Option Tower.
-
+various sources comprise what we will call the Options Tower.
 
 Let's add something from a configuration file now. CLIFF looks in the present
 working directory, as well as an OS-dependent, home-based location, which is

docs/overview.html

@@ -42,7 +42,7 @@
   <h1 class="doc-title">CLIFF: Command Line Interface Functional Framework</h1>
   <article id="article" data-section="overview">
     <aside>
-      <ol class="toc"><li><a href="overview.html" data-node="overview">Overview</a></li><li><a href="tutorial.html" data-node="tutorial">Tutorial</a><ol><li><a href="install.html" data-node="install">Install</a></li><li><a href="up-and-running.html" data-node="up-and-running">Up and Running</a></li><li><a href="open-world-configuration.html" data-node="open-world-configuration">Open World Configuration</a></li><li><a href="the-option-tower.html" data-node="the-option-tower">The Option Tower</a></li><li><a href="add-a-default-function.html" data-node="add-a-default-function">Add a Default Function</a></li><li><a href="string-conversion.html" data-node="string-conversion">String Conversion</a></li><li><a href="provide-command-line-aliases.html" data-node="provide-command-line-aliases">Provide Command-Line Aliases</a></li><li><a href="override-default-output.html" data-node="override-default-output">Override Default Output</a></li><li><a href="add-subcommands.html" data-node="add-subcommands">Add Subcommands</a></li><li><a href="add-more-help-documentation.html" data-node="add-more-help-documentation">Add More Help Documentation</a></li><li><a href="wrap-up.html" data-node="wrap-up">Wrap-up</a></li></ol></li><li><a href="api-reference.html" data-node="api-reference">API Reference</a><ol><li><a href="com.djhaskin.cliff.html" data-node="com.djhaskin.cliff"><code>com.djhaskin.cliff</code></a><ol><li><a href="0-overview.html" data-node="0-overview">Overview</a></li><li><a href="the-options-tower.html" data-node="the-options-tower">The Options Tower</a><ol><li><a href="configuration-files.html" data-node="configuration-files">Configuration Files</a></li><li><a href="environment-variables.html" data-node="environment-variables">Environment Variables</a></li><li><a href="command-line-arguments.html" data-node="command-line-arguments">Command Line Arguments</a></li><li><a href="the-setup-function.html" data-node="the-setup-function">The Setup Function</a></li></ol></li><li><a href="determining-the-action-function.html" data-node="determining-the-action-function">Determining the Action Function</a></li><li><a href="the-help-page.html" data-node="the-help-page">The Help Page</a></li><li><a href="execution.html" data-node="execution">Execution</a></li><li><a href="error-handling.html" data-node="error-handling">Error Handling</a></li><li><a href="goals-and-discussion.html" data-node="goals-and-discussion">Goals and Discussion</a></li></ol></li><li><a href="com.djhaskin.cliff-errors.html" data-node="com.djhaskin.cliff-errors"><code>com.djhaskin.cliff/errors</code></a></li></ol></li></ol>
+      <ol class="toc"><li><a href="overview.html" data-node="overview">Overview</a></li><li><a href="tutorial.html" data-node="tutorial">Tutorial</a><ol><li><a href="install.html" data-node="install">Install</a></li><li><a href="up-and-running.html" data-node="up-and-running">Up and Running</a></li><li><a href="open-world-configuration.html" data-node="open-world-configuration">Open World Configuration</a></li><li><a href="the-options-tower.html" data-node="the-options-tower">The Options Tower</a></li><li><a href="add-a-default-function.html" data-node="add-a-default-function">Add a Default Function</a></li><li><a href="string-conversion.html" data-node="string-conversion">String Conversion</a></li><li><a href="provide-command-line-aliases.html" data-node="provide-command-line-aliases">Provide Command-Line Aliases</a></li><li><a href="override-default-output.html" data-node="override-default-output">Override Default Output</a></li><li><a href="add-subcommands.html" data-node="add-subcommands">Add Subcommands</a></li><li><a href="add-more-help-documentation.html" data-node="add-more-help-documentation">Add More Help Documentation</a></li><li><a href="wrap-up.html" data-node="wrap-up">Wrap-up</a></li></ol></li><li><a href="api-reference.html" data-node="api-reference">API Reference</a><ol><li><a href="com.djhaskin.cliff.html" data-node="com.djhaskin.cliff"><code>com.djhaskin.cliff</code></a><ol><li><a href="0-overview.html" data-node="0-overview">Overview</a></li><li><a href="1-the-options-tower.html" data-node="1-the-options-tower">The Options Tower</a><ol><li><a href="configuration-files.html" data-node="configuration-files">Configuration Files</a></li><li><a href="environment-variables.html" data-node="environment-variables">Environment Variables</a></li><li><a href="command-line-arguments.html" data-node="command-line-arguments">Command Line Arguments</a></li><li><a href="the-setup-function.html" data-node="the-setup-function">The Setup Function</a></li></ol></li><li><a href="determining-the-action-function.html" data-node="determining-the-action-function">Determining the Action Function</a></li><li><a href="the-help-page.html" data-node="the-help-page">The Help Page</a></li><li><a href="execution.html" data-node="execution">Execution</a></li><li><a href="error-handling.html" data-node="error-handling">Error Handling</a></li><li><a href="discussion.html" data-node="discussion">Discussion</a></li></ol></li><li><a href="com.djhaskin.cliff-errors.html" data-node="com.djhaskin.cliff-errors"><code>com.djhaskin.cliff/errors</code></a></li></ol></li></ol>
     </aside>
     <main class="codex-section">
       <header>