Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

A lua filter enabling multiple columns in Latex, PDF, and HTML documents #191

Open
wants to merge 16 commits into
base: master
Choose a base branch
from

Conversation

chrisaga
Copy link

It's based on the use of simple Pandoc fenced divs, their class names and some arguments. This filter extends what is already available for HTML output, gives the same features to Latex (and PDF via Latex) documents.
Multiple columns are very useful to format fancy documents with text, pictograms etc. I have been missing this feature for a long time. I finally made my first Pandoc lua filter and share it hoping it will be useful to others.

@chrisaga
Copy link
Author

I think I corrected what failed in the test workflow in my two last commits (5296ecd & 9d650d4). Sorry for the inconvenience.

column-div/column-div.lua Outdated Show resolved Hide resolved
column-div/column-div.lua Outdated Show resolved Hide resolved
as suggested by Benct Philip Jonsson
Plus other minor refactoring and some details in README.md
Some enhencements in the sample file.
@jdutant
Copy link
Contributor

jdutant commented Oct 24, 2021

NB, there's already a filter for that: https://github.com/jdutant/columns . The syntax is the same, and it provides the header-includes if needed. It handles column spacing, rules etc. as well. I didn't submit it here because @tarleb wants to keep this repo for smaller, easily maintainable filters, but I included it in the filters wiki. The main thing I'd like to add to my columns filter is handling tables within multiple columns in LaTeX (this requires converting longtables to xtabs, I've worked on that a bit: https://github.com/jdutant/dialectica-filters/tree/main/longtable-to-xtab).

BTW few people seem to find the filters mentioned in the Pandoc filters wiki. This repo is good because we know we can trust the filters on it; but on the other hand, it can't accept largish filters. I hope at some point we get something more like CTAN...

@chrisaga
Copy link
Author

@jdutant Thanks for the clarification.
I eventually found your column.lua when I was trying to figure out a solution.
Am I wrong or It processes even column (multicols style) but not uneven, width fixed, columns ? The later are OK in plain Pandoc for HTML output but not for Latex/PDF output.
I wanted a small easilly maintenable solution to do some document formating which would render the same in HTML and PDF.
This column thing (both types) have been an issue for quite some time (see questions in multiple StackExchange lists). It's the reason why I thought this filter could interest somebody. If this is not the right place. No problem for me.

@jdutant
Copy link
Contributor

jdutant commented Oct 24, 2021

@chrisaga ah, good point! Indeed columns.lua only reproduces the functionality of the LaTeX package multicol, which doesn't handle variable width. I see different widths are a challenge; they can't be fluid in LaTeX as paragraphs can't change their width midway, so you need to explicit column breaks, and they can't break across pages if they're created by minipage, as in your filter. I wonder if it's worth implementing that in columns.lua filter, or just make sure that the two syntaxes don't overlap so people can use both.

@chrisaga
Copy link
Author

@jdutant I don't know. It's up to you.
minipages is the way I found to implement this :

:::::::: {.columns }
:::: {.column width="20%"}
content ...
::::
:::: {.column width="80%"}
content ...
::::
::::::::

Which is what you find on the net when you google something like "pandoc markdown columns".
It's consistent with what plain Pandoc makes with divs for HTML output. Obviously no page break problem here.
I just say that using both column types makes it super easy to get some pretty fancy page formatting with text and symbols (see attached image below). The rendering is very consistent between HTML and PDF. I am very happy with that. I may just need to add the bells and whistles of multicols (already checked that almost everything can be done both with HTML and LATEX).
what-you-can-expect
F.

column-div/column-div.lua Outdated Show resolved Hide resolved
@alerque alerque marked this pull request as draft January 6, 2022 10:42
Copy link
Collaborator

@alerque alerque left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for working on this, dropping the requirement on specific class order, and especially for adding tests!

column-div/column-div.lua Outdated Show resolved Hide resolved
.display.math{display: block; text-align: center; margin: 0.5rem auto;}
</style>
<!--[if lt IE 9]>
<script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am uncomfortable with this. Do we have other instances in Pandoc templates where the default output includes loading 3rd party external resources?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well … I didn't do this. pandoc --standalone did. I can remove the --standalone option on the html test file.
I already did for the latex test file.
Would it be better like this ?

if style then
div.attributes.style = style .. (div.attributes.style or '')
returned_list = List:new{pandoc.Div(div.content, div.attr)}
--returned_list = List:new{pandoc.Div(div.content)}
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I realize I'm reviewing this still in Draft mode so it might be too early, but just as a note for when this is ready for review lets cleanup the code so there are not instances of commented out bits without explanation for why the logic is not transparent.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Of course !

-- process supported options
opt = div.attributes['column-count']
if opt then options = '{' .. opt .. '}' end
--[[ This functionality will be moved in another filter since it can't be consistent with the positionless classname requirement
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

c.f. Comment on L151.

@chrisaga chrisaga marked this pull request as ready for review January 26, 2022 13:38
@chrisaga chrisaga requested review from jgm and tarleb as code owners January 26, 2022 13:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants