The most frequently asked question of new contributors who join the GDP is “which document should I start with?”. Because most people involved are volunteers, we do not assign projects and applications to write documents for. The first step is all yours - you must decide what about GNOME interests you most and find out if it has complete documents or not.
It is also important to spend some time with GNOME to make sure you are familiar enough with it to be authoritative in your writing. The best way to do this is to just sit down and play with GNOME as much as possible before starting to write.
The easiest way to get started is to improve existing documentation. If you notice some inaccuracies or omissions in the documentation, or you think that you can explain the material more clearly, just send your suggestions to the author of the original documentation or to the GNOME documentation project at <docs@gnome.org>.
The GDP Documentation Status Table (DocTable) (http://developer.gnome.org/projects/gdp/doctable--.html ) is a web page which tracks the status of all the various documentation components of GNOME. These components include application documentation, internal GNOME component documentation, user documentation, and developer documentation. For each documentation item, it tracks the current status of the documentation, who is working on the particular document, where the documentation can be found, and provides a forum for the discussion of each item.
The GDP is currently looking at alternative ways to track our documentation. The DocTable fell into disuse and never completely tracked all the documents in GNOME. Alternatives we are looking into is a new and better DocTable or a Lampadas like system to track the documentation in GNOME. If anyone has experience in distributed project management email suggests or a willingness to help to <docs@gnome.org>.
You should use the DocTable to help you select a documentation item which needs work done. Once you have selected an item to work on, please register yourself as an author so that other authors do not duplicate your work and may contact you to help or offer suggestions.
 | Note |
|---|---|
Note that the information in the DocTable may not always be up-to-date or accurate. When you assign yourself to documenting an application, make sure you find out the latest status of documentation by contacting the application author. | |
Also send an email to the GNOME documentation mailing list (<gnome-doc-list@gnome.org>). You should introduce yourself and ask which programs need docs or ask if a particular program you are interested in documenting already has someone working on the docs. People reading the list will know which docs need working on and which docs need updating or writing.
All documentation for the GNOME project is written in XML using the DocBook DTD. There are many advantages to using this for documentation, not least of which is the single source nature of XML. To contribute to the GDP you should learn to use DocBook.
| Note |
|---|---|
To get started writing for the GDP you do not need to rush out and learn DocBook - if you feel it is too much to handle for now, you can submit plain ASCII text to the gnome-doc-list mailing list and a volunteer will mark it up for you. Seeing your document marked up will also be a great way for you to start learning DocBook. | |
There isn't a standard set of packages to install DocBook XML and make it work locally. Each distribution installs DocBook XML a bit differently with various degrees of support for needed features.
Download and install the following RPM packages from Tim Waugh's DocBook page:
xml-common
docbook-dtds
docbook-style-xsl
libxml2
libxslt
This will setup a basic build environment to convert DocBook XML documents into HTML. If you wish to convert your DocBook document into multiple formats, you will need to download and install the following RPM packages from Tim Waugh's DocBook page:
xmltex
passivetex
xmlto
| Note |
|---|---|
The RPMs for docbook-dtds and docbook-style-xsl might not install a correct entry in your XML Catalog. To check if there is a proper XML Catalog entry for the DTD run the command $ xmlcatalog /etc/xml/docbook "-//OASIS//DTD DocBook XML V4.1.2//EN". If this command returns a URI which starts with file:// then the DTD is correctly installed in the XML Catalog. However, if the command returns No entry for PUBLIC then the DTD is not installed in the XML Catalog. To check if there is a proper XML Catalog entry for the stylesheets run the command $ xmlcatalog /etc/xml/docbook "http://docbook.sourceforge.net/release/xsl/1.49/". If this command returns a URI which starts with file:// then the stylesheet is correctly installed in the XML Catalog. However, if the command returns No entry for SYSTEM then the stylesheet is not installed in the XML Catalog. | |
To fetch all required packages, simply run:
# apt-get install libxslt1 # apt-get install docbook-xsl
Debian packages do not install a XML Catalog currently. Since a XML Catalog is essential to view DocBook documents quickly and easily, you will need to install a XML Catalog by hand. This is not too hard because there is a nice script buildDocBookCatalog which will install a XML Catalog. If you want the XML Catalog to be installed in /etc/xml/ you need to run the script as the root user. However, if you want the XML Catalog to be install in your home directory you need to run the script as a regular user.
| Note |
|---|---|
If the program xmlcatalog is not installed in /usr/bin you might need to alter the buildDocBookCatalog script. Just edit the file in your favorite editor and replace “/usr/bin/xmlcatalog” with “xmlcatalog”. Then as long as the program xmlcatalog is in your path you should be fine. | |
To install the DocBook tools from source get the latest version of libxml2 and libxslt and compile it. This will install the basic tools for working with XML files. Next you will need to download the DocBook XML DTD and DocBook XSL Stylesheets (docbook-xsl). These need to be unpacked and placed in the /usr/local/share/xml/docbook/xml-dtd-4.1.2 directory and the /usr/local/share/xml/docbook/xsl-stylesheets-1.48 directory respectively. Now you need to install a XML Catalog so the DTD and stylesheets can be located locally. This is not too hard because there is a nice script buildDocBookCatalog which will install a XML Catalog. If you want the XML Catalog to be install in /etc/xml/ you need to run the script as the root user. However, if you want the XML Catalog to be installed in your home directory you need to run the script as a regular user.
| Note |
|---|---|
If the program xmlcatalog is not installed in /usr/bin you might need to alter the buildDocBookCatalog script. Just edit the file in your favorite editor and replace “/usr/bin/xmlcatalog” with “xmlcatalog”. Then as long as the program xmlcatalog is in your path you should be fine. | |
There are three tools used with DocBook documents. Xmllint checks the documentation to make sure it is valid DocBook and follows all the rules of XML and the DTD. Xsltproc transforms the document from DocBook to a variety of document formats, including HTML, using XSL stylesheets. Xmlcatalog generates, updates, and checks to make sure the XML catalog is working. You may have used these tools installing DocBook. This isn't meant to be a complete guide to these tools, but an introduction to famaliarize you with the common DocBook tools. If you want more information about any of them consult http://xmlsoft.org or view their respective man pages.
There are many different ways to use xmllint. Xmllint can check the document conforms to the XML specification. It can check the document validates against the delcared DTD or you can force xmllint to use another DTD. Xmllint resolves Xinlcudes and can then check the document validates against a DTD after the Xinclude resolution is complete. There are many options to use with xmllint.
The standard way to use xmllint to show just the errors is to type: xmllint --noout --noent --valid filename.xml . The option --noout suppresses the output of the XML document. Xmllint normally outputs the XML document to the screen and this option stops that behavior. The option --noent resolves any entities which are declared in the document. This allows xmllint to check the validity of the document once the entities are replaced in the document. The last option --valid validates the document against the delcared DTD. By default xmllint just checks to see if the document is well-formed XML. This option tells xmllint to check and make sure the document conforms to the DTD too.
Occasionally you want to validate a document against another DTD. The way to use xmllint to check for errors is to type: xmllint --noout --noent --dtdvalid file:///path/to/dtd/filename.dtd filename.xml. The option --dtdvalid lets you validate the document against a different DTD than the one which was declared in the document. The option has two parts. The first part is the option itself and the second part is the URL to the DTD. In the example above the URL is for a DTD on your local file system. Xmllint can also retreive the DTD from the internet with a valid URL. This is useful to test if the document will conform to two different versions of the DTD.
Sometimes you have a large document and use XIncludes so you have multiple XML files each with their own DTD. The way to use xmlllint to check for errors is to type: xmllint --noout --noent --xinclude --postvalid filename.xml. There are two new options --xinclude and --postvalid. The option --xinclude processes the the document using the XInclude namespace. After the processing is complete you want to check to make sure the entire document conforms to the DTD. The option --postvalid validates the document once all the processing is complete. So, after the XInclude processing is done xmllint is told to validate the document.
The program to convert DocBook XML to a variety of output formats is xsltproc. It is a very quick and powerful XSLT processor. This means it can transform large documents from DocBook to HTML using XSLT stylesheets in seconds instead of minutes.
To transform a XML file using a XSLT stylesheet type: xsltproc --noout -o output stylesheet.xsl filename.xml . This takes the file filename.xml and applies the XSL stylesheet stylesheet.xsl. The output of this transformation is saved in the file output. The option --noout surpresses the output of the transformation to the screen. Using the option -o the output of the transformation is saved in the output file. If the stylesheet you are using saves the document in multiple files, also called chunking, the option -o will save the files in the specified directory. This is an important distinction. When the stylesheet saves the document to a single file, -o specifies the output file. When the stylesheet saves the document in multiple files, -o specifies the output directory.
The program xmlcatalog is a versatile application which creates, edits, and deletes entries in the XML catalog. The XML catalog is similar to the SGML catalog in function, but very different in implementation. XML catalogs are XML files which provide lookup and redirection for DTDs and URIs. This allows the URL given in the DTD delcaration of a XML file to be used in the lookup of the DTD locally in your system. XML catalogs can also cascade so one XML catalog can be redirected to another.
To create an XML Catalog type: xmlcatalog --noout --create /etc/xml/catalog. An empty XML Catalog will be created in the directory /etc/xml as the file catalog. Make sure you have write permissions to the directory so the file can be created. Now that you have an empty XML Catalog you need to populate the catalog. To add a DTD to the catalog type: xmlcatalog --noout --add "public" ""-//OASIS//DTD DocBook XML V4.1.2//EN" "file://usr/share/xml/docbook/docbookx.dtd" /etc/xml/catalog. This will redirect all queries for the DocBook V4.1.2 DTD to the location of the DocBook DTD, in this example file://usr/share/xml/docbook/docbookx.dtd. The last option in the command is the location of the XML Catalog. This should be the same place you created the XML Catalog.
There are many editors on Linux and UNIX systems available to you. Which editor you use to work on the XML documents is completely up to you, as long as the editor is able to preserve XML and produce the source in a format that is readable by everyone.
Probably the two most popular editors available are Emacs and vi. These and other editors are used regularly by members of the GDP. Emacs has a major mode, psgml, for editing DocBook files which can save you time and effort in adding and closing tags. You will find the psgml package in your distribution of Linux. If your distribution does not use binary packages, the source code for psgml is available at http://psgml.sourceforge.net.
To view your DocBook documents you've made you need to run Yelp from the commandline. This can be done by typing yelp ghelp:/path/to/filename.xml to have Yelp display the XML file.
If you do not want to use Yelp to view your documentation, you can use xsltproc with the GNOME stylesheets. The program xsltproc takes the DocBook file and using the GNOME stylesheets makes a new HTML file. The HTML file can be viewed from your favorite web browser. You will need to download the GNOME XSL stylesheets in the module gnome-docu/gdp/xsl in GNOME CVS. To run xsltproc type xsltproc general-customizations.xsl filename.xml to produce the HTML.
| Note |
|---|---|
Producing the HTML directly from the XML is not recommended. The user documentation will be viewed in Yelp. Therefore to see how the docs will look to the user the GDP recommends you use Yelp to view the documentation. An alternative way to view the documentation is given to those who may not have Yelp installed. | |
Templates for various types of GNOME documents are found at the GDP Document Templates website. They are kept in CVS at gnome-docu/gdp/templates. These templates are meant to guide you through the process of making documentation. They contain the structure of the articleinfo section. The basic structure of a document is outlined. Many different elements are marked up in DocBook such as itemized lists, variable lists, and figures. It is okay to change the templates to fit the application you are writing documentation for. Changing the format of the articleinfo section is not recommended as the output will not look nice.
GNOME 2 documentation is written in DocBook XML, version 4.1.2.
We use DocBook because it provides structured semantic markup, allowing publication in a variety of media. We use XML because of the more flexible tool kit available to use with it.
Converting documents from SGML to XML requires a few changes.
- The DTD
A new DTD is needed at the start of the document:
<?xml version="1.0"?> <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ ]>Note that the system identifier is required.- Graphic
The graphic tag is deprecated in DocBook version 4, and while it will still work, we plan to change to figure and mediaobject of several flavors, depending on whether the image is a large figure, a small figure, or a screenshot. This will utilize the greater flexibility of DocBook 4.1.2 and specify the content of the images more accurately.
A large figure is a large image which isn't a screenshot. This can be a variety of images. The markup for a large figure:
<figure id="id"> <title>Figure Description</title> <mediaobject> <imageobject> <imagedata fileref="path/to/image.png" format="PNG"/> </imageobject> <imageobject> <imagedata fileref="path/to/image.eps" format="EPS"/> </imageobject> <textobject> <phrase>Acessibility description</phrase> </textobject> </mediaobject> </figure>A small figure is a small image which isn't a screenshot. This can be a variety of things. The markup for a small figure:
<mediaobject id="id"> <imageobject> <imagedata fileref="path/to/image.png" format="PNG"/> </imageobject> <imageobject> <imagedata fileref="path/to/image.eps" format="EPS"/> </imageobject> <textobject> <phrase>Acessibility description</phrase> </textobject> </mediaobject>
A screenshot is an image which is taken of the desktop or of an application or a dialog box. The markup for a screenshot:
<figure id="id"> <title>Figure Description</title> <screenshot> <mediaobject> <imageobject> <imagedata fileref="path/to/image.png" format="PNG"/> </imageobject> <imageobject> <imagedata fileref="path/to/image.eps" format="EPS"/> </imageobject> <textobject> <phrase>Acessibility description</phrase> </textobject> </mediaobject> </screenshot> </figure>- xref
The xref tag also must be closed:
<xref linkend="mainwindow-fig" />
- Artheader
artheader must be replaced with articleinfo.
The GDP Style Guide should be read in conjunction with this document. The Style Guide tells how to write documentation, ways to structure the documentation, and technical writing techniques. The GDP Style Guide is located at http://developer.gnome.org/projects/gdp/styleguide.html.
Most GNOME documents will have screenshots of the particular applet, application, GNOME component, or widget being discussed. As discussed previously all images for GNOME documentation should be in the PNG format. Alternatively if you wish the documentation to be printed you should also include the same images in EPS format. For the basic DocBook structure used to insert images in a document, see Screenshots in DocBook above.
If your document uses images you will need to take note of a few things that should take place in order for you to make use of those images in your output.
The DocBook tools and applications are smart enough to know that when you are creating html you will be using PNG files and when you are creating Postscript you will be using EPS files (you must use EPS with Postscript).
<figure id="id">
<title>My Picture</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="myfile.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>Acessibility description</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
If you want to create PostScript ouput, you will need to create an EPS version of your image file to be displayed in the PostScript file. There is a simple script available which allows you to change a PNG image into an EPS file easily. You can download this file - png2eps - from http://dmason.net/download/png2eps.
For all screenshots of windows that typically have border decorations (e.g. applications and dialogs, but not applets in a panel), GDP standards dictate the appearance of the window. (This is to minimize possible confusion to the reader, improve the appearance of GNOME documents, and guarantee the screenshot is readable when printed.) All screenshots should be taken with the SawFish window manager using the Crux theme and Helvetica 12pt font. (A different window manager can be used provided the Crux theme is available for this window manager and the appearance is identical to that when using the SawFish window manager.) The default GTK+ theme (Raleigh) and font (Helvetica 12 pt) should be used for all screenshots. If you are unable to provide screenshots in this form, you should create screenshots as you wish them to appear and send an email to the gnome-doc-list mailing list requesting a GDP member reproduce these screenshots in the correct format and email them to you. Please do not send the actual images in the email but wait until you contact someone to do the screenshots for you and mail them the images.
There are many tools for taking screenshots in GNOME/Linux. Perhaps the most convenient is the Take a Screen Shot tool located in Actions->Take a Screen Shot. Just choose whether you want to save the screenshot to a file or on the desktop and click Okay. When you click the Okay button the tool will take a screenshot in a second. If you want a window in focus you will need to focus the window in the second from when you click the Okay button to when the tool takes a screen shot. For applets in a Panel, GIMP can be used to crop the screenshot to only include the relevant portion of the Panel. Note that GIMP can both be used for taking screenshots, cropping screenshots, and converting image formats. If you need to convert an image to PNG from another format make sure you use compression liberally. A high compression level will usually look fine in Yelp.
To create a screenshot that does not require callouts, follow these steps:
Start GIMP.
Choose File->Acquire->Screenshot. A Screen Shot dialog is displayed.
Select the options that you require in the Screen Shot dialog, then click OK. GIMP takes the screenshot, and displays the screenshot.
If necessary, scale the image down. Save the image as PNG.
Alternatively, to take a screenshot of the desktop, choose Actions->Take a Screen Shot. The screenshot is displayed in a Screenshot dialog. If necessary, you can use GIMP to crop the screenshot, or to scale the image down.
You can download a sample screenshot with callouts, sample_anno_panel.xcf. This file is in the native format of GIMP, XCF. To create a screenshot and all callouts to the screenshot, follow these steps:
Start GIMP.
Choose File->Acquire->Screenshot. A Screen Shot dialog is displayed.
Select the options that you require in the Screen Shot dialog, then click OK. GIMP takes the screenshot, and displays the screenshot.
Create space on the image in which to add the callouts. To do this, right-click on the image, then choose Image->Canvas Size. A Set Canvas Size dialog is displayed. Specify the new size of the image in the upper part of this dialog. Use the lower part of the dialog to position the screenshot in the image.
Alternatively, you can create a large new image, then paste in the screenshot. When you are finished you can use the Crop tool to resize the image.
Save the file in XCF format. XCF is the native format of GIMP and allows you to use complex graphical features such as layers.
When your screenshot is localized, the localizer might cut out the screenshot in the original language, and paste in the screenshot in the new language. A mark that indicates the location of the screenshot might be helpful in this case.
Create the mark in a new layer. To create a new layer, right-click on the image, then choose Layers->Layers, Channels & Paths. The Layers, Channels & Paths dialog is displayed. Click on the New Layer button at the bottom left of the dialog. Name the layer Top left corner of image.
Use the Pencil tool to draw a right angle around the top left corner of the image. Format the lines as follows:
Foreground colour: Green (Hex triplet: #00ff00)
Create a new layer for the callout lines. Name the layer Callout lines.
Use the Pencil tool to draw the callout lines. To keep the lines straight, click to start drawing the line, then press-and-hold Shift. Format the lines as follows:
Brush: pixel (1 x 1 square)
Foreground colour: Black (Hex triplet: #000000)
Use straight horizontal and vertical lines only.
Use the dynamic text plugin to create the callout text. To access the Dynamic Text plugin, right-click on an image, then choose Filters->Render->Dynamic Text. This creates a new layer for each text item. Format the text as follows:
helvetica(adobe)
medium
11-point
anti-aliased
Rename the layers so that the name of the layer matches the text that appears in the callout. Prefix each layer name with Text: .
Save the image as PNG (right-click on the image and choose File->Save As). An Export File dialog is displayed. This warns that you are about to flatten the layers in the image. Click on the Export button. A Save As PNG dialog is displayed. Deselect the Save background color option. Ensure that you do not overwrite the XCF file!
Documentation authors tend to investigate and test applets and applications more thoroughly than most users. Often documentation authors will discover one or more bugs in the software. These bugs vary from small ones, such as mis-spelled words or missing About dialogs in the menu, to large ones which cause the applet to crash. As all users, you should be sure to report these bugs so that application developers know of them and can fix them. The easiest way to submit a bug report is by using Bug Buddy located in Applications->Programming->Bug Report Tool.