Allow 'signifiant' class names to be in random position in the list

as suggested by Benct Philip Jonsson
Plus other minor refactoring and some details in README.md
Some enhencements in the sample file.

Author: chrisaga

column-div/README.md

@@ -1,6 +1,6 @@
 ---
 title: "Column Div - leverage Pandoc native divs to make columns
- an other things"
+ and other things"
 author: "Christophe Agathon"
 ---
 
@@ -32,6 +32,14 @@ PDF document from markdown sources.
 The main purpose of this filter is to make it possible and give
 similar formating features for both Latex/PDF and HTML outputs.
 
+My guidelines are :
+
+1) Use Pandoc divs like many already have proposed for uneven and even columns
+2) Same functionalities and rendering in HTML and Latex+PDF
+3) Mess the least possible with plain Pandoc processing which is quite OK already for HTML (miss only column-count for even columning).
+4) Allow users to use unknown Latex environments from exotic packages if they wish, provided they include them in the preamble.
+
+
 Usage
 -----
 
@@ -56,10 +64,10 @@ Pandoc markdown files.
 ### Formating the document
 
 Everything is done with Pandoc's fenced divs with class names and
-attributes. The attributes are similar to those from Latex and/or
-HTML styling.
+attributes. The attributes are similar to those from HTML styling and/or
+Latex.
 
-#### Multiple balanced columns
+#### Multiple even columns
 For Latex and PDF output, you will need to call the multicol
 package. This can be done un the YAML header.
 
@@ -85,7 +93,7 @@ Some text formatted on 2 columns
 * Latex output is done with `multicols` environment.
 * HTML output uses `style="column-count: 2"` on a div block.
 
-#### Unbalanced columns
+#### Uneven columns
 
 No specific Latex package are needed. We use Nested Pandoc divs in
 the same way that columns and column environments are used in
@@ -112,14 +120,17 @@ well already (based on divs with `width` attributes).
 
 #### Other usages
 
-HTML : you can already create divs with whatever class names youl
+For HTML outputs, you already can create divs with whatever class names you
 like and style them with `style=" … "` attributes. This is
-proccessed by Pandoc and as nothing to do with this filter.
+processed by Pandoc and has nothing to do with this filter.
 
 This filter allows to do the same in Latex (and PDF).
-The class name is used as the environment name and a
-`data-latex=" … "` attribute allows you to pass options and
-parameters to the `\begin` instruction.
+You can create whatever environment you need. The environment name is the
+class name given to the fenced div. In case of multiple class names, the 
+first one is used. Other are ignored but allowed to help you to maintain 
+a single markdown source for PDF and HTML outputs.
+The `data-latex=" … "` attribute allows you to pass options and
+parameters to the `\begin` environment instruction.
 
 To Do
 -----
@@ -129,7 +140,7 @@ spacing, rules, etc.
 
 Since Pandoc does a very good job with the `width` styling
 attribute to implement variable column width, it could easily
-support HTML balanced column via the `column-count` attribute.
+support HTML even column via the `column-count` attribute.
 
 Contributing
 ------------

column-div/column-div.lua

@@ -26,18 +26,28 @@ Note:       You need to include multicol latex package to get balanced columns
 local List = require 'pandoc.List'
 
 function Div(div)
-  options = ''
-  local env = div.classes[1]
+  local options = ''
+  local env = ''
   local returned_list
   local begin_env
   local end_env
   local opt
 
   -- if the div has no class, the object is left unchanged
-  if not env then return nil end
+  -- if the div has no class but an id, div.classes ~= nil
+  -- TODO: use a div with no class to build a 'scope' in Latex
+  --        usefull for user who would throw inline Latex code and limit it's
+  --        effect.
+  if not div.classes or #div.classes == 0 then return nil end
 
   -- if the output is beamer do columns
   if FORMAT:match 'beamer' then
+    -- only arbitrary environment support in beamer for now. Environment has to
+    -- be the firs class name.
+    env = div.classes[1]
+    if options == '' and div.attributes['data-latex'] then
+      options = div.attributes['data-latex']
+    end
     -- build the returned list of blocks
     begin_env = List:new{pandoc.RawBlock('tex',
                                   '\\begin' .. '{' .. env .. '}' .. options)}
@@ -47,8 +57,8 @@ function Div(div)
   -- if the format is latex then do minipage and others (like multicol)
   elseif FORMAT:match 'latex' then
     -- build the returned list of blocks
-    if env == 'column' then
-      --opt = div.attributes['width']
+    if div.classes:includes('column') then
+      env = 'column'
       opt = div.attributes.width
       if opt then
         local width=tonumber(string.match(opt,'(%f[%d]%d[,.%d]*%f[%D])%%'))/100
