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

Try editing a Desktop help (ubuntu-docs) branch file (for example ~/your_branch_name/ubuntu-help/C/about-this-guide.page, which is the Mallard source of the Desktop help about this guide page. It starts with something like:

<page xmlns="http://projectmallard.org/1.0/"

The xmlns attribute specifies that the XML tags in this file are from the Mallard 1.0 namespace.

Then there's something like this:

      type="topic"
      style="tip"
      id="about-this-guide">

The id attribute provides a unique identifier that other pages can use to link to this page. You must match the id attribute to the name of the file without the .page extension, and there is a yelp-check validation step that will complain otherwise. The type attribute specifies that this is a topic page.

A little further down there's something like this:

    <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"/>
    <link type="guide" xref="more-help"/>
    <link type="seealso" xref="unity-introduction"/>

In Mallard, guides don't have to specify which pages they link to. Instead, pages can specify that guides (the index.page file is the overall guide page) should link to them. This is done via the link elements.

The about-this-guide.page example then continues on with paragraphs, <p>, <list> and <item>, making up the actual content of the page.

For more details see the mallard ten minute tour.

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.

Some modifications

This example is specific to DocBook, but the process is similar for Mallard.

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.