Introduction to DocBook - eBower.com · Introduction to DocBook DocBook provides a common format...

Introduction to DocBook

DocBook provides a common format for documentation that canbe converted to many differentfile types quickly and easily, this document describes how toget up and running quickly.

1. Introduction to DocBook

The DocBook format uses XML or SGML to create a generic document. It focuses on the content of thedocument rather than the formatting, this allows you to quickly and easily use style sheets to convertentire libraries into custom formats without needing to open a single document for editing.

A DocBook file looks a bit like an HTML file. To see what the DocBook Language looks like, click the"DocBook Inline" link at the top of this page. You’ll also note that you can download the source fileitself, this is useful if you need to edit someone else’s DocBook file as you don’t need to recreate it fromscratch.

This document won’t describe the details of the DocBook language and history, however it will providesome links inAppendix Bfor you that can help you learn.

2. DocBook Requirements and Components

DocBook is a portable format so it works equally well on all platforms. But some platforms are moreequal than others. This document assumes that you’ve got access to a Linux machine as your primarymeans of compiling a DocBook document. If you want to run DocBook on your Mac or Windows laptopone of the more flexible means of doing so is to install Linux asa virtual machine using a program likeVirtualBox (http://www.virtualbox.org).

Assuming you’ve got a Debian-based system like Ubuntu installing DocBook requires the commandsudo apt-get install docbook-utils. That’s it. You’re done. Well, mostly. The scripts I’ve published hereare linked inAppendix Aand there is also a more comprehensiveapt-get statement.

2.1. Creating a DocBook File

I recommend creating a new directory for each document, it’sup to you if you want to create furthersubdirectories to organize things. My method is to create a docs directory with an index document athttp://www.ebower.com/docs and then have each document a subdirectory off of that. I name each

1

.docbook file with the same base filename as the directory (forexample,docs/Document-Subject/Document-Subject.docbook). Finding what works for you is importanthere.

There is no WYSIWYG editor for DocBook stuff (actually, several exist but you and Google need toshare some alone time to see if any fit your needs). The first step in creating a DocBook is to load upyour favorite text editor VIM (if you’re an Emacs user simplytype Ctrl-Fn-Command-Alt-F12-D and theLISP interpreter will pretend to understand the DocBook XMLformat). The easiest route is to open upsomeone else’s document to see what it looks like. The tags are fairly well-named so comparing theHTML version of the file to the DocBook version should be pretty intuitive. I’d recommend creating atemplate (../docbook.template) file, just an empty file withbasic headers and fundamental buildingblocks so you can reference common tasks quickly. You can then copy this template file over and edit itrather than typing the header information in every time.

Example 1. An example DocBook template

<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML v4.5//EN" "/usr/share/xml/docbook/schema/dtd/4.5<article lang="en">

<articleinfo><keywordset><keyword></keyword>

</keywordset><title></title><abstract><para></para>

</abstract></articleinfo><section id="">

<title></title><para></para>

</section></article>

In February 2010 I modified my template to include an appendix. Currently this is used to refer to aforum post for comments and suggestions, but the number of insightful posts (currently 1) isoverwhelmed by the spammers (which is >>1). This appendix can also be used to reference changerequest numbers for requirements, or any other "once-and-done" editable information. While I was at it Iranxml_pp to normalize the formatting.

In January 2011 I also added functionality for INCLUDE statements which will dynamically include atext file at compilation time. I use this for an "About Me" page, but any semi-dynamic content will work.I use the made-up term "semi-dynamic" because it only gets read at compile and not on view. This isperfect for my needs.

2


2.2. Compiling a DocBook Document

Once you’ve created a DocBook document you’ll probably wantto compile it into something that’s a bitprettier. A simple place to start is with thedocbook2html command. When you run this command withan argument of the filename you’re working with you should endup with an HTML file for each section.If you rundocbook2html -u filename you should have a single HTML file with the entire document.

There are a slew of other converters installed for various formats such as PDF, TXT, and RTF. You mayfind that it’s more efficient to use a script to create multiplefiles at once so you don’t have to rememberthe parameters of each one. I’ve also added Charlie Gero’s set of links to the top of my HTML files toallow for easy downloads. The script I use is in/usr/bin/dbcompile and the contents can be seenbelow.Skip past listing.

Example 2. An example DocBook compile script

#!/bin/bash

# Version 0.1.2.1

#First setup some variables#This is the current directory level represented by the number of / characters#For example, to use a filename in /home/user you need 3 slashes.directorylevel=$(pwd|sed ’s/[^/]//g’|wc -m)

#Finds the name of the current directory.bottomlevel=$(pwd | cut -d/ -f$directorylevel)

#Set up some filenamesorigfilename=$bottomlevel.docbookfilename=$bottomlevel-proc.docbookbasefilename=$(basename $filename .docbook)tablefilename=table.html

if [ -f ~/.dbcompile/dbcompile.header ]; thentableheader=~/.dbcompile/dbcompile.headerecho Found custom header file in $tableheader

elsetableheader=/etc/dbcompile/dbcompile.header

fi

echo Running custom scriptif [ -e "run-on-compile" ]; then

echo Found script!chmod 755 run-on-compile./run-on-compile

elseecho No script found.

fi

echo Running Spellcheck on Original $note we don\’t check the INCLUDES$xml_spellcheck $origfilename

3

echo Cleaning up Spellcheck filesrm xml_spellcheck_*.txtrm xml_spellcheck_*.bak

echo Making the XML Print Pretty on the originaldocbook_pp $origfilenamexml_pp -p programlisting -i.last $origfilename

OPERATION_RESULT=$?if [ $OPERATION_RESULT != 0 ]; then

echo Exit Code: $OPERATION_RESULTexit $OPERATION_RESULT

fi

echo Processing INCLUDESif [ -f "$filename" ]; then

rm $filenamefi

includefound=false

while read linedo

if [ ! "$line" = "" ]; thenecho "$line" >> $filename

fiiscomment=$(echo $line | awk ’{print $1}’)command=$(echo $line | awk ’{print $2}’)if [ "$iscomment" = "" >> $filename

elseecho Can\’t find $includefile, aborting.exit 2

fifi

done < $origfilename

if [ $includefound = "true" ]; thenecho Done processing includes.

elseecho No INCLUDE tags found.

fi

echo Making the XML Print Prettydocbook_pp $origfilenamexml_pp -p programlisting -i.last $filenameOPERATION_RESULT=$?if [ $OPERATION_RESULT != 0 ]; then

4


echo Exit Code: $OPERATION_RESULTexit $OPERATION_RESULT

fi

echo Updating changelogdatelog "$1"

echo Creating HTML...docbook2html -u $filename

echo Creating TXT...docbook2txt $filenamemv $basefilename.txt $bottomlevel.txt

echo Creating PS...docbook2ps $filenamemv $basefilename.ps $bottomlevel.ps

echo Creating PDF...# Docbook2PDF is a little broken when it comes to images, using ps2pdf instead# docbook2pdf $filenameps2pdf $bottomlevel.ps

echo Creating RTF...docbook2rtf $filenamemv $basefilename.rtf $bottomlevel.rtf

#To create the inline we need to take the original and remove the#special characters.

echo Creating DocBook Inline...cat $filename | sed -e ’s~&~\&~g’ -e ’s~<~\<~g’ -e ’s~>~\>~g’ \

> $filename.ildb

echo Creating Wiki...docbook2wiki $filenamemv $basefilename.wiki $bottomlevel.wiki

echo Generating header...rm $tablefilename 2> /dev/nullcat $tableheader | grep -v ’^#’ \

| sed s/\$DB_BASENAME/$bottomlevel/ > $tablefilename

# The following code is left for historical purposes and will be removed# in a future release.##echo \<style\>body\{font-family\: helvetica, sans-serif\;\} td\{border\: \# 1px solid black\; padding\: 2px\;\} table \{ width\: 80\%\; \# border-collapse\: collapse\;\} table.BLOCKQUOTE \{width\: 100\%\} \# table.BLOCKQUOTE td \{border\: 0px\;\}\</style\> >> $tablefilename#echo \<table bgcolor=#BBEEFF width=100% style=\"width\: 100%\"\> >> \# $tablefilename#echo \<tr\> >> $tablefilename#echo \<td style="font-family: helvetica, sans-serif;font-size:11pt;"\>\

5


# \<b\>View:\</b\> \<a href="index.html"\>HTML\</a\> \| \# \<a href="$bottomlevel.txt" rel="nofollow"\>Text\</a\> \| \# \<a href="$bottomlevel.ps" rel="nofollow"\>PS\</a\> \| \# \<a href="$bottomlevel.pdf" rel="nofollow"\>PDF\</a\> \| \# \<a href="$bottomlevel.rtf" rel="nofollow"\>RTF\</a\> \| \# \<a href="$bottomlevel.docbook" rel="nofollow"\>DocBook\</a\> \| \# \<a href="$bottomlevel.docbook.html" rel="nofollow"\>DocBook Inline\</a\> \ \| \# \<a href="changelog.html"\>changelog\</a\> \| \# \<a href="https://www.ebower.com/docs/docbook/"\>about this header\</a\>\</td\> >> $tablefilename#echo \</tr\> >> $tablefilename#echo \</table\> >> $tablefilename

echo Merging table into HTML file...cat $tablefilename > index.html ; cat $basefilename.html >> index.html

echo Making index file Print Pretty...tidy -m -i -q index.html &> /dev/null

echo Merging table into Inline Docbook file...cat $tablefilename > $origfilename.htmlecho \<pre style=white-space\:pre-wrap\> >> $origfilename.htmlcat $filename.ildb >> $origfilename.htmlecho \</pre\> >> $origfilename.html

echo Making Inline Docbook file print pretty...tidy -m -i -q $origfilename.html &> /dev/null

echo Cleaning up after myself...rm $filename.ildbrm $tablefilename# For some reason the DocBook file ends up losing global read permissionschmod +r $filenamechmod +r $origfilename

It assumes that you’ve created a directorysubject and inside there is asubject.docbook file. Icreate anindex.html file which will provide links to the other formats which are all also contained inthe same directory.

As of Feb 2010 I’ve updated this script to includexml_pp to help make the XML itself a little moreuniform. This program is in thexml-twig-toolspackage and it will reformat the tag indents for you. Thescript will save your last docbook file as filename.docbook.last in case it screws something up. Since itdoesn’t actually edit the file in a meaningful way you can continue yourvi session with impunity andoverwrite the new file if that’s how you roll.

I’ve also added a spellcheck to the script fromxml_twig_tools. The spellcheck engine is actuallyaspell and if you accidentally add a word to the dictionary that you didn’t intend, edit~/.aspell.en.pws (assuming you’re using English, of course).

6


In February 2010 I added a changelog mechanism. This adds a changelog link at the end of the htmldocument which lists when the document was first compiled, when it was last compiled, and anymilestones you wish to record. By issuing the commanddbcompile "Updated table 7" a milestone willappear with the current date associated with it. If there is no text supplied the compile with be largelyinvisible except for the Last Compiled line changing. This is intentional since many times I needmultiple compiles because of a missing bracket or a simple typo and these compiles do not need to belogged. If you feel every compile should be logged, feel freeto editchangelog.html yourself.

Example 3. Logging Changes

#!/bin/bash#Set the date variablestoday=$(date +"%Y %b %d")now=$(date +"%H:%M %Z")logfile=changelog.html

#Create changelog if it doesn’t exist

if [ -e "$logfile" ]; thenecho Changelog found#Remove the last change messagesed ’$d’ $logfile > $logfile.tempmv $logfile.temp $logfile

elseecho Creating new changelogecho \<pre\>Document created $today at $now > $logfile

fi

if [ -n "$1" ]; thenecho $today "$1" >> $logfile

fi

#Add the last compile time todayecho Last change $today at $now \</pre\> >> $logfile

In April 2010 I added a mechanism to run a custom script on compile. Thedbcompile script now checksfor a file calledrun-on-compile and, if found, will first ensure its permissions are 755 and then run it.This function is useful if you need to link a live file, in that caserun-on-compile would simply containthecp command.

After playing with all sorts of ways to get external file references in through official means, in January of2011 I’ve modified my script to recognize an HTML-style comment of the format<-- INCLUDE

filename -->. During the processing withdbcompile I’ll replace this comment with the contents ofthe named file if it exists, or error out if it doesn’t exist. Note that a normal DocBook compiler willsimply skip over this step, you can view the DocBook (docbook.docbook) file to see what thepre-processed DocBook format looks like (with just the INCLUDE tag) or you can look at the DocBookInline (docbook.docbook.html) link and check out the "About Me" appendix to see how it looks afterI’ve included the text. The nice thing about this is that it doesn’t break standard implementations but itprovides the "nearly live" functionality I’m looking for.

7


Also in January 2011 I modified the script such that the links to documents in other formats (forexample, the PDF version) has the "nofollow" tag. This tag really just affects search engines and preventsthem from indexing these documents. Since they’re a clone ofthe HTML document (minus links) it’s notuseful for Google to pull up a PostScript or Text file when the HTML main page is available.

As a part of this change I also moved the header file to/etc/dbcompile/dbcompile.header. Thisallows me to make the HTML for the header table listing the various formats look a little nicer. You canalso more easily replace this with a custom header in~/.dbcompile/dbcompile.header in caseyou’d like to customize things. An exampledbcompile.header appears below.

Example 4. Default Header Table

# This file is a template for the dbcompile header table. It ignores lines# starting with "#" and replaces $DB_BASENAME with the base DocBook filename.# For example, to reference the text version of foo.docbook, use# $DB_BASENAME.txt## You may copy this file to ~/.dbcompile/dbcompile.header and edit as you wish.

<style>body{font-family: helvetica, sans-serif;}td{border: 1px solid black; padding: 2px;}table { width: 80%; border-collapse: collapse;}table.BLOCKQUOTE {width: 100%}table.BLOCKQUOTE td {border: 0px;}

</style>

<table summary="Table for formatting only" bgcolor=#BBEEFF width=100% style="width: 100%"><tr>

<td style="font-family: helvetica, sans-serif;font-size:11pt;"><b>View:</b> <a href="index.html">HTML</a> |<a href="$DB_BASENAME.txt" rel="nofollow">Text</a> |<a href="$DB_BASENAME.ps" rel="nofollow">PS</a> |<a href="$DB_BASENAME.pdf" rel="nofollow">PDF</a> |<a href="$DB_BASENAME.rtf" rel="nofollow">RTF</a> |<a href="$DB_BASENAME.wiki" rel="nofollow">Wiki</a> |<a href="$DB_BASENAME.docbook" rel="nofollow">DocBook</a> |<a href="$DB_BASENAME.docbook.html" rel="nofollow">DocBook Inline</a> |<a href="changelog.html">changelog</a> |<a href="https://www.ebower.com/docs/docbook/">about this header</a>

</td></tr>

</table>

As a final part of this update, I’ve also started usingtidy to make the HTML more rational. Not only doesdocbook2html produce ugly output, but my kludge of tacking the table to thebeginning (before thebody and meta tags) probably breaks some simplistic browsers or web crawlers. This adds a dependencyof tidy.

8


In February 2011 I introduced another helper tool,docbook_pp (DocBook Print Pretty). This workshand-in-hand withxml_pp to normalize some formatting. While I expect this to grow in size, currently itis primarily responsible for ensuring that<para> tags exist on their own line. This helps with my poorattempt to convert from DocBook to Wiki format.

Example 5. docbook_pp

#!/bin/bash

# Version 0.1.2.1

# docbook_pp is meant to pre-process a DocBook file before it’s fed into xml_pp

tempfile=/tmp/$1_pp.$$.tmpbackup=$1_pp.bak

if [ ! $# = 1 ]; thenecho Usage:echo " $(basename $0) filename"exit 1

fi

if [ ! -f "$1" ]; thenecho File \"$1\" not found.exit 2

fi

echo Preformatting $1echo Backup saved at $backup

cp $1 $backup

sed -r \-e s/’<para>(.)’/"<para>\\n\\1"/g -e s/’(.)<\/para>’/"\\1\\n<\/para>"/g \$1 > $tempfile

mv $tempfile $1

2.2.1. PDF Files

Thedocbook2pdf command doesn’t like to insert the images properly. My scripts will call ps2pdf afterthe PostScript file is created instead.

2.2.2. Text Files

There is an undocumented dependency on the text-based browser Lynx to create proper text files.Runningsudo apt-get install lynx should clean that up for you. Thanks to David Gay for discoveringthis.

9


2.2.3. Wiki Files

Sometimes it’s useful to be able to export a DocBook file to a Wiki page. This is a tricky thing to actuallypull off, Wiki pages are designed to be edited by a group whileDocBook files are more traditionaldocuments with tighter controls. One of the primary functions of this process is to migrate control of thedocument to the public, as of now there’s not a good method of keeping Wiki changes in sync with yourDocBook source. Hopefully soon I’ll be able to work on awiki2docbook that will help keep theDocBook version up-to-date, in the mean time this may be a good way to hand off the document tosomeone else who isn’t enlightened enough to use DocBook.

Thedocbook2wiki script is an early beta. It handles most of the tag I use, but none that I don’t. Thereare also likely significant flaws in the processing of potentially complex entities like tables. There willalso probably be issues if you don’t write your documents in my style or usedbcompile to preformatthem. Please read the notes at the beginning of the script fora list of known issues and feel free tocontact me if you run into troubles. The output seems to work well with my work’s WikiMedia-basedWiki page, but there isn’t a hard-and-fast standard.Skip past listing.

Example 6. docbook2wiki

#!/bin/bash

# Version 0.1.2.1

# Fundamentally is this a good idea? It can be used to migrate from DocBook# to Wiki but Wiki is dynamic and Docbook is static. Another project will be# wiki2docbook but a lot of tag info is lost.

# Known issues:# URLs with "file://" are not supported on Wiki?# Relative URLs are not supportable on Wiki# Try to keep tags on unique lines in DocBook, and use xml_pp before processing# No support for images (yet)# Table support likely very weak# Title support needs work, can omit main document title, have it as parent# (pushing other sections down a level), or have it as first topic# (incrementing other sections by one)# Meta tags not often supportable on Wiki# Appendix tags are rendered as ordinary sections# Included files sometimes skip last character of the line, expecially "if"s

if [ ! $# = 1 ]; thenecho Usage:echo " $(basename $0) filename"exit 1

fi

if [ ! -f "$1" ]; thenecho File $1 not foundexit 2

fi

10


echo Warning: Using hardcoded catalogs and stylesecho Working on: $(pwd)/$1

printmeta=falsefilebase=$(basename $1 .docbook)inputfile=$1programbasename=$(basename $0)tempdir=/tmp/$programbasename.$$sectionfile=$tempdir/$filebase.sectionsoutputfile=$filebase.wikipreprocessedoutput=$tempdir/$filebase.tmptempoutput=$tempdir/$filebase.tmp.wikimode=normallevel=0debug=0

mkdir $tempdir

# Set up wiki markupssectionbreak=\=bold=\’\’\’bold_end=$bolditalic=\’\’italic_end=$italicbold_italic=\’\’\’\’\’bold_italic_end=$bold_italicfixedwidth=’<tt><nowiki>’fixedwidth_end=’<\/nowiki><\/tt>’bullet=’*’number=’#’code=’ ’int_link=’[[’int_link_end=’]]’ext_link=’\[’ext_link_end=’\]’hline=’----’

# Set up mapping between DocBook and Wiki markupscommand=$boldcommand_end=$bold_endemphasis=$italicemphasis_end=$italic_endfilename=$fixedwidthfilename_end=$fixedwidth_endcomputeroutput=$fixedwidthcomputeroutput_end=$fixedwidth_end

function global_process {# This function does global search and replace on the entire line.cat $inputfile | sed -r \

-e s/’<para>’//g -e s/’<\/para>’/_/g \-e s/’<abstract>’//g -e s/’<\/abstract>’/"__TOC__"/g \

11

-e s/’<command>’/$command/g -e s/’<\/command>’/${command_end}/g \-e s/’<filename>’/$filename/g -e s/’<\/filename>’/$filename_end/g \-e s/’<computeroutput>’/$computeroutput/g \-e s/’<\/computeroutput>’/$computeroutput_end/g \-e s/’<emphasis>’/$emphasis/g -e s/’<\/emphasis>’/$emphasis_end/g \-e s/’<thead>’/"!"/g -e s/’<\/thead>’/"!!"/g \-e s/’<row>’/"|-"/g -e s/’<\/row>’//g \-e s/’<tbody>’//g -e s/’<\/tbody>’//g \-e s/’<entry>’/"|"/g -e s/’<\/entry>’//g \-e s/’<\/table>’/_/g \> $preprocessedoutput

}

function line_process {# This function does a line-by line process of the fileprocessed_line_whitespace=$(echo "$line" | \sed -r \

-e s/’<\?xml(.*?)\?>’//g \-e s/’’//g \-e s/’<!DOCTYPE(.*?)>’//g \-e s/’<article(.*?)>’//g \-e s/’<\/article(.*?)>’//g \-e s/’<email>(.*?)<\/email>’/"[mailto:\\1 \\1]"/g \-e s/’<tgroup(.*?)>’/’{| border="1" frame="border" rules="all" class="CALSTABLE"\n|+ ’"$tabletitle"/g

)# Regexps are greedy, so more than one <ulink> per line is problematic# We replace the </ulink> with <</ulink>> one at a time until we’ve got them# all. Not efficient, but it works.while [ ! "$(echo "$processed_line_whitespace" | grep ’</ulink>’)" = "" ]; do

processed_line_whitespace=$(echo "$processed_line_whitespace" | \sed s/’<\/ulink>’/’<<\/ulink>>’/)

if [ "$debug" -gt 6 ]; thenecho "Hunting ulinks, be vewwwy quit! $processed_line_whitespace"

fiprocessed_line_whitespace=$(echo "$processed_line_whitespace" | \sed -r s/’<ulink url="(.*?)">(.*?)<<\/ulink>>’/"$ext_link\\1 \\2$ext_link_end"/g)

doneprocessed_line=$(echo "$processed_line_whitespace")

}

function check_for_title {# Checks to see if $processed_line contains a <title> tag and extracts to# $title. Sets $istitle to true/false and changes mode to "look_for_title"# to force certain behaviors.title=$(echo $processed_line | sed -r s/’<title>(.*?)<\/title>’/\\1/g)if [ "$title" = "" ] || [ "$title" = "$processed_line" ]; then

istitle=falseelse

mode=look_for_titleistitle=true

fiif [ "$debug" -gt 6 ]; then

echo "istitle : \"$istitle\""

12


fi}

# Do a global processing of the fileglobal_process

# Process the input file line-by-line and put output into $tmpoutputcat $preprocessedoutput |while read line; do

if [ "$debug" -gt 6 ]; thenecho ""echo "Line Start Mode : $mode"echo "Unprocessed Line: \"$line\""

fiprintline=trueline_processif [ "$debug" -gt 6 ]; then

echo "Processed Line : \"$processed_line\""fi# If there’s a blank line, don’t print it unless you’re in a <programlisting># block.if [ "$processed_line" = "" ] && [ ! "$mode" = "programlisting" ]; then

printline=falsefi

# We need to check for the document title at level 0if [ "$level" = 0 ]; then

check_for_titlefi

# Do special things based on the mode we’re incase "$mode" in

"look_for_title")title=$(echo $processed_line | sed -r s/’<title>(.*?)<\/title>’/\\1/g)if [ ! "$title" = "" ] && [ ! "$title" = "$processed_line" ]; then

if [ ! "$level" = 0 ]; thenecho "$sectionid=$title" >> $sectionfile

fiif [ $debug -gt 3 ]; then

echo Found new section at level $level called \"$title\"fiprocessed_line="$sectionbreak $title $sectionbreak"if [ $level = 0 ]; then

if [ "$debug" -gt 6 ]; thenecho "Found document title"

fi# This line will create a new section for the title, incrementing the other# sections by one.# processed_line="$sectionbreak$sectionbreak $title $sec$sec"

# This line will create a master section for the title, indenting subsequent# sections by one# processed_line="$sectionbreak $title $sectionbreak"

13


# These lines will create a simple bold version of the title followed by a# horizontal line, leaving the section hierarchy alone.

echo "$bold$title$bold_end" >> $tempoutputecho "$hline" >> $tempoutputprocessed_line="_"

fimode=normal

fi;;"keyword")keyword=$(echo $processed_line | sed -r s/’<keyword>(.*?)<\/keyword>’/\\1/g)if [ ! "$keyword" = "" ] && [ ! "$keyword" = "</keywordset>" ]; then

printline=falseif [ $debug -gt 3 ]; then

echo Found new keyword called \"$keyword\"keywords="$keywords$keyword "

fifi

;;"example")check_for_titlemode=exampleif [ "$istitle" = "true" ]; then

