Ubuntu Wiki

Once you have made a change to one of the documents, the next step is to check your work. It seems like a lot of extra work, but it's worth it. You will save yourself the embarrassment when you catch your own mistakes before someone else does.

First, check that the DocBook markup you have written is valid. There is a script in our branches which allows you to do this easily and automatically:

1. From the top level of the branch, run the script as follows on the file you changed (replace document with the name of the document you have been working on).

   scripts/validate.sh document/C/document.xml

   If the file is valid, the script will not say anything. If there is a problem with the validity of the markup, the script will show an error message which should permit you to see where you have gone wrong. If you do not understand the error message, ask on the mailing list or on irc (see our Contact page for contact details).

Second, check the document visually by opening it in yelp, the Gnome documentation viewer:

1. Open the file in yelp and visually double check your work.

   yelp /address/to/file.xml

   • Note: there is a bug in yelp which makes it necessary to specify the full path to an xml file in order to be able to view it.

Alternatively, turn the DocBook into html so that you can view it with a browser:

1. Install the necessary libraries by running:

   sudo apt-get build-dep ubuntu-docs

2. From the top level of the branch, run the script for building html versions of the documents:

   make all

3. You can then view the documents with a web browser from the build directory:

   firefox build/document/C/index.html

The next step is to submit your work. Go to the Submitting page for details.

Advanced

To help keep track of what we are doing in the documents we mark the status of items and leave messages of what we are doing. This information is collected into the 'Project Status Reports' found on the DocumentationTeam/Projects page. The first thing to know about this is how to mark an item status. To mark item status add the 'status' attribute to any of the following elements: <chapter>, <sect1>, <sect2>, <sect3>, <sect4>, <sect5>. The value of the 'status' attribute is, well, its status. Valid state values include:

• status="help" = Help Wanted

• status="writing" = In Progress

• status="review" = Awaiting Review

• status="reviewing" = In Review

• status="complete" = Finished

To build the status pages, run make status. This will build the status reports in your working copy under build/status. There are two formats: XML and HTML. The reports can therefore be viewed under Yelp or a Web Browser.