Docs use static markdown translation.

chrisant996 · chrisant996 · commit d5b39caf7a1a · 2020-10-17T10:31:32.000-07:00
Building the documentation now does compile time translation from
markdown to HTML, rather than dynamic translation of hidden content via
script after loading the page.

That takes a dependency on npm, and it uses the latest marked instead of
one contained in this repo.  I'd rather not have either of those
dependencies, but I can accept them in order to improve the outputed
documentation.
diff --git a/README.md b/README.md
@@ -42,13 +42,18 @@ Clink can be extended through its Lua API which allows easy creation context sen
 
 ### Building Clink
 
-Clink's uses [Premake](https://premake.github.io) to generate Visual Studio solutions or makefiles for MinGW. Note that Premake >= 5.0-alpha12 is required.
+Clink uses [Premake](https://premake.github.io) to generate Visual Studio solutions or makefiles for MinGW. Note that Premake >= 5.0-alpha12 is required.
 
 1. Cd to your clone of Clink.
 2. Run `premake5.exe <toolchain>` (where `<toolchain>` is one of Premake's actions - see `premake5.exe --help`)
 3. Build scripts will be generated in `.build\<toolchain>`. For example `.build\vs2013\clink.sln`.
 4. Call your toolchain of choice (VS, mingw32-make.exe, msbuild.exe, etc). GNU makefiles (Premake's *gmake* target) have a **help** target for more info.
 
+### Building Documentation
+
+1. Run `npm install marked` to install the [marked](https://marked.js.org) markdown library.
+2. Run `premake5.exe docs`.
+
 ### License
 
 Clink is distributed under the terms of the GNU General Public License v3.0.
diff --git a/TODO.md b/TODO.md
@@ -46,6 +46,7 @@ Lua support changed significantly.  Explore how to support backward compatibilit
 - What to do about completion colors in popup list?
   - Make it owner draw and add text like "dir", "doskey", etc?
   - Add stat chars when so configured?
+- Use `npm` to run `marked.min.js` at compile time to produce static documentation rather than dynamic scripted documentation with embedded copies of marked.min.js and highlight.js.
 
 ## Questions
 - What is `set-mark`?
diff --git a/docs/clink.html b/docs/clink.html
@@ -9,21 +9,10 @@
     $(INCLUDE docs/atom-one-light.css)
 </style>
 <script type="text/javascript">
-    $(INCLUDE docs/marked.min.js)
     $(INCLUDE docs/highlight.pack.js)
 
     function go()
     {
-        // Convert markdown to HTML.
-        var content = document.getElementById("content");
-        var mds = document.getElementsByTagName("md");
-        for (var i = 0; i < mds.length; ++i)
-        {
-            var md = mds[i];
-            var div = document.getElementById(md.getAttribute("fill_id"));
-            div.innerHTML = marked(md.innerText);
-        }
-
         // Generate a table of contents from h* tags.
         var toc = document.getElementById("toc");
         toc.innerHTML = "";
@@ -70,23 +59,19 @@
     </div>
     <div id="toc"></div>
     <div id="content">
-        <div class="section" id="documentation"></div>
+        <div class="section" id="documentation">
+            $(MARKDOWN docs/clink.md)
+        </div>
         <h1 id="lua-api">Lua API Reference</h1>
         <div class="section" id="api">
             $(INCLUDE .build/docs/api_html)
         </div>
-        <div class="section" id="changes"></div>
-        <div class="section" id="credits"></div>
-        <!-- All md tags must come last, otherwise they interfere with each other -->
-        <md fill_id="credits" style="display: none;">
-            $(INCLUDE docs/credits.md)
-        </md>
-        <md fill_id="documentation" style="display: none;">
-            $(INCLUDE docs/clink.md)
-        </md>
-        <md fill_id="changes" style="display: none;">
-            $(INCLUDE CHANGES)
-        </md>
+        <div class="section" id="changes">
+            $(MARKDOWN CHANGES)
+        </div>
+        <div class="section" id="credits">
+            $(MARKDOWN docs/credits.md)
+        </div>
     </div>
 </body>
 
diff --git a/docs/premake5.lua b/docs/premake5.lua
@@ -1,6 +1,19 @@
 -- Copyright (c) 2012 Martin Ridgers
 -- License: https://opensource.org/licenses/MIT
 
+--------------------------------------------------------------------------------
+local function markdown_file(source_path, out)
+    print("  << " .. source_path)
+
+    local out_file = '.build\\docs\\'..source_path:match('([^/\\]+)$')..'.html'
+    os.execute('marked -o '..out_file..' < '..source_path)
+
+    local line_reader = io.lines(out_file)
+    for line in line_reader do
+        out:write(line .. "\n")
+    end
+end
+
 --------------------------------------------------------------------------------
 local function generate_file(source_path, out)
     print("  << " .. source_path)
@@ -9,10 +22,15 @@ local function generate_file(source_path, out)
         if include then
             generate_file(include, out)
         else
-            line = line:gsub("%$%(CLINK_VERSION%)", clink_git_name:upper())
-            line = line:gsub("<(/?kbd)>", "&lt;%1&gt;")
-            line = line:gsub("<br>", "&lt;br&gt;")
-            out:write(line .. "\n")
+            local md = line:match("%$%(MARKDOWN +([^)]+)%)")
+            if md then
+                markdown_file(md, out)
+            else
+                line = line:gsub("%$%(CLINK_VERSION%)", clink_git_name:upper())
+                line = line:gsub("<(/?kbd)>", "&lt;%1&gt;")
+                line = line:gsub("<br>", "&lt;br&gt;")
+                out:write(line .. "\n")
+            end
         end
     end
 end
