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.

For the serverguide, 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:

   scripts/validate.sh serverguide/C/serverguide.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).

   • Note: Be sure to validate the serverguide and not a single chapter within. For example, serverguide/C/serverguide.xml will validate whereas serverguide/C/foo.xml will not.

For DeskTop help, 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.

or browse to the file with the file browser, right click, select open with, and select help.

Alternatively, build the html versions of the documents so that you can view them with a browser. See either the Ubuntu Desktop Guide Single Page or the Ubuntu ServerGuide Single Page or the Building page.

The next step is to submit your work. Go to either the Ubuntu Desktop Guide Single Page or the Ubuntu ServerGuide Single Page or the Submitting page for details.

Advanced

Note: At least for the serverguide, and probably for other documents, "make status" does not work, and that Makefile option is being deleted.

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 (Note: the page does not exist). 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.