This is a fairly complex and technical document. For a simpler guide, see DocumentationProject/Contributing/SubmittingPatches.

Creating a Documentation Patch

/!\ This is only a draft. If you see something wrong, please correct it, or let me know so I can correct it.

So, you want to help out the documentation team by updating or writing docs? Excellent. All help is much appreciated. This page gives you a quick guide of how to create your first documentation change and send it to the developer.

Deciding what needs done

The first thing to do is to subscribe to the gnome doc list and introduce yourself. You can also come and visit us on IRC by pointing your IRC client to irc.gimp.org and joining #docs

You'll also want to create a bugzilla account if you don't already have one. Instructions for doing this can be found here

You should also read the style guide. This will give you some idea of the style of documentation that we are looking for.

If you've already decided what you want to work on, great! Have a look at the Team page and add your name and what you want to work on to it. This helps us keep track of who is working on what and helps reduce duplicate work. You can skip down to the next section now.

If you don't know what to work on, great! There are a couple of ways to get working. The best way (if you don't mind working on anything) is to ask either on the mailing list or on IRC. Someone should point you in the direction that needs the most love. Note: Please be patient when you ask.

Another way to decide what to work on is to have a look around the docs and decide what needs work yourself. For this, its advisable to have an up-to-date version of GNOME (see the next section). Once you've got yourself an up-to-date system, log into it and launch the help browser. Have a look through the documentation and find something that appeals to you. Once you've found something, add your name and what your working on to the Team page. You are now ready to start making changes.

Getting an up to date system

  • I'm not sure we should be suggesting this for all doc writers. Not everyone is capable of building GNOME. I have yet to manage it. -- Joachim

There are several ways of getting a current build of GNOME. The best way is to use jhbuild. This is described here (you may need to adjust the instructions slightly to suit the distro you are running).

This can take a long time to compile but at the end, you'll have a complete and up-to-date GNOME build.

As this will build all of gnome from CVS, you may run into problems. If you do, please ask on IRC. Hopefully someone will be able to help you.

Creating your first patch

By now, you should be ready to start editing documentation and have an idea of a change you want to make. This section will show you how to make that change and get it submitted.