processed_line="${bold}Example:${bold_end} $title"if [ "$debug" -gt 6 ]; then

echo "Found example title \"$title\""fi

elseexamplefilename=$(echo $processed_line | awk -F "\"" ’{print $2}’)exampletype=$(echo $processed_line | awk -F "\"" ’{print $4}’)if [ "$debug" -gt 6 ]; then

echo "Example filename: \"$examplefilename\""echo "Example type : \"$exampletype\""

ficase "$exampletype" in

"linespecific")if [ -f "$examplefilename" ]; then

processed_line="_"(

IFS=’\n’cat "$examplefilename" |while read "exampleline"; doecho "$code$exampleline" | sed s/’<’/’\<’/g >> "$tempoutput"

done)if [ "$debug" -gt 6 ]; then

echo "Adding filename $examplefilename"fi

elseecho File "$examplefilename" not foundif [ "$debug" -gt 6 ]; then

echo "\"$examplefilename\" not found"

14


fiecho "${italic}${bold}ERROR! $examplefilename not found!${italic_end}${bold_end}"processed_line="_"

fi;;"")printline=false

;;esac

fi;;"programlisting")if [ ! "$processed_line" = "</programlisting>" ]; then

processed_line="$code$(echo "$processed_line_whitespace" | sed s/’<’/’\<’/g)"fi

