Add support for including text from other files into code blocks. (#277)

Also strip out carriage-returns, as it messes with code block rendering.

Author: bluegate010

build.sh

@@ -789,6 +789,7 @@ do_latex() {
 		--lua-filter=convert-diagrams.lua
 		--lua-filter=convert-images.lua
 		--lua-filter=center-images.lua
+		--lua-filter=include-into-code-blocks.lua
 		--lua-filter=informative-sections.lua
 		--lua-filter=parse-html.lua
 		--lua-filter=apply-classes-to-tables.lua
@@ -984,6 +985,7 @@ do_docx() {
 		--standalone
 		--lua-filter=convert-diagrams.lua
 		--lua-filter=convert-images.lua
+		--lua-filter=include-into-code-blocks.lua
 		--lua-filter=parse-html.lua
 		--lua-filter=apply-classes-to-tables.lua
 		--lua-filter=landscape-pages.lua
@@ -1025,6 +1027,7 @@ do_html() {
 		--standalone
 		${HTML_ARGS}
 		--lua-filter=convert-diagrams.lua
+		--lua-filter=include-into-code-blocks.lua
 		--lua-filter=parse-html.lua
 		--lua-filter=apply-classes-to-tables.lua
 		--lua-filter=landscape-pages.lua

filter/divide-code-blocks.lua

@@ -28,6 +28,8 @@ function CodeBlock(block)
     -- all code blocks are rendered consistently.
     table.insert(block.classes, "_placeholder")
 
+    block.text = block.text:gsub("\r", "") -- Remove carriage-returns.
+
     font = class_spec["font"]
     return {
         pandoc.RawInline('latex', string.format([[

filter/include-into-code-blocks.lua

@@ -0,0 +1,26 @@
+-- Allow code blocks to include code from other files.
+
+-- Patch the path to include the current script's directory.
+package.path = package.path .. ";" .. debug.getinfo(1).source:match("@?(.*/)") .. "?.lua"
+utils = require "utils"
+
+function resolveIncludes(text)
+    -- A hack to make the regex below work, since gsub can't match `^ | \n`
+    if text:match("^!include ") then
+        text = "\n" .. text
+    end
+
+    return text:gsub("\n(!include )(%C+)", function(_, include_path)
+        return utils.readFile(include_path)
+    end)
+end
+
+function CodeBlock(el)
+    for i, class in ipairs(el.classes) do
+        if class == 'include' then
+            return pandoc.CodeBlock(resolveIncludes(el.text), el.attr)
+        end
+    end
+
+    return el
+end

guide.tcg

@@ -574,6 +574,23 @@ auctor lorem, ultricies vehicula orci aliquam sed. Praesent interdum leo metus,
 ut rhoncus sem consequat a.
 ```
 
+Code blocks can also include content from other files.
+
+````md
+```include {.small}
+!include sample-text.inc
+```
+````
+
+The result looks like this:
+
+```include {.small}
+!include sample-text.inc
+```
+
+An `include` block can contain multiple `!include` directives. Paths are resolved
+relative to the directory in which the build occurs.
+
 ## Footnotes {#sec:footnotes}
 
 ```md

sample-text.inc

@@ -0,0 +1,3 @@
+This file now can
+be included verbatim
+into the source spec.