Wednesday November 22, 2006

Markup quest

Markup quest

Most of the documents I am dealing with have a simple structure. They need to have sections and subsections, numbered and unnumbered lists, a few different founts for emphasizing things (like code fragments and things to pay attention to). Occasionally I use tables and sometimes hyperlinks to other parts of the same document or some useful external links.

Here are some candidates I have considered so far:

• Plain old ASCII
• Perl Plain Old Documentation Format (POD).
• HTML
• LaTeX
• Texinfo - The GNU Documentation System

There are, probably, a whole bunch of other things that I am not very familiar with:

• nroff
• Lout
• DocBook
• SGML
• Your favorite markup language here...

ASCII lacks any structure and although there are some automatic converters of text to HTML, the author still have to use some implicit markup structure to communicate intentions to the conversion tool.

Perl POD is simple enough and is quite suitable for something resembling man pages, but its support for lists is buggy and the support for hyoperlinks is missing. It has converters to HTML, ASCII, LaTeX, bubdled with Perl, so I use it once in a while.

Texinfo is pretty powerful, but I just never understood it, it might be the best choice, though.

HTML may be a good choice and there is HTML->LaTeX converter. But why use it if we can use LaTex directly?

This leaves me with LaTeX which provides very powerful facilities and can be combined with latex2html to produce HTML. That is what I used for various documentation for the CPU Caps project. LaTeX provides very powerful markup facilities and a whole bunch of third-party packages (unfortunately most of them are unlikely to be interpreted correctly by latex2html). As a bonus, LaTex has a pretty powerful Emacs AUCTeX support.

Here are some tricks that I use in LaTeX to deal with on-line documents. The document starts with the following preamble:

\documentclass{article}
\usepackage{url}
\usepackage{html}

Sometimes, I use \documentclass[twoside]{article} or \documentclass[twocolumn,twoside]{article} to produce two-sided or two column documents.

The url package allows me to say things like \url{http://www.opensolaris.org} to point readers to various external resources.

The htmlextension package provides some nice features for the latex to HTML conversion. One that I actually use is a way to provide hypertext links where I can control the link and its text separately: \htmladdnormallink {link name} {link-URL}

As an example, when I want to mention various bug IDs in the document I define the following macro:

% Provide URL for a bug ID for latex2html.
\newcommand{\bug}[1]{\htmladdnormallink{#1}
  {http://bugs.opensolaris.org/bugdatabase/view_bug.do?bug_id=#1}
}

[ Technorati: LaTeX, markup, HTML, documentation, ]