;;"list")if [ ! "$processed_line" = "" ]; then

processed_line="$bullet $processed_line"mode=normal

fi;;"table")check_for_titlemode=normalif [ "$istitle" = "true" ]; then

tabletitle="$title"printline=falseif [ "$debug" -gt 6 ]; then

echo "Found table title \"$title\""fi

fi;;"thead")if [ ! "$processed_line" = "|-" ]; then

processed_line=$(echo "$processed_line" | sed s/’|’/’!’/)fi

;;esac

# Now we check the $processed_line to see if we need to change modescase "$(echo $processed_line)" in

’<section’*)mode=look_for_titlelevel=$(echo "$level + 1" | bc)sectionbreak="$sectionbreak="sectionid=$(echo $processed_line | awk -F "\"" ’{print $2}’)printline=falseif [ "$debug" -gt 6 ]; then

echo "Found section start - level: $level id: $sectionid"fi

;;"</section>")

15


mode=normalsectionbreak=${sectionbreak:0:$level}level=$(echo "$level - 1" | bc)printline=falseif [ "$debug" -gt 6 ]; then

echo "Found section stop - level $level"fi

;;’<appendix’*)mode=look_for_titlelevel=$(echo "$level + 1" | bc)sectionbreak="$sectionbreak="sectionid=$(echo $processed_line | awk -F "\"" ’{print $2}’)printline=falseif [ "$debug" -gt 6 ]; then

