Doc-org: org-mode + latex + docker = pdf
For better formatting read this article on my website:
Why plain text is better than word processors
I was so tired of working with word processors like Microsoft Word that I created yet another a documentation system based on plain text.
With plain text you can:
- use git
- easily see differences between a version and another
- use grep and other basic utilities
- generate documents automatically with simple scripts
- use your favorite editor
In short, with plain text I am free to do whatever I want.
Alternatives to word processors
The first thing you need in order to create a documentation system based on plain text is to choose a markup language. After many years of experiments with markdown, asciidoc and so on, I fell in love with org-mode. You can search for online demos if you don't believe me: if you are comfortable with emacs, there is nothing better than writing documents using org-mode.
Anyway, emacs does not reinvent the wheel and so there isn't a direct way to convert org-mode to pdf. What it does instead, is to translate org-mode into latex, which is the best language to create pdf files in my opinion.
So, by using emacs, you can export org-mode to latex in order to avoid writing directly in latex, which is too much verbose and it's not very readable until you export it.
This is how I have done my MSc thesis and overall I was happy of the final result. Anyway, when you try to mix your own latex customizations with latex automatically exported by emacs, it becomes a little bit difficult to achieve what you want.
That's why emacs has a body-only export option, which let you export only the body of your document. In this way you can have full control of your latex customizations.
Convincing your colleagues to migrate
So, given for granted that org-mode + latex is the best way to create pdf files you still need to convince your colleagues to install emacs and latex on their machines and to learn how to use emacs. Basically this is not possible. ??
That's why I have created doc-org, a command line utility based on docker that generates pdf files starting from org mode and latex. The only installation requirement is docker, therefore you/your colleagues don't need to install and learn how to use emacs and latex. Of course you can edit org-mode documents with any editor, you are not forced to use emacs..it's just plain text! ??
Here there are tons of example documents that are automatically generated by using github actions. Yes, you can version your small plain text files with git and then automatically build the pdf after every git push! ??
Conclusion
I am very happy I have started this project providing lots of toy examples. I hope that more companies leave behind the idea of word processors, because the best way to write documents together is the same of writing code together: plain text + version control systems like git.
Check out doc-org on github. If you have problems/suggestions just open an issue. ??