[Pandoc Writer] Ordered Lists

* OL Styles: Tweak writer to properly handle numeral styles via html attributes. It uses a look-up table to convert pandoc styles name to valid CSS attributes, and the list is not yet complete. * OL Start: Implemented support for start numbers, but the generated `html_start` node had to be suppressed from output because it would crash PMLC 3.1.0 due to a bug. See: pml-lang/pml-companion#91 * Images: Polish the image element(s) code and add tests to confirm it works fine with HTTP URLs (added in PML 3.0). * pandoc 2.17.1.1: adopt latest pandoc release and diff the old `sample.lua` filter with the latest to see if there are any changes worth integrating (weren't any).
tajmone · Oct 22, 2022 · 2c983ae · 2c983ae
1 parent 21f9bd0
commit 2c983ae
Show file tree

Hide file tree

Showing 5 changed files with 167 additions and 51 deletions.
diff --git a/pandoc/filters-lua/pml-writer/README.md b/pandoc/filters-lua/pml-writer/README.md
@@ -8,8 +8,9 @@ An attempt to implement a PML [custom pandoc writer] via Lua filters.
 
 Builds via `rake pandoc`.
 
-> **NOTE** — Except for a patch fixing the `caption` attribute to the new `[caption` node, the Lua filter hasn't been updated since PML 2.3.0.
-> Many source comments about PML limitations no longer apply, we only need to update the filter to make use of the new PML 3.x features.
+> **IMPORTANT** — The Lua filter contains many obsolete source comments about PML limitations which are no longer true.
+> These comments are left over from PML 2.3.0 and don't take into account the new PML 3.x features.
+> Therefore, until this notice is standing always double check comments against current PMLC status; once all the old comments are purged remove this notice.
 
 -----
 
@@ -88,7 +89,7 @@ In order to build the assets in this folder, you'll need the following tools:
 - [pandoc][pandoc install] — use latest release.
 - Ruby 3 — only required for the Rake toolchain of this project.
 
-To use this pandoc filter in your own projects, you'll only need PMLC, pandoc and the `pml-writer.lua` file.
+To use this pandoc filter in your own projects, you'll only need PMLC, pandoc and the `pml-writer.lua` and `default.pml.lua` files from this folder.
 
 <!-----------------------------------------------------------------------------
                                REFERENCE LINKS

diff --git a/pandoc/filters-lua/pml-writer/pml-writer.lua b/pandoc/filters-lua/pml-writer/pml-writer.lua
@@ -1,13 +1,13 @@
--- "pml-writer.lua" v0.0.6 | 2022/03/01            | PML 2.3.0 | pandoc 2.17.1.1
+-- "pml-writer.lua" v0.0.7 | 2022/10/22            | PML 3.1.0 | pandoc 2.19.2
 -- =============================================================================
 -- ** WARNING ** This PML writer is being built on top of the sample writer that
 --               ships with pandoc; generated via:
 --
 --    pandoc --print-default-data-file sample.lua > pml-writer.lua
 --
--- This source integrates the changes of the sample writer from pandoc 2.17.1.1
+-- This source integrates the changes of the sample writer from pandoc 2.19.2
 -- (i.e. from time to time it's diffed with the latest sample to see if there
--- are new updated worth integrating).
+-- are new code changes worth integrating).
 --
 -- Since it emulates pandoc's HTML writer it will be used as a starting point
 -- to build our PML writer on top of with. PML is structurally similar to HTML,
@@ -193,17 +193,12 @@ function Link(s, tgt, tit, attr)
 end
 
 function Image(s, src, tit, attr)
-  -- @FIXME: If src is a web URL, emit Raw HTML instead!
   local outstr
   outstr = '[image source="' .. escape(src,true) .. '"'
   if #tit ~= 0 then
-    outstr = outstr .. ' html_title="' .. escape(tit,true) .. '"'
+    outstr = outstr .. ' html_alt="' .. escape(tit,true) .. '"'
   end
   return outstr .. ']'
---[[
-  return '<img src="' .. escape(src,true) .. '" title="' ..
-         escape(tit,true) .. '"/>'
---]]
 end
 
 function Code(s, attr)
@@ -336,12 +331,40 @@ function BulletList(items)
   return "[list\n" .. table.concat(buffer, "\n") .. "\n]"
 end
 