echo "Found section start - level: $level id: $sectionid"fi

;;"</appendix>")mode=normalsectionbreak=${sectionbreak:0:$level}level=$(echo "$level - 1" | bc)printline=falseif [ "$debug" -gt 6 ]; then

echo "Found section stop - level $level"fi

;;"<programlisting>")mode=programlistingprintline=false

;;"</programlisting>")mode=normalprocessed_line=""

;;"<keywordset>")mode=keywordkeywords="{{keywords>"printline=falseif [ "$debug" -gt 6 ]; then

echo "Found keyword start"fi

;;"</keywordset>")mode=normalkeywords="$keywords}}"processed_line=$keywordsif [ "$printmeta" = false ]; then

printline=falsefiif [ "$debug" -gt 6 ]; then

echo "Done adding keywords \"$keywords\", printmeta is $printmeta"fi

16


;;"<example>")mode=exampleprintline=falseif [ "$debug" -gt 6 ]; then

echo "Found example start"fi

;;"</example>")mode=normalprintline=falseif [ "$debug" -gt 6 ]; then

echo "Found example end"fi

;;"<listitem>")mode=listprintline=falseif [ "$debug" -gt 6 ]; then

echo "Found list item"fi

;;"</listitem>")mode=normalprintline=falseif [ "$debug" -gt 6 ]; then

