Checking

Differences between revisions 1 and 2
⇤ ← Revision 1 as of 2008-08-31 13:14:26 →
Size: 1694
Editor: 79-72-87-179
Comment: creating page, writing extra material
← Revision 2 as of 2008-08-31 13:20:07 → ⇥
Size: 2730
Editor: 79-72-87-179
Comment: dumping section status information here for now
Deletions are marked like this. Additions are marked like this.
Line 25: Line 25:

== 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.

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

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

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

    make all

  2. 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.

DocumentationTeam/SystemDocumentation/Checking (last edited 2016-10-03 16:18:17 by gunnarhj)