Wednesday November 22, 2006 Weblog
Wednesday November 22, 2006 Markup quest
Every time I start a new document I face the same problem - what markup language to use for it? My high-level goal is pretty simple - I need a good way to create good looking printed documents and Web pages from a single source. I guess, everyone has his/her own solution. I'll just describe what I use currently.
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:
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}
}
\bug{6468451} in the document and both printed
and WEB will show bug ID while WEB version will show a hyperlink to the bug
description in the OpenSolaris bug
database.
It would be interesting to know how others solve the same problem.
[ Technorati: LaTeX, markup, HTML, documentation, ]
( Nov 22 2006, 02:01:15 PM PST ) Permalink Comments [2]