echo "Found list item end"fi

;;"<itemizedlist>")listmode=itemizedprintline=falseif [ "$debug" -gt 6 ]; then

echo "Found itemized list"fi

;;"</itemizedlist>")listmode=noneprintline=falseif [ "$debug" -gt 6 ]; then

echo "Found itemized list end"fi

;;"<table"*)mode=tableprintline=false

;;"!")# This can be changed to <thead>, I misunderstood the wiki markupmode=theadprintline=false

;;"!!")

17


# This can be changes to </thead>mode=normalprintline=false

;;" _")# This is a kludge saying that we need to print a blank line in a# <programlisting> tagprocessed_line=" "

;;"_")# By default I through away blanks, but sometimes we need them. This# is most commonly a </para> tag.processed_line=""

;;esac

if [ $printline = true ]; thenecho "$processed_line" >> "$tempoutput"if [ "$debug" -gt 6 ]; thenecho "Output line : \"$processed_line\""

fifi

done

# xref tags stink. We need to associate the section ID to the section name# I store these as I find them and then do one pass through the temp file# for every section. There must be a better way...echo Processing xref tagscat $sectionfile |while read line; do

sectionid=$(echo "$line" | awk -F "=" ’{print $1}’)sectionname=$(echo "$line" | awk -F "=" ’{print $2}’)if [ "$debug" -gt 6 ]; then

echo Processing $sectionid $$sectionname$fised -r -e s^’<xref linkend="’$sectionid’"(.*?)\/>’^"[[#$sectionname|$sectionname]]"^g "$tempoutput"mv "$tempoutput".tmp "$tempoutput"

done

cp "$tempoutput" "$outputfile"

rm -r $tempdirecho Done.

2.3. Doing a Global Update

Sometimes it makes sense to just globally recompile all documents. An example of this is an update tothe stylesheets or just as a catchall to ensure that the latest files are included in the builds. When thishappens, a simple script I’ve calleddb-rebuildall can be run.

18


Example 7. A global rebuild script

#!/bin/bashdbcompilefor DIR in *do

if [ -d $DIR ]then

cd $DIRecho ""echo Executing global rebuild for $DIRdbcompile "Routine global rebuild"cd ..

fidone

