Pandoc to docx: tips for myself

With bonus LibreOffice content!

Background

I’ve been using pandoc for a few years now as part of my workflow in sending out minutes of a local group- I use LaTeX to make ’em beautiful in a PDF and also use markdown to format a WordPress post, which becomes the basis for a newsletter. The statute among you will realise that this is actually working in the opposite direction to the title- well done you!

Recently I have produced a couple of reports, for which the recipient desired them in an editable format- .docx. I am comfortable working in LaTeX or markdown in vim, so that’s what I used to write up the reports, figuring on using pandoc to convert in the opposite direction. But there were a couple of gotchas and stumbling blocks along the way, which I’m writing down here so that the next time I come to do it I can look here, rather than hunting them down.

Pandoc’s Markdown is More Than Markdown

One thing I noticed is that the convention I had used for underlining, wrapping in underscores, instead produced italicised content. I’m not sure where I picked that convention up, as it italicises in messaging clients — Matrix, hangouts, etc — too.

The Pandoc manual makes a point of mentioning that it understands more than just simple markdown:

Pandoc understands an extended and slightly revised version of John Gruber’s Markdown syntax. This document explains the syntax, noting differences from original Markdown.

For underlining, it uses a curly brace notation:

To underline text, use the underline class:
[Underline]{.underline}

As a side note to myself: that explains the [link]{.ul} generated when generating markdown, which I had put down to some idiosyncrasy in LaTeX interpretation- eg that in LaTeX it was manually underlining to reproduce links, so the LaTeX-to-markdown translation thought it would have to manually underline a link too…

Quickly Changing Those Underscores to Square Brackets in Vim

Since I was in vim, a search/replace did the trick (vi/vim stackexchange link, cheers AndyB):

:s/_\(.*\)_/[\1]{\.underline}/

( in:) _I Should Be Underlined_
(out:) [I Should Be Underlined]{.underline}

that will do the search and replace on the current line, which I wanted. if you’d like a global search and replace, prefix the leading ‘s’ with a % (and maybe add a trailing ‘c’ to ‘c’onfirm)

Tables Are Supported! But They’re Cumbersome

Looking through the manual some more, I found that there was support for including tables, which is great as my latest report had a couple.

Unfortunately, my table was pretty long, and didn’t have a reasonable plain-text representation. I tried a grid table, but while it managed the table header row okay, it choked on the cell contents. That said, I kept the table in the output, which I then edited with LibreOffice.

Which brings me to…

LibreOffice

LO supports .docx, which is great. But after I discovered LaTeX, I developed a mild allergy to WYSIWYG word processors, and my usage of them dropped precipitously. As such, I had to rediscover how to do things in LibreOffice Writer.

UI Scaling / Actually Seeing the Menus

My eyesight is pretty bad- to give an idea (eye-dea?), if I close my good one all the text on my screens disappears. Magic! But only for an audience of one. So I need to make things bigger to see them.

LibreOffice used to do UI scaling. Then they took it out (documentfoundation bugzilla link) about five years ago, citing focus on HiDPI accessibility. That’s all well and good, but, uh… I cannot see it very well.

Buried in that bug report was a suggestion which worked for me: set the GDK_SCALE environment variable. I set it to 2, which is a little on the big side as fractional values. But fractional values seem to be ignored (?), and I’d rather have it too big than too small. I think this worked as I have a gtk3 version of LO, apparently.

Other users report that setting UI scaling from their desktop environment (Arch wiki link) (eg KDE settings “about this system” page) seems to work… in some cases. In Windows, apps can be scaled globally, per monitor, or per application.

Superscripts (and subscripts)

I always forget this:

Press Ctrl+Shift+P to make the text superscript, and Ctrl+Shift+B to make the text subscript.

Quickly add a row to a table

As I had a bunch of rows to add, I wanted a way to do this quickly. The documentation for version 6.2 mentions the following:

To insert a new row in a table, place the cursor in a table cell, press Alt+Insert, and then press the up or down arrow key. You can also move the cursor to the last cell in the table, and then press Tab.

The first method didn’t work, but the ‘last cell, press TAB’ did!

For whatever reason I couldn’t find the equivalent documentation for 7.2 until now, which reads:

To insert a column, place the cursor in a table cell, hold down Alt and press Insert, release, and then press the left or the right arrow.

that method didn’t work for me. Oh well, pressing TAB does!

Change the Orientation of a Single/Few Page(s)

This one had me scratching my head for a bit. A search took me to this help page (outdated!), though it took me straight to that heading, skipping the warning about being outdated. The information there works though:

• create a new style via Styles and Formatting with the changed page options
• insert a manual break and select a page style: Insert → More Breaks → Manual breaks… → Page break and select ‘Page Style:’

Simple, eh?

A Note on Pandoc’s Logo

They don’t seem to have one. I pulled the best looking one from an image search, but discussion about creating one has been ongoing since 2015 (Google Groups link).