Why plain text documentation

How and why I write in plain text format.

This article is about the various plain text document formats I’m interested in using. Mainly orgmode and the new GitLab flavoured markdown, which is based upon CommonMark. This is very similar to GitHubs new GitHub flavoured Markdown.

I want to write in a lightweight markup language and be able to export to a lot of different formats. Mainly pdf, html and .docx. The source document format needs to be version controlled in Git. It needs to be able to be edited in an editor of sorts, not some proprietery application. Others need to be be able to edit the document too. Therefore it would be nice if something like GitLab supports the format so others can edit it on the easy to use GitLab web interface.

I really like orgmode format. Some of the reasons I like it are written about by Karl Voit in his orgmode-as-markup-only blog post. Ideally I would write everything in orgmode and convert from there.

Few problems with orgmode only format. I need to collaborately work on documents with others. Ideally the place I work would standardise on org format, but that’s very unlikely since org format is not popular. Moreover the tooling around org format is mostly MIA as it’s mostly used in the Emacs world. Markdown and it’s various flavours is a better format to collaborate with others in.

Therefore I need good ability to convert back and forth between orgmode and gfm to be able to write consistently in orgmode format.

The problem with that is, orgmode import and export with pandoc is not very good as discussed later in this article.

Due to the limited options in converting to and from orgmode, I will, for the time being, be writing a lot of my documents in GitLab Flavoured Markdown.

Converting between documentation formats

Converting from orgmode

Here are some options when the source document is in org format.

org2markdown

Pandoc org mode support is not very good. We should report bugs upstream and follow them closely. Ideally pandoc would fix this improve the situation a lot.

One could use this command in pandoc, though the results are not great.

pandoc input.org -t gfm -o /tmp/output.md

Use the various org-md- functions from ox-md.el which is part of orgmode itself.

These work better but still don’t convert to markdown that well. Pierre Neidhardt wrote a nice wrapper which improves the org2markdown export. One can use it like this:

In a directory with a file called input.org run emacs --script org2md.el --funcall=org2md-export. This will generate a well formatted gfm markdown output.md document.

org2confluence

Same as markdown2confluence (except for the initial pandoc command).

Converting from markdown

Here are some options when the source document is in markdown format.

markdown2pdf

Let gitlab render the document for you. From Chrome print it. Draw back here is the table of contents links don’t render correctly.
Let gitlab render the document for you. Export the document to PDF. This requires a gitlab enterprise edition. So one could perhaps use gitlab.com for this?
Use pandoc to convert it to PDF with one of these commands.
```
pandoc -f gfm input.md -o output.pdf
```
Note, you can select a different pdf-engine backend, by default it is pdflatex. As per man pandoc the options currently are:
```
--pdf-engine=pdflatex|lualatex|xelatex|wkhtmltopdf|weasyprint|prince|context|pdfroff
```
Use on of the many online markdown converters like one of the below websites.
- https://dillinger.io/
- https://stackedit.io/
This is really not ideal, since it gives your data to others.

markdown2html

Once again pandoc like so:

pandoc  -f gfm  input.md -o output.html

An online markdown editor as mentioned in markdown2pdf.

markdown2org

Pandoc org mode support is not very good. We should report bugs upstream and follow them closely. Ideally pandoc would fix this which would help things a lot.

One could use this command in pandoc, though the results are not great.

pandoc input.md -f gfm -o /tmp/output.org

markdown2confluence

This has been tested with Atlassian Confluence 6.6.2.

First convert to .docx with pandoc like so:

pandoc input.md -f gfm -o /tmp/output.docx

Then convert the document to .doc following the doc2docx section.

Once you have the document in .doc format you can import it into Confluence using the Confluence web interface.

Note that the Confluence web interface only seems to support .doc as an import format, not even .docx. Worse off, even though it only supports one import format, it doesn’t seem to even import that format correctly either. In my experience the code blocks aren’t don’t contain line breaks.

Corverting from docx

docx2doc

Pandoc doesn’t support .doc format. Guessing this is due to it being a proprietary format. It does support .docx which is kind of an “open and standard” format.

One could open the .docx file in libreoffice and then save it in .doc format.

One can also use abiword like so abiword --to=doc input.docx output.doc.