include-files: add automatic shifting (#105)

Author: St-Ex

include-files/Makefile

@@ -3,8 +3,13 @@ DIFF ?= diff --strip-trailing-cr -u
 test: sample.md file-a.md file-b.md file-c.md include-files.lua
 	@pandoc --lua-filter=include-files.lua --to=native $< \
 	    | $(DIFF) expected.native -
+	@pandoc --lua-filter=include-files.lua -M include-auto --to=native $< \
+	    | $(DIFF) expected-auto.native -
 
 expected.native: sample.md file-a.md file-b.md file-c.md include-files.lua
 	pandoc --lua-filter=include-files.lua --output $@ $<
 
+expected-auto.native: sample.md file-a.md file-b.md file-c.md include-files.lua
+	pandoc --lua-filter=include-files.lua --output $@ $<
+
 .PHONY: test

include-files/README.md

@@ -16,8 +16,36 @@ Metadata from included files is discarded.
 The default is to include the subdocuments unchanged, but it can
 be convenient to modify the level of headers; a top-level header
 in an included file should be a second or third-level header in
-the final document. Use the `shift-heading-level-by` attribute to
-control header shifting.
+the final document.
+
+#### Manual shifting
+
+Use the `shift-heading-level-by` attribute to control header
+shifting.
+
+#### Automatic shifting
+
+1. Add metadata `-M include-auto` to enable automatic shifting.
+2. Do not specify `shift-heading-level-by`
+3. It will be inferred to the last heading level encountered
+
+_Example_ :
+
+````md
+# Title f
+
+This is `file-f.md`.
+
+## Subtitle f
+
+```{.include} >> equivalent to {.include shift-heading-level-by=2}
+file-a.md
+```
+
+```{.include shift-heading-level-by=1} >> force shift to be 1
+file-a.md
+```
+````
 
 ### Comments
 
@@ -37,7 +65,7 @@ Included files can in turn include other files. Note that all
 filenames must be relative to the directory from which pandoc is
 run. I.e., if a file `a/b.md` is included in the main document,
 and another file `a/b/c.md` should be included, the full relative
-path must be used. Writing `b/c.md` in `a/b.md` would *not* work.
+path must be used. Writing `b/c.md` in `a/b.md` would _not_ work.
 
 ## Example
 

include-files/expected-auto.native

@@ -0,0 +1,23 @@
+[Header 1 ("section-1",[],[]) [Str "Section",Space,Str "1"]
+,Para [Str "Thanks",Space,Str "everyone!"]
+,Header 2 ("title-of-file-a",[],[]) [Str "Title",Space,Str "of",Space,Str "file-a"]
+,Para [Str "This",Space,Str "is",Space,Code ("",[],[]) "file-a.md",Str "."]
+,Header 2 ("file-b",[],[]) [Str "File",Space,Str "b"]
+,Para [Str "This",Space,Str "is",Space,Code ("",[],[]) "file-b.md",Str "."]
+,Para [Str "It",Space,Str "has",Space,Str "two",Space,Str "paragraphs",Space,Str "and",Space,Str "a",Space,Str "header."]
+,Header 1 ("different-format",[],[]) [Str "Different",Space,Str "format"]
+,Header 2 ("org-header",[],[]) [Str "Org",Space,Str "header"]
+,Para [Str "This",Space,Str "is",Space,Emph [Str "emphasized"],Str "."]
+,Header 1 ("recursive-transclusion",[],[]) [Str "Recursive",Space,Str "transclusion"]
+,Header 2 ("title-f",[],[]) [Str "Title",Space,Str "f"]
+,Para [Str "This",Space,Str "is",Space,Code ("",[],[]) "file-f.md",Str "."]
+,Header 3 ("subtitle-f",[],[]) [Str "Subtitle",Space,Str "f"]
+,Header 4 ("title-of-file-a",[],[]) [Str "Title",Space,Str "of",Space,Str "file-a"]
+,Para [Str "This",Space,Str "is",Space,Code ("",[],[]) "file-a.md",Str "."]
+,Header 3 ("title-of-file-a",[],[]) [Str "Title",Space,Str "of",Space,Str "file-a"]
+,Para [Str "This",Space,Str "is",Space,Code ("",[],[]) "file-a.md",Str "."]
+,Header 1 ("appendix",[],[]) [Str "Appendix"]
+,Para [Str "More",Space,Str "info",Space,Str "goes",Space,Str "here."]
+,Header 2 ("questionaire",[],[]) [Str "Questionaire"]
+,BulletList
+ [[Plain [Str "Is",Space,Str "this",Space,Str "good?"]]]]

include-files/expected.native

@@ -1,5 +1,6 @@
 [Header 1 ("section-1",[],[]) [Str "Section",Space,Str "1"]
 ,Para [Str "Thanks",Space,Str "everyone!"]
+,Header 1 ("title-of-file-a",[],[]) [Str "Title",Space,Str "of",Space,Str "file-a"]
 ,Para [Str "This",Space,Str "is",Space,Code ("",[],[]) "file-a.md",Str "."]
 ,Header 1 ("file-b",[],[]) [Str "File",Space,Str "b"]
 ,Para [Str "This",Space,Str "is",Space,Code ("",[],[]) "file-b.md",Str "."]
@@ -8,7 +9,12 @@
 ,Header 2 ("org-header",[],[]) [Str "Org",Space,Str "header"]
 ,Para [Str "This",Space,Str "is",Space,Emph [Str "emphasized"],Str "."]
 ,Header 1 ("recursive-transclusion",[],[]) [Str "Recursive",Space,Str "transclusion"]
+,Header 1 ("title-f",[],[]) [Str "Title",Space,Str "f"]
 ,Para [Str "This",Space,Str "is",Space,Code ("",[],[]) "file-f.md",Str "."]
+,Header 2 ("subtitle-f",[],[]) [Str "Subtitle",Space,Str "f"]
+,Header 1 ("title-of-file-a",[],[]) [Str "Title",Space,Str "of",Space,Str "file-a"]
+,Para [Str "This",Space,Str "is",Space,Code ("",[],[]) "file-a.md",Str "."]
+,Header 2 ("title-of-file-a",[],[]) [Str "Title",Space,Str "of",Space,Str "file-a"]
 ,Para [Str "This",Space,Str "is",Space,Code ("",[],[]) "file-a.md",Str "."]
 ,Header 1 ("appendix",[],[]) [Str "Appendix"]
 ,Para [Str "More",Space,Str "info",Space,Str "goes",Space,Str "here."]

include-files/file-a.md

@@ -1 +1,3 @@
+# Title of file-a
+
 This is `file-a.md`.

include-files/file-f.md

@@ -1,5 +1,13 @@
+# Title f
+
 This is `file-f.md`.
 
-``` {.include}
+## Subtitle f
+
+```{.include}
+file-a.md
+```
+
+```{.include shift-heading-level-by=1}
 file-a.md
 ```

include-files/include-files.lua

@@ -6,6 +6,20 @@
 -- pandoc's List type
 local List = require 'pandoc.List'
 
+--- Get include auto mode
+local include_auto = false
+function get_vars (meta)
+  if meta['include-auto'] then
+    include_auto = true
+  end
+end
+
+--- Keep last heading level found
+local last_heading_level = 0
+function update_last_level(header)
+  last_heading_level = header.level
+end
+
 --- Shift headings in block list by given number
 local function shift_headings(blocks, shift_by)
   if not shift_by then
@@ -32,9 +46,21 @@ function transclude (cb)
 
   -- Markdown is used if this is nil.
   local format = cb.attributes['format']
-  local shift_heading_level_by =
-    tonumber(cb.attributes['shift-heading-level-by'])
 
+  -- Attributes shift headings
+  local shift_heading_level_by = 0
+  local shift_input = cb.attributes['shift-heading-level-by']
+  if shift_input then
+    shift_heading_level_by = tonumber(shift_input)
+  else
+    if include_auto then
+      -- Auto shift headings
+      shift_heading_level_by = last_heading_level
+    end
+  end
+
+  --- keep track of level before recusion
+  local buffer_last_heading_level = last_heading_level
 
   local blocks = List:new()
   for line in cb.text:gmatch('[^\n]+') do
@@ -44,11 +70,14 @@ function transclude (cb)
         io.stderr:write("Cannot open file " .. line .. " | Skipping includes\n")
       else
         local contents = pandoc.read(fh:read '*a', format).blocks
+        last_heading_level = 0
         -- recursive transclusion
         contents = pandoc.walk_block(
           pandoc.Div(contents),
-          {CodeBlock = transclude}
+          { Header = update_last_level, CodeBlock = transclude }
           ).content
+        --- reset to level before recursion
+        last_heading_level = buffer_last_heading_level
         blocks:extend(shift_headings(contents, shift_heading_level_by))
         fh:close()
       end
@@ -58,5 +87,6 @@ function transclude (cb)
 end
 
 return {
-  {CodeBlock = transclude}
+  { Meta = get_vars },
+  { Header = update_last_level, CodeBlock = transclude }
 }