(Note: I'm going to do this from the terminal. If someone wants to do it through nautilus, please add instructions on how)

First, navigate to the directory where jhbuild has downloaded all the sources. For example, in my system, this is

/home/don/cvs/gnome2

FIXME!!!! Use ~ notation so someone following this can just copy-paste to terminal. Match the folder structure used in jhbuild tutorials.

Here, there should be folders containing the sources for all the components. Change into the directory of the component you want to change. For this example, I'm going to make a change to the gedit manual. The help files are normally stored in the help subdirectory. The files you want to edit are normally in the C subdirectory. To get there, issue the command:

cd /home/don/cvs/gnome2/gedit/help/C

The file I want to edit is gedit.xml. This is the main help file for gedit. I can view the current version of it by typing

yelp ./gedit.xml &

This will bring up the help browser with the gedit manual loaded. Load up the file in your favourite text editor.

Gnome help files are normally written in docbook, a type of XML. You can find many tutorials about docbook using google. Here are two:

http://opensource.bureau-cornavin.com/crash-course/

http://www.galassi.org/mark/mydocs/docbook-intro/docbook-intro.html

You don't really need to know all about docbook. For most text, you can get by using the <para> tag. There are special tags for menu items and various other elements. Look through one of the manuals in a text editor to see some of these.

Back to creating a patch. In the text editor, look through the source of manual until you find the bit to fix. Here, I want to add a bit to the usage section about opening a new document by selecting the "New" toolbar item. Adding the text changes the item from:

<para>To create a new file, choose <menuchoice><guimenu>File</guimenu><guimenuitem>New</guimenuitem></menuchoice>. The application displays
a new file in the <application>&app;</application> window.<para>

To:

<para>To create a new file, choose <menuchoice><guimenu>File</guimenu><guimenuitem>New</guimenuitem></menuchoice>. The application displays
a new file in the <application>&app;</application> window.  This can also be performed using the <guimenuitem>New</guimenuitem> toolbar item.</para>

(Note: This is not a real change. I'm also unsure about using guimenitem tags for this. Can someone correct?)

Its not a big change for this example. Save the file and in the help browser window (if its still open) press Control-r. This will refresh the display from the file. If you've closed the window, simply rerun the yelp command to see your changes.

Once your happy with the additions / edits, its time to create a patch. (See GnomeLove/SubmittingPatches for more on this.) In the terminal, you can create a patch file by running the command:

cvs diff -u <files changed> > <patch file>

From the applications topmost directory. In the example, to create the patch, I would run the commands:

cd /home/don/cvs/gnome2/gedit
cvs diff -u help/C/gedit.xml > gedit-update-docs.patch

This will create your patch file that looks like:

Index: help/C/gedit.xml
===================================================================
RCS file: /cvs/gnome/gedit/help/C/gedit.xml,v
retrieving revision 1.12
diff -u -r1.12 gedit.xml
--- help/C/gedit.xml    18 Dec 2005 22:37:09 -0000      1.12
+++ help/C/gedit.xml    14 Jan 2006 13:58:56 -0000
@@ -345,7 +345,7 @@
 <!-- ============= To Create a New File ======================== -->
         <sect2 id="gedit-create-new-file">
                <title>To Create a New File</title>
-               <para>To create a new file, choose <menuchoice><guimenu>File</guimenu><guimenuitem>New</guimenuitem></menuchoice>. The application displays
-               a new file in the <application>&app;</application> window.</para>
+               <para>To create a new file, choose <menuchoice><guimenu>File</guimenu><guimenuitem>New</guimenuitem></menuchoice>. The application displays
+               a new file in the <application>&app;</application> window.  This can also be performed using the <guimenuitem>New</guimenuitem> toolbar item.</para>
         </sect2>
 <!-- ============= To Save a File ============================== -->
         <sect2 id="gedit-save-file">

Once this file has been created, fire up your web browser and point it at [bugzilla.gnome.org bugzilla]

and add a new bug against the product you've created the patch for. This should always be filed against the documentation element. In the bug report, it is useful to explain what the change is and why you've made it. At this stage, you'll be unable to add the patch just yet. Instead, create the bug without the patch attached. Once bugzilla confirms that the bug has been added to the database, you can then select your bug and see the current comment. Near the bottom of the page is an option to add a new attachment. Select this and add your patch to the bug.

After doing this, you should send an email to the gnome-doc-list to get someone to review your changes for you. This may take a little time to get done, so please be patient. Once someone reviews it for you, there may be some corrections to make. Once all this is complete, its then up to the maintainer of the module to commit the changes and your work is done. Congratulations. Your first patch has been completed.

Some additional Notes

Here are some additional pointers to keep you on the right track:

  • If you want to make large changes to a document (i.e. binning it and rewritting from scratch), you should discuss this with the maintainer of the program and the doc team before you begin.
  • You may notice that in the docbook source for manuals, some elements have id attributes:

<sect1 id="index">

Please don't change these. Its ok to move complete sections around (although if you do, this would be considered a large change. See note above), if you think it makes more sense a different way, but you shouldn't change the id tags for sections. These are used in the program for help buttons to open the correct page when clicked. If a section is no longer valid and should be removed, then please see the next section on how to remove sections and still maintain backwards compatibility.

  • When submitting changes to bugzilla, try to give a good description of the change you've made and why you've made it. Saying "Here's a change to foos documentation. Please commit" will be less well recieved than "Foos documentation is out of date. The documentation says that clicking the blah button will launch a new window but the new version instead opens a toolbar. This patch changes the section of the manual to reflect that.".
  • If you have any questions, feel free to ask them in #docs on IRC. There is normally someone around who can help. If you get no reply, try emailing the doc list. Again, please be patient it may take some time before someone replies to you. Remember, we are mainly volunteers doing this in our spare time.

Removing sections

If you decide to remove a section because the contents are no longer valid, then you need to take note of the "id" attribute for that section and place it in an anchor element somewhere else in the document where it is most relevant. This is most easily illustrated by an example patch:

 <sect1 id="perform-actions">
   <title>Performing actions in Application</title>
+  <!-- action two is no longer present in the application -->
+  <anchor id="action-two"/>
   <sect2 id="action-one"><title>Action One</title><para>this is how you perform action one</para></sect2>
-  <sect2 id="action-two"><title>Action Two</title><para>this is how you perform action two</para></sect2>
 </sect1>

The <anchor> element can appear just about anywhere. If you are putting it at the beginning of a section though, you must put it after the <title> element, but before any <para> elements as in the above example. For more information about where <anchor> is allowed, please see http://www.docbook.org/tdg/en/html/anchor.html

If you want to check for regressions, or removed id attributes, then you can download the xmlstarlet utility and run the following commands before and after the patch is applied:

xmlstarlet sel -t -m '//@id' -v '.' -n user-guide.xml | sort > beforepatch.txt
xmlstarlet sel -t -m '//@id' -v '.' -n user-guide.xml | sort > afterpatch.txt
diff -u ~/beforepatch.txt ~/afterpatch.txt

Here is an example where you can see that an id attribute was added. A minus symbol "-" would mean that an id attribute was removed, which would be a regression.

--- /home/smitten/beforepatch.txt       2006-01-13 20:43:50.000000000 -0700
+++ /home/smitten/afterpatch.txt        2006-01-13 20:54:16.000000000 -0700
@@ -242,6 +242,7 @@
 gosnautilus-80
 gosnautilus-82
 gosnautilus-9
+gosnautilus-add-actions
 gosnautilus-FIG-504
 gosnautilus-FIG-505
 gosnautilus-TBL-10

Verifying your changes

Checking the XML

After making changes to a docbook file, you want to make sure that the structure is still valid. You can do this with the following command:

xmllint --valid --noout <docbook file> 2> /dev/null

Alternatively, copy the following script to a new file in your Nautilus scripts folder, and name it something like "Validate XML". Then simply choose File->Scripts->Validate XML. (But remember there is a bug with using scripts in expanded list view folders :(

# Brent Smith <gnome@nextreality.net>

XMLFILE="$1"
OUTFILE=`date '+%Y%m%d.%H%M%S'`

xmllint --postvalid --xinclude --noout $NAUTILUS_SCRIPT_CURRENT_URI/$XMLFILE 2> /tmp/$OUTFILE

if [ "$?" -eq 0 ]; then
  zenity --info --text "$XMLFILE successfully validated."
else
  zenity --text-info --filename="/tmp/$OUTFILE"
fi

This will validate the docbook file against the DocBook DTD to make sure it has the correct structure. It will also check for XML errors such as elements that have not been closed, etc.

If you happen to have an error with the structure of your document, you will see message like this:

gosoverview.xml:195: element figure: validity error : Element figure content does not follow the DTD, expecting (blockinfo? , (title , titleabbrev?) , 
(literallayout | programlisting | programlistingco | screen | screenco | screenshot | synopsis | cmdsynopsis | funcsynopsis | classsynopsis | fieldsynopsis | 
constructorsynopsis | destructorsynopsis | methodsynopsis | address | blockquote | graphic | graphicco | mediaobject | mediaobjectco | informalequation |
informalexample | informalfigure | informaltable | indexterm | beginpage | link | olink | ulink)+), got (title anchor screenshot )
    </figure>
             ^

If the error has to do with your XML syntax, you will see an error message like this:

yelp.xml:283: parser error : Opening and ending tag mismatch: title line 161 and sect2
    </sect2>
            ^
yelp.xml:284: parser error : Opening and ending tag mismatch: title line 161 and sect1
  </sect1>
          ^
yelp.xml:881: parser error : Opening and ending tag mismatch: sect2 line 160 and article
</article>
          ^

This usually indicates that there was an element in <sect2> that didn't have an ending tag (such as a <title> without a corresponding </title>)

Previewing

Once your document is valid XML, you may preview it in Yelp. To do this, eithur run "yelp" at the command line followed by the path to your file, or drag the file to the Yelp window or icon.

Yelp caches docs while still running. If you have more than one yelp window open and are trying to load the document again, the cached version will be used. Either close all instances of Yelp, or try the key-combination <ctrl>-r to reload the document, while its already loaded. This will force yelp to reread the file from disk.

Getting an up to date table of contents in yelp

For some reason, the default jhbuild environment doesn't properly install various bits that are needed to get an up to date help system. In order to fix this before you log into your new jhbuild session, edit the file:

$prefix/etc/scrollkeeper.conf

where prefix is where jhbuild installed your base system.

Change the line

OMF_DIR=/usr/share/omf:/usr/local/share/omf:/opt/gnome/share/omf:/opt/gnome-2.0/share/omf:/opt/kde/omf

to look like

OMF_DIR=$prefix/share/omf

where, again, $prefix is replaced by the correct directory.

In my system, jhbuild is installed to /opt/gnome2, so I edit the file:

/opt/gnome2/etc/scrollkeeper.conf

and change the line to look like:

OMF_DIR=/opt/gnome2/share/omf

You then need to run the following commands:

jhbuild shell
scrollkeeper-rebuilddb

This will take some time to run. Once it has finished, you should have an up-to-date table of contents in yelp.

Note: If your running the above instructions from inside your jhbuild session, you can ignore the "jhbuild shell" command.


CategoryDocumentationProject

DocumentationProject/FirstPatch (last edited 2008-02-03 14:46:45 by localhost)