In the last couple of days I’ve been searching for a way to write some of my posts outside of the editor in Wordpress. I’ve been a user of the ViM editor for many years and I’ve gotten too used to editing documents with it. Using the editor in Wordpress seems to me to be slow and clunky.
Another problem I have with using the WP editor is that you have no version control either. It only stores the last set of changes you make. This doesn’t suit my writing style at all. I like to get a basic draft version out there and then make changes to it. On occasion though I’ve made changes that I don’t like and then can’t remember exactly what I had there before. This is where the version control comes in as it would be nice to roll back the change.
What I’ve been doing with my posts up to now is writing them in ViM and then adding some basic HTML markup for the blog posts. I’m just saving the files on my computer as plain text files which works relatively well. Last night I had this crazy idea that if I ever wanted to use the posts for something other than my blog, say turn them into a PDF, I would have to go through and edit out all the HTML tags.
Since the open source community has been using Docbook as the defacto standard for documentation for years I took a look at it. While doing some research I ran across another tool that I liked, called AsciiDoc.
Docbook
Docbook is a semantic markup language. It was designed and intended for technical documentation related to computer hardware and software. It is a presentation-neutral way of writing a document. What all this means is you write your document and add markup tags to it for things like title, paragraph, chapters, sections, etc. You do not worry about what it looks like. Then the marked up document you created gets run through a process where the presentation is defined in stylesheets.
The process of doing this is much simpler than it sounds. If you know how to write HTML code you can easily write with Docbook tags. You can also decide on what kind of format the presentation will be in whether it be HTML or PDF.
AsciiDoc
AsciiDoc on the other hand is writing documents in plain Ascii text. No tags to learn. By creating a row of certain characters under a line you can define sections. Writing paragraphs is simple as well. No tags just a line of whitespace between paragraphs. When running the file through the asciidoc command you can specify what kind of output you want. This is what really convinced me to use AsciiDoc. I can run my document through asciidoc and get a document marked-up with Docbook. So now I have the power of Docbook but I don’t have to learn all the different tags that go along with it.
Conclusion
I believe that the easiest solution to my problem is using AsciiDoc. There is very little to learn besides which characters to use for underlining sections and so on. I could use SVN on my text files but by using AsciiDoc I can always change the format of the output in the future. So AsciiDoc it is. If anybody is interested in the source documents for these posts, leave a comment. I might look at the possibility of providing them online.
External Links
No related posts.
Related posts brought to you by Yet Another Related Posts Plugin.
One Response to “Docbook or AsciiDoc?”
Maybe you should take a look to Markdown. It’s simpler than AsciiDoc and more suitable for tasks like writing blog posts IMHO.