an introduction to docbook

IntroductionStarting with Docbook

Advanced usage

An introduction to DocbookMaster on Free Software

Juanjo Amor

[email protected]/Libresoft

October 25th 2007

Juanjo Amor An introduction to Docbook


Advanced usage

(cc) 2007 Juanjo Amor

Some rights reserved. This work licensed under Creative Commons Attribution-ShareAlike License. To view a copy

of full license, see http://creativecommons.org/licenses/by-sa/2.0/ or write to Creative Commons, 559 Nathan

Abbott Way, Stanford, California 94305, USA.



Advanced usage

Summary

Introduction.

Starting with Docbook.

“Advanced” usage.



Advanced usage

What are SGML and XML?

Some characteristics...

SGML and XML are “markup languages”.

HTML, the language used in web pages, is a subset of SGML.

Markup languages?

Provide a way to combine text and extra information about it.

The extra information is expressed through a “markup”.

The extra information covers from character aspect (ex: bold,italic) to structure, layout or meta-data.

DTD: Document Type Definition

The “schema” for defining a particular set of markups in themarkup language.

For us, Docbook is a DTD of SGML or XML for writingtechnical documents.



Advanced usage

Objectives

Docbook:

A DTD for writing technical documents in SGML or XML.

Defacto standard for technical documentation in a wide rangeof FLOSS projects.

Objectives:

To know the Docbook concepts.

To have the abilities to write Docbook/XML documents.

To know the software needed for compiling



Advanced usage

Docbook

What is Docbook?

DocBook is a markup language for technical documentation.

Of course it can be used for other type of documentation.

Benefits:

Users can create document content in a presentation-neutralform that captures the logical structure of the content.

Content can be published in a variety of formats (HTML,PDF, RTF, man pages, etc), by using some tools.

Who created Docbook?

1991: Some companies (O’Reilly, Hal Computer Systems)proposed first versions.

Later moved to the SGML Open Consortium.

Currently maintained by OASIS (Organization for theAdvancement of Structured Information Standards).



Advanced usage

Docbook (II)

Current Docbook:

Currently: Version 4.5.

Next release: Version 5. Publication planned for November2007.

Documentation:

There is a lot of documentation about Docbook.

However, the main reference is:

N. Walsh, L. Muellner. “Docbook. The Definitive Guide”.O’Reilly & Associates, 1999.

Main references available at: http://www.docbook.org/


http://www.docbook.org/


Advanced usage

The Environment

Before more acronyms, let’s start with Docbook. What do weneed?

An editor. Forget WYSIWYG. Use emacs or bluefish (orwhatever you prefer).

A set of tools.

Exercise:

Install and test bluefish.

Verify the installation of docbook tools (SGML).

Install XMLTO and FOP.



Advanced usage

Docbook example

<?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE book PUBLIC "-//OASIS//DTD Docbook XML V4.5//EN"

"file:///usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd">

<book lang="en">

<bookinfo>

<title>My first book written in Docbook</title>

<author>

<firstname>John</firstname>

<surname>Smith</surname>

</author>

</bookinfo>

<chapter>

<title>Preface</title>

<para>

Welcome to my first document in Docbook.

</para>

</chapter>

</book>



Advanced usage

Compile your book!

Exercise:

Compile it as HTML.

Compile it as HTML in one file.

Compile it as PDF.

Typical output without errors (but warnings):

$ xmlto fo prueba.xmlMaking portrait pages on USletter paper (8.5inx11in)$ /opt/fop-0.94/fop -fo prueba.fo -pdf prueba.pdfOct 21, 2007 7:57:53 PM org.apache.fop.hyphenation.Hyphenator

getHyphenationTreeSEVERE: Couldn’t find hyphenation pattern en



Advanced usage

Compile your book! (alternate method)

Exercise:

Download db2latex.xml

Follow teacher instructions.

Examine the output.

Conclusions?



Advanced usage

Docbook XML basics

All markups are case-sensitive.

All markups must be written in lowercase.

