node10-libxslt

<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>The GNOME Handbook of Writing Software Documentation</title><meta name="generator" content="DocBook XSL Stylesheets V1.40"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article"><div class="titlepage"><div><h2 class="title"><a name="index"></a>The GNOME Handbook of Writing Software Documentation</h2></div><div><h3 class="author">David Mason</h3><div class="affiliation"><span class="orgname">Red Hat, Inc.<br></span><div class="address"><br> ��<tt><<a href="mailto:dcm@redhat.com">dcm@redhat.com</a>></tt><br> ��</div></div><h3 class="author">Daniel Mueth</h3><div class="affiliation"><div class="address"><br> ��<tt><<a href="mailto:d-mueth@uchicago.edu">d-mueth@uchicago.edu</a>></tt><br> ��</div></div><h3 class="author">Alexander Kirillov</h3><div class="affiliation"><div class="address"><br> ��<tt><<a href="mailto:kirillov@math.sunysb.edu">kirillov@math.sunysb.edu</a>></tt><br> ��</div></div></div><div><p class="releaseinfo"> This is a pre-release! </p></div><div><p class="copyright">Copyright � 2000 Red Hat, Inc., Daniel Mueth, and Alexander Kirillov</p></div><div><div class="legalnotice"><p> Permission is granted to copy, distribute and/or modify this document under the terms of the <i>GNU Free Documentation License</i>, Version 1.1 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. You may obtain a copy of the <i>GNU Free Documentation License</i> from the Free Software Foundation by visiting <a href="http://www.fsf.org" target="_top">their Web site</a> or by writing to: Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. </p><p> Many of the names used by companies to distinguish their products and services are claimed as trademarks. Where those names appear in any GNOME documentation, and those trademarks are made aware to the members of the GNOME Documentation Project, the names have been printed in caps or initial caps. </p></div></div><div><div class="revhistory"><table border="1" width="100%" summary="Revision history"><tr><th align="left" valign="top" colspan="2"><b>Revision History</b></th></tr><tr><td align="left">Revision 0.99 </td><td align="left"> 04.10.2000 </td></tr></table></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt> <a href="#intro">Introduction</a></dt><dd><dl><dt> <a href="#gdp">The GNOME Documentation Project</a></dt><dt> <a href="#notation">Notation and Conventions</a></dt><dt> <a href="#about">About This Handbook</a></dt></dl></dd><dt> <a href="#gettingstarted">Getting Started Writing GNOME Documentation</a></dt><dd><dl><dt> <a href="#selecting">Selecting A Document</a></dt><dt> <a href="#docbook">Installing and Using DocBook</a></dt><dt> <a href="#gdptemplates">GDP Document Templates</a></dt><dt> <a href="#screenshots">Screenshots</a></dt><dt> <a href="#applicationbugs">Application Bugs</a></dt><dt> <a href="#cvs">Using CVS</a></dt></dl></dd><dt> <a href="#gnomedocsystem">The GNOME Documentation System</a></dt><dd><dl><dt> <a href="#gnomehelpbrowser">The GNOME Help Browser</a></dt><dt> <a href="#gnomehelpbrowser2">The GNOME Help Browser (GNOME-2.0)</a></dt><dt> <a href="#gnomehelponthefly">Dynamic Document Synthesis(GNOME-2.0)</a></dt><dt> <a href="#gnomehelpcomponents">The GNOME Documentation Components</a></dt></dl></dd><dt> <a href="#docbookbasics">DocBook Basics </a></dt><dd><dl><dt> <a href="#introtodocbook">Introduction to DocBook</a></dt><dt> <a href="#xml">XML and SGML</a></dt><dt> <a href="#structure"> Structure Elements</a></dt><dt> <a href="#inline">Inline Elements</a></dt></dl></dd><dt> <a href="#conventions">GDP Documentation Conventions </a></dt><dd><dl><dt> <a href="#conventionsalldocs">Conventions for All GDP Documentation</a></dt><dt> <a href="#conventionsappdocs">Conventions for Application Documentation</a></dt></dl></dd><dt> <a href="#writingapplicationmanuals">Writing Application and Applet Manuals</a></dt><dt> <a href="#listingdocsinhelpmenu">Listing Documents in the Help Menu</a></dt><dt> <a href="#applicationhelpbuttons">Application Help Buttons</a></dt><dt> <a href="#packagingappletdocs">Packaging Applet Documentation</a></dt><dd><dl><dt> <a href="#appletfiles">Applet Documentation Files</a></dt><dt> <a href="#appletmenu">Adding Documentation to an Applet Menu</a></dt></dl></dd><dt> <a href="#writingcontextsensitivehelp">Writing Context Sensitive Help (coming in GNOME-2.0)</a></dt><dt> <a href="#referring">Referring to Other GNOME Documentation (coming in GNOME-2.0)</a></dt><dt> <a href="#basics">Basics of Documentation Style</a></dt><dd><dl><dt> <a href="#styleplanning">Planning</a></dt><dt> <a href="#balance">Achieving a Balanced Style</a></dt><dt> <a href="#stylestructure">Structure</a></dt><dt> <a href="#stylegrammar">Grammar and Spelling</a></dt></dl></dd><dt> <a href="#teamwork">Teamwork</a></dt><dd><dl><dt> <a href="#teamworkgdp">Working With The GDP Team</a></dt><dt> <a href="#teamworkdevelopers">Working With Developers</a></dt></dl></dd><dt> <a href="#finishing">Finishing A Document</a></dt><dd><dl><dt> <a href="#editting">Editing The Document</a></dt><dt> <a href="#submitting">Submitting The Document</a></dt></dl></dd><dt> <a href="#resources">Resources</a></dt><dd><dl><dt> <a href="#resourcesweb">Resources On The Web</a></dt><dt> <a href="#resourcesbooks">Books</a></dt><dt> <a href="#mailinglists">Mailing Lists</a></dt><dt> <a href="#irc">IRC</a></dt></dl></dd><dt>A <a href="#templates">Document Templates</a></dt><dd><dl><dt> <a href="#template1">Template 1: Application Manual</a></dt><dt> <a href="#template2-1x">Template 2: Applet Manual For GNOME 1.x</a></dt><dt> <a href="#template2-2x">Template 2: Applet Manual For GNOME 2.x</a></dt></dl></dd></dl></div><div class="sect1"><a name="intro"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="intro"></a>Introduction</h2></div></div><div class="sect2"><a name="gdp"></a><div class="titlepage"><div><h3 class="title"><a name="gdp"></a>The GNOME Documentation Project</h3></div></div><div class="sect3"><a name="goals"></a><div class="titlepage"><div><h4 class="title"><a name="goals"></a>Goals</h4></div></div><p> The GNOME Documentation Project (GDP) aims to provide GNOME and GNOME applications with a complete, intuitive, and clear documentation system. At the center of the GDP is the GNOME Help Browser, which presents a unified interface to GNOME-specific documentation as well as other Linux documentation such as man pages and texinfo documents. The GNOME Help System provides a comprehensive view of documentation on a machine by dynamically assembling the documentation of GNOME applications and components which are installed. The GDP is responsible for writing numerous GNOME-related documents, both for developers and for users. Developer documentation includes <a href="http://developer.gnome.org/doc/API/" target="_top">APIs for the GNOME libraries</a>, <a href="http://developer.gnome.org/doc/whitepapers/" target="_top"><i>GNOME White Papers</i></a>, GNOME developer <a href="http://developer.gnome.org/doc/tutorials/" target="_top">tutorials</a>, the <a href="http://developer.gnome.org/doc/FAQ/" target="_top"><i>GNOME Developer FAQ</i></a>, the <a href="http://developer.gnome.org" target="_top">GNOME Developer's Website</a>, and <i>GNOME Handbook</i>'s, such as the one you are reading. User documentation include the <a href="http://www.gnome.org/learn/" target="_top"><i>GNOME User's Guide</i></a>, the <a href="http://www.gnome.org/learn/" target="_top"><i>GNOME FAQ</i></a>, and GNOME application documentation. Most GNOME applications have their own manual in addition to context sensitive help. </p></div><div class="sect3"><a name="joining"></a><div class="titlepage"><div><h4 class="title"><a name="joining"></a>Joining the GDP</h4></div></div><p> Documenting GNOME and all the numerous GNOME applications is a very large project. The GDP is always looking for people to help write, update, and edit documentation. If you are interested in joining the GDP team, you should join the <a href="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/" target="_top"> <i>gnome-doc-list mailing list</i> </a>. Read <a href="#gettingstarted" title="Getting Started Writing GNOME Documentation">the section called “Getting Started Writing GNOME Documentation”</a>, for help selecting a project to work on. Feel free to introduce yourself on the gnome-doc-list mailing list and indicate which project you intend to work on, or else ask for suggestions of important documents which need work done. You may also want to join the #docs IRC channel on irc.gnome.org to meet other GDP members and discuss any questions you may have. For a list of GDP projects and members, see the <a href="http://developer.gnome.org/projects/gdp" target="_top"> <i>GDP Website</i></a>. </p></div><div class="sect3"><a name="collaborating"></a><div class="titlepage"><div><h4 class="title"><a name="collaborating"></a>Collaborating with the GDP</h4></div></div><p> GNOME developers, packagers, and translators may not be writing GNOME documentation but will want to understand how the GNOME documentation system works and will need to collaborate with GDP members. This document should help to outline the structure of how the GNOME documentation system works. Developers who do not write the documentation for their applications are encouraged to find a GDP member to write the documentation. This is best done by sending an email to the <a href="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/" target="_top"> <i>gnome-doc-list mailing list</i> </a> describing the application, where it can be downloaded from, and that the developer(s) would like a GDP member to write documentation for the application. The #docs IRC channel on irc.gnome.org is another option for contacting GDP members. </p></div></div><div class="sect2"><a name="notation"></a><div class="titlepage"><div><h3 class="title"><a name="notation"></a>Notation and Conventions</h3></div></div><p> This Handbook uses the following notation: <div class="informaltable" id="id2797678"><a name="id2797678"></a><table border="0"><colgroup><col><col></colgroup><tbody><tr><td><tt>/usr/bin</tt></td><td> Directory </td></tr><tr><td><tt>foo.sgml</tt></td><td> Filename </td></tr><tr><td><b>command</b></td><td> Command or text that would be typed. </td></tr><tr><td><b><i><tt>replaceable</tt></i></b></td><td> "Variable" text that can be replaced. </td></tr><tr><td><tt>Program or Doc Code</tt></td><td>Program or document code</td></tr></tbody></table></div> </p></div><div class="sect2"><a name="about"></a><div class="titlepage"><div><h3 class="title"><a name="about"></a>About This Handbook</h3></div></div><p> This Handbook is a guide for both writing documentation for GNOME components and applications and for properly binding and packaging documentation into GNOME applications. </p><p> This Handbook, like all GNOME documentation, was written in DocBook(SGML) and is available in several formats including SGML, HTML, PostScript, and PDF. For the latest version, see <a href="http://developer.gnome.org/projects/gdp/handbook.html" target="_top"> <i>Getting The GNOME Handbook of Writing Software Documentation</i> </a>. Alternately, one may download it anonymously from GNOME CVS under <tt>gnome-docu/gdp</tt>. </p></div></div><div class="sect1"><a name="gettingstarted"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="gettingstarted"></a>Getting Started Writing GNOME Documentation</h2></div></div><div class="sect2"><a name="selecting"></a><div class="titlepage"><div><h3 class="title"><a name="selecting"></a>Selecting A Document</h3></div></div><div class="sect3"><a name="know"></a><div class="titlepage"><div><h4 class="title"><a name="know"></a>Document Something You Know</h4></div></div><p> 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 <i>assign</i> 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. </p><p> It is also important to spend some time with GNOME to make sure you are familiar enough with it to be <i>authoritative</i> 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. </p><p> 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 <tt><<a href="mailto:docs@gnome.org">docs@gnome.org</a>></tt>. </p></div><div class="sect3"><a name="doctable"></a><div class="titlepage"><div><h4 class="title"><a name="doctable"></a>The GNOME Documentation Status Table</h4></div></div><p> The <i>GDP Documentation Status Table</i> (<i>DocTable</i>) (<a href="http://www.gnome.org/gdp/doctable/" target="_top">http://www.gnome.org/gdp/doctable/</a>) 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. </p><p> You should use the <i>DocTable</i> 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. Also be sure to keep the status icons up-to-date so that the GDP team can easily identify which items need additional help. The <i>DocTable</i> also allows people to make announcements and suggestions and to discuss issues in the comments section. </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a name="id2795548"></a>Note</h3><p> Note that the information in the <i>DocTable</i> 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. </p></div></div></div><div class="sect2"><a name="docbook"></a><div class="titlepage"><div><h3 class="title"><a name="docbook"></a>Installing and Using DocBook</h3></div></div><p> All documentation for the GNOME project is written in SGML using the DocBook DTD. There are many advantages to using this for documentation, not least of which is the single source nature of SGML. To contribute to the GDP you should learn to use DocBook. </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a name="id2795631"></a>NOTE</h3><p> 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 <a href="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/" target="_top"> <i>gnome-doc-list mailing list</i> </a>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. </p></div><div class="sect3"><a name="installingdocbook"></a><div class="titlepage"><div><h4 class="title"><a name="installingdocbook"></a>Installing DocBook</h4></div></div><p> Download and install the following <a href="ftp://sourceware.cygnus.com:/pub/docbook-tools/" target="_top">DocBook Tools packages</a>: jade, docbook, jadetex, sgml-common, and stylesheets. (RPM users should note that jade is platform dependent (eg. i386), while the other packages are in the <tt>noarch</tt> directory.) You can find more information on DocBook Tools <a href="http://sourceware.cygnus.com/docbook-tools/" target="_top">here</a>. </p><p> If you are an Emacs user you may want to grab the psgml package as well. This is a major mode for editing sgml files in Emacs. </p></div><div class="sect3"><a name="gdpstylesheets"></a><div class="titlepage"><div><h4 class="title"><a name="gdpstylesheets"></a>GDP Stylesheets</h4></div></div><p> The GDP uses its own DocBook stylesheets. To use the GDP stylesheets, you should download the file <tt>gdp-both.dsl</tt> from the <tt>gnome-docu/gdp/dsssl</tt> module in CVS (or from <a href="http://developer.gnome.org/projects/gdp/stylesheets.html" target="_top"> GDP Custom DSSSL Stylesheet</a>)and copy it over the file <tt>/usr/lib/sgml/stylesheets/cygnus-both.dsl</tt>. Alternately, you can download and install the <a href="http://people.redhat.com/dcm/software.html" target="_top">gnome-doc-tools package</a> which will set up the stylesheets as well as the DTD discussed below. </p></div><div class="sect3"><a name="gdpdtd"></a><div class="titlepage"><div><h4 class="title"><a name="gdpdtd"></a>GDP DTD (PNG Image Support)</h4></div></div><p> Due to some license issues involved with the creation of gifs, the GNOME Documentation Project has decided to use the PNG image format for all images in GNOME documentation. You can read more about the issues involved with gifs at <a href="http://www.gnu.org/philosophy/gif.html" target="_top">http://www.gnu.org/philosophy/gif.html</a>. </p><p> The current DocBook DTD(3.1) does not include support for embedding PNG images in your documents. Since the GDP uses many screenshots in its documentation, we use our own variation on the DocBook DTD which has PNG image support. We encourage everybody to use this DTD instead of the default DocBook DTD since your source document header and your output document appearance subtly vary between the two DTD's. To install the GDP custom DTD with PNG image support by hand: </p><div class="itemizedlist"><ul><li style="list-style-type: opencircle"><p><a name="id2796045"></a> Download <a href="http://www.labs.redhat.com/png/png-support.html" target="_top">the GDP DocBook DTD for PNG support</a> and install it where you keep your DTD's. (On Red Hat use <tt>/usr/lib/sgml/</tt>.) Note that the 3.0 DTD is missing support for the <tt><legalnotice></tt> tag, so it is recommended that you use version 3.1 </p></li><li style="list-style-type: disc"><p><a name="id2796107"></a> Add the new DTD to your SGML CATALOG file. The location of your SGML CATALOG file may vary depending upon your distribution. (On Red Hat it is usually in /usr/lib/sgml/CATALOG.) Add the following line to this file: <pre class="programlisting"> PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.0//EN" "png-support-3.0.dtd" </pre> If you are using the 3.1 DTD, use: <pre class="programlisting"> PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN" "png-support-3.1.dtd" </pre> </p></li></ul></div><p> Alternately, you can download and install the <a href="http://people.redhat.com/dcm/software.html" target="_top">gnome-doc-tools package</a> which will set up the custom stylesheets and DTD for you. </p><p> To include PNG files in your documents, you will need to indicate that you are using this special DTD. To do this, use the following headers: </p><p> Articles: <pre class="programlisting"> <!DOCTYPE Article PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[]> </pre> </p><p> Books: <pre class="programlisting"> <!DOCTYPE Book PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[]> </pre> </p></div><div class="sect3"><a name="editors"></a><div class="titlepage"><div><h4 class="title"><a name="editors"></a>Editors</h4></div></div><p> There are many editors on Linux and UNIX systems available to you. Which editor you use to work on the sgml documents is completely up to you, as long as the editor is able to preserve sgml and produce the source in a format that is readable by everyone. </p><p> 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 sgml files which can save you time and effort in adding and closing tags. You will find the psgml package in DocBook Tools, which is the standard set of tools for the GDP. You may find out more about DocBook Tools in <a href="#installingdocbook" title="Installing DocBook">the section called “Installing DocBook”</a>. </p></div><div class="sect3"><a name="make-output"></a><div class="titlepage"><div><h4 class="title"><a name="make-output"></a>Creating Something Useful with your Docs</h4></div></div><p> The tools available in DocBook Tools allow you to convert your sgml document to many different formats including html and Postscript. The primary tool used to do the conversion is an application called Jade. In most cases you will not have to work directly with Jade; Instead, you will use the scripts provided by DocBook Tools. </p><p> To preview your DocBook document, it is easiest to convert it to <tt>html</tt>. If you have installed the DocBook tools described above, all you have to do is to run the command <tt>$</tt><b>db2html mydocument.sgml</b>. If there are no sgml syntax errors, this will create a directory <tt>mydocument</tt> and place the resulting html files in it. The title page of the document will typically be <tt>mydocument/index.html</tt>. If you have screenshots in your document, you will have to copy these files into the <tt>mydocument</tt> directory by hand. You can use any web browser to view your document. Note that every time you run <b>db2html</b>, it creates the <tt>mydocument</tt> directory over, so you will have to copy the screenshots over each time. </p><p> You can also convert your document to PostScript by running the command <tt>$</tt><b>db2ps mydocument.sgml</b>, after which you can print out or view the resulting .ps file. </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a name="id2796585"></a>NOTE</h3><p> The html files you get will not look quite the same as the documentation distributed with GNOME unless you have the custom stylesheets installed on your machine. DocBook Tools' default stylesheets will produce a different look to your docs. You can read more about the GDP stylesheets in <a href="#gdpstylesheets" title="GDP Stylesheets">the section called “GDP Stylesheets”</a>. </p></div></div><div class="sect3"><a name="jadeimages"></a><div class="titlepage"><div><h4 class="title"><a name="jadeimages"></a>Images in DocBook Tools</h4></div></div><p> 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. </p><p> The DocBook Tools scripts 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). </p><p> Thus, you should never explicitly include the extension of the image file, since DocBook Tools will automatically insert it for you. For example: </p><pre class="programlisting"> <figure> <title>My Image</title> <screenshot> <screeninfo>Sample GNOME Display</screeninfo> <graphic format="png" fileref="myfile" srccredit="me"> </graphic> </screenshot> </figure> </pre><p> You will notice in this example that the file <tt>myfile.png</tt> was referred to as simply <tt>myfile</tt>. Now when you run <b>db2html</b> to create an html file, it will automatically look for <tt>myfile.png</tt> in the directory. </p><p> 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 - img2eps - from <a href="http://people.redhat.com/dcm/sgml.html" target="_top">http://people.redhat.com/dcm/sgml.html</a> (look for the img2eps section). Note that this script is included in the gnome-doc-tools package, so if you are using this package, you should already have <b>img2eps</b> on you system. </p></div><div class="sect3"><a name="moredocbookinfo"></a><div class="titlepage"><div><h4 class="title"><a name="moredocbookinfo"></a>Learning DocBook</h4></div></div><p> There are many resources available to help you learn DocBook. The following resources on the web are useful for learning DocBook: </p><div class="itemizedlist"><ul><li style="list-style-type: disc"><p><a name="id2918531"></a> <a href="http://www.docbook.org" target="_top">http://www.docbook.org</a> - Norman Walsh's <i>DocBook: The Definitive Guide</i>. Online O'Reilly book on using DocBook. Contains an excellent element reference. May be too formal for a beginner. </p></li><li style="list-style-type: disc"><p><a name="id2918577"></a> <a href="http://www.oswg.org/oswg-nightly/oswg/en_US.ISO_8859-1/articles/DocBook-Intro/docbook-intro/index.html" target="_top">A Practical Introduction to DocBook</a> - The Open Source Writers Group's introduction to using DocBook. This is an excellent HOW-TO type article on getting started. </p></li><li style="list-style-type: disc"><p><a name="id2918619"></a> <a href="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro/docbook-intro.html" target="_top">Getting Going with DocBook: Notes for Hackers</a> - Mark Galassi's introduction to DocBook for hackers. This has to be one of the first introductions to DocBook ever - still as good as it ever was. </p></li><li style="list-style-type: disc"><p><a name="id2918658"></a> <a href="http://www.freebsd.org/tutorials/docproj-primer/" target="_top"> FreeBSD Documentation Project Primer for New Contributors</a> - FreeBSD documentation project primer. Chapter 4.2 provides a very good introduction to writing documentation using DocBook. Note that it also describes some custom extensions of DocBook; fortunately, they are clearly marked as such. </p></li></ul></div><p> Norman Walsh's book is also available in print. </p><p> The following sections of this document are designed to help documentation authors write correct and consistent DocBook: </p><div class="itemizedlist"><ul><li style="list-style-type: disc"><p><a name="id2918733"></a> <a href="#docbookbasics" title="DocBook Basics ">the section called “DocBook Basics ”</a> - Descriptions of commonly used DocBook tags. </p></li></ul></div><p> You may also discuss specific DocBook questions with GDP members on the #docs IRC channel at irc.gnome.org and on the gnome-doc-list mailing list. </p></div></div><div class="sect2"><a name="gdptemplates"></a><div class="titlepage"><div><h3 class="title"><a name="gdptemplates"></a>GDP Document Templates</h3></div></div><p> Templates for various types of GNOME documents are found in <a href="#templates" title="A. Document Templates">Appendix A. Document Templates</a>. They are kept in CVS in gnome-docu/gdp/templates. The easiest source to get them from is probably the <a href="http://developer.gnome.org/projects/gdp/templates.html" target="_top">GDP Document Templates</a> web page, which is typically kept completely up-to-date with CVS and has a basic description of each file from CVS. </p></div><div class="sect2"><a name="screenshots"></a><div class="titlepage"><div><h3 class="title"><a name="screenshots"></a>Screenshots</h3></div></div><p> Most GNOME documents will have screenshots of the particular applet, application, GNOME component, or widget being discussed. As discussed above in <a href="#gdpdtd" title="GDP DTD (PNG Image Support)">the section called “GDP DTD (PNG Image Support)”</a> you will need to install the special GDP DocBook DTD which supports PNG images, the format used for all images in GNOME documentation. For the basic DocBook structure used to insert images in a document, see <a href="#jadeimages" title="Images in DocBook Tools">the section called “Images in DocBook Tools”</a> above. </p><div class="sect3"><a name="screenshotappearance"></a><div class="titlepage"><div><h4 class="title"><a name="screenshotappearance"></a>Screenshot Appearance</h4></div></div><p> 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 (formerly known as Sawmill) window manager using the MicroGui theme and Helvetica 12pt font. (A different window manager can be used provided the MicroGui theme is available for this window manager and the appearance is identical to that when using the SawFish window manager.) The default GTK+ theme(gtk) 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 them to the <a href="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/" target="_top"> <i>gnome-doc-list mailing list</i> </a> requesting a GDP member reproduce these screenshots in the correct format and email them to you. </p></div><div class="sect3"><a name="screenshottools"></a><div class="titlepage"><div><h4 class="title"><a name="screenshottools"></a>Screenshot Tools</h4></div></div><p> There are many tools for taking screenshots in GNOME/Linux. Perhaps the most convenient is the Screen-Shooter Applet. Just click on the window icon in the applet and then on the window you would like to take a screenshot of. (Note that at the time of this writing, PNG images taken by screenshooter do not appear properly in Netscape or the GNOME Help Browser. You should save your screenshot as a GIF and then use <b>convert filename.gif filename.png</b>.) For applets in a Panel, xv can be used to crop the screenshot to only include the relevant portion of the Panel. Note that xv and gimp can both be used for taking screenshots, cropping screenshots, and converting image formats. </p></div><div class="sect3"><a name="screenshotfiles"></a><div class="titlepage"><div><h4 class="title"><a name="screenshotfiles"></a>Screenshot Files</h4></div></div><p> Screenshots should be kept in the main documentation directory with your SGML file for applets, or should be kept in a directory called "figs" for application and other documentation. After you use <b>db2html</b> to convert your SGML file to HTML (see <a href="#make-output" title="Creating Something Useful with your Docs">the section called “Creating Something Useful with your Docs”</a>), you will need to copy your screenshots (either the individual PNG files for applet documentation, or the whole "figs" directory for other documentation) into the newly created HTML directory. Note that every time you use <b>db2html</b> the HTML directory is erased and rewritten, so do not store your only copy of the screenshots in that directory. If you wish to create PostScript or PDF output, you will need to manually convert the PNG images to EPS as described in <a href="#jadeimages" title="Images in DocBook Tools">the section called “Images in DocBook Tools”</a>, but will not need to copy these images from their default location, as they are included directly into the output(PostScript of PDF) file. </p></div></div><div class="sect2"><a name="applicationbugs"></a><div class="titlepage"><div><h3 class="title"><a name="applicationbugs"></a>Application Bugs</h3></div></div><p> 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 the Bug Buddy applet which is part of the gnome-applets package. </p></div><div class="sect2"><a name="cvs"></a><div class="titlepage"><div><h3 class="title"><a name="cvs"></a>Using CVS</h3></div></div><p> CVS (Concurrent Versions System) is a tool that allows multiple developers to concurrently work on a set of documents, keeping track of the modifications made by each person. The files are stored on a server and each developer checks files out, modifies them, and then checks in their modified version of the files. Many GNOME programs and documents are stored in CVS. The GNOME CVS server allows users to anonymously check out CVS files. Most GDP members will need to use anonymous CVS to download the most up-to-date version of documentation or programs. Modified documents will typically be emailed to the the application developer. Core GDP members may also be granted login CVS privileges so they may commit modified files directly to CVS. </p><div class="sect3"><a name="anonymouscvs"></a><div class="titlepage"><div><h4 class="title"><a name="anonymouscvs"></a>Anonymous CVS</h4></div></div><p> To anonymously check out documents from CVS, you must first log in. From the bash shell, you should set your CVSROOT shell variable with <b> export CVSROOT=':pserver:anonymous@anoncvs.gnome.org:/cvs/gnome'</b> and then login with <b>cvs login</b>(there is no password, just hit return). As an example, we will use the "gnome-docu/gdp" module which contains this and several other documents. To check these documents out for the first time, type <b>cvs -z3 checkout gnome-docu/gdp</b>. After you have this document checked out and you would like to download any updates on the CVS server, use <b>cvs -z3 update -Pd</b>. </p></div><div class="sect3"><a name="logincvs"></a><div class="titlepage"><div><h4 class="title"><a name="logincvs"></a>Login CVS</h4></div></div><p> If you have been given a login for the GNOME CVS server, you may commit your file modifications to CVS. Be sure to read the following section on CVS etiquette before making any commits to CVS. To log in to the CVS server as user <b><i><tt>username</tt></i></b> with a password, you must first set your CVSROOT shell variable with <b> export CVSROOT=':pserver:<i><tt>username</tt></i>@cvs.gnome.org:/cvs/gnome'</b>. Log in with <b>cvs login</b> and enter your password. You may check out and update modules as described above for anonymous CVS access. As a login CVS user, you may also check modified versions of a file into the CVS server. To check <b><i><tt>filename</tt></i></b> into the CVS server, type <b>cvs -z3 commit <i><tt>filename</tt></i></b>. You will be given a vi editor window to type in a brief log entry, summarizing your changes. The default editor can be changed using the <tt>EDITOR</tt> environment variable or with the <b><tt>-e</tt></b> option. You may also check in any modifications to files in the working directory and subdirectories using <b>cvs -z3 commit</b>. To add a new file to the CVS server, use <b>cvs -z3 add <i><tt>filename</tt></i></b>, followed by the commit command. </p></div><div class="sect3"><a name="cvsetiquette"></a><div class="titlepage"><div><h4 class="title"><a name="cvsetiquette"></a>CVS Etiquette</h4></div></div><p> Because files in CVS are typically used and modified by multiple developers and documentation authors, users should exercise a few simple practices out of courtesy towards the other CVS users and the project leader. First, you should not make CVS commits to a package without first discussing your plans with the project leader. This way, the project leader knows who is modifying the files and generally, what sort of changes/development is being done. Also, whenever a CVS user commits a file to CVS, they should make an entry in the CVS log and in the <tt>ChangeLog</tt> so that other users know who is making modifications and what is being modified. When modifying files created by others, you should follow the indentation scheme used by the initial author. </p></div></div></div><div class="sect1"><a name="gnomedocsystem"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="gnomedocsystem"></a>The GNOME Documentation System</h2></div></div><div class="sect2"><a name="gnomehelpbrowser"></a><div class="titlepage"><div><h3 class="title"><a name="gnomehelpbrowser"></a>The GNOME Help Browser</h3></div></div><p> At the core of the GNOME help system is the GNOME Help Browser. The Help Browser provides a unified interface to several distinct documentation systems on Linux/Unix systems: man pages, texinfo pages, Linux Documentation Project(LDP) documents, GNOME application documentation, and other GNOME documents. </p><p> The GNOME Help Browser works by searching standard directories for documents which are to be presented. Thus, the documentation that appears in the GHB is specific to each computer and will typically only represent software that is installed on the computer. </p></div><div class="sect2"><a name="gnomehelpbrowser2"></a><div class="titlepage"><div><h3 class="title"><a name="gnomehelpbrowser2"></a>The GNOME Help Browser (GNOME-2.0)</h3></div></div><p> In GNOME 2.0, the GNOME Help Browser will be replaced by Nautilus. Nautilus will be the file manager/graphical shell for GNOME 2.0 and will also implement a more sophisticated help system than that used by the GNOME Help Browser used in GNOME 1.0. It will read and display DocBook files directly, avoiding the need for duplicating documents in both DocBook and HTML formats. Its display engine for DocBook will be much faster than running jade to convert to HTML for rendering. Because it uses the original DocBook source for documentation, it will be possible to do more sophisticated searching using the meta information included in the documents. And since Nautilus is a virtual file system layer which is Internet-capable, it will be able to find and display documents which are on the web as well as those on the local file system. For more information on Nautilus, visit the #nautilus IRC channel on irc.gnome.org. </p></div><div class="sect2"><a name="gnomehelponthefly"></a><div class="titlepage"><div><h3 class="title"><a name="gnomehelponthefly"></a>Dynamic Document Synthesis(GNOME-2.0)</h3></div></div><p> GNOME uses the documentation presented by all the various GNOME components and applications installed on the system to present a complete and customized documentation environment describing only components which are currently installed on a users system. Some of this documentation, such as the manuals for applets, will be combined in such a way that it appears to be a single document. </p><p> By using such a system, you can be sure that any GNOME app you install that has documentation will show up in the index, table of contents, any search you do in the help browser. </p></div><div class="sect2"><a name="gnomehelpcomponents"></a><div class="titlepage"><div><h3 class="title"><a name="gnomehelpcomponents"></a>The GNOME Documentation Components</h3></div></div><div class="sect3"><a name="applicationmanualsintro"></a><div class="titlepage"><div><h4 class="title"><a name="applicationmanualsintro"></a>Application Manuals</h4></div></div><p> Every GNOME application should have an application manual. An application manual is a document specific to the particular application which explains the various windows and features of the application. Application Manuals typically use screenshots (PNG format) for clarity. Writing application manuals is discussed in more detail in <a href="#writingapplicationmanuals" title="Writing Application and Applet Manuals">the section called “Writing Application and Applet Manuals”</a> below. </p></div><div class="sect3"><a name="applicationhelpintro"></a><div class="titlepage"><div><h4 class="title"><a name="applicationhelpintro"></a>Application Help</h4></div></div><p> Applications should have a Help button on screens on which users may need help. These Help buttons should pull up the default help browser, determined by the <tt>ghelp</tt> URL Handler (configured using the Control Center), typically the GNOME Help Browser. The help browser should show either the first page of the application manual, or else the relevant page thereof. Application help is described in more detail in <a href="#applicationhelpbuttons" title="Application Help Buttons">the section called “Application Help Buttons”</a> below. </p></div><div class="sect3"><a name="contextsensitivehelpintro"></a><div class="titlepage"><div><h4 class="title"><a name="contextsensitivehelpintro"></a>Application Context Sensitive Help (coming in GNOME-2.0)</h4></div></div><p> Context sensitive help is a system which will allow the user to query any part (button, widget, etc.) of an application window. This is done by either entering a CS Help mode by clicking on an icon or by right clicking on the application part and selecting "What's This" or whatever is decided on at the time. Context sensitive help is described in more detail in <a href="#writingcontextsensitivehelp" title="Writing Context Sensitive Help (coming in GNOME-2.0)">the section called “Writing Context Sensitive Help (coming in GNOME-2.0)”</a> below. </p></div><div class="sect3"><a name="userguide"></a><div class="titlepage"><div><h4 class="title"><a name="userguide"></a>The GNOME User Guide</h4></div></div><p> The <i>GNOME User Guide</i> describes the GNOME desktop environment and core components of GNOME such as the panel and control center. In GNOME 1.x this was the main and only source of documentation. In GNOME 2.0 this will become a document for the web and for printing that is derived from various parts chosen in the system that are necessary for the new user to understand. </p></div><div class="sect3"><a name="userdocs"></a><div class="titlepage"><div><h4 class="title"><a name="userdocs"></a>User Documents</h4></div></div><p> Aside from the <i>GNOME User Guide</i>, there are several other documents to help GNOME users learn GNOME, including the <i>GNOME FAQ</i>, <i>GNOME Installation and Configuration Guide</i>, and the <i>GNOME Administrators Guide</i>. </p></div><div class="sect3"><a name="developerdocs"></a><div class="titlepage"><div><h4 class="title"><a name="developerdocs"></a>Developer Documents</h4></div></div><p> There are many White Papers, Tutorials, HOWTO's and FAQ's to make programming GNOME and GNOME applications as easy as possible. </p><p> API documentation is also available for the GNOME libraries. This is detailed documentation of the code that is used to build GNOME apps. You can keep up with the GNOME API docs on the <a href="http://developer.gnome.org/doc/API/" target="_top">GNOME API Reference</a> page. </p></div><div class="sect3"><a name="projectdocs"></a><div class="titlepage"><div><h4 class="title"><a name="projectdocs"></a>Project Documents</h4></div></div><p> Some GNOME projects have documentation to maintain consistency in their product and to help new contributors get up to speed quickly. Among these are the GDP documents, such as the one you are reading now. </p></div></div></div><div class="sect1"><a name="docbookbasics"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="docbookbasics"></a>DocBook Basics </h2></div></div><div class="sect2"><a name="introtodocbook"></a><div class="titlepage"><div><h3 class="title"><a name="introtodocbook"></a>Introduction to DocBook</h3></di