a gold fountain pen

AsciiDoc Convert

Over the years, I find myself writing in Markdown and LaTeX more often than anything else. Markdown is quick and easy to write out ideas, letters, and the like without having to think much about the formatting. I let pandoc handle the conversion from markdown into whatever file format I need to use, like pdf, html, rtf, etc. In fact, I only write in markdown or LaTeX now. Word processors and WYSIWYG are cumbersome and I find myself wasting time figuring out how to do something simple than I do writing the content. 

On the other end of simplicity is LaTeX. It's grea to focus on the content and not worry too much about the formatting while writing it. However, I find myself using Lyx more and more to write LaTeX documents. And then you "publish" to a pdf for the final step. It works, and lyx is amazing. However, LaTeX is a programming language unto itself; one in which I frequently forget the nuances until I can't get something to format or look the way I want. I then have to re-learn, or find my notes from prior trips down this path, the language and how to change the tags to do what I want. 

I find myself wanting something with slightly more structure and easy to use, standardized features than markdown. Simultaneously, I want something lighter than LaTeX for small or simpler content. Much like the story of Goldilocks and the Three Bears, I need something just right .o0 (or "just write" ha!)

I spent a week trying a few lightweight markup languages. The goal was to learn how productive I was at writing, and how it handled special cases--like math equations or code snippets. The criteria were pretty simple:

  1. Must be a plain text format. This means that it should work in vim or kate without issue. I must be able to 'less' or 'cat' it with ease.
  2. Must be a published standard or specification. One of the issues with markdown is there are various flavors, all slightly different enough to not be interoperable with each other. 
  3. Must be capable of directly converting to pdf. Other formats such as html and rtf are nice to have.
  4. Should let me focus on writing, not formatting. Shouldn't require a second pass to do the formatting. 
  5. Should be able to use it in my physical notebook. The bonus of plain text languages is that you can type and hand write them with ease.

After using various languages, I find that the content flows and the output succeeds with AsciiDoc. It took me about a week to learn the spec and formatting. However, it's not that steep of a learning curve. For practice, I converted a few markdown docs to asciidoc format. It's a pretty easy conversion and shows the power of asciidoc. Slightly more challenging to convert some latex docs to asciidoc. However, in both cases I have the pdf output, so I have a point of comparison. Happy to report that the conversion is simple and the output the same or better than the original format. 

The challenge now is to convert my notetaking system from markdown to asciidoc. The first challenge is finding a notetaking app that is asciidoc first, works on mobile, can securely sync between mobile and other, not cloud encumbered, and is free software (BSD or GPL licensed for example). It's a high bar to cross, but I'll find something. The simplest solution is probably to use syncthing to keep a Notes directory in sync and use any editor to edit/write in asciidoc format. 

For now, all new docs, reports, proposals are written in asciidoc. Writing notes or ideas in my physical notebook is also in asciidoc. As an aside, some day, OCR or scanning will work well enough that I can simply convert my handwritten notes to digital files. It doesn't work well now because I haven't had time to train an algorithm on my messy handwriting. I can read it, but a computer just sees blurred letters. All existing OCR systems fail to convert the written word into the correct text. 

I'll update as progress is made.