This page briefly describes how to edit the system documentation. The official Ubuntu documentation uses two formats: Mallard, used by Desktop help; And DocBook XML used by xubuntu and the Serverguide. 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 DocBook documents, and using the Serverguide as an example, that can be edited will typically be found in serverguide/C/*.xml.

The Mallard documents, and using Desktop help as an example, that can be edited will typically be found in ubuntu-help/C/*.page.

The C directory represents the default language of the system (in our case, U.S. English). Depending on the project, translations of each document are found in the documentname/language directory or the documentname/po directory.

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

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

• debian/ - (for projects that also have package versions) 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/or PDF from the documents.

• scripts/ - this contains specific scripts which are used by the team for various tasks, especially translation. (Not all projects have this directory.)

A look at Mallard

TODO

A look at DocBook

Try editing a file in one of the docteam branches (for example ~/your_branch_name/serverguide/C/introduction.xml, which is the DocBook source of the Serverguide Introduction chapter). 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 chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" 
        "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY % globalent SYSTEM "../../../libs/global.ent">
%globalent;
<!ENTITY % xinclude SYSTEM "../../libs/xinclude.mod">
%xinclude;
<!ENTITY language "&EnglishAmerican;">
]>

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 introduction document, you can see a <chapter> which can contain many <sect1> which can contain many <para>. It makes some sense. The overall document, serverguide.xml uses <book> rather than <chapter>, and it includes that various chapters.

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.