@@ -63,7 +73,8 @@ function Div(div)
       end_env = List:new{pandoc.RawBlock('tex', '\\end{' .. 'minipage' .. '}')}
       returned_list = begin_env .. div.content .. end_env
 
-    elseif env == 'columns' then
+    elseif div.classes:includes('columns') then
+      env = 'columns'
       -- merge two consecutives RawBlocks (\end... and \begin...)
       -- to get rid of the unwanted blank line
       local blocks = div.content
@@ -82,13 +93,20 @@ function Div(div)
 
     else
       -- other environments ex: multicols
-
-      -- process supported options
-      opt = div.attributes['column-count']    -- this synthax needed due to '_'
-      if opt then options = '{' .. opt .. '}' end
-
-      -- default if no known options
-      if options == '' then options = div.attributes.data-latex end
+      if div.classes:includes('multicols') then
+        env = 'multicols'
+        -- process supported options
+        opt = div.attributes['column-count']
+        if opt then options = '{' .. opt .. '}' end
+      else
+        -- Latex skilled users can use arbitrary environments passed as
+        -- the first (and only signifiant) class name.
+        env = div.classes[1]
+        -- default if no known options
+        if options == '' and div.attributes['data-latex'] then
+          options = div.attributes['data-latex']
+        end
+      end
 
       begin_env = List:new{pandoc.RawBlock('tex',
                                     '\\begin' .. '{' .. env .. '}' .. options)}
@@ -105,9 +123,11 @@ function Div(div)
         div.attributes.style = div.attributes.style ..
                                 '; column-count: ' .. opt
       else
-        div.attributes.style = 'column-count:' .. opt
+        div.attributes.style = 'column-count: ' .. opt
       end
       div.attributes['column-count'] = nil
+      -- column-count is "consumed" by the filter otherwise it would appear as
+      -- data-column-count="…" in the resulting document
       returned_list = List:new{pandoc.Div(div.content, div.attr)}
     end
   end

column-div/expected.html

@@ -21,13 +21,16 @@ <h1 class="title">Test</h1>
 </header>
 <h1 id="column-div-test">column-div test</h1>
 <p>content…</p>
+<div id="thisdivdoesnothing">
+<p>content…</p>
+</div>
 <h2 id="three-columns">Three columns</h2>
-<div class="multicols" style="column-count:3">
+<div class="anotherclassname multicols" style="column-count: 3">
 <p>content…</p>
 <p>content…</p>
 <p>content…</p>
 </div>
-<h2 id="two-unbalanced-columns">Two unbalanced columns</h2>
+<h2 id="two-uneven-columns">Two uneven columns</h2>
 <div class="columns">
 <div class="column" data-valign="b" style="width:40%;">
 <p>contents…</p>
@@ -36,7 +39,7 @@ <h2 id="two-unbalanced-columns">Two unbalanced columns</h2>
 </div>
 </div>
 <h2 id="columns-in-columns">Columns in columns</h2>
-<div class="multicols" style="column-count:3">
+<div class="multicols" style="column-count: 3">
 <div class="columns">
 <div class="column" data-valign="b" style="width:20%;">
 <p>contents…</p>

column-div/expected.tex

@@ -3,6 +3,9 @@ \section{column-div test}\label{column-div-test}}
 
 content\ldots{}
 
+\leavevmode\hypertarget{thisdivdoesnothing}{}%
+content\ldots{}
+
 \hypertarget{three-columns}{%
 \subsection{Three columns}\label{three-columns}}
 
@@ -16,8 +19,8 @@ \subsection{Three columns}\label{three-columns}}
 
 \end{multicols}
 
-\hypertarget{two-unbalanced-columns}{%
-\subsection{Two unbalanced columns}\label{two-unbalanced-columns}}
+\hypertarget{two-uneven-columns}{%
+\subsection{Two uneven columns}\label{two-uneven-columns}}
 
 \begin{minipage}[b]{0.4\columnwidth}
 

column-div/sample.md

@@ -11,16 +11,20 @@ header-includes:
 # column-div test
 content...
 
+::: {#thisdivdoesnothing}
+content...
+:::
+
 ## Three columns
-::: {.multicols column-count="3"}
+::: {.anotherclassname .multicols column-count="3"}
 content...
 
 content...
 
 content...
 :::
 
-## Two unbalanced columns
+## Two uneven columns
 :::::: {.columns}
 ::: {.column width="40%" valign="b"}
 contents...