Generate documentation by assembling markdown and litcoffee files

.gitignore

@@ -1,3 +1,4 @@
 node_modules
 site
+docbuild
 *~

doc/gendoc.litcoffee

@@ -0,0 +1,17 @@
+- The documentation will be generated by a coffeescript template (gendoc.litcoffee) which collates in the proper order several particular Markdown files, starting with README.md. The list of files includes all of the Literate Coffeescript files, with the actual code stripped out, leaving just the Markdown. The resulting dyna3.md file will be further processed into HTML and placed in the site directory.
+```javascript
+
+    fs = require 'fs'
+    striplit = (text) -> String(text).replace(/^```javascript[^]*?```\n/mg,'')
+    incfile = (fn, filt = null) ->
+        if (filt is null)
+            if (/litcoffee$/.test(fn)) then filt = striplit
+            else filt = (x)->x
+        process.stdout.write filt fs.readFileSync fn
+        process.stdout.write "\n"
+    incfile f for f in [
+        'README.md', 'src/dyna3.litcoffee',
+        'src/helpers/pkglock_to_externals.litcoffee', 'docbuild/extlist.md',
+        'doc/tech.md', 'doc/gendoc.litcoffee' ]
+
+```

doc/tech.md

@@ -2,17 +2,9 @@
 
 The intial modest outline for bootstrapping dyna3 is as follows:
 
-- dyna3 will be an npm project, but as it runs entirely client-side, there's no initial concern for being able to run under Node.js. However, npm will be useful as a dependency manager and build tool. In addition, helper scripts for the build can be run via node.
+- dyna3 will be an npm project, but as it runs entirely client-side, there's no initial concern for being able to run under Node.js. However, npm will be useful as a dependency manager and build tool. In addition, helper scripts for the build can be run with node (via coffee).
 - The package will build into a top-level site/ directory, which will contain all and only the files that must be on a server to deliver dyna3 to a client browser. Everything in site/ will generated from the package files; nothing in site/ will be committed to the repository. Right now the planned contents a of site/ are just a handful of top-level files, the modules/ directory for in-package javascript, the /doc directory for generated documentation, and a copy of the node_modules/ directory as a backup for the external dependencies.
 - Literate coffeescript modules (in the src/modules directory except for the top-level application) will compile into individual js modules in the site/modules directory (again, except for the top-level application)
 - Why coffeescript? The motivation for the javascript family of languages is wide deployability and availability of numerous libraries; the motivation for coffeescript is that it (still) reduces the amount of punctuation and extraneous characters from Javascript, resulting in better readability. And Literate coffeescript so that the manual and code are co-located.
-- The list of external modules will be harvested from npm, automatically generating a site/modules/externals.js from which specific external items can be imported into the local modules. Within externals.js, modules will be imported from the appropriate CDN, with a fallback to a copy in site/node_modules/ for when the CDN is off line.
 - All modules will use ES Modules syntax/format for imports.
 - index.html will be minimal, perhaps containing just a title, and maybe a link to generated documentation in the site/doc directory. All of the modules will create the DOM elements needed to display themselves on the fly.
-- The documentation will be generated by using an m4 master template to collate in the proper order several particular Markdown files, starting with the README and ending with this file, and all of the Literate coffeescript files, into a single site/doc/dyna3.md file. In the process, all of the actual source code of dyna3 will be stripped from the  literate coffeescript, leaving just the markdown.  The dyna3.md will be further processed into HTML for the site/doc directory.
-
-Specific packages/implementation approaches for components of dyna3 will include:
-
-- For WebGL rendering of the 3D view of the geometry, the three package from npm.
-
-- For test harness for the package: QUnit

package.json

@@ -5,13 +5,21 @@
   "private": "true",  
   "main": "dyna3.js",
   "scripts": {
-    "clean": "rm -r site",
+    "clean": "rm -rf site docbuild",
+    "doc:extra":
+      "mkdir -p docbuild && coffee src/helpers/pkglock_to_externals.litcoffee --doc > docbuild/extlist.md",
+    "doc:collate":
+      "mkdir -p site/doc && coffee doc/gendoc.litcoffee > site/doc/dyna3.md",
+    "doc": "npm run doc:extra && npm run doc:collate",
     "prebuild": "npm run clean",
     "build:coffee": "coffee -o site -c -m src/*.litcoffee",
     "build:ext":
       "coffee src/helpers/pkglock_to_externals.litcoffee > site/externals.js",
+    "build:doc":
+      "npm run doc && pandoc -s --toc site/doc/dyna3.md > site/doc/dyna3.html",
     "build:copy": "cp src/*.html site && cp -r node_modules site",
-    "build": "npm run build:coffee && npm run build:ext && npm run build:copy",
+    "build":
+      "npm run build:coffee && npm run build:ext && npm run build:doc && npm run build:copy",
     "test": "qunit"
   },
   "repository": {

src/helpers/pkglock_to_externals.litcoffee

@@ -1,19 +1,23 @@
+## Technical details
+
 ### External dependencies
 
-The dyna3 program depends on some externally-maintained JavaScript
+The dyna3 program depends on some externally-maintained JavaScript libraries/modules. The package uses npm to track these external dependencies. A module externals.js is automatically generated from the package_lock.json file created by npm to load the necessary modules at runtime.
-libraries/modules. The package uses npm to track these external dependencies.
+
-A module externals.js is automatically generated from the package_lock.json file
+The generation is performed by pkglock_to_externals.litcoffee, which also records the main importable file within the library, as there does not seem to be a systematic way to generate that filename from the module name.
-created by npm to load the necessary modules at runtime.
+
+Specific packages/implementation approaches for components of dyna3 include the following items. All packages are obtained from npm unless otherwise noted.
+
+- for conversion of markdown to HTML: pandoc
+- For a test harness for the package: QUnit
+- For WebGL rendering of the 3D view of the geometry: three
 
-The generation is performed by pkglock_to_externals.litcoffee, which also
-records the main importable file within the library, as there does not seem
-to be a systematic way to generate that filename from the module name.
 ```javascript
 
     importable = { three: 'build/three.module.js' }
 
 ```
-Currently, dyna3 makes use of the following external libraries:
+And here is the current complete list of external libraries on which operation of dyna3 depends:
 ```javascript
 
     if process.argv.length < 3
@@ -31,7 +35,7 @@ Currently, dyna3 makes use of the following external libraries:
     pdata = JSON.parse pl
     for dep in Object.keys pdata.dependencies
         if process.argv.length > 2
-            process.stdout.write "* #{dep}\n"
+            process.stdout.write "- #{dep}\n"
         else
             block =
             """