-function OrderedList(items)
+-- Look-up Table for pandoc to HTML numeric styles names
+num_styles_lut = {
+-- @TODO: complete list: https://www.w3schools.com/CSSref/pr_list-style-type.asp
+  LowerRoman = "lower-roman",
+  UpperRoman = "upper-roman",
+  LowerAlpha = "lower-alpha",
+  UpperAlpha = "upper-alpha",
+  -- DefaultStyle ???
+  -- Example ???
+  -- Decimal -> already covered by our fallback value
+}
+
+function OrderedList(items, start, style)
+  -- @TODO: Extract info about:
+  --   [x] Numerals list-style-type.
+  --   [ ] Start number (WIP: commented out due to PMLC bug #91).
+  --   [ ] Optimize code: The above LUT should be kept inside the func
+  --       block, to keep the code clean, but *without* the performance
+  --       hit of heap-allocating the table at each function call! See:
+  --          http://lua-users.org/wiki/SwitchStatement
   local buffer = {}
   for _, item in pairs(items) do
     table.insert(buffer, "[el " .. item .. "]")
   end
-  return '[list (html_style="list-style-type:decimal")\n' .. table.concat(buffer, "\n") .. "\n]"
+  html_style = num_styles_lut[style] or "decimal"
+  if start ~= 1
+    then start_str = ' html_start=' .. start
+    else start_str = ''
+  end
+  -- A bug in PML 3.1.0 causes 'html_start' to crash, so we temporarily
+  -- need to suppress the attribute until fixed. See: pml-lang/pml-companion#91
+  start_str = '' -- @DELME!
+  return '[list (html_style="list-style-type:'.. html_style ..'"' ..
+          start_str .. ")\n" .. table.concat(buffer, "\n") .. "\n]"
 end
 
 function DefinitionList(items)
@@ -369,28 +392,18 @@ local function html_align(align)
 end
 
 function CaptionedImage(src, tit, caption, attr)
-  -- @FIXME: If src is a web URL, emit Raw HTML instead!
   if attr.id then
     local img_id = " id=" .. attr.id
   end
   if #caption == 0 then
     return  '[image source="' .. escape(src,true) ..
             '"' .. attr.id .. ']'
---[[
-    return '<p><img src="' .. escape(src,true) .. '"' .. attr.id ..
-      '"/></p>'
---]]
   else
     local ecaption = escape(caption)
     return '[image source="' .. escape(src,true) .. '"' ..
            attr.id ..
            ' html_alt="' .. ecaption .. '"]' ..
            '[caption ' .. ecaption .. ']'
---[[
-    return '<figure>\n<img src="' .. escape(src,true) ..
-        '" id="' .. attr.id .. '" alt="' .. ecaption  .. '"/>' ..
-        '<figcaption>' .. ecaption .. '</figcaption>\n</figure>'
---]]
   end
 end
 

diff --git a/pandoc/filters-lua/pml-writer/sample.lua b/pandoc/filters-lua/pml-writer/sample.lua
@@ -1,8 +1,3 @@
--- =============================================================================
--- The sample writer that ships with pandoc 2.17.1.1; generated via:
---
---    pandoc --print-default-data-file sample.lua > sample.lua
--- =============================================================================
 -- This is a sample custom writer for pandoc.  It produces output
 -- that is very similar to that of pandoc's HTML writer.
 -- There is one new feature: code blocks marked with class 'dot'

diff --git a/pandoc/filters-lua/pml-writer/tests/pandoc.markdown b/pandoc/filters-lua/pml-writer/tests/pandoc.markdown
@@ -46,19 +46,55 @@ end
 
 ### Bullet Lists
 
-- Bold: **Lorem ipsum**.
-- Italic: _Lorem ipsum_.
-- Code: `Lorem ipsum`.
+- Top level -- **bold**.
+- Top level -- _italic_.
+    + Sub level.
+    + Sub level.
+        * Sub-sub level.
+- Top level -- `inline code`.
 
 ### Ordered Lists
 
-1. AAA
-    1. Sub-element 1.
-        1. Sub-sub-element.
-    1. Sub-element 2.
-2. BBB
-3. CCC
-4. DDD
+Decimal numerals:
+
+1. One
+    1. One-Sub
+        1. One-Sub-Sub
+    #. Two-Sub
+#. Two
+#. Three
+#. Four
+
+Lower-roman numerals:
+
+i. One
+#. Two
+#. Three
+#. Four
+
+Lower-alpha numerals:
+
+a. One
+#. Two
+#. Three
+#. Four
+
+Arbitrary start numbers:
+
+3. Three (dec)
+#. Four
+#. Five
+    II.  Two (roman uc)
+    #.  Three
+    #.  Four
+#. Six
+#. Seven
+    C.  Three (alpha uc)
+    #.  Four
+    #.  Five
+
+
+> **WARNING** — The code that handles the list `start` attribute had to be commented out because `html_start` crashes PMLC 3.1.0 due to a bug. (See: [Issue #91](https://github.com/pml-lang/pml-companion/issues/91))
 
 
 ## Horizontal Rules
@@ -118,10 +154,18 @@ The PML Writer corrects empty links by rendering the link text only:
 
 Images are considered by pandoc to be inline if they are not the only element in a paragraph.
 
+#### Local Image File
+
 An inline image: ![The PML cool image](./pml-cool.png)
 
 An inline image with alt-text: ![The PML cool image](./pml-cool.png "Alt-text is cool too!")
 
+#### Web Image
+
+An inline image: ![The PML cool image](https://www.pml-lang.dev/images/PML_plane_200_200.png)
+
+An inline image with alt-text: ![The PML cool image](https://www.pml-lang.dev/images/PML_plane_200_200.png "Alt-text is cool too!")
+
 ### Captioned Images
 
 ![The PML cool image](./pml-cool.png)

diff --git a/pandoc/filters-lua/pml-writer/tests/pandoc.pml b/pandoc/filters-lua/pml-writer/tests/pandoc.pml
@@ -56,27 +56,82 @@ code]
 [ch [title Bullet Lists]
 
 [list
-[el Bold: [b Lorem ipsum].]
-[el Italic: [i Lorem ipsum].]
-[el Code: [c Lorem ipsum].]
+[el Top level – [b bold].]
+[el Top level – [i italic].
+
+[list
+[el Sub level.]
+[el Sub level.
+
+[list
+[el Sub-sub level.]
+]]
+]]
+[el Top level – [c inline code].]
 ]
 
 ][ch [title Ordered Lists]
 
+Decimal numerals:
+
 [list (html_style="list-style-type:decimal")
-[el AAA
+[el One
 
 [list (html_style="list-style-type:decimal")
-[el Sub-element 1.
+[el One-Sub
 
 [list (html_style="list-style-type:decimal")
-[el Sub-sub-element.]
+[el One-Sub-Sub]
 ]]
-[el Sub-element 2.]
+[el Two-Sub]
 ]]
-[el BBB]
-[el CCC]
-[el DDD]
+[el Two]
+[el Three]
+[el Four]
+]
+
+Lower-roman numerals:
+
+[list (html_style="list-style-type:lower-roman")
+[el One]
+[el Two]
+[el Three]
+[el Four]
+]
+
+Lower-alpha numerals:
+
+[list (html_style="list-style-type:lower-alpha")
+[el One]
+[el Two]
+[el Three]
+[el Four]
+]
+
+Arbitrary start numbers:
+
+[list (html_style="list-style-type:decimal")
+[el Three (dec)]
+[el Four]
+[el Five
+
+[list (html_style="list-style-type:upper-roman")
+[el Two (roman uc)]
+[el Three]
+[el Four]
+]]
+[el Six]
+[el Seven
+
+[list (html_style="list-style-type:upper-alpha")
+[el Three (alpha uc)]
+[el Four]
+[el Five]
+]]
+]
+
+[quote
+[b WARNING] — The code that handles the list [c start] attribute had to be commented out because [c html_start] crashes PMLC 3.1.0 due to a bug. (See: [link url=https://github.com/pml-lang/pml-companion/issues/91 text="Issue #91"])
 ]
 
 ]][ch [title Horizontal Rules]
@@ -153,11 +208,19 @@ The PML Writer corrects empty links by rendering the link text only:
 
 Images are considered by pandoc to be inline if they are not the only element in a paragraph.
 
+[ch [title Local Image File]
+
 An inline image: [image source="./pml-cool.png"]
 
-An inline image with alt-text: [image source="./pml-cool.png" html_title="Alt-text is cool too!"]
+An inline image with alt-text: [image source="./pml-cool.png" html_alt="Alt-text is cool too!"]
+
+][ch [title Web Image]
+
+An inline image: [image source="https://www.pml-lang.dev/images/PML_plane_200_200.png"]
+
+An inline image with alt-text: [image source="https://www.pml-lang.dev/images/PML_plane_200_200.png" html_alt="Alt-text is cool too!"]
 
-][ch [title Captioned Images]
+]][ch [title Captioned Images]
 
 [image source="./pml-cool.png" html_alt="The PML cool image"][caption The PML cool image]