on May 30, 2011 by Phillip Lord in How To, Under Review, Comments (0)

It is possible to use the asciidoc to publish to a Knowledge Blog. This document describes why you might wish to do this, and how this is achieved.

## Author

Phillip Lord
School of Computing Science
Newcastle University
United Kingdom
NE3 4PH

phillip.lord@newcastle.ac.uk

## What is, and why asciidoc?

Asciidoc is a tool which allows authoring of richly-formatted documents, using a structured marked-up text document as a source. Asciidoc works well as a part of a toolchain and can be used to generate HTML, Docbook and a number of other formats. There is an associated tool, called blogpost which can be used to manage the process of posting articles written using asciidoc.

Authoring in this way has a number of advantages. Articles can be written as a simple text document. This allows easy use of versioning tools or collaborative sharing tools. Asciidoc provides a relative rich markup, which can manage external hyperlinks. It also deals well with mathematics, can apply syntax highlighting to program listings and provides the ability to define abbreviations. It is possible to define include statements, allowing, for example, use of a single author name and address file shared between many articles. Asciidoc is also extensible — although this is not well-supported by the Knowledge Blog process, this could, for example, be used to incorporate additional semantic markup into a Knowledge Blog. Finally, it is possible to use the asciidoc tool chain to generate a number of different formats — standalone HTML (not requiring a Knowledge Blog backend), PDF, or even a HTML based slideshow; this allows the author to use the same text in a number of different environments.

However, it also requires use of a (sometimes obscure) syntax, which means a relatively complex learning curve. As such, asciidoc is not ideal as a general-purpose end-user tool, being more suited to developers or those used to text markup languages. Other authoring environments, such as Word or google docs are better suited for other users.

## How to

Asciidoc and the associated syntax is already well-described through the main website. This article therefore describes those features which are specific its use within a Knowledge Blog.

Given that asciidoc is mostly useful for programmers, this how-to assumes a relatively high level of technical competance.

### Installation

Asciidoc is relatively widely-used, and is available as a package for many different different environments. I have used it under (Ubuntu) linux and MS Windows using the Cygwin packages. It is also possible to install from its main “tarball” distribution or from a Mercurial checkout; it has no dependencies (other than python) and can be run without further installation, from these environments.

Blogpost is less well used and has not yet been widely packaged, and must be installed directly from a tarball or the Mercurial repository.

### Usage

Asciidoc with blogpost supports a number of “attributes” which can be used to specify metadata for articles. For example, the first few lines of this document are (currently):

 Posting to a Knowledge Blog in asciidoc ======================================= :blogpost-categories: How To,Under Review :blogpost-status: published

This defines the title, the categories and that the article is draft or unpublished (which will have been changed to “published” by the time this is being read). Secondary files can be included with code such as:

  include::../../asciidoc-include/abbreviation.adoc[]

In this case, an extra space has been placed at the start of the line, to prevent asciidoc interpreting the include command directly, within this file.

This can be translated to HTML and posted to WordPress, using a single call to blogpost — it calls asciidoc internally — using this commandline:

 blogpost.py --mandatory-parameters=status,categories --conf-file process.conf post FILENAME.adoc

By default, blogpost assumes that the file is to be published as a post — using the commandline options, pages can also be created. The file, process.conf contains connection, username and password information, formatted like this:

 URL = 'http://process.knowledgeblog.org/xmlrpc.php' USERNAME = 'your username' PASSWORD = 'your password'

Obviously this file contains all the essential details someone else needs to break into your account, so you should be careful about where you place this file, if you are using tools such as Dropbox to work on the source collaboratively.

Blogpost is relatively intelligent about incorporated media — if images are included within the asciidoc source, these will be uploaded to the Knowledge Blog server, along with the HTML.

### Usage with Makefile

While direct use through the command line is possible, I prefer to drive blogpost through the use of a Makefile. Combined with the file-driven connection configuration, I use one directory per blog (one, for example, for this kblog, one for Ontogenesis and one for my own personal blog. This is particularly useful for maintaining a set of pages, as any changed source will be updated with a single command, or for writting a series of articles offline, which can then be published in batch at a later date.

This can be achieved with the following Makefile and a small, supporting python file. In practice, I include most of the contents of the Makefile from a single location, but this adds complexity so I have not shown it here.

 # -*- Makefile -*- SOURCES = $(shell echo *.adoc) TARGETS =$(filter-out *.blogpost,$(SOURCES:%.adoc=%.blogpost)) .SUFFIXES: .adoc .blogpost .adoc.blogpost: ## call blog post -- force status attribute blogpost.py --mandatory-parameters=status --conf-file process.conf post$< all: $(TARGETS) Makefile-generated: Makefile generate_makefile.py$(SOURCES) > Makefile-generated

The python functions just to generate dependency rules and is relatively simple.

 #!/usr/bin/env python import sys sys.argv.pop( 0 ) for i in sys.argv: stem = i.split( '.' )[ 0 ] print ( stem + ".blogpost: " + stem + ".adoc" ) print ( stem + ": " + stem + ".blogpost" )

It is also possible to replace the python file by directly including dependency rules generated by hand, of this form:

 filename: filename.blogpost filename.blogpost: filename.adoc

## Editing Environments

A number of different editors provide specialised support for asciidoc, which are more fully documented at the http://www.methods.co.nz/asciidoc/ website. Currently, I use Emacs with adoc-mode.

## Conclusion

While asciidoc is not a general-purpose tool, and has significant setup costs, it can be a very convenient method for kblogging, particularly for documents with a high technical content.

## Related Tools

Asciidoc is not the only light-weight markup tool which can be used for blogging; markdown or textile are also popular. A more complete list is available on Wikipedia. Tools such as sweave provide a more literate environment with the R statistical language, or Dexy which can use arbitrary programmatic languages to generate and incorporate content.