This page describes how to edit the system documentation, and in particular introduces you to the format used by the DocumentationTeam for the system documentation, DocBook XML. We assume that you have already downloaded one of the branches which stores the system documentation. If not, visit the Repository page.

Structure of the branch

The documents that can be edited appear in the top level of the branch. Documents use the structure documentname/C/documentname.xml. The C directory represents the default language of the system (in our case, English). Translations of each document are found in the documentname/po directory.

There are some directories there which do not correspond to documents. These are briefly explained as follows:

• build/ - this is where HTML versions of the documents are put when generated as explained on the Building Documentation page.

• debian/ - this contains the files used to generate an Ubuntu package from the branch. For more information on packaging, see the PackagingGuide page.

• libs/ - this contains the files used to generate HTML and PDF from the documents.

• scripts/ - this contains specific scripts which are used by the team for various tasks, especially translation.

A look at DocBook

Try editing a file in one of the docteam branches (for example ~/ubuntu/about-ubuntu/C/about-ubuntu.xml, which is the DocBook source of the About Ubuntu document). It starts with something like:

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

That's called the xml declaration, and is found at the beginning of any XML file. DocBook is a dialect of XML, so it must have that starting line.

Then there's something like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
        "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY % globalent SYSTEM "../../../libs/global.ent">
%globalent;
<!ENTITY % cdo-C SYSTEM "../../../libs/cdo-C.ent">
%cdo-C;
<!ENTITY % gnome-menus-C SYSTEM "../../libs/gnome-menus-C.ent">
%gnome-menus-C;
<!ENTITY language "&EnglishAmerican;">
<!ENTITY language "en">
]>

This is called the Document Type Declaration: basically it says that this xml file must conform to the rules of the Docbook DTD version 4.3.

The rest is the XML tree. XML files are made of elements, which contain elements, which contain sub-elements, and so on. DocBook is just a dialect of XML, so it follows the same structure.

In the case of the about-ubuntu document, you can see a <article> which contains many <sect1> which contain many <para>. It makes some sense. Some longer documents use <book> rather than <article>, like the Internet document. These also have several <chapter> tags.

The top-level element that contains all the rest is called the root element, and in About Ubuntu it is called <article>.

Scroll down slowly, reading the names of the xml elements: you can see that the elements are a semantic nomenclature that defines the role of the text.

For more details about the tags which are found in docbook xml documents, see the Docbook Tags page.

Some modifications

Now try to add some text: find a <para> element and type something in it, then save. You'll have changed an existing paragraph. You can easily review text and correct typos and spelling this way.

You can add a new paragraph by adding a new <para> element next to some other. For many other similar kinds of editing, you can easily guess how DocBook works just by looking at what has been written already, as you probably noticed even before reading these lines.

For more complicated t