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 you should do the following:

1. Go to the scripts folder and run the validate.sh script:

   ./validate.sh

   This tests all the ubuntu-help/C/*.page files, and reports erroneous Mallard syntax, incorrect internal links, etc.

2. View the changed page in yelp, and make sure it looks as expected:

   yelp /path/to/[whatever-name].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.