2.4. Publishing DocBook Files

Generally the easiest method of publishing the DocBook filesis to put them on a webserver and share alink to the HTML formatted document. This allows the user to download any other formats that mayappeal to them if they need to read them offline and it helps prevent filling up mail quotas.

3. Hello World

It’s taken me a long time to realize that I was missing the quintessential part of any programming-relatedtopic - the infamous "Hello World" example. Granted, I do break Hello World a bit in that I try to get abunch of simple functions in a single document, but here (helloworld.docbook) is the DocBook file andhere (helloworld.html) is the compiled HTML (if you view thesource you’ll note it’s ugly HTML, hencemy use oftidy to clean things up):

Example 8. helloworld.docbook

<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML v4.4//EN" "/usr/share/xml/docbook/schema/dtd/4.4<article lang="en">

<articleinfo><keywordset><keyword>hello</keyword><keyword>world</keyword>

</keywordset><title>Hello World</title><abstract><para>

A very simple, but complete, DocBook document.</para>

</abstract>

19


</articleinfo><section id="hello">

<title>Hello</title><para>

World!</para>

<para>I don’t do anything fancy in this document, but I did want to show you a basicdocument that should compile just fine. It’s sometimes hard to find completeexamples like this, many snippets work well is you know what XML is supposedto look like but if you’re new to the topic it can be confusing.</para>

<para>You don’t need the carriage returns at the end of every line, but when I put itinto a listing in my main document it doesn’t provide word wrapping. Ina normal compilation excess whitespace and line breaks are ignored.</para>

<para>To compile this document, simply download it and run <command>docbook2html -u helloworld.docbook</command>.This should create <filename>helloworld.html</filename> which you can openin any web browser and it should look something like<ulink url="helloworld.html">this</ulink>.</para>

<section id="nesting"><title>Nesting</title><para>

You can nest many things like <emphasis>sections</emphasis>, but note thatyou’ll need to close each one individually.</para>

</section></section><appendix id="other-objects">

<title>Other Objects</title><para>

