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.

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 things, the Docteam Mailing List is there for you.

There is some information on using gEdit for docbook/xml at https://help.ubuntu.com/community/gedit.

Checking your changes

For more information on how to contribute your changes, see the Checking page.