Attribute values must be quoted with a quote (’ or ").

Processing instructions begin and end with question mark:<?pitarget data>

Empty elements: </xref>



Advanced usage

The Docbook documents

Docbook documents we will write:

Books. A book consists of one preface, several chapters.

Articles. An article consists of several sections. Sections canbe nested.

There are other optional or mandatory elements to be includedinto a book or an article.Exercise:

Learn to look for a Docbook element in the reference.

See the elements of a book and an article.



Advanced usage

The book document

<?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE book PUBLIC "-//OASIS//DTD Docbook XML V4.5//EN"

"file:///usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd">

<book lang="en">

<bookinfo>

<title>My first book written in Docbook</title>

<author>

<firstname>John</firstname>

<surname>Smith</surname>

</author>

</bookinfo>

<chapter>

<title>Preface</title>

<para>

Welcome to my first document in Docbook.

</para>

<section>

<title>Section title</title>

<para>We can divide a chapter in sections</para>

</section>

</chapter>

</book>



Advanced usage

The article document

<?xml version="1.0" encoding="UTF-8" ?><!DOCTYPE article PUBLIC "-//OASIS//DTD Docbook XML V4.5//EN""file:///usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd">

<article lang="en"><artheader><title>My Article</title><author><honorific>Dr</honorific>

<firstname>Emilio</firstname><surname>Lizardo</surname></author>

</artheader><para> ... </para><sect1><title>On the Possibility of Going Home</title><para> ... </para></sect1><bibliography> ... </bibliography></article>



Advanced usage

Typical article contents

Authorship:

<article lang="es">

<articleinfo>

<title>My article</title>

<date>April 2005</date>

<authorgroup>

<author>

<firstname>Juan J.</firstname>

<surname>Amor Iglesias</surname>

</author>

<author>

<firstname>Gregorio</firstname>

<surname>Robles Martínez</surname>

</author>

</authorgroup>

</articleinfo>

...

</article>



Advanced usage


Nested sections:

...</articleinfo><section>

<title>Main section</title><para>Paragraph in main section

</para><para>...</para><section>

<title>A subsection</title><para>...</para><para>...</para><para>...</para>

</section></section>

...Juanjo Amor An introduction to Docbook


Advanced usage


Sections: <sect1>, <sect2>, <sect3>...

Other: <appendix>, <glossary>, <bibliography>...

See:http://www.docbook.org/tdg/en/html/article.html

Exercise:

Look to the previous URL.

See the accepted elements as children and parents.

See the examples.


http://www.docbook.org/tdg/en/html/article.html


Advanced usage

Simple lists

Simple list:

<itemizedlist><listitem><para>First element</para></listitem><listitem><para>Second element</para></listitem>

</itemizedlist>

Ordered list:

<orderededlist><listitem><para>First element</para></listitem><listitem><para>Second element</para></listitem>

</orderededlist>



Advanced usage

Descriptions

<variablelist><listitem><term>Potato</term><para>An edible tuber native to South America.</para>

</listitem><listitem><term>Tomato</term><para>Mildly acid red or yellow pulpy fruit

eaten as a vegetable.</para></listitem>

</variablelist>



Advanced usage

Other block elements

Listings: programlisting, screen, literallayout.

Warns: caution, important, note, tip, warning.

Comments: remark.

blockquote, procedure, qandaset...

Footnotes: footnote.

Exercise: See each element into the reference. Look to theparent and children elements. Look to the examples.



Advanced usage

Elements within a line

Emphasis: emphasis, literal, quote.

Commands: filename, command, option, parameter.

Internal references:

For more information, please see <xref linkend="more1"/>...<section id="more1"><title>The other section</title><para> .....

External (URI) references:

<ulink url="http://curso-sobre.berlios.de">FLOSScourse</ulink>



Advanced usage

Tables

<informaltable>

<tgroup cols="3">

<colspec align="left" colnum="1" colwidth="2*"/>

<colspec align="left" colnum="2" colwidth="1*"/>

<colspec align="justify" colnum="3" colwidth="4*"/>

<thead>

<row>

<entry>Concept</entry>

<entry>Hours</entry>

<entry>Content</entry>

</row>

</thead>

<tbody>

<row>

<entry>Introduction</entry>

<entry>20</entry>

<entry>

Introduction to <emphasis>Software

Engineering</emphasis>, blah blah

</entry>

</row>

...

</tbody>

<tgroup>

</informaltable>



Advanced usage

Figures

<mediaobject><imageobject>

<imagedatascale="80"fileref="figures/ccby.png"format="EPS"

/></imageobject>

</mediaobject>



Advanced usage

Formal figures and tables

<figure id="img1"><title>Figure caption</title><mediaobject><imageobject><imagedata fileref="img.png"/></imageobject>

</mediaobject></figure>

<table id="tbl1"><title>Table caption</title><tgroup cols="2">

<tbody><row><entry>xxx</entry><entry>yyy</entry></row><row><entry>zzz</entry><entry>ttt</entry></row>

</tbody></tgroup>

</table>



Advanced usage

Bibliography

...

IP telephony<citation>HGP2003</citation>

...

<bibliography>

<title>Bibliography</title>

<biblioentry><abbrev>HGP2000</abbrev>

<title>IP Telephony. Packet-based multimedia communications systems.</title>

<authorgroup>

<author><firstname>Olivier</firstname><surname>Hersen</surname></author>

<author><firstname>David</firstname><surname>Gurle</surname></author>

<author><firstname>Jean-Pierre</firstname><surname>Petit</surname></author>

</authorgroup>

<pubdate>2000</pubdate>

<publisher><publishername>Addison Wesley</publishername></publisher>

</biblioentry>

...

</biblography>



Advanced usage

Entities

Entities allow you to assign a name to some chunk of data,and use that name to refer to that data.Two main types: General and Parameter entities.Parameter entities are most often used in the DTD.General entities:

Internal general entities:<!ENTITY ora "O’Reilly & Associates">External general entities:<!ENTITY ch01 SYSTEM "ch01.sgm">

One can refer to a general entity using a character referencein the text. For example: &ora; and &ch01;.The effect of referring to an internal entity is the expansion ofits value.The effect of referring to an external entity is the file inclusion.Other uses of character entities: national characters:España.



Advanced usage

Exercise

Using the editor, you should write a Docbook document(article) including all elements seen in the paper.

Elements to include:

Authorship data.The abstract.The sections.Use for the text, as many elements as possible (ex: itemizedlists, references, etc).Compile, and control the errors.Produce an HTML output and a PDF. See the results.


an introduction to docbook

Technology