Other objects like tables and images just go between <para> objects(note the use of HTML-style escape characters for things like <, >, (non-breaking space), &, ", and others - a search for HTMLescape characters should turn up gold here).</para>

<programlisting>As an example object, this is a program listing.

It could be an image, or a table, or anything else.

Spaces are not eaten when rendered in HTML so t h i s will not looklike t h i s and carriage returns/linefeeds are also preserved. And this istypically a non-kerning (fixed-width) font but you can change that in thestylesheet definition (but I don’t recommend it).

</programlisting>

20


<para>After the object just pick up where you left off as if it was just a paragraphabove you.</para>

</appendix></article>

4. Common Functions

This section will describe some common functions that may ormay not be intuitively obvious to thebeginner. Most of these are covered in the tutorial links inAppendix B, but it’s often useful to have acentralized reference.

4.1. Common Formatting Tags

There are several common tags you’ll probably run into frequently. While you have control over howthese tags are formatted, there are defaults defined for the standard DocBook Style Sheets. Note thatmany of these tags, by default, will render identically. It’s up to you to be diligent about using the righttag for the right entity, remember that the purpose of DocBook is to make it easy if you decide to changeall variables to italicized text - if you had defined them all asliteral this can be a problem. This meansyou need to break the habit of thinkingbold anditalics and start thinkingcommand andvarname.

You can use the<emphasis>emphasis tag</emphasis> to create emphasis in your document. This willtypically be an italicized version of your default font. Forreferences to literal text you can use the<literal>literal tag</literal>.

Computer-related documents frequently refer to many standard entities. When referring to filenames ordirectories you can use the<filename>filename tag</filename>, but packages may be betterexpressed with the<package>package tag</package>. When expressing commands the<command>command tag</command> helps them stand out. Variables can be expressed with the<varname>varname tag</varname> and tags themselves can be expressed with the<sgmltag>sgml tag<sgmltag>.

There are two methods to express computer output, the first isan inline<computeroutput>computeroutput tag</computeroutput> which is good for short bits ofoutput or fragments. For extended output that spans multiple lines, consider the following:

<programlisting>The programlisting tags are great for displaying the entireoutput of a command or for listing chunks of code.It preserves whitespace and uses a non-kerning (fixed-width) font in moststylesheets. However, it also will force a newline before and after thetags so it is not appropriate for inline text.

21


</programlisting>

References to foreign phrases can use the<foreignphrase>foreignphrase tag</foreignphrase>.

4.1.1. Special Characters

Sometimes you need to use special characters in your document and without proper escaping thedocument won’t compile. Since DocBook is based on XML, it uses the same XML/HTTP-style escapecharacters. Some common characters appear in the table below.

Table 1. List of Selected Special Characters

Character Name Appearance Escape Sequence Description

Less Than < < The < symbolinterpreted as theof an XML tag, soshould be used ininstances.

Greater Than > > The > symbolmisread as an XMLend, but this is notcommon. Still, use> can be beneficialsome circumstances.

Ampersand & & the & symbolfrequentlyverbotencan be replaced with&

Quote " " Quotes can sometimesconfuse parsers, use" will indicatethis is not startingending a quote butsimply the quotecharacter.

22



Non<8209>BreakingSpace

A non-breaking spacea space that doesn’count as whitespace.can be used to keepwords together, butoften used forformatting. As anexample, aprogramlisting

block will often remoleading spaces.Converting the initialcharacter to prevent this fromhappening.

Currency ¤ ¢ £ ¥ € ¢ £¥

Select currencieseasy to work with,dollar symbol is usedmany keyboardsbecause it is usedmany programminglanguages. Additionalsymbols for currencoften exist, but don’have a commonreference and mustexpressed in UNICODEformat. Anotherconsideration is thatsome symbols mayrender well in alldocument types. Aof most commoncurrencies can behere(http://www.alanw

Symbols © ® ◦± textmu © ® °

± µSome common symbols

have text to describethem, many othersymbols exist thatbe expressed inUNICODE format.

23



General UNICODECharacter

N/A &#xHHHH or&#DDDD

UNICODE characterscan be expressed inor decimal formatof characters can befound here(http://en.wikipedia.orAs an example,π will resultthe Pi (π) symbol.Similarly, πproduce the samecharacter (π).

4.2. Lists

Docbook supports several different list styles. A simple bullet item list can be expressed as follows:

<itemizedlist><listitem><para>

Entry 1</para>

</listitem><listitem><para>

Entry 2</para>

</listitem></itemizedlist>

The result of the code above looks like this:

• Entry 1

• Entry 2

A numbered or enumerated list is called an ordered list in Docbook and is expressed like this:

<orderedlist><listitem>

<para>Entry 1

</para></listitem><listitem>

<para>

24


Entry 2</para>

</listitem></orderedlist>

When processed this is the result:

1. Entry 1

2. Entry 2

A list of variables can also be expressed, typically as a variable name followed by a description:

<variablelist><varlistentry>

<term>Variable 1

</term><listitem>

<para>Description

</para></listitem>

</varlistentry><varlistentry>

<term>Variable 2

</term><listitem>

<para>Description

</para></listitem>

</varlistentry></variablelist>

This will produce the following output:

Variable 1

Description

Variable 2

Description

25


4.3. Intra-Document Cross References

Frequently you’ll want to make references to internal sections of your document. To do so, you’ll want touse theid="section_name" variable for yoursection tags. This has the added benefit of creatingmore intelligent URL markers for your table of contents links (using things likeindex.html#install-ubuntu instead of an automatically generatedindex.html#AEN13):

<section id="section-name-here"><para>

Paragraph text here.</para>

</section>

Note that theid variable can belong to asection or anappendix. Once you’ve got one defined youcan put anxref reference anyplace in your document (well, anyplace there would normally be text) andit will be replaced at compile time with the section number and (in link-enabled formats like HTML) alink to the section. As an example:

Please see <xref linkend="xref" /> for more details on this.

Will yield:

Please see Section 4.3 for more details on this.

You can also insert ananchor tag arbitrarily in a document as the target of anxref. This tag is invisibleand has the format<anchor id="anchor-name" xreflabel="text" />. Thexref will use"anchor-name" as thelinkend value and the output will use "text" as a replacement for thexref tag.Again, theanchor tag is invisible and will be omitted in the final output.

4.4. Using META tags

Since many times DocBook documents are read in HTML form it’suseful to use META tags so searchengines can properly classify a document. These are called Keywords in DocBook and can be a memberof anarticleinfo or chapterinfo grouping. The following is an example of keywords for an articleon IPv6 and Ubuntu:

<articleinfo><keywordset>

<keyword>ubuntu</keyword><keyword>ipv6</keyword>

</keywordset>...

</articleinfo>

Will produce output in your HTML documents of the format:

26


<META NAME="KEYWORD" CONTENT="docbook">

4.5. Inserting Hyperlinks

Hyperlinks are fairly trivial to use in DocBook. They work the same as HTML hyperlinks but use theulink tag.

<ulink url="http://www.ebower.com/">eBower</ulink>will generate eBower(http://www.ebower.com/)

Email hyperlinks are of a special format.

<email>[email protected]</email>will generate <[email protected]>

4.6. Inserting Images

DocBook allows for multiple image formats to be listed so thevarious compilers can select a formatthat’s compatible. For example, thedocbook2html looks for jpg or png files whiledocbook2ps preferseps files. As such it’s frequently useful to write a script that converts images to common formats. I’vecreated a script that will convert all images in the current directory to png and eps files. By default it willconvert the jpg files, but if you supply it with another format(for example, a gif) it will convert thoseinstead. I’ve placed it in/usr/bin/convertimg.

Example 9. An example DocBook image conversion script

#!/bin/bash

if [ $1 ] ; thenext=$1

elseext=jpg

fi

for infile in $( ls *.$ext )do

outfile=$(echo $infile | sed ’s/$.*$\..*/\1/’)echo Converting $infileconvert $infile $(echo $outfile).pngconvert -resize 400x800\> $infile $(echo $outfile).eps

done

Theconvert command is not included in Ubuntu’s default desktop install, you may need to get theimagemagickpackage to use this script.

27


Once you’ve got the images in a common format you need to include them in amediaobject block.Note that by enclosing this in afigure you get numbering.

<figure><title>Figure Title</title><mediaobject>

<imageobject><imagedata fileref="filename.png" format="PNG" /></imageobject><imageobject><imagedata fileref="filename.eps" format="EPS" /></imageobject>

</mediaobject></figure>

4.6.1. Inserting Sparklines and Other Inline Images

Sparklines are the use of graphs as typography. A small chapter by their inventor (Edward Tufte) appearson his forum (http://www.edwardtufte.com/bboard/q-and-a-fetch-msg?msg_id=0001OR). While theexamples given tend to focus on the use of small, concise graphs to augment numbers and text in tables,they can also appear inline to a paragraph. As an example, onecan include a sparkline to indicate that the

current temperature is 15◦C to concisely show a brief temperature history inthe space equivalent to a word. Sparklines are not native to DocBook but are instead simple, inlinegraphics approximately 15 pixels high (this prevents line spacing issues in most formats). You’ll notethat sparklines are limited in that there is no room for scales or labels so they will need to beself-explanatory. They will only work in graphics-enabledoutput (HTML, PDF and PS).

A snippet of the paragraph above can be represented with theinlinemediaobject tags used in thenormal figures above. The difference is that thefigure andtitle tags don’t cause the image to appearas a traditional figure would.

the current temperature is <inlinemediaobject><imageobject><imagedatafileref="sparkline.png"/></imageobject><imageobject><imagedatafileref="sparkline.eps"/></imageobject></inlinemediaobject> 15◦C

The same mechanism can be used for other inline graphics suchas mathematical forumulae or evensmall graphics that do not require a separate callout, figurenumber, or all that precious space. Thepremise behind this methodology is that before computers and movable type there was no distinctionbetween graphics and text. It was only once we migrated to using movable type for text and engravingsor woodcuts for graphics, and now Word (vim!) for text, Excel(gnuplot!) for graphs and Photoshop(gimp!) for images that we’ve found a need to create an artificial separation.

4.7. Inserting External Text Files

Often it makes sense to insert a text file into a document instead of copying the contents of the file. Forexample, if you’re referencing code you don’t want to have toduplicate the changes in thedocumentation whenever the code changes. This document also uses these references so it’s easy to keepit up to date should my scripts change. Theexample tags create a caption and theprogramlisting

28


tags will format it in a way that says whitespace is important. Note, however, that these links are not live.They are compiled into the final documents so you’ll need to run dbcompile whenever the source fileschange manually.

<example><title>The Title of the Text File</title><programlisting><inlinemediaobject><imageobject><imagedata fileref="/path/to/file" format="linespecific" />

</imageobject></inlinemediaobject></programlisting></example>

4.8. Inserting Tables

Tables can be very complex critters and the links inAppendix Bhave a reference to a more full-fledgedtable definition. The code below will get you a very basic table without any spans.

<table frame="all"><title>The Title of the Table</title><tgroup align="center" cols="3" colsep="1" rowsep="1"><thead>

<row><entry>Heading1</entry><entry>Heading2</entry><entry>Heading3</entry>

</row></thead><tbody>

<row><entry>Data1</entry><entry>Data2</entry><entry>Data3</entry>

</row><row>

<entry>Data4</entry><entry>Data5</entry><entry>Data6</entry>

</row></tbody>

</tgroup></table>

This code will produce the following table:

Table 2. The Title of the Table

Heading1 Heading2 Heading3

Data1 Data2 Data3

Data4 Data5 Data6

29


4.9. Footnotes

Sometimes it’s useful to have footnotes, a reference to textat the bottom of the document. To do so, youcan use afootnote block to create a reference to a footnote that will appear at the end of the document.If you need to reuse the same footnote, use thefootnoteref tag to refer to the original footnote.

<para>Footnotes can appear anyplace<footnote id="footnote-appearance">

<para>Footnotes will typically appear between <para> tags but canalso be the child of <programlisting> and other tags as described<ulink url="http://www.docbook.org/tdg/en/html/footnote.html">here</ulink>

</para></footnote> in the text. You can also duplicate a footnote anywhereelse in the document<footnoteref linkend="footnote-appearance"/>without retyping the footnote text, but the reverse link will be tothe part of the document where the footnote text was defined.

</para>

This will produce the following output:

Footnotes can appear anyplace1 in the text. You can also duplicate a footnote anywhere else in thedocument1 without retyping the footnote text, but the reverse link will be to the part of the documentwhere the footnote text was defined.

A. Complete Package Install

You can also now install from PPA by loadingppa:ubuntu-ebower/ebower (see instructions inAppendix C) and runningsudo apt-get install dbcompile. This is the easiest method as it takes care ofdependencies for you and will be the most up-to-date.

If you want to do things manually, the following line will install all packages required for properDocBook happiness:

sudo apt-get install vim docbook-utils docbook-defguide xml-twig-tools imagemagick lynx tidy

In addition to the packages above, you may wish to include my DocBook helper scripts(docbook-helpers.tar.gz). I store mine in/usr/bin but feel free to put them wherever you like. Note thatI now use some external config files so you’ll probably want to examine the non-executable files toensure they’re in the right spot. For example,dbcompile.header should be in/etc/dbcompile/ or~/.dbcompile/.

30


To install all of this in one fell swoop you can experiment with dbcompile-0.1.1.1.deb which will installmy scripts to/usr/bin as well as the dependencies above. Simply runsudo dpkg -idbcompile-0.1.1.1.deb after downloading to install it. Assuming you’ll get an error message thanks tothe dependencies, you’ll want to runsudo apt-get -f upgrade to finish the install. Note that this file maybe out of date, so please consider using the PPA for the latestand greatest.

B. References• Common DocBook Commands

(http://www.ibiblio.org/godoy/sgml/docbook/howto/writing-docbook.html)

• DocBook Tables (http://www.ibiblio.org/godoy/sgml/docbook/howto/tables.html)

• A short docbook primer (http://www.svgopen.org/2009/papers/103-Test_Paper/)

• DocBook: The Definitive Guide (http://www.docbook.org/tdg/en/html/docbook.html)

• DocBook: The Definitive Guide (file:///usr/share/doc/docbook-defguide/html/docbook.html) (local -installs withdocbook-defguide)

C. Installing the eBower PPA

I’ve created a Personal Packages Archive (PPA) on Launchpad.net. You can add this using the commandsudo add-apt-repository ppa:ubuntu-ebower/ebower and thensudo apt-get update to load the list ofpackages. Alternatively you can add the following lines to your/etc/apt/sources.lst (this is usefulif you’re running server and don’t want to add theadd-apt-repository command):

deb http://ppa.launchpad.net/ubuntu-ebower/ebower/ubuntu precise maindeb-src http://ppa.launchpad.net/ubuntu-ebower/ebower/ubuntu precise main

Make sure you replaceprecise above with your distro (lucid, oneiric, etc.). If your distro is not availableplease contact me with the version and package name and I’ll try to update things posthaste. After this isdone, run the commandsudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys C27A63B3to import the keys.

By installing my scripts from the PPA you’ll be sure to have the most up-to-date versions in case I needto make changes. However, note that I’m not a developer and I only play one on the Internet. If you usemy scripts as a baseline and make changes yourself please letme know how you’re changing things andI’ll try to accommodate your efforts to ensure that I don’t stomp on your customizations.

31


D. About Me

My name is Jeff Bower, I’m a technology professional (http://www.linkedin.com/in/jdbower) with moreyears of experience in the telecommunications industry than I’d care to admit. I tend to post with theusername jdbower on various forums, including Komodo Kamado (http://komodokamado.com/forum/),Android Central (http://forum.androidcentral.com/), VirtualBox (http://forums.virtualbox.org/), andMakeMKV (http://www.makemkv.com/forum2/). Writing these documents is a hobby of mine, I hopeyou find them useful and feel free to browse more at https://www.ebower.com/docs.

I also enjoy cooking, especially outdoors with my Komodo Kamado (http://www.komodokamado.com)and using my Stoker (https://www.rocksbarbque.com). Takea look at my recipes stored athttps://www.ebower.com/recipes.

If you’ve got any questions or feedback please feel free to email me at [email protected](mailto:[email protected]) or follow me on Google+(https://profiles.google.com/100268310848930740059) or Twitter (http://twitter.com/jdbower).

Notes1. Footnotes will typically appear between <para> tags but can also be the child of <programlisting>

and other tags as described here (http://www.docbook.org/tdg/en/html/footnote.html)

32

Introduction to DocBook - eBower.com · Introduction to DocBook DocBook provides a common format...

Documents

Transcript of Introduction to DocBook - eBower.com · Introduction to DocBook DocBook provides a common format...