| <?xml version="1.0"?> |
| <!DOCTYPE article [ |
| <!ENTITY version "1.0.53"> |
| <!ENTITY mdash "--"> |
| <!ENTITY hellip "..."> |
| <!ENTITY copy "©"> <!-- COPYRIGHT SIGN --> |
| <!-- replace version above with actual application version number--> |
| <!-- Template Version: 1.0.1 (do not remove this line) --> |
| |
| |
| |
| <!ENTITY APPLET-TEMPLATE-1x-SHELL SYSTEM |
| "templates/applet_template_1-applet.sgml.cdata"> |
| <!ENTITY APPLET-TEMPLATE-1x SYSTEM |
| "templates/applet_template_1.sgml.cdata"> |
| ]> |
| |
| <!-- Version: 1.0.1 --> |
| |
| <article id="index"> |
| <articleinfo> |
| |
| <authorgroup> |
| |
| <author> |
| <firstname>David</firstname> |
| <surname>Mason</surname> |
| <affiliation> |
| <orgname>Red Hat, Inc.</orgname> |
| <address> |
| <email>dcm@redhat.com</email> |
| </address> |
| </affiliation> |
| </author> |
| |
| <author> |
| <firstname>Daniel</firstname> |
| <surname>Mueth</surname> |
| <affiliation> |
| <address> |
| <email>d-mueth@uchicago.edu</email> |
| </address> |
| </affiliation> |
| </author> |
| |
| <author> |
| <firstname>Alexander</firstname> |
| <surname>Kirillov</surname> |
| <affiliation> |
| <address> |
| <email>kirillov@math.sunysb.edu</email> |
| </address> |
| </affiliation> |
| </author> |
| |
| </authorgroup> |
| |
| <releaseinfo> |
| This is a pre-release! |
| </releaseinfo> |
| |
| <revhistory> |
| <revision> |
| <revnumber> |
| 0.99 |
| </revnumber> |
| <date> |
| 04.10.2000 |
| </date> |
| </revision> |
| </revhistory> |
| |
| <copyright> |
| <year>2000</year> |
| <holder>Red Hat, Inc., Daniel Mueth, and Alexander Kirillov</holder> |
| </copyright> |
| |
| <legalnotice> |
| <para> |
| Permission is granted to copy, distribute and/or modify this |
| document under the terms of the <citetitle>GNU Free Documentation |
| License</citetitle>, 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 <citetitle>GNU Free Documentation License</citetitle> from |
| the Free Software Foundation by visiting <ulink type="http" |
| url="http://www.fsf.org">their Web site</ulink> or by writing to: |
| Free Software Foundation, Inc., 59 Temple Place - Suite 330, |
| Boston, MA 02111-1307, USA. |
| </para> |
| <para> |
| 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. |
| </para> |
| </legalnotice> |
| |
| <title>The GNOME Handbook of Writing Software Documentation</title> |
| |
| </articleinfo> |
| |
| <!-- ################# Introduction ############### --> |
| |
| <sect1 id="intro"> |
| <title>Introduction</title> |
| |
| <!-- ####### Introduction | The GNOME Documentation Project ####### --> |
| |
| <sect2 id="gdp"> |
| <title>The GNOME Documentation Project</title> |
| |
| <sect3 id="goals"> |
| <title>Goals</title> |
| <para> |
| 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 |
| <application>GNOME Help Browser</application>, 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 <ulink url="http://developer.gnome.org/doc/API/" |
| type="http">APIs for the GNOME libraries</ulink>, <ulink |
| url="http://developer.gnome.org/doc/whitepapers/" |
| type="http"><citetitle>GNOME White |
| Papers</citetitle></ulink>, GNOME developer <ulink |
| url="http://developer.gnome.org/doc/tutorials/" |
| type="http">tutorials</ulink>, the <ulink |
| url="http://developer.gnome.org/doc/FAQ/" |
| type="http"><citetitle>GNOME Developer |
| FAQ</citetitle></ulink>, the <ulink |
| url="http://developer.gnome.org" type="http">GNOME |
| Developer's Website</ulink>, and <citetitle>GNOME |
| Handbook</citetitle>'s, such as the one you are reading. |
| User documentation include the <ulink |
| url="http://www.gnome.org/learn/" |
| type="http"><citetitle>GNOME User's |
| Guide</citetitle></ulink>, the <ulink |
| url="http://www.gnome.org/learn/" |
| type="http"><citetitle>GNOME FAQ</citetitle></ulink>, and |
| GNOME application documentation. Most GNOME applications |
| have their own manual in addition to context sensitive help. |
| </para> |
| </sect3> |
| |
| <sect3 id="joining"> |
| <title>Joining the GDP</title> |
| <para> |
| 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 |
| <ulink url="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/"> |
| <citetitle>gnome-doc-list mailing list</citetitle> </ulink>. |
| Read <xref linkend="gettingstarted" />, 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 |
| <ulink url="http://developer.gnome.org/projects/gdp"> |
| <citetitle>GDP Website</citetitle></ulink>. |
| </para> |
| </sect3> |
| |
| <sect3 id="collaborating"> |
| <title>Collaborating with the GDP</title> |
| <para> |
| 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 <ulink |
| url="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/"> |
| <citetitle>gnome-doc-list mailing list</citetitle> </ulink> |
| 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. |
| </para> |
| </sect3> |
| </sect2> |
| |
| <!-- ####### Introduction | Notation and Conventions ####### --> |
| |
| <sect2 id="notation"> |
| <title>Notation and Conventions</title> |
| <para> |
| This Handbook uses the following notation: |
| <informaltable frame="none"> |
| <tgroup cols="2"> |
| <tbody> |
| <row> |
| <entry> |
| <filename class="directory">/usr/bin</filename> |
| </entry> |
| <entry> |
| Directory |
| </entry> |
| </row> |
| <row> |
| <entry> |
| <filename>foo.sgml</filename> |
| </entry> |
| <entry> |
| Filename |
| </entry> |
| </row> |
| <row> |
| <entry> |
| <command>command</command> |
| </entry> |
| <entry> |
| Command or text that would be typed. |
| </entry> |
| </row> |
| <row> |
| <entry> |
| <command><replaceable>replaceable</replaceable></command> |
| </entry> |
| <entry> |
| "Variable" text that can be replaced. |
| </entry> |
| </row> |
| <row> |
| <entry> |
| <literal>Program or Doc Code</literal> |
| </entry> |
| <entry>Program or document code</entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </informaltable> |
| </para> |
| </sect2> |
| |
| <!-- ####### Introduction | About This Handbook ####### --> |
| |
| <sect2 id="about"> |
| <title>About This Handbook</title> |
| <para> |
| This Handbook is a guide for both writing documentation for |
| GNOME components and applications and for properly binding and |
| packaging documentation into GNOME applications. |
| </para> |
| <para> |
| 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 |
| <ulink |
| url="http://developer.gnome.org/projects/gdp/handbook.html"> |
| <citetitle>Getting The GNOME Handbook of Writing Software |
| Documentation</citetitle> </ulink>. Alternately, one may |
| download it anonymously from GNOME CVS under <filename |
| class="directory">gnome-docu/gdp</filename>. |
| </para> |
| </sect2> |
| </sect1> |
| |
| <!-- ################# Getting Started ############### --> |
| |
| <sect1 id="gettingstarted"> |
| <title>Getting Started Writing GNOME Documentation</title> |
| |
| <!--####### Getting Started | Selecting A Document ####### --> |
| |
| <sect2 id="selecting"> |
| <title>Selecting A Document</title> |
| |
| <sect3 id="know"> |
| <title>Document Something You Know</title> |
| <para> |
| 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 <emphasis>assign</emphasis> 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. |
| </para> |
| <para> |
| It is also important to spend some time with GNOME to make |
| sure you are familiar enough with it to be |
| <emphasis>authoritative</emphasis> 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. |
| </para> |
| <para> |
| 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 <email>docs@gnome.org</email>. |
| </para> |
| </sect3> |
| |
| <sect3 id="doctable"> |
| <title>The GNOME Documentation Status Table</title> |
| <para> |
| The <citetitle>GDP Documentation Status Table</citetitle> |
| (<citetitle>DocTable</citetitle>) (<ulink |
| url="http://www.gnome.org/gdp/doctable/" |
| type="http">http://www.gnome.org/gdp/doctable/</ulink>) 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. |
| </para> |
| <para> |
| You should use the <citetitle>DocTable</citetitle> 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 <citetitle>DocTable</citetitle> also allows |
| people to make announcements and suggestions and to discuss |
| issues in the comments section. |
| </para> |
| <note> |
| <title>Note</title> |
| <para> |
| Note that the information in the |
| <citetitle>DocTable</citetitle> 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. |
| </para> |
| </note> |
| </sect3> |
| </sect2> |
| |
| <!-- ####### Getting Started | Installing And Using DocBook ####### --> |
| |
| <sect2 id="docbook"> |
| <title>Installing and Using DocBook</title> |
| <para> |
| 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. |
| </para> |
| <note> |
| <title>NOTE</title> |
| <para> |
| 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 <ulink |
| url="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/"> |
| <citetitle>gnome-doc-list mailing list</citetitle> |
| </ulink>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. |
| </para> |
| </note> |
| <sect3 id="installingdocbook"> |
| <title>Installing DocBook</title> |
| <para> |
| Download and install the following <ulink |
| url="ftp://sourceware.cygnus.com:/pub/docbook-tools/" |
| type="ftp">DocBook Tools packages</ulink>: 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 <filename class="directory">noarch</filename> |
| directory.) You can find more |
| information on DocBook Tools <ulink url=" |
| http://sourceware.cygnus.com/docbook-tools/" |
| type="http">here</ulink>. |
| </para> |
| <para> |
| If you are an <application>Emacs</application> user you may |
| want to grab the psgml package as well. This is a major mode |
| for editing sgml files in <application>Emacs</application>. |
| </para> |
| </sect3> |
| |
| <sect3 id="gdpstylesheets"> |
| <title>GDP Stylesheets</title> |
| <para> |
| The GDP uses its own DocBook stylesheets. To use the GDP |
| stylesheets, you should download the file |
| <filename>gdp-both.dsl</filename> from the <filename |
| class="directory">gnome-docu/gdp/dsssl</filename> module in |
| CVS (or from <ulink |
| url="http://developer.gnome.org/projects/gdp/stylesheets.html"> |
| GDP Custom DSSSL Stylesheet</ulink>)and copy it |
| <!-- into <filename |
| class="directory">/usr/lib/sgml/stylesheets</filename>. You |
| will need to point DocBook Tools to this stylesheet with the |
| <command><option>-d</option></command> option: |
| <command>db2html -d /usr/lib/sgml/stylesheets/gdp-both.dsl |
| <replaceable>foo.sgml</replaceable></command>. (Creating an |
| alias to include this option and path is convenient.) |
| Alternately, you could overwrite |
| <filename>/usr/lib/sgml/stylesheets/cygnus-both.dsl</filename> |
| with <filename>gdp-both.dsl</filename>. |
| --> |
| over the file |
| <filename>/usr/lib/sgml/stylesheets/cygnus-both.dsl</filename>. |
| Alternately, you can download and install the |
| <ulink url="http://people.redhat.com/dcm/software.html" |
| type="http">gnome-doc-tools package</ulink> which will set |
| up the stylesheets as well as the DTD discussed below. |
| </para> |
| |
| <!-- <note> |
| <para> |
| The current version of the DocBook Tools command |
| <command>db2ps</command> does not have a |
| <command><option>-d</option></command> option. In order to |
| create PostScript output, you must overwrite |
| <filename>/usr/lib/sgml/stylesheets/cygnus-both.dsl</filename> |
| with <filename>gdp-both.dsl</filename>. |
| </para> |
| </note> |
| --> |
| </sect3> |
| |
| <sect3 id="gdpdtd"> |
| <title>GDP DTD (PNG Image Support)</title> |
| <para> |
| 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 <ulink |
| url="http://www.gnu.org/philosophy/gif.html" |
| type="http">http://www.gnu.org/philosophy/gif.html</ulink>. |
| </para> |
| <para> |
| 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: |
| </para> |
| <itemizedlist mark="opencircle"> |
| <listitem> |
| <para> |
| Download <ulink |
| url="http://www.labs.redhat.com/png/png-support.html">the |
| GDP DocBook DTD for PNG support</ulink> and install it |
| where you keep your DTD's. (On Red Hat use <filename |
| class="directory">/usr/lib/sgml/</filename>.) Note that |
| the 3.0 DTD is missing support for the |
| <sgmltag><legalnotice></sgmltag> tag, so it is |
| recommended that you use version 3.1 |
| </para> |
| </listitem> |
| <listitem override="bullet"> |
| <para> |
| 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: |
| <programlisting> |
| PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.0//EN" "png-support-3.0.dtd" |
| </programlisting> |
| If you are using the 3.1 DTD, use: |
| <programlisting> |
| PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN" "png-support-3.1.dtd" |
| </programlisting> |
| </para> |
| </listitem> |
| </itemizedlist> |
| <para> |
| Alternately, you can download and install the |
| <ulink url="http://people.redhat.com/dcm/software.html" |
| type="http">gnome-doc-tools package</ulink> which will set |
| up the custom stylesheets and DTD for you. |
| </para> |
| <para> |
| 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: |
| </para> |
| <para> |
| Articles: |
| <programlisting> |
| <![CDATA[<!DOCTYPE Article PUBLIC "-//GNOME//DTD DocBook PNG Variant |
| V1.1//EN"[]>]]> |
| </programlisting> |
| </para> |
| <para> |
| Books: |
| <programlisting> |
| <![CDATA[<!DOCTYPE Book PUBLIC "-//GNOME//DTD DocBook PNG Variant |
| V1.1//EN"[]>]]> |
| </programlisting> |
| </para> |
| |
| </sect3> |
| |
| <sect3 id="editors"> |
| <title>Editors</title> |
| <para> |
| 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. |
| </para> |
| <para> |
| Probably the two most popular editors available are |
| <application>Emacs</application> and |
| <application>vi</application>. 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 <xref linkend="installingdocbook" />. |
| </para> |
| </sect3> |
| |
| <sect3 id="make-output"> |
| <title>Creating Something Useful with your Docs</title> |
| <para> |
| 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 <application>Jade</application>. In |
| most cases you will not have to work directly with |
| <application>Jade</application>; Instead, you will use the |
| scripts provided by DocBook Tools. |
| </para> |
| <para> |
| To preview your DocBook document, it is easiest to convert |
| it to <filename>html</filename>. If you have installed the |
| DocBook tools described above, all you have to do is to run |
| the command <prompt>$</prompt><command>db2html |
| mydocument.sgml</command>. If there are no sgml syntax |
| errors, this will create a directory <filename |
| class="directory">mydocument</filename> and place the |
| resulting html files in it. The title page of the document |
| will typically be |
| <filename>mydocument/index.html</filename>. If you have |
| screenshots in your document, you will have to copy these |
| files into the <filename |
| class="directory">mydocument</filename> directory by |
| hand. You can use any web browser to view your document. |
| Note that every time you run <command>db2html</command>, it |
| creates the <filename |
| class="directory">mydocument</filename> directory over, so |
| you will have to copy the screenshots over each time. |
| </para> |
| <para> |
| You can also convert your document to PostScript by running |
| the command <prompt>$</prompt><command>db2ps |
| mydocument.sgml</command>, after which you can print out or |
| view the resulting .ps file. |
| </para> |
| <note> |
| <title>NOTE</title> |
| <para> |
| 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 <xref linkend="gdpstylesheets" />. |
| </para> |
| </note> |
| </sect3> |
| |
| <sect3 id="jadeimages"> |
| <title>Images in DocBook Tools</title> |
| <para> |
| 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. |
| </para> |
| <para> |
| 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). |
| </para> |
| <para> |
| Thus, you should never explicitly |
| include the extension of the image file, since DocBook |
| Tools will automatically insert it for you. For example: |
| </para> |
| <programlisting> |
| <![CDATA[ |
| <figure> |
| <title>My Image</title> |
| <screenshot> |
| <screeninfo>Sample GNOME Display</screeninfo> |
| <graphic format="png" fileref="myfile" srccredit="me"> |
| </graphic> |
| </screenshot> |
| </figure> |
| ]]> </programlisting> |
| <para> |
| You will notice in this example that the file |
| <filename>myfile.png</filename> was referred to as simply |
| <filename>myfile</filename>. Now when you run |
| <command>db2html</command> to create an html file, it will |
| automatically look for <filename>myfile.png</filename> in |
| the directory. |
| </para> |
| <para> |
| 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 <ulink |
| url="http://people.redhat.com/dcm/sgml.html" |
| type="html">http://people.redhat.com/dcm/sgml.html</ulink> |
| (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 |
| <command>img2eps</command> on you system. |
| </para> |
| </sect3> |
| |
| <sect3 id="moredocbookinfo"> |
| <title>Learning DocBook</title> |
| <para> |
| There are many resources available to help you learn DocBook. |
| The following resources on the web are useful for learning |
| DocBook: |
| </para> |
| <itemizedlist mark="bullet"> |
| <listitem> |
| <para> |
| <ulink url="http://www.docbook.org" |
| type="http">http://www.docbook.org</ulink> - Norman |
| Walsh's <citetitle>DocBook: The Definitive |
| Guide</citetitle>. Online O'Reilly book on using |
| DocBook. Contains an excellent element reference. May be |
| too formal for a beginner. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <ulink |
| url="http://www.oswg.org/oswg-nightly/oswg/en_US.ISO_8859-1/articles/DocBook-Intro/docbook-intro/index.html" |
| type="http">A Practical Introduction to DocBook</ulink> |
| - The Open Source Writers Group's introduction to using |
| DocBook. This is an excellent HOW-TO type article on |
| getting started. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <ulink |
| url="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro/docbook-intro.html" |
| type="http">Getting Going with DocBook: Notes for |
| Hackers</ulink> - 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. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <ulink type="http" url="http://www.freebsd.org/tutorials/docproj-primer/"> |
| FreeBSD Documentation Project Primer for New |
| Contributors</ulink> - 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. |
| </para> |
| </listitem> |
| </itemizedlist> |
| <para> |
| Norman Walsh's book is also available in print. |
| </para> |
| <para> |
| The following sections of this document are designed to help |
| documentation authors write correct and consistent DocBook: |
| </para> |
| <itemizedlist mark="bullet"> |
| <listitem> |
| <para> |
| <xref linkend="docbookbasics" /> - Descriptions of |
| commonly used DocBook tags. |
| </para> |
| </listitem> |
| </itemizedlist> |
| <para> |
| 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. |
| </para> |
| </sect3> |
| </sect2> |
| |
| <!-- ####### Getting Started | GDP Document Examples ####### --> |
| <!-- |
| <sect2 id="examples"> |
| <title>GDP Document Examples</title> |
| <para> |
| Examples of various types of GNOME documents are found in |
| <xref linkend="examples" />. There is also an example GNOME |
| application with documentation called |
| <application>gnome-hello</application> in GNOME cvs. |
| </para> |
| </sect2> |
| --> |
| <!-- ####### Getting Started | GDP Document Templates ####### --> |
| |
| <sect2 id="gdptemplates"> |
| <title>GDP Document Templates</title> |
| <para> |
| Templates for various types of GNOME documents are found in |
| <xref linkend="templates" />. They are kept in CVS in |
| gnome-docu/gdp/templates. The easiest source to get them from |
| is probably the <ulink |
| url="http://developer.gnome.org/projects/gdp/templates.html" |
| type="http">GDP |
| Document Templates</ulink> web page, which is typically kept |
| completely up-to-date with CVS and has a basic description of |
| each file from CVS. |
| </para> |
| </sect2> |
| |
| <!-- ####### Getting Started | Screenshots ####### --> |
| |
| <sect2 id="screenshots"> |
| <title>Screenshots</title> |
| <para> |
| Most GNOME documents will have screenshots of the particular |
| applet, application, GNOME component, or widget being |
| discussed. As discussed above in <xref linkend="gdpdtd"/> 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 <xref linkend="jadeimages"/> above. |
| </para> |
| <sect3 id="screenshotappearance"> |
| <title>Screenshot Appearance</title> |
| <para> |
| For all screenshots of windows that typically have border |
| decorations (e.g. applications and dialogs, but not applets |
| in a <interface>panel</interface>), 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 |
| <ulink url="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/"> |
| <citetitle>gnome-doc-list mailing list</citetitle> </ulink> |
| requesting a GDP member reproduce these screenshots in the |
| correct format and email them to you. |
| </para> |
| </sect3> |
| <sect3 id="screenshottools"> |
| <title>Screenshot Tools</title> |
| <para> |
| There are many tools for taking screenshots in |
| GNOME/Linux. Perhaps the most convenient is the |
| <application>Screen-Shooter Applet</application>. 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 |
| <application>Netscape</application> or the |
| <application>GNOME Help Browser</application>. You |
| should save your screenshot as a GIF and |
| then use <command>convert filename.gif |
| filename.png</command>.) For applets |
| in a <interface>Panel</interface>, |
| <application>xv</application> can be used to crop the |
| screenshot to only include the relevant portion of the |
| <interface>Panel</interface>. Note that |
| <application>xv</application> and |
| <application>gimp</application> can both be used for taking |
| screenshots, cropping screenshots, and converting image |
| formats. |
| </para> |
| </sect3> |
| <sect3 id="screenshotfiles"> |
| <title>Screenshot Files</title> |
| <para> |
| 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 <command>db2html</command> to |
| convert your SGML file to HTML (see <xref |
| linkend="make-output"/>), 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 <command>db2html</command> 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 <xref |
| linkend="jadeimages"/>, but will not need to copy these |
| images from their default location, as they are included |
| directly into the output(PostScript of PDF) file. |
| </para> |
| </sect3> |
| </sect2> |
| |
| |
| <!-- ####### Getting Started | Application Bugs ####### --> |
| |
| <sect2 id="applicationbugs"> |
| <title>Application Bugs</title> |
| <para> |
| 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 |
| <interface>About</interface> 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 <application>Bug |
| Buddy</application> applet which is part of the gnome-applets |
| package. |
| </para> |
| </sect2> |
| |
| |
| <!-- ####### Getting Started | Using CVS ####### --> |
| |
| <sect2 id="cvs"> |
| <title>Using CVS</title> |
| <para> |
| 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. |
| </para> |
| |
| <sect3 id="anonymouscvs"> |
| <title>Anonymous CVS</title> |
| <para> |
| To anonymously check out documents from CVS, you must first |
| log in. From the bash shell, you should set your CVSROOT |
| shell variable with <command> export |
| CVSROOT=':pserver:anonymous@anoncvs.gnome.org:/cvs/gnome'</command> |
| and then login with <command>cvs login</command>(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 <command>cvs -z3 checkout |
| gnome-docu/gdp</command>. After you have this document |
| checked out and you would like to download any updates on |
| the CVS server, use <command>cvs -z3 update -Pd</command>. |
| </para> |
| </sect3> |
| |
| <sect3 id="logincvs"> |
| <title>Login CVS</title> <para> 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 |
| <command><replaceable>username</replaceable></command> with a |
| password, you must first set your CVSROOT shell variable with |
| <command> export |
| CVSROOT=':pserver:<replaceable>username</replaceable>@cvs.gnome.org:/cvs/gnome'</command>. |
| Log in with <command>cvs login</command> 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 |
| <command><replaceable>filename</replaceable></command> into |
| the CVS server, type <command>cvs -z3 commit |
| <replaceable>filename</replaceable></command>. 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 <varname>EDITOR</varname> environment variable or |
| with the <command><option>-e</option></command> option. You |
| may also check in any modifications to files in the working |
| directory and subdirectories using <command>cvs -z3 |
| commit</command>. To |
| add a new file to the CVS server, use <command>cvs -z3 add |
| <replaceable>filename</replaceable></command>, followed by the |
| commit command. |
| </para> |
| </sect3> |
| |
| <sect3 id="cvsetiquette"> |
| <title>CVS Etiquette</title> |
| <para> |
| 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 <filename>ChangeLog</filename> 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. |
| </para> |
| </sect3> |
| </sect2> |
| </sect1> |
| |
| <!-- ################# The GNOME Documentation System############### |
| --> |
| |
| <sect1 id="gnomedocsystem"> |
| <title>The GNOME Documentation System</title> |
| |
| <!-- ####### The GNOME Documentation System | The GNOME Help Browser |
| ####### --> |
| |
| <sect2 id="gnomehelpbrowser"> |
| <title>The GNOME Help Browser</title> |
| <para> |
| At the core of the GNOME help system is the <application>GNOME |
| Help Browser</application>. The <application>Help |
| Browser</application> 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. |
| </para> |
| <para> |
| The <application>GNOME Help Browser</application> 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. |
| </para> |
| </sect2> |
| |
| <!-- ####### The GNOME Documentation System | The GNOME Help Browser |
| ####### --> |
| |
| <sect2 id="gnomehelpbrowser2"> |
| <title>The GNOME Help Browser (GNOME-2.0)</title> <para> In |
| GNOME 2.0, the <application>GNOME Help Browser</application> |
| will be replaced by <application>Nautilus</application>. |
| 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 <application>GNOME Help Browser</application> |
| 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 <application>jade</application> 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 |
| <application>Nautilus</application>, visit the #nautilus IRC |
| channel on irc.gnome.org. </para> |
| </sect2> |
| |
| <!-- ####### The GNOME Documentation System | GNOME On-The-Fly |
| Documentation Generation ####### --> |
| |
| <sect2 id="gnomehelponthefly"> |
| <title>Dynamic Document Synthesis(GNOME-2.0)</title> |
| <para> |
| 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. |
| </para> |
| <para> |
| 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. |
| </para> |
| </sect2> |
| |
| <!-- ####### The GNOME Documentation System | The GNOME Documentation |
| Components ####### --> |
| |
| <sect2 id="gnomehelpcomponents"> |
| <title>The GNOME Documentation Components</title> |
| |
| <sect3 id="applicationmanualsintro"> |
| <title>Application Manuals</title> |
| <para> |
| 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 <xref |
| linkend="writingapplicationmanuals" /> below. |
| </para> |
| </sect3> |
| |
| <sect3 id="applicationhelpintro"> |
| <title>Application Help</title> |
| <para> |
| Applications should have a <guibutton>Help</guibutton> |
| button on screens on which users may need help. These |
| <guibutton>Help</guibutton> buttons should pull up the |
| default help browser, determined by the |
| <varname>ghelp</varname> URL Handler (configured using the |
| <application>Control Center</application>), typically the |
| <application>GNOME Help Browser</application>. 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 <xref |
| linkend="applicationhelpbuttons" /> below. |
| </para> |
| </sect3> |
| |
| <sect3 id="contextsensitivehelpintro"> |
| <title>Application Context Sensitive Help (coming in |
| GNOME-2.0)</title> |
| <para> |
| 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 <xref linkend="writingcontextsensitivehelp" /> |
| below. |
| </para> |
| </sect3> |
| |
| <sect3 id="userguide"> |
| <title>The GNOME User Guide</title> |
| <para> |
| The <citetitle>GNOME User Guide</citetitle> describes the |
| GNOME desktop environment and core components of GNOME such |
| as the <application>panel</application> and |
| <application>control center</application>. 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. |
| </para> |
| </sect3> |
| |
| <sect3 id="userdocs"> |
| <title>User Documents</title> |
| <para> |
| Aside from the <citetitle>GNOME User Guide</citetitle>, |
| there are several other documents to help GNOME users learn |
| GNOME, including the <citetitle>GNOME FAQ</citetitle>, |
| <citetitle>GNOME Installation and Configuration |
| Guide</citetitle>, and the <citetitle>GNOME Administrators |
| Guide</citetitle>. |
| </para> |
| </sect3> |
| |
| <sect3 id="developerdocs"> |
| <title>Developer Documents</title> |
| <para> |
| There are many White Papers, Tutorials, HOWTO's and FAQ's to |
| make programming GNOME and GNOME applications as easy as |
| possible. |
| </para> |
| <para> |
| 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 <ulink |
| url="http://developer.gnome.org/doc/API/" type="http">GNOME API |
| Reference</ulink> page. |
| </para> |
| </sect3> |
| |
| <sect3 id="projectdocs"> |
| <title>Project Documents</title> |
| <para> |
| 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. |
| </para> |
| </sect3> |
| </sect2> |
| </sect1> |
| |
| |
| <!-- ################# DocBook Basics ############### --> |
| |
| <sect1 id="docbookbasics"> |
| <title>DocBook Basics </title> |
| <!-- ####### DocBook Basics | Introduction to DocBook ####### --> |
| |
| <sect2 id="introtodocbook"> |
| <title>Introduction to DocBook</title> |
| <para> |
| To understand DocBook, a basic understanding of SGML is |
| helpful. SGML stands for Standard General Markup Language and |
| is one of the first markup languages every created. HTML is |
| actually derived from SGML and XML is a subset of SGML. SGML |
| uses what is called a Document Type Definition to specify |
| <emphasis>elements</emphasis> which are contained between |
| brackets, < and >. Text is marked by both beginning and |
| ending elements, for example in the DocBook DTD, one denotes a |
| title with <sgmltag><title></sgmltag>The |
| Title<sgmltag></title></sgmltag>. |
| </para> |
| <para> |
| The DTD (in the case of the GDP, DocBook) defines rules for how the |
| elements can be used. For example, if one element can only be used when |
| embedded within another, this is defined in the DTD. |
| </para> |
| <para> |
| An SGML file is just a plain ASCII file containing the text |
| with the markup specified above. To convert it to some easily |
| readable format, you need special tools. The GDP uses <emphasis>DocBook |
| Tools</emphasis>, a free package of utilities for working with DocBook |
| which includes <emphasis>Jade</emphasis>, which does the SGML/DSSL |
| parsing. You can read more about DocBook Tools in <xref |
| linkend="installingdocbook" />. |
| </para> |
| <para> |
| The final appearance of the output (e.g. PostScript or HTML) |
| is determined by a |
| <emphasis>stylesheet</emphasis>. Stylesheets are files, |
| written in a special language (DSSSL — Document Style |
| Semantics and Specification Language), which specify the |
| appearance of various DocBook elements, for example, |
| what fonts to use for titles and various inline elements, page |
| numbering style, and much more. DocBook tools come with a |
| collection of stylesheets (Norman Walsh's modular |
| stylesheets); GNOME Document Project uses some customized |
| version of this stylesheets — see <xref |
| linkend="gdpstylesheets"/>. |
| </para> |
| <para> |
| The advantage of specifying the <emphasis>structure</emphasis> |
| of a document with SGML instead of specifying the |
| <emphasis>appearance</emphasis> of the document with a typical |
| word processor, or with html, is that the resulting document |
| can be processed in a variety of ways using the structural |
| information. Whereas formatting a document for appearance |
| assumes a medium (typically written text on a standard-sized |
| piece of paper), SGML can be processed to produce output for a |
| large variety of media such as text, postscript, HTML, |
| Braille, audio, and potentially many other formats. |
| </para> |
| <para> |
| Using 'content' as the elements to define the text of a document also |
| allows for search engines to make use of the actual elements to make a |
| "smarter search". For example, if you are searching for all documents |
| written by the author "Susie" your search engine could be made smart |
| enough to only search <author> elements, making for a faster and more |
| accurate search. |
| </para> |
| <para> |
| Since the overall appearance of the output is determined not by the DTD |
| or the SGML document, but rather by a stylesheet, the appearance of a |
| document can be easily changed just by changing the stylesheet. This |
| allows everyone in the project to create documents that all look the |
| same. |
| </para> |
| <para> |
| As stated before, the GDP uses the DocBook DTD. For a list of |
| introductory and reference resources on DocBook, see <xref |
| linkend="resources" />. The following sections also provide |
| convenient instructions on which markup tags to use in various |
| circumstances. Be sure to read <xref linkend="conventions" /> |
| for GDP documentation-specific guidelines. |
| </para> |
| </sect2> |
| |
| <!-- ###### DocBook Basics | XML and SGML ########--> |
| <sect2 id="xml"> |
| <title>XML and SGML</title> |
| |
| <para> In not so distant future (probably before GNOME 2.0), |
| DocBook itself and GNOME Documentation project will migrate from |
| SGML to XML. This transition should be relatively painless: |
| (almost) all DocBook tags will remain the same. However, XML has |
| stricter syntax rules than SGML; thus, some constructions which |
| are valid in SGML will not be valid in XML. Therefore, to be |
| ready for this transistion, it is <emphasis>strongly |
| advised</emphasis> that the documentation writers conform to XML |
| syntax rules. Here are most important differences: |
| </para> |
| |
| <variablelist> |
| <varlistentry> |
| <term> <emphasis>Minimization</emphasis></term> |
| <listitem> |
| |
| <para> |
| It is possible with some implementations of SGML to use |
| minimizations to close elements in a document by using |
| </>, for example: |
| <literal><sgmltag><title></sgmltag>The |
| Title<sgmltag></></sgmltag></literal>. This is not |
| allowed in XML. You can use <command>sgmlnorm</command> command, |
| included in DocBook Tools package, to expand minimized tags; |
| if you are using <application>Emacs</application> with psgml |
| mode, you can also use menu command |
| <menuchoice> |
| <guimenu>Modify</guimenu> |
| <guimenuitem>Normalize</guimenuitem> |
| </menuchoice>. |
| </para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term> <emphasis>Self-closing tags</emphasis></term> |
| <listitem> |
| |
| <para> |
| Also, in SGML some tags are allowed not to have closing |
| tags. For example, it is legal for |
| <sgmltag><xref></sgmltag> not to have a closing tag: |
| <literal><sgmltag><xref |
| linkend="someid"></sgmltag></literal>. In |
| XML, it is illegal; instead, you should use |
| <literal><sgmltag><xref |
| linkend="someid"/></sgmltag></literal> (note the |
| slash!). |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term> <emphasis>Case sensitive tags</emphasis></term> |
| <listitem> |
| <para> |
| In XML, unlike SGML, tags are case-senstive |
| <sgmltag><title></sgmltag> and |
| <sgmltag><TITLE></sgmltag> are different tags! |
| Therefore, please always use lowercase tags (except for |
| things like <literal>DOCTYPE, CDATA</literal> and |
| <literal>ENTITY</literal>, which are not DocBook tags). |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| |
| |
| </variablelist> |
| </sect2> |
| |
| |
| |
| <!-- ####### DocBook Basics | Structure Elements ####### --> |
| |
| |
| <sect2 id="structure"> <title> Structure Elements</title> |
| |
| <sect3 id="section"> |
| <title>Sections and paragraphs</title> |
| <para> |
| Top-level element of a book body must be |
| <sgmltag><chapter></sgmltag>; it may contain one or more |
| <sgmltag><sect1></sgmltag>, each of them may contain |
| <sgmltag><sect2></sgmltag> and so on up to |
| <sgmltag><sect5></sgmltag>. The top-level element of an |
| article body is always |
| <sgmltag><sect1></sgmltag>. Regardless of which elements |
| you use, give each structural element a unique id, so that |
| you can link to it. For usage example, see the template. |
| </para> |
| <para> Please try to avoid using deeply nested sections; for |
| most situations, <sgmltag><sect1></sgmltag> and |
| <sgmltag><sect2></sgmltag> should be sufficient. If not, |
| you probably should split your <sgmltag><sect1></sgmltag> |
| into several smaller ones. |
| </para> |
| <para> Use the tag <sgmltag><para></sgmltag> for |
| paragraphs, even if there is only one paragraph in a |
| section—see template for examples. |
| </para> |
| </sect3> |
| |
| <sect3 id="notes"> |
| <title>Notes, Warnings, And Tips</title> |
| <para> |
| For notes, tips, warnings, and important information, which |
| should be set apart from the main text (usually as a |
| paragraph with some warning sign on the margin), use tags |
| <sgmltag><note></sgmltag>, <sgmltag><tip></sgmltag>, |
| <sgmltag><warning></sgmltag>, |
| <sgmltag><important></sgmltag> respectively. For example: |
| <programlisting> |
| <![CDATA[ |
| <tip> |
| <title>TIP</title> |
| <para> |
| To speed up program compilation, use <application>gcc</application> |
| compiler with Pentium optimization. |
| </para> |
| </tip>]]> </programlisting> produces |
| </para> |
| <tip id="extip"> |
| <title>TIP</title> |
| <para> |
| To speed up program compilation, use |
| <application>gcc</application> compiler with Pentium |
| optimization. </para> |
| </tip> |
| <para> |
| Note that this should not be inside a |
| <sgmltag><para></sgmltag> but between paragraphs. |
| </para> |
| </sect3> |
| <sect3 id="figures"> |
| <title> Screenshots and other figures</title> |
| <para> |
| To include screenshots and other figures, use the following |
| tags: |
| |
| <programlisting> |
| <![CDATA[ |
| <figure id="shot1"> |
| <title>Screenshot</title> |
| <screenshot> |
| <screeninfo>Screenshot of a program</screeninfo> |
| <graphic format="PNG" fileref="figures/example_screenshot" srccredit="ME"> |
| </graphic> |
| </screenshot> |
| </figure>]]> |
| </programlisting> |
| replacing <filename>example_screenshot</filename> with the |
| actual file name (without extension). The result will look like this: |
| |
| <figure id="shot1"> |
| <title>Screenshot</title> |
| <screenshot> |
| <screeninfo>Screenshot of a program</screeninfo> |
| <graphic format="PNG" |
| fileref="figures/example_screenshot" srccredit="ME"/> |
| |
| </screenshot> |
| </figure> |
| </para> |
| <note> |
| <title>NOTE</title> |
| <para> |
| Notice in this example that the screenshot file name does |
| not include the file type extension — to find out |
| why, please read <xref linkend="jadeimages" />. |
| </para> |
| </note> |
| </sect3> |
| <sect3 id="listing"> |
| <title>Program listings and terminal session</title> <para> |
| To show a file fragment—for example, program |
| listing—use <sgmltag><programlisting></sgmltag> tag: |
| <programlisting> |
| <![CDATA[ |
| <programlisting> |
| [Desktop Entry] |
| Name=Gnumeric spreadsheet |
| Exec=gnumeric |
| Icon=gnome-gnumeric.png |
| Terminal=0 |
| Type=Application |
| </programlisting>]]> |
| </programlisting> |
| which produces |
| <programlisting> |
| [Desktop Entry] |
| Name=Gnumeric spreadsheet |
| Exec=gnumeric |
| Icon=gnome-gnumeric.png |
| Terminal=0 |
| Type=Application |
| </programlisting> |
| As a matter of fact, all examples in this document were |
| produced using <sgmltag><programlisting></sgmltag>. |
| </para> |
| <para> |
| To show a record of terminal session—i.e., sequence of |
| commands entered at the command line—use |
| <sgmltag><screen></sgmltag> tag: |
| <programlisting> |
| <![CDATA[ |
| <screen> |
| <prompt>bash$</prompt><userinput>make love</userinput> |
| make: *** No rule to make target `love'. Stop. |
| </screen>]]> |
| </programlisting> |
| which produces |
| <screen> |
| <prompt>bash$</prompt><userinput>make love</userinput> |
| make: *** No rule to make target `love'. Stop. |
| </screen> |
| Note the use of tags <sgmltag><prompt></sgmltag> and |
| <sgmltag><userinput></sgmltag> for marking system prompt |
| and commands entered by user. |
| <note> |
| <title>NOTE</title> |
| <para> |
| Note that both <sgmltag><programlisting></sgmltag> |
| and <sgmltag><screen></sgmltag> preserve linebreaks, |
| but interpret SGML tags (unlike LaTeX |
| <markup>verbatim</markup> environment). Take a look at |
| the source of this document to see how you can have SGML |
| tags literally shown but not interpreted, |
| </para> |
| </note> |
| </para> |
| </sect3> |
| <sect3 id="lists"> |
| <title> Lists</title> |
| <para> |
| The most common list types in DocBook are |
| <sgmltag><itemizedlist></sgmltag>, |
| <sgmltag><orderedlist></sgmltag>, and |
| <sgmltag><variablelist></sgmltag>. |
| </para> |
| <variablelist> |
| <varlistentry> |
| <term> <sgmltag><itemizedlist></sgmltag></term> |
| <listitem><para> |
| This is the simplest unnumbered list, parallel to |
| <sgmltag><ul></sgmltag> in HTML. Here is an example: |
| <programlisting> |
| <![CDATA[ |
| <itemizedlist> |
| <listitem> |
| <para> |
| <guilabel>Show backup files</guilabel> — This will |
| show any backup file that might be on your system. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <guilabel>Show hidden files</guilabel> — This will |
| show all "dot files" or files that begin with a dot. This |
| files typically include configuration files and directories. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <guilabel>Mix files and directories</guilabel> — This |
| option will display files and directories in the order you |
| sort them instead of |
| always having directories shown above files. |
| </para> |
| </listitem> |
| </itemizedlist> |
| ]]> |
| </programlisting> |
| and output: |
| </para> |
| <itemizedlist> |
| <listitem> |
| <para> |
| <guilabel>Show backup files</guilabel> — |
| This will show any backup file that might be on |
| your system. |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| <guilabel>Show hidden files</guilabel> — |
| This will show all "dot files" or files that |
| begin with a dot. This files typically include |
| configuration files and directories. |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| <guilabel>Mix files and directories</guilabel> |
| — This option will display files and |
| directories in the order you sort them instead |
| of always having directories shown above files. |
| </para> |
| </listitem> |
| </itemizedlist> |
| <para> Note the use of <sgmltag>&mdash;</sgmltag> |
| for long dash (see <xref linkend="specsymb" />). Also, |
| please note that the result looks much nicer because the |
| terms being explained (<guilabel>Show backup |
| files</guilabel>, etc.) are set in a different font. In |
| this case, it was achieved by using <link |
| linkend="gui"><sgmltag><guilabel></sgmltag></link> |
| tag. In other cases, use appropriate tags such as |
| <link linkend="gui"><sgmltag><guimenuitem></sgmltag></link>, |
| <link |
| linkend="filenames"><sgmltag><command></sgmltag></link>, |
| or — if none of |
| this applies — use |
| <link linkend="gui"><sgmltag><emphasis></sgmltag></link>. |
| </para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term> <sgmltag><orderedlist></sgmltag></term> |
| <listitem><para> |
| This list is completely analogous to |
| <sgmltag><itemizedlist></sgmltag> and has the same |
| syntax, but it produces numbered list. By default, |
| this list uses Arabic numerals for numbering entries; |
| you can override this using <sgmltag>numeration</sgmltag>, |
| for example <sgmltag><orderedlist |
| numeration="lowerroman"></sgmltag>. Possible values of |
| these attribute are <sgmltag>arabic</sgmltag>, |
| <sgmltag>upperalpha</sgmltag>, |
| <sgmltag>loweralpha</sgmltag>, |
| <sgmltag>upperroman</sgmltag>, |
| <sgmltag>lowerroman</sgmltag>. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term> <sgmltag><variablelist></sgmltag></term> |
| <listitem><para> This list is used when each entry is |
| rather long, so it should be formatted as a block of text |
| with some subtitle, like a small subsection. The |
| <sgmltag><variablelist></sgmltag> is more complicated |
| than itemizedlists, but for larger blocks of text, or when |
| you're explaining or defining something, it's best to use |
| them. Their greatest advantage is that it's easier for a |
| computer to search. The lines you are reading now were |
| produced by <sgmltag><variablelist></sgmltag>. The |
| source looked liked this: |
| <programlisting> |
| <![CDATA[ |
| <variablelist> |
| <varlistentry> |
| <term> <sgmltag><itemizedlist></sgmltag></term> |
| <listitem><para> |
| This is the simplest unnumbered list, parallel to |
| <sgmltag><ul></sgmltag> in HTML. Here is an example:... |
| </para></listitem> |
| </varlistentry> |
| <varlistentry> |
| <term> <sgmltag><orderedlist></sgmltag></term> |
| <listitem><para> |
| This list is completely analogous to |
| <sgmltag><itemizedlist></sgmltag> |
| </para></listitem> |
| </varlistentry> |
| <varlistentry> |
| <term> <sgmltag><variablelist></sgmltag></term> |
| <listitem><para> |
| This list is used when each entry is rather long,... |
| </para></listitem> |
| </varlistentry> |
| </variablelist> |
| ]]> |
| </programlisting> |
| </para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| <para> |
| Lists can be nested; in this case, the stylesheets |
| are smart enough to change the numeration (for |
| <sgmltag><orderedlist></sgmltag>) or marks of each entry |
| (in <sgmltag><itemizedlist></sgmltag>) for sub-lists |
| </para> |
| </sect3> |
| |
| </sect2> |
| |
| <!-- ####### DocBook Basics | Inline Elements ####### --> |
| |
| <sect2 id="inline"> |
| <title>Inline Elements</title> |
| |
| <sect3 id="gui"> |
| <title>GUI elements</title> |
| <itemizedlist> |
| <listitem> |
| <para> |
| <sgmltag><guibutton></sgmltag> — used for |
| buttons, including checkbuttons and radio buttons |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| <sgmltag><guimenu></sgmltag>, |
| <sgmltag><guisubmenu></sgmltag> —used for |
| top-level menus and submenus |
| respectively, for example <literal><![CDATA[ |
| <guisubmenu>Utilities</guisubmenu> submenu of the |
| <guimenu>Main Menu</guimenu>]]></literal> |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| <sgmltag><guimenuitem></sgmltag>—an entry in a |
| menu |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| <sgmltag><guiicon></sgmltag>—an icon |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| <sgmltag><guilabel></sgmltag>—for items which have |
| labels, like tabs, or bounding boxes. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <sgmltag><interface></sgmltag>— for most everything |
| else... a window, a dialog box, the Panel, etc. |
| </para> |
| </listitem> |
| </itemizedlist> |
| <para> |
| If you need to refer to a sequence of menu choices, such as |
| <menuchoice> |
| <guimenu>Main Menu</guimenu> |
| <guisubmenu>Utilities</guisubmenu> <guimenuitem>GNOME |
| terminal</guimenuitem> |
| </menuchoice> |
| there is a special construction for this, too: |
| <programlisting> |
| <![CDATA[ |
| <menuchoice> |
| <guimenu>Main Menu</guimenu> <guisubmenu>Utilities</guisubmenu> |
| <guimenuitem>GNOME terminal</guimenuitem> </menuchoice>]]> |
| </programlisting> |
| </para> |
| </sect3> |
| |
| <sect3 id="links"> |
| <title>Links and references</title> |
| <para> |
| To refer to another place in the same document, you can use |
| tags <sgmltag><xref></sgmltag> and |
| <sgmltag><link></sgmltag>. The first of them |
| automatically inserts the full name of the element you refer |
| to (section, figure, etc.), while the second just creates a |
| link (in HTML output). Here is an example: |
| <programlisting> |
| <![CDATA[An example of a <link linkend="extip">tip</link> was given in |
| <xref linkend="notes" />. ]]> |
| </programlisting> |
| which produces: An example of a <link |
| linkend="extip">tip</link> was given in <xref |
| linkend="notes" />. |
| </para> |
| <para> |
| Here <sgmltag>notes</sgmltag> and <sgmltag>extip</sgmltag> |
| are the id attributes of <xref linkend="notes" /> and of the |
| example of a tip in it. |
| </para> |
| <para> To produce a link to an external source, such as a |
| Web page or a local file, use <sgmltag><ulink></sgmltag> |
| tag, for example: |
| <programlisting> |
| <![CDATA[ To find more about GNOME, please visit <ulink type="http" |
| url="http://www.gnome.org">GNOME Web page</ulink> ]]> |
| </programlisting> |
| which produces: To find more about GNOME, please visit |
| <ulink type="http" url="http://www.gnome.org">The GNOME Web |
| Site</ulink> You can use any of the standard URL types, such |
| as <literal>http, ftp, file, telnet, mailto</literal> (in |
| most cases, however, use of <literal>mailto</literal> is |
| unnecessary—see discussion of |
| <sgmltag><email></sgmltag> tag). |
| </para> |
| </sect3> |
| |
| <sect3 id="filenames"> <title>Filenames, commands, and other |
| computer-related things</title> |
| <para> |
| Here are some tags used to describe operating system-related |
| things: |
| </para> |
| <itemizedlist> |
| <listitem> |
| <para> <sgmltag><filename></sgmltag> — used |
| for filenames, |
| e.g.<sgmltag><filename></sgmltag> |
| foo.sgml |
| <sgmltag></filename></sgmltag> |
| produces: <filename>foo.sgml</filename>. |
| </para> |
| </listitem> |
| <listitem> |
| <para> <sgmltag><filename |
| class="directory"></sgmltag> — used for |
| directories, e.g.<sgmltag><filename |
| class="directory"></sgmltag>/usr/bin |
| <sgmltag></filename></sgmltag> |
| produces: <filename |
| class="directory">/usr/bin</filename>. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <sgmltag><application></sgmltag> — used for |
| application names, |
| e.g. <sgmltag><application></sgmltag>Gnumeric |
| <sgmltag></application></sgmltag> produces: |
| <application>Gnumeric</application>. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <sgmltag><envar></sgmltag> — used for |
| environment variables, e.g. |
| <sgmltag><envar></sgmltag>PATH<sgmltag></envar></sgmltag>. |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| <sgmltag><command></sgmltag> — used for |
| commands entered on command line, e.g. |
| <sgmltag><command></sgmltag>make install |
| <sgmltag></command></sgmltag> produces: |
| <command>make install</command>. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <sgmltag><replaceable></sgmltag> — used for |
| replaceable text, e.g. |
| <sgmltag><command></sgmltag>db2html<sgmltag><replaceable></sgmltag> |
| foo.sgml |
| <sgmltag></replaceable></sgmltag><sgmltag></command></sgmltag> |
| produces: <command>db2html |
| <replaceable>foo.sgml</replaceable></command>. |
| </para> |
| </listitem> |
| </itemizedlist> |
| </sect3> |
| |
| <sect3 id="keys"> |
| <title>Keyboard input</title> |
| <para> To mark up text input by the user, use |
| <sgmltag><userinput></sgmltag>. |
| </para> |
| <para> To mark keystrokes such as shortcuts and other |
| commands, use <sgmltag><keycap></sgmltag>. |
| This is used for marking up what is printed on the top |
| of the physical key on the keyboard. There are a couple of |
| other tags for keys, too: <sgmltag><keysym></sgmltag> |
| and <sgmltag><keycode></sgmltag>. However you are |
| unlikely to need these for most documentation. For reference, |
| <sgmltag><keysym></sgmltag> is for the <quote>symbolic |
| name</quote> of a key. <sgmltag><keycode></sgmltag> is |
| for the <quote>scan code</quote> of a key. These are not |
| terms commonly required in <acronym>GNOME</acronym> documentation, |
| although <sgmltag><keysym></sgmltag> is useful for marking |
| up control codes. |
| </para> |
| <para> |
| To mark up a combination of keystrokes, use the |
| <sgmltag><keycombo></sgmltag> wrapper: |
| <programlisting> |
| <![CDATA[ |
| <keycombo> |
| <keycap>Ctrl</keycap> |
| <keycap>Alt</keycap> |
| <keycap>F1</keycap> |
| </keycombo>]]> |
| </programlisting> |
| </para> |
| <para> |
| Finally, if you want to show a shortcut for some menu |
| command, here are the appropriate tags (rather long): |
| <programlisting> |
| <![CDATA[ |
| <menuchoice> |
| <shortcut> |
| <keycombo><keycap>Ctrl</keycap><keycap>q</keycap></keycombo> |
| </shortcut> |
| <guimenuitem> Quit</guimenuitem> |
| </menuchoice>]]> |
| </programlisting> |
| which produces simply |
| <menuchoice> |
| <shortcut> <keysym>Ctrl-q</keysym> </shortcut> |
| <guimenuitem> Quit</guimenuitem> |
| </menuchoice> |
| </para> |
| </sect3> |
| |
| <sect3 id="email"> |
| <title>E-mail addresses</title> <para> To mark up e-mail |
| address, use <sgmltag><email></sgmltag>: |
| <programlisting> |
| <![CDATA[ The easiest way to get in touch with me is by e-mail |
| (<email>me@mydomain.com</email>)]]> |
| </programlisting> |
| which produces: The easiest way to get in touch with me is |
| by e-mail (<email>me@mydomain.com</email>) Note that |
| <sgmltag><email></sgmltag> automatically produces a link |
| in html version. |
| </para> |
| </sect3> |
| |
| <sect3 id="specsymb"> |
| <title> Special symbols </title> |
| <para> |
| DocBook also provides special means for entering |
| typographic symbols which can not be entered directly |
| form the keyboard (such as copyright sign). This is done using |
| <emphasis>entities</emphasis>, which is SGML analogue of |
| macros, or commands, of LaTeX. They generally have the form |
| <sgmltag>&entityname;</sgmltag>. Note that the semicolon |
| is required. |
| </para> |
| <para> |
| here is partial list of most commonly used enitites: |
| </para> |
| <itemizedlist> |
| <listitem><para> |
| <sgmltag>&amp;</sgmltag> — ampersend (&) |
| </para></listitem> |
| <listitem><para> |
| <sgmltag>&lt;</sgmltag> — left angle bracket (<) |
| </para></listitem> |
| <listitem><para> |
| <sgmltag>&copy;</sgmltag> — copyright sign (©) |
| </para></listitem> |
| <listitem><para> |
| <sgmltag>&mdash;</sgmltag> — long dash (—) |
| </para></listitem> |
| <listitem><para> |
| <sgmltag>&hellip;</sgmltag> — ellipsis (…) |
| </para></listitem> |
| </itemizedlist> |
| <para> |
| Note that the actual look of the resulting symbols depends |
| on the fonts used by your browser; for example, it might |
| happen that long dash (<sgmltag>&mdash;</sgmltag>) looks |
| exactly like the usual dash (-). However, in the PostScript |
| (and thus, in print) the output will look markedly better if |
| you use appropriate tags. |
| </para> |
| </sect3> |
| </sect2> |
| </sect1> |
| |
| <!-- ################# GDP Documentation Conventions ############### --> |
| |
| <sect1 id="conventions"> |
| <title>GDP Documentation Conventions </title> |
| |
| <!-- ####### GDP Documentation Conventions | All Documentation ####### --> |
| |
| <sect2 id="conventionsalldocs"> |
| <title>Conventions for All GDP Documentation</title> |
| <sect3 id="xmlcomp"> |
| <title> XML compatibility </title> |
| <para> |
| All GNOME documentation should conform to XML syntax |
| requirements, which are stricter than SGML ones — see |
| <xref linkend="xml" /> for more informaion. |
| </para> |
| </sect3> |
| |
| <sect3 id="authorsnames"> |
| <title> Authors' names</title> |
| <para> |
| All GNOME documentation should contain the names of both the |
| application authors and documentation authors, as well as a |
| link to the application web page (if it exists) and |
| information for bug submission — see templates for an |
| example. |
| </para> |
| </sect3> |
| </sect2> |
| |
| <!-- ####### GDP Documentation Conventions | All Documentation ####### --> |
| |
| <sect2 id="conventionsappdocs"> |
| <title>Conventions for Application Documentation</title> |
| |
| <sect3 id="applicationversionid"> |
| <title>Application Version Identification</title> |
| <para> |
| Application documentation should identify the version of the |
| application for which the documentation is written: |
| <programlisting> |
| <![CDATA[ |
| <sect1 id="intro"> |
| <title>Introduction</title> |
| <para> |
| blah-blah-blah This document describes version 1.0.53 of gfoo. |
| </para> |
| </sect1>]]> |
| </programlisting> |
| </para> |
| </sect3> |
| <sect3 id="license"> |
| <title> Copyright information </title> |
| <para> Application |
| documentation should contain a copyright notice, stating the |
| licensing terms. It is suggested that you use the GNU Free |
| Documentation License. You could also use some other license |
| allowing free redistribution, such as GPL or Open Content |
| license. If documentation uses some trademarks (such as UNIX, |
| Linux, Windows, etc.), proper legal junk should also be |
| included (see templates). |
| </para> |
| </sect3> |
| <sect3 id="license2"> |
| <title>Software license</title> |
| <para> |
| All GNOME applications must contain information about the |
| license (for software, not for documentation), either in the |
| "About" box or in the manual. |
| </para> |
| </sect3> |
| |
| <sect3 id="bugtraq"> |
| <title> Bug reporting</title> |
| <para> |
| Application documentation should give an address for |
| reporting bugs and for submitting comments about the |
| documentaion (see templates for an example). |
| </para> |
| </sect3> |
| </sect2> |
| </sect1> |
| |
| <!-- ################# Writing Application Manuals ###############--> |
| |
| <sect1 id="writingapplicationmanuals"> |
| <title>Writing Application and Applet Manuals</title> |
| <para> |
| Every GNOME application or applet should have a manual specific |
| to that particular application. This manual should be a complete |
| and authoritative guide. The manual should describe what the |
| program does and how to use it. Manuals will typically describe |
| each window or panel presented to the user using screenshots (in |
| PNG format only) when appropriate. They should also describe |
| each feature and preference option available. |
| </para> |
| <note> |
| <title>Documentation Availability</title> |
| <para> |
| Applications and applets should not rely on documentation |
| which is only available on the internet. All manuals and |
| other documentation should be packaged with the application or |
| applet and be made available to the user through the standard |
| GNOME help system methods described below. |
| </para> |
| </note> |
| <para> Application manuals should be based on the template in |
| <xref linkend="template1" />. Applet manuals should be based on |
| the templates in <xref linkend="template2-1x" /> for GNOME |
| versions 1.x and the templates in <xref linkend="template2-2x" /> |
| for GNOME versions 2.x. |
| </para> |
| <note> |
| <title>Manuals For Large Applications</title> |
| <para> |
| Manuals for very large applications, such as GNOME Workshop |
| components should be a <sgmltag><book></sgmltag> (and thus |
| use <sgmltag><chapter></sgmltag> for each primary section) |
| , instead of <sgmltag><article></sgmltag> which most |
| applications use(with each primary section being a |
| <sgmltag><sect1></sgmltag>). |
| </para> |
| </note> |
| <note> |
| <title>Applet Manuals in GNOME 2.0</title> |
| <para> |
| Note that applet manuals in GNOME 2.0 are treated in a special |
| way. The manuals for all applets are merged into a single |
| virtual document by Nautilus. For this reason, the header |
| information for applet manuals is omitted and the first |
| section of each applet is |
| <sgmltag><sect1></sgmltag>. Applet manuals will typically |
| have several sections, each of which is |
| <sgmltag><sect2></sgmltag>. |
| </para> |
| </note> |
| <para> |
| Application manuals should be made available by having a |
| "Manual" entry in the <guimenu>Help</guimenu> pull-down menu |
| at the top of the |
| application, as described in <xref linkend="listingdocsinhelpmenu" />. |
| Applets should make their manuals available by |
| right-clicking on the applet. |
| </para> |
| </sect1> |
| |
| |
| <!-- ############### Listing Documents in the Help Menu ############# --> |
| |
| <sect1 id="listingdocsinhelpmenu"> |
| <title>Listing Documents in the Help Menu</title> |
| |
| <note> |
| <title>Developer Information</title> |
| <para> |
| This section is for developers. Documentation authors |
| generally do not need to know this material. |
| </para> |
| </note> |
| <para> |
| Typically the application manual and possibly additional help |
| documents will be made available to the user under the |
| <guimenu>Help</guimenu> menu at the top right of the |
| application. To do this, you must first write a |
| <filename>topic.dat</filename> file. The format for this file is: |
| <programlisting> |
| One line for each 'topic'. |
| |
| Two columns, as defined by perl -e 'split(/\s+/,$aline,2)' |
| |
| First column is the HTML file (and optional section) for the topic, |
| relative to the app's help file dir. |
| |
| Second column is the user-visible topic name. |
| </programlisting> |
| For example, <application>Gnumeric</application>'s |
| <filename>topic.dat</filename> file is: |
| <programlisting> |
| gnumeric.html Gnumeric manual |
| function-reference.html Gnumeric function reference |
| </programlisting> |
| When the application is installed, the |
| <filename>topic.dat</filename> file should be placed in the |
| <filename |
| class="directory">$prefix/share/gnome/help/<replaceable>appname</replaceable>/C/</filename> directory |
| where <replaceable>appname</replaceable> is replaced by the |
| application's name. The application documentation (converted |
| from SGML into HTML with <command>db2html</command>) should be |
| placed in this directory too. |
| </para> |
| <note> |
| <para> |
| If the help files are not present in the correct directory, the |
| menu items will NOT appear when the program is run. |
| </para> |
| </note> |
| <para> |
| The <filename>topic.dat</filename> file is used by the GNOME |
| menu building code to generate the <guimenu>Help</guimenu> |
| menu. When you define your menu: |
| <programlisting> |
| GnomeUIInfo helpmenu[] = { |
| {GNOME_APP_UI_ITEM, |
| N_("About"), N_("Info about this program"), |
| about_cb, NULL, NULL, |
| GNOME_APP_PIXMAP_STOCK, GNOME_STOCK_MENU_ABOUT, |
| 0, 0, NULL}, |
| GNOMEUIINFO_SEPARATOR, |
| GNOMEUIINFO_HELP("<emphasis>appname</emphasis>"), |
| GNOMEUIINFO_END |
| }; |
| </programlisting> |
| the line specifying <varname>GNOMEUIINFO_HELP</varname> causes |
| GNOME to create a menu entry which is tied to the documentation |
| in the directory mentioned above. Also, all the topics in the |
| <filename>topic.dat</filename> file will get menu entries in the |
| <guimenu>Help</guimenu> menu. When the user selects any of these |
| topics from the <guimenu>Help</guimenu> menu, a help browser |
| will be started with the associated HTML documentation. |
| </para> |
| </sect1> |
| |
| |
| <!-- ################# Application Help Buttons ############### --> |
| |
| <sect1 id="applicationhelpbuttons"> |
| <title>Application Help Buttons</title> |
| |
| <note> |
| <title>Developer Information</title> |
| <para> |
| This section is for developers. Documentation authors |
| generally do not need to know this material. |
| </para> |
| </note> |
| <para> |
| Most GNOME applications will have <guibutton>Help</guibutton> |
| buttons. These are most often seen in Preference windows. (All |
| Preference windows should have <guibutton>Help</guibutton> |
| buttons.) Most <guibutton>Help</guibutton> buttons will connect |
| to the application manual, although some may connect to special |
| documents. Because the <guibutton>Help</guibutton> buttons do |
| not generally have their own special documentation, the |
| documentation author(s) do not need to do very much. However, |
| the application author must be careful to guarantee that the |
| application correctly opens the help documentation when the |
| <guibutton>Help</guibutton> buttons are pressed. |
| </para> |
| <para> |
| To make the Help buttons call the correct document in the GNOME Help |
| Browser the developer should add code based on the following example: |
| </para> |
| <programlisting> |
| gchar *tmp; |
| tmp = gnome_help_file_find_file ("module", "page.html"); |
| if (tmp) { |
| gnome_help_goto(0, tmp); |
| g_free(tmp); |
| } |
| </programlisting> |
| <note> |
| <title>NOTE</title> |
| <para> |
| The example above is in the C language, please refer to other |
| documentation or forums for other GNOME language bindings. |
| </para> |
| </note> |
| </sect1> |
| |
| <!-- ################# Packaging Applet Documentation ############### --> |
| |
| <sect1 id="packagingappletdocs"> |
| <title>Packaging Applet Documentation</title> |
| <sect2 id="appletfiles"> |
| <title>Applet Documentation Files</title> |
| <para> |
| In GNOME 2.0 each applet will have its own documentation |
| installed separately, and the GNOME 2.0 help |
| browser (<application>Nautilus</application>) will dynamically |
| merge the applet documents into a single virtual book |
| called <citetitle>GNOME Applets</citetitle>. During the |
| transitionary stage between GNOME 1.0 and GNOME 2.0, each |
| applet in the gnome-applets package has its own manual(stored |
| with the applet in CVS), but they are merged together manually |
| to create the <citetitle>GNOME Applets</citetitle> book before |
| distribution. Telsa |
| <email>hobbit@aloss.ukuu.org.uk</email> is the maintainer of |
| this document. Applet documentation should be sent to Telsa |
| (or placed in CVS) who will make sure they are correctly |
| packaged with the applets. The applet author should be |
| contacted to modify the menu items and help buttons to bind to |
| the applet documentation if necessary. |
| </para> |
| <para> |
| Images which are part of the applet documentation should be in |
| PNG format and should reside in the same directory as the SGML |
| document file in CVS(gnome-applets/APPLETNAME/help/C). |
| </para> |
| <para> |
| Applets which are not part of the gnome-applets package must |
| package their documentation with the particular applet |
| package. They should use the same applet template as other |
| applets. However, the <sgmltag><xref></sgmltag> links to |
| the introductory chapter of the <citetitle>GNOME |
| Applets</citetitle> book must be removed (as the 1.x |
| <application>GNOME Help Browser</application> does not allow |
| you to create links between separate documents) and replaced |
| with suitable text. Note that since this document is not part |
| of the <citetitle>GNOME Applets</citetitle> book, you must |
| remember to add <sgmltag><legalnotice></sgmltag> and |
| <sgmltag><copyright></sgmltag> sections. |
| </para> |
| </sect2> |
| |
| <sect2 id="appletmenu"> |
| <title>Adding Documentation to an Applet Menu</title> |
| <note> |
| <title>Developer Information</title> |
| <para> |
| This section is for developers. Documentation authors |
| generally do not need to know this material. |
| </para> |
| </note> |
| <para> |
| Applets should have <guimenu>About</guimenu> and |
| <guimenu>Manual</guimenu> menu items, typically as the first |
| and second top-most items in the menu respectively. This |
| section describes how the developer creates these menu items |
| and links them to the documentation. |
| </para> |
| <para> |
| To add an applet's manual to its applet menu, use: |
| <programlisting> |
| /* add an item to the applet menu */ |
| applet_widget_register_callback(APPLET_WIDGET(applet), "manual", |
| _("Manual"), &open_manual, NULL); |
| </programlisting> |
| Here the second argument is an arbitrary name for the |
| callback, the third argument is the label which will appear |
| when the user right clicks on the applet, and the fourth |
| argument is the callback function. |
| </para> |
| <para> |
| You will need to write a simple callback function to open the |
| help browser to the appropriate document. This is done using |
| the <function>gnome_help_file_find_file</function> function, |
| as described in <xref linkend="applicationhelpbuttons" />. |
| </para> |
| <para> |
| You will also want to add an <guimenu>About</guimenu> menu |
| item to the applet's menu. This is a |
| stock menu item and is done: |
| <programlisting> |
| applet_widget_register_stock_callback (APPLET_WIDGET(applet), "about", |
| GNOME_STOCK_MENU_ABOUT, _("About"), &my_applet_cb_about, |
| NULL); |
| </programlisting> |
| </para> |
| <para> |
| More information can be found at <ulink type="http" |
| url="http://developer.gnome.org/doc/tutorials/applet/index.html">Writing |
| GNOME panel applets using the GTK+/GTK-- widget set</ulink>. |
| </para> |
| </sect2> |
| </sect1> |
| |
| |
| <!-- ################# Writing Context Sensitive Help ############### |
| --> |
| |
| <sect1 id="writingcontextsensitivehelp"> |
| <title>Writing Context Sensitive Help (coming in GNOME-2.0)</title> |
| <para> |
| Context sensitive help, also known as "pop-up" help, will allow |
| a user to obtain help information about specific buttons or |
| parts of an application. |
| </para> |
| <para> |
| Context sensitive help is still under development and not all |
| the details are available at this time. However, the basics can |
| be shown here so that you can understand how the system will |
| work. |
| </para> |
| <para> |
| The Context Sensitive Help system is designed to allow the |
| developer to give an id to a particular portion of the User |
| Interface, for example, a button. Once the interface is complete |
| a Perl script can then be run against the interface code to |
| create a "map" file. This map file allows the developer or |
| writer to associate particular paragraph sections from an XML |
| document to the interface items. |
| </para> |
| <para> |
| The XML used for the document is a small XML DTD that is being |
| developed to use the same tags (albeit, much fewer) as DocBook |
| so that writers do not have to re-learn a new DTD. |
| </para> |
| <para> |
| Once the document is written and map file is complete, when the |
| user launches context sensitive help on the interface (either by |
| pressing a button and then clicking on the interface item they |
| want information on, or by right mouse clicking on the interface |
| item and selecting a pop-up menu item like "What's This") a |
| small transient window will appear with brief but detailed |
| information on the interface item. |
| </para> |
| </sect1> |
| |
| <!-- ################# Referring to Other GNOME Documentation |
| ############# --> |
| |
| <sect1 id="referring"> |
| <title>Referring to Other GNOME Documentation (coming in |
| GNOME-2.0)</title> |
| <para> |
| In the GNOME 2.0 Help System, you will be able to create links |
| from one document to another. The exact mechanism for doing |
| this is in development. |
| </para> |
| </sect1> |
| |
| |
| <!-- ################# Basics of Documentation Style ############### --> |
| |
| <sect1 id="basics"> |
| <title>Basics of Documentation Style</title> |
| <para> |
| Most people have never enjoyed reading a software manual, and |
| they probably never will. Many times, they'll read the |
| documentation only when they run into problems, and they'll be |
| frustrated and upset before they even read a word. On the |
| other hand, some readers will read the manual all the way |
| through, or at least look at the introduction before they |
| start. Your document might serve as a reference for an expert |
| or a guide to a beginner, and it must have enough depth to |
| satisfy the first without overwhelming the second. Ideally, it |
| will serve beginners as they <emphasis>become</emphasis> |
| experts. Remember, your goal is to produce <emphasis>complete, |
| intuitive and clear</emphasis> documentation. |
| </para> |
| <para> |
| In order to write useful documentation, you'll have to know who |
| your audience is likely to be. Then, you can look for the |
| problems they're likely to run into, and solve them. It will |
| also help if you focus on the tasks users will perform, and |
| group features accordingly, rather than simply describing |
| features at random. |
| </para> |
| |
| <!-- *********** Basics of Documentation Style: planning --> |
| |
| <sect2 id="styleplanning"> |
| <title>Planning</title> |
| <para> |
| Begin documenting by learning how to use the application and |
| reading over any existing documentation. Pay attention to |
| places where your document will differ from the template. It |
| may help to develop a document skeleton: a valid XML or SGML |
| document that has little or no content. For very large |
| applications, you will need to make significant departures |
| from the templates, since you'll be using the |
| <sgmltag><book></sgmltag> tag instead of |
| <sgmltag><chapter></sgmltag> or |
| <sgmltag><article></sgmltag>. |
| </para> |
| </sect2> |
| |
| |
| <!-- ####### Basics of Documentation Style | Balance ####### --> |
| <sect2 id="balance"> |
| <title>Achieving a Balanced Style</title> |
| |
| <para> |
| Just as you need to juggle expert and novice readers, |
| you'll have to juggle a number of other extremes as you write: |
| <itemizedlist> |
| <listitem> |
| <para> |
| Documents should be complete, yet concise. You should |
| describe every feature, but you'll have decide how much |
| detail is really necessary. It's not, for example, |
| necessary to describe every button and form field in a |
| dialog box, but you should make sure that your readers |
| know how to bring up the dialog and what it does. If |
| you spend fewer words on the obvious, you can spend more |
| time clarifying the ambiguous labels and explaining |
| items that are more complex. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| Be engaging and friendly, yet professional. Games |
| documents may be less formal than productivity |
| application documents (people don't |
| <emphasis>use</emphasis> games, they |
| <emphasis>play</emphasis> them), but all of them should |
| maintain a standard of style which holds the reader's |
| interest without resorting to jokes and untranslatable |
| allusions or puns. |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| Examples, tips, notes, and screenshots are useful to |
| break up long stretches of text, but too many can get in |
| the way, and make your documents too choppy to read. |
| It's good to provide a screenshot of any dialog windows |
| a user might run into, but if a dialog box has several |
| tabs, it's not usually necessary to have one for each. |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| The GDP strives to have all of its documentation conform |
| to certain standards of style and content, but every |
| document (and every writer) is different. You will need |
| to use your judgement, and write documents to fit with |
| the rest of the project, without compromising the |
| individual needs of your subject, or your own |
| individuality as a writer. |
| </para> |
| </listitem> |
| |
| </itemizedlist> |
| </para> |
| </sect2> |
| |
| |
| <!-- ####### Basics of Documentation Style | Structure ####### --> |
| |
| <sect2 id="stylestructure"> |
| <title>Structure</title> |
| <para> |
| In general, you won't have to worry too much about structure, |
| because the templates provide you with an excellent example. |
| As a general rule, try to follow that structural example. |
| That means using links, hierarchical nesting, and, if |
| necessary, a glossary or index. You probably won't need to |
| use every available structural tag, but take advantage of |
| what DocBook provides you. |
| </para> |
| <para> |
| As to linking, there's some disagreement about whether to use |
| <sgmltag><xref></sgmltag> <sgmltag><link></sgmltag> |
| when you make links within your documents. You'll have to |
| decide, based on the different ways that they are presented |
| in output, which is more appropriate given the context. |
| Regardless of which you use, you should not forget to use |
| them. Help your readers find information that relevant to |
| the issue at hand. |
| </para> |
| <para> |
| The table of contents will be generated automatically, but |
| you will probably have to develop your own index if you wish |
| to have one. The Nautilus Help Browser will have new, and |
| currently unknown, indexing capabilities, so index style and |
| structure are still under discussion. The GNOME User's Guide |
| will contain a glossary in its next versions; unless you're |
| writing a<sgmltag><book></sgmltag>, it will probably be best to |
| contribute to that rather than developing your own. |
| </para> |
| </sect2> |
| <!-- ####### Basics of Documentation Style | Grammar & Spelling ####### --> |
| |
| <sect2 id="stylegrammar"> |
| <title>Grammar and Spelling</title> |
| <para> |
| Nobody expects you to be perfect; they just expect the |
| documentation for their software to be error-free. That means |
| that, in the same way that developers look for bugs and accept |
| bug reports, writers must check for errors in their documents. |
| Poor grammar, bad spelling, and gross technical errors in |
| draft documents are fine. However, if those problems show up |
| in a "real" release, they can count against the credibility of |
| GNOME and Linux. They'll also make you look bad. |
| </para> |
| <para> |
| There is no substitute for a human proofreader; use a |
| spell-check program, then read it over yourself, and then find |
| someone else to help you. Other GDP members are, of course, |
| willing and able to help you, but non-writers are often at |
| least as helpful. |
| </para> |
| <para> |
| Proofreading documents is both a also a good way to |
| familiarize yourself with documentation, and it certainly |
| makes you valuable to the GDP. Help other writers proof their |
| documents, and they will help you with yours. |
| </para> |
| </sect2> |
| </sect1> |
| |
| <!-- ################# Teamwork ############### --> |
| |
| <sect1 id="teamwork"> |
| <title>Teamwork</title> <!-- ####### Teamwork | Working With The |
| GDP Team ####### --> |
| |
| <sect2 id="teamworkgdp"> |
| <title>Working With The GDP Team</title> |
| <para> |
| The GDP team is a valuable resource for any documentation |
| author. GDP members can answer most questions documentation |
| authors have during the course of their work. It is also |
| important to make sure you are not duplicating work of other |
| GDP members by visiting the <citetitle>GDP Documentation |
| Status Table</citetitle> (<ulink |
| url="http://www.gnome.org/gdp/doctable/" |
| type="http">http://www.gnome.org/gdp/doctable/</ulink>) and |
| assigning a documentation item to yourself. This table also |
| provides a forum for making suggestions and announcements for |
| each documentation item. The best way to get in touch with |
| GDP members is on the #docs IRC channel at irc.gnome.org or |
| else by emailing the <ulink type="http" |
| url="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/"> |
| <citetitle>gnome-doc-list mailing list</citetitle></ulink>. |
| </para> |
| <para> |
| After an author has finished a document (or even a draft |
| version of the document), it is a good idea to ask a member of |
| the GDP team to read the document, checking it for grammar, |
| proper DocBook markup, and clarity. One may typically find |
| another author to do this by either asking on the #docs IRC |
| channel at irc.gnome.org or by emailing the <ulink type="http" |
| url="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/"> |
| <citetitle>gnome-doc-list mailing list</citetitle></ulink>. |
| </para> |
| </sect2> |
| |
| <!-- ####### Teamwork | Working With Developers ####### --> |
| |
| <sect2 id="teamworkdevelopers"> |
| <title>Working With Developers</title> |
| <para> |
| Writing documentation typically involves a certain amount of |
| interaction with the developers of GNOME or the application |
| which is being documented. Often a document author will need |
| to ask the developer technical questions during the course of |
| writing a document. After the document is finished, it is good |
| idea to ask the developer to read the document to make sure it |
| is technically correct. The documentation author should also |
| make sure that the application author correctly binds and |
| packages the documentation with the application. |
| </para> |
| </sect2> |
| |
| <!-- ####### Teamwork | Working With Users ####### |
| |
| <sect2 id="teamworkusers"> |
| <title>Working With Users</title> |
| <para> |
| Some document authors may wish to get feedback on their |
| documents directly from users. This may be done by ... |
| </para> |
| </sect2>--> |
| </sect1> |
| |
| <!-- ################# Finishing a Document ############### --> |
| |
| <sect1 id="finishing"> |
| <title>Finishing A Document</title> |
| |
| <!-- ####### Finishing a Document | Editting the Document ####### --> |
| |
| <sect2 id="editting"> |
| <title>Editing The Document</title> |
| <para> |
| When the document is finished, the document should be edited |
| by another member of the GDP for spelling, clarity, and |
| DocBook markup. It should also be read by an application |
| author to make sure the document is technically accurate. |
| </para> |
| </sect2> |
| |
| <!-- ####### Finishing a Document | Submitting the Document ####### --> |
| |
| <sect2 id="submitting"> |
| <title>Submitting The Document</title> |
| <para> |
| After the document has been edited and checked for technical |
| accuracy, it is ready to be combined with the application or |
| documentation package. This is typically done by passing the |
| document to the application or package developer. In some |
| cases, the documents can be committed directly into CVS, |
| however this should only be done after obtaining permission to |
| make CVS commits from the developer. Note that in many cases, |
| the application may need to be modified to correctly link to |
| the documentation. The packaging system (tarballs and binary |
| packages) may also need to be modified to include the |
| documentation in the package. Generally, this should be done |
| by the developers. |
| </para> |
| <para> |
| The final step is to email the GNOME Translation Team at |
| <email>gnome-i18n@nuclecu.unam.mx</email> to notify them that |
| there is a new document for them to translate. |
| </para> |
| </sect2> |
| </sect1> |
| |
| <!-- ################# Resources ############### --> |
| |
| <sect1 id="resources"> |
| <title>Resources</title> |
| <!-- ####### Resources | Resources on the Web ####### --> |
| |
| <sect2 id="resourcesweb"> |
| <title>Resources On The Web</title> <para> The <ulink |
| type="http" url="http://developer.gnome.org/projects/gdp/">GNOME |
| Documentation Project Web page</ulink> lists current GDP |
| projects and members. |
| </para> |
| <para> |
| The <ulink url="http://www.gnome.org/gdp/doctable/" |
| type="http">GDP Documentation Status Table</ulink> tracks the |
| status of all the various documentation components of GNOME. |
| </para> |
| <para> |
| Norman Walsh's <ulink url="http://www.docbook.org" |
| type="http"> <citetitle>DocBook: The Definitive |
| Guide</citetitle></ulink> in an excellent book on DocBook, |
| available both online and in print. |
| </para> |
| </sect2> |
| |
| <!-- ####### Resources | Books ####### --> |
| |
| <sect2 id="resourcesbooks"> |
| <title>Books</title> |
| <para> |
| Docbook: The Definitive Guide is available in both printed |
| form and on the web at: |
| <ulink url="http://www.docbook.org/tdg/index.html"> |
| <citetitle>Docbook: The Definitive Guide</citetitle> |
| </ulink> |
| </para> |
| </sect2> |
| |
| <!-- ####### Resources | Mailing Lists ####### --> |
| |
| <sect2 id="mailinglists"> |
| <title>Mailing Lists</title> |
| <para> |
| The <emphasis>gnome-docs-list</emphasis> mailing list is the |
| main discussion area for all contributors to the GNOME |
| Documentation Project. You can find out how to subscribe to |
| this list on <ulink |
| url="http://www.gnome.org/resources/mailing-lists.html" |
| type="http">GNOME Mailing Lists</ulink>. This is a rather |
| low-volume list, so you will not be flooded with messages. |
| </para> |
| </sect2> |
| |
| <!-- ####### Resources | IRC ####### --> |
| |
| <sect2 id="irc"> |
| <title>IRC</title> |
| <para> |
| Internet Relay Chat (IRC) is a fast and easy way to get in |
| touch with other GDP members. There are generally at least a |
| few members here who can answer questions or discuss |
| documentation issues. The IRC channel is #docs at |
| irc.gnome.org. |
| </para> |
| </sect2> |
| </sect1> |
| |
| <!-- ################# Example Docs ############### |
| |
| <appendix id="exampledocs"> |
| <title>Example Docs</title> |
| |
| ####### Example Docs | Example 1: Application Manual ####### |
| |
| <sect1 id="ex1"> |
| <title>Example 1: Application Manual</title> |
| <programlisting> |
| <![CDATA[ (Put sgml here.)]]> </programlisting> |
| </sect1> |
| |
| ####### Example Docs | Example 2: Applet Manual ####### |
| |
| <sect1 id="ex2"> |
| <title>Example 2: Applet Manual</title> |
| <programlisting> |
| <![CDATA[(Put sgml here.)]]> </programlisting> |
| </sect1> |
| |
| ##### Example Docs | Example 3: Application Context Sensitive Help #### |
| |
| <sect1 id="ex3"> |
| <title>Example 3: Application Context Sensitive Help</title> |
| <programlisting> |
| <![CDATA[(Put sgml here.)]]> </programlisting> |
| </sect1> |
| |
| ####### Example Docs | Example 4: Complete Application: gnome-hello ####### |
| |
| <sect1 id="ex4"> |
| <title>Example 4: Complete Application: gnome-hello</title> |
| <programlisting> |
| <![CDATA[(Put sgml here.)]]> </programlisting> |
| </sect1> |
| |
| ####### Example Docs | Example 5: Tutorial ####### |
| |
| <sect1 id="ex5"> |
| <title>Example 5: Tutorial</title> |
| <programlisting> |
| <![CDATA[(Put sgml here.)]]> </programlisting> |
| </sect1> |
| </appendix>--> |
| |
| <!-- ################# Document Templates ############### --> |
| |
| <appendix id="templates"> |
| <title>Document Templates</title> |
| <!-- ####### Document Templates | Templates 1: Application Manual ####### --> |
| |
| <sect1 id="template1"> |
| <title>Template 1: Application Manual</title> |
| <para> |
| The following template should be used for all application |
| manuals. You can always get the latest copy of this |
| template from <ulink type="http" |
| url="http://developer.gnome.org/projects/gdp/templates.html">GDP |
| Documentation Templates</ulink>. |
| <programlisting> |
| |
| <![CDATA[ |
| <!DOCTYPE Article PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[ |
| <!-- if not using PNG graphic, replace reference above with |
| .....PUBLIC "-//OASIS//DTD DocBook V3.1//EN"[ |
| --> |
| <!ENTITY version "1.0.53"> |
| <!-- replace version above with actual application version number--> |
| <!-- Template Version: 1.0.1 (do not remove this line) --> |
| ]> |
| |
| |
| <!-- This is a GNOME documentation template, designed by the GNOME |
| Documentation Project Team. Please use it for writing GNOME |
| documentation, making obvious changes. In particular, all the words |
| written in UPPERCASE (with the exception of GNOME) should be |
| replaced. As for "legalnotice", please leave the reference |
| unchanged. |
| |
| Remember that this is a guide, rather than a perfect model to follow |
| slavishly. Make your manual logical and readable. And don't forget |
| to remove these comments in your final documentation! ;-) |
| --> |
| |
| <!-- =============Document Header ============================= --> |
| |
| <article id="index"> <!-- please do not change the id --> |
| |
| <artheader> |
| <title>MY-GNOME-APP</title> |
| <copyright> |
| <year>2000</year> |
| <holder>ME-THE-AUTHOR</holder> |
| </copyright> |
| |
| <!-- translators: uncomment this: |
| |
| <copyright> |
| <year>2000</year> |
| <holder>ME-THE-TRANSLATOR (Latin translation)</holder> |
| </copyright> |
| |
| --> |
| |
| <!-- do not put authorname in the header except in copyright - use |
| section "authors" below --> |
| |
| <legalnotice> |
| <para> |
| Permission is granted to copy, distribute and/or modify this |
| document under the terms of the <citetitle>GNU Free |
| Documentation License</citetitle>, 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 <citetitle>GNU Free |
| Documentation License</citetitle> from the Free Software |
| Foundation by visiting <ulink type="http" |
| url="http://www.fsf.org">their Web site</ulink> or by writing |
| to: Free Software Foundation, Inc., 59 Temple Place - Suite |
| 330, Boston, MA 02111-1307, USA. |
| </para> |
| <para> |
| 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. |
| </para> |
| </legalnotice> |
| |
| <!-- this is the version of manual, not application --> |
| <releaseinfo> |
| This is version 1.0 of MY-GNOME-APP manual. |
| </releaseinfo> |
| |
| </artheader> |
| |
| <!-- ============= Document Body ============================= --> |
| |
| <!-- ============= Introduction ============================== --> |
| <sect1 id="intro"> |
| <title>Introduction</title> |
| |
| <para> |
| <application>MY-GNOME-APP</application> is an application which |
| proves mathematical theorems. It has all the basic features |
| expected from a mathematical theorem prover, as well as a number |
| of advanced ones, such as proof by confusion. In fact, many of |
| the proofs produced by <application>MY-GNOME-APP</application> |
| are so complex that they are capable of proving almost anything |
| with a virtually null likelihood of being disproven. It also has |
| the very popular predecessor of proof by confusion, proof by |
| dialog, first implemented by Plato. |
| </para> |
| <para> |
| It also allows you to save and print theorem proofs and to add |
| comments to the proofs it produces. |
| </para> |
| |
| <para> |
| To run <application>MY-GNOME-APP</application>, select |
| <menuchoice> |
| <guisubmenu>SUBMENU</guisubmenu> |
| <guimenuitem>MY-GNOME-APP</guimenuitem> |
| </menuchoice> |
| from the <guimenu>Main Menu</guimenu>, or type |
| <command>MYGNOMEAPP</command> on the command line. |
| </para> |
| |
| <para> |
| <application>MY-GNOME-APP</application> is included in the |
| <filename>GNOME-PACKAGE</filename> package, which is part of the |
| GNOME desktop environment. This document describes version |
| &version; of <application>MY-GNOME-APP</application>. |
| </para> |
| </sect1> |
| |
| |
| <!-- ================ Usage ================================ --> |
| <!-- This section should describe basic usage of the application. --> |
| |
| <sect1 id="usage"> |
| <title>Using MY-GNOME-APP</title> |
| <para> |
| <application>MY-GNOME-APP</application> can be used to produce a |
| perfect proof of <emphasis>any</emphasis> mathematical theorem |
| (provided, of course, that this theorem is correct), thus |
| providing for new users an easy-to-use graphical interface to |
| modern mathematics. This section describes basic usage of |
| <application>MY-GNOME-APP</application>. |
| </para> |
| |
| <!-- ========= Basic Usage =========================== --> |
| <sect2 id="mainwin"> |
| <title>Basic usage</title> |
| <para> |
| Starting <application>MY-GNOME-APP</application> opens the |
| <interface>Main window</interface>, shown in <xref |
| linkend="mainwindow-fig">. The window is at first empty. |
| |
| <!-- ==== Figure ==== --> |
| <figure id="mainwindow-fig"> |
| <title>MY-GNOME-APP Main Window</title> |
| <screenshot> |
| <screeninfo>MY-GNOME-APP Main Window</screeninfo> |
| <graphic fileref="SCREENSHOT" format="png" srccredit="ME"> |
| </graphic> |
| </screenshot> |
| </figure> |
| <!-- ==== End of Figure ==== --> |
| </para> |
| |
| |
| <!-- For this app, one could put "proving" or "edit" (probably even |
| both of them) as sect2's seperate from the main window |
| section. Since they were both so closely involved with the main |
| window, I decided to have them as sect3's isntead. Judgement |
| call. --> |
| |
| <sect3 id="proving"> |
| <title>Proving a Theorem</title> |
| <para> |
| To get a proof of a theorem, select |
| <menuchoice> |
| <guisubmenu>File</guisubmenu> |
| <guimenuitem>New</guimenuitem> |
| </menuchoice>, |
| which will |
| bring up the <interface>New Proof</interface> dialog box. |
| Enter the statement of the theorem in the |
| <guilabel>Theorem statement</guilabel> field, select your |
| desired proof type from the drop-down menu, and and press |
| <guibutton>Prove!</guibutton>. |
| </para> |
| <para> |
| If <application>MY-GNOME-APP</application> cannot prove the |
| theorem by the method you have chosen, or if you have not |
| selected a proof type at all, |
| <application>MY-GNOME-APP</application> will attempt to |
| choose the one that it thinks is most conclusive. In order, |
| it will attempt to prove the theorem with the following techniques: |
| |
| <variablelist> |
| <varlistentry> |
| <term>Deduction</term> |
| <listitem> |
| <para> |
| This is a proof method that is generally accepted |
| for full credit by Logic professors. |
| </para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>Induction</term> |
| <listitem> |
| <para> |
| This logical style will also earn you full credit on |
| your homework. |
| </para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>Dialog</term> |
| <listitem> |
| <para> |
| This logical method is best for Philosophy classes, |
| and will probably only merit partial credit on Logic |
| or Mathematics homework. |
| </para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>Confusion</term> |
| <listitem> |
| <para> |
| Suitable only for political debates, battles of wits |
| against the unarmed, and Philosophy classes focusing |
| on the works of Kant. Use with caution. |
| </para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </para> |
| |
| <!-- You might want to include a note, warning, or tip, e.g. --> |
| |
| <warning> |
| <title>Proving Incorrect Theorms</title> |
| <para> |
| <application>MY-GNOME-APP</application> cannot prove |
| incorrect theorems. If the theorem you have entered is not |
| demonstrably true, you will get a message to that effect |
| in the main window. To disprove a theorem, ask |
| <application>MY-GNOME-APP</application> to prove its |
| logical inverse. |
| </para> |
| </warning> |
| </sect3> |
| <sect3 id="editing"> |
| <title>Editing Proofs</title> |
| <para> |
| Once you have proven the theorem, it will be displayed in |
| the <interface>main window</interface>. There, you can read |
| it over, choose text styles for different portions of it, |
| and make comments on it. This section will guide you through |
| that process. |
| </para> |
| <para> |
| To alter text styles, first select the statement you wish to |
| change by clicking on it once. You can select several |
| statements by Then, choose the style you want to apply from |
| the <guisubmenu>Style</guisubmenu> submenu of the |
| <guimenu>Edit</guimenu> menu. |
| <application>MY-GNOME-APP</application> will convert the |
| text to that style. |
| </para> |
| <para> |
| You can also enter comments on a statement by selecting that |
| statement, and then beginning to type. Comments will appear |
| after the statement you have selected. |
| </para> |
| |
| <note> |
| <title>Altering The Proofs Themselves</title> |
| <para> |
| <application>MY-GNOME-APP</application> does not allow you |
| to alter a proof it has produced itself. You can, save |
| your proof as a plain text file (using the |
| <guimenuitem>Save as...</guimenuitem> menu), and alter it |
| that way. Be aware, however, that |
| <application>MY-GNOME-APP</application> uses its own file |
| format for saved proofs, and cannot re-open a file unless |
| it is in the .mga format. |
| </para> |
| </note> |
| </sect3> |
| |
| |
| <!-- If there are other functions performed from the main window, |
| they belong here. --> |
| |
| </sect2> |
| |
| <!-- ========================================================= |
| Additional Sect2's should describe additional windows, such as |
| larger dialog boxes, or functionality that differs significantly |
| from the most immediate functions of the application. Make the |
| structure logical. |
| ============================================================= --> |
| |
| |
| <sect2 id="toolbar"> |
| <title>Toolbar</title> |
| <para> |
| The toolbar (shown in <xref linkend="figure-usage-toolbar">) |
| provides access to several commonly used routines. |
| <figure id="figure-usage-toolbar"> |
| <title>MY-GNOME-APP Toolbar</title> |
| <screenshot> |
| <screeninfo>MY-GNOME-APP Toolbar</screeninfo> |
| <graphic fileref="usage-toolbar.png" format="png"></graphic> |
| </screenshot> |
| </figure> |
| <variablelist> |
| <varlistentry> |
| <term>New</term> |
| <listitem> |
| <para> |
| Brings up the <interface>New Theorem</interface> |
| dialog. |
| </para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>Open</term> |
| <listitem> |
| <para> |
| Open an exisiting theorem you want to prove, or a |
| completed proof you wish to print or format. |
| </para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>Save</term> |
| <listitem> |
| <para> |
| Save the current theorem permanently in a |
| file. |
| </para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </para> |
| </sect2> |
| <!-- ========= Menus =========================== --> |
| |
| <sect2 id="menubar"> |
| |
| <!-- Describing the menubar ensures comprehensive feature |
| coverage. Nest itemizedlists inside variablelists so that each |
| menu is easily located by indexing software. Proper indentation |
| makes it easier! --> |
| |
| <title>Menus</title> |
| <para> |
| The menu bar, located at the top of the <interface>Main |
| Window</interface>, contains the following menus: |
| </para> |
| <variablelist> |
| <varlistentry> |
| <term><guimenu>File</guimenu></term> |
| <listitem> |
| <para> |
| This menu contains: |
| <itemizedlist> |
| <listitem> |
| <para> |
| <menuchoice> |
| <shortcut> |
| <keycap>F3</keycap> |
| </shortcut> |
| <guimenuitem>Open</guimenuitem> |
| </menuchoice> |
| — This opens a file which is saved on your computer. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <menuchoice> |
| <shortcut> |
| <keycombo><keycap>Ctrl</keycap><keycap>S</keycap></keycombo> |
| </shortcut> |
| <guimenuitem>Save</guimenuitem> |
| </menuchoice> |
| — This saves your file. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <menuchoice> |
| <shortcut> |
| <keycombo><keycap>Ctrl</keycap><keycap>W</keycap></keycombo> |
| </shortcut> |
| <guimenuitem>Close</guimenuitem> |
| </menuchoice> |
| — This closes your file. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <menuchoice> |
| <shortcut> |
| <keycombo><keycap>Ctrl</keycap><keycap>Q</keycap></keycombo> |
| </shortcut> |
| <guimenuitem>Exit</guimenuitem> |
| </menuchoice> |
| — This quits the application. |
| </para> |
| </listitem> |
| </itemizedlist> |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><guimenu>Edit</guimenu></term> |
| <listitem> |
| <para> |
| This menu contains: |
| <itemizedlist> |
| <listitem> |
| <para> |
| <menuchoice> |
| <shortcut> |
| <keycombo><keycap>Ctrl</keycap><keycap>X</keycap></keycombo> |
| </shortcut> |
| <guimenuitem>Cut</guimenuitem> |
| </menuchoice> |
| — This removes any text or data which is selected and |
| places it in the buffer. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <menuchoice> |
| <shortcut> |
| <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo> |
| </shortcut> |
| <guimenuitem>Copy</guimenuitem> |
| </menuchoice> |
| — This copies any text or data which is selected into |
| the buffer. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <menuchoice> |
| <shortcut> |
| <keycombo><keycap>Ctrl</keycap><keycap>V</keycap></keycombo> |
| </shortcut> |
| <guimenuitem>Paste</guimenuitem> |
| </menuchoice> |
| — This pastes any text or data which is copied into |
| the buffer. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <guimenuitem>COMMAND1…</guimenuitem> |
| — This opens the <interface>COMMAND1</interface> |
| dialog, which is used to .... |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <guimenuitem>COMMAND2</guimenuitem> |
| — This .... |
| </para> |
| </listitem> |
| </itemizedlist> |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| |
| <varlistentry> |
| <term><guimenu>Settings</guimenu></term> |
| <listitem> |
| <para> |
| This menu contains: |
| <itemizedlist> |
| <listitem> |
| <para> |
| <guimenuitem>Preferences…</guimenuitem> |
| — This opens the <link |
| linkend="prefs"><interface>Preferences |
| Dialog</interface></link>, which allows you to configure |
| many settings. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <guimenuitem>COMMAND3</guimenuitem> — |
| This command does something. |
| </para> |
| </listitem> |
| </itemizedlist> |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><guimenu>Help</guimenu></term> |
| <listitem> |
| <para> |
| This menu contains: |
| <itemizedlist> |
| <listitem> |
| <para> |
| <guimenuitem>Manual</guimenuitem> — This |
| opens the <application>GNOME Help |
| Browser</application> and displays this manual. |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| <guimenuitem>About</guimenuitem> — This |
| opens the <interface>About</interface> dialog |
| which shows basic information about |
| <application>MY-GNOME-APP</application>, such as |
| the author's name, the application version number, |
| and the URL for the application's Web page if one |
| exists. |
| </para> |
| </listitem> |
| </itemizedlist> |
| </para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </sect2> |
| </sect1> |
| |
| |
| |
| <!-- ============= Customization ============================= --> |
| |
| <sect1 id="prefs"> |
| <title>Customization</title> |
| <para> |
| To change the application settings, select |
| <menuchoice> |
| <guimenu>Settings</guimenu> |
| <guimenuitem>Preferences...</guimenuitem> |
| </menuchoice>. This opens the |
| <interface>Preferences</interface> dialog, shown in <xref |
| linkend="preferences-fig">. |
| </para> |
| |
| <figure id="preferences-fig"> |
| <title>Preferences Dialog</title> |
| <screenshot> |
| <screeninfo>Preferences Dialog</screeninfo> |
| <graphic fileref="SCREENSHOT" format="png" |
| srccredit="ME"> |
| </graphic> |
| </screenshot> |
| </figure> |
| |
| <para> |
| The properties in the <guilabel>PREFSTABNAME</guilabel> tab are: |
| |
| <!--many people use itemizedlists in cases like this. Variablelists |
| are more appropriate --> |
| |
| <variablelist> |
| <varlistentry> |
| <term> <guilabel>Default Text Style</guilabel></term> |
| <listitem> |
| <para> |
| Select the default text style for statements in your |
| proof. You can still change the style for individual |
| proofs or sections of a proof at a later date. |
| </para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>(Configuration Item Label)</term> |
| <listitem> |
| <para> |
| (Description of Configuration) |
| </para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>(Configuration Item Label)</term> |
| <listitem> |
| <para> |
| (Description of Configuration) |
| </para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </para> |
| |
| <para> |
| The properties in the <guilabel>SECONDTABNAME</guilabel> tab are: |
| <variablelist> |
| <varlistentry> |
| <term>(Configuration Item Label)</term> |
| <listitem> |
| <para> |
| (Description of Configuration) |
| </para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>(Configuration Item Label)</term> |
| <listitem> |
| <para> |
| (Description of Configuration) |
| </para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </para> |
| |
| <para> |
| After you have made all the changes you want, click on |
| <guibutton>OK</guibutton> to apply the changes and close the |
| <interface>Properties</interface> dialog. To cancel the changes |
| and return to previous values, click the |
| <guibutton>Close</guibutton> button. |
| </para> |
| |
| </sect1> |
| |
| |
| <!-- ============= Various Sections ============================= --> |
| |
| <!-- Here you should add, if necessary, several more sect1's, |
| describing other windows (besides the main one), file formats, |
| preferences dialogs, etc. as appropriate. Try not to make any of |
| these sections too long. --> |
| |
| |
| <!-- ============= Bugs ================================== --> |
| <!-- This section should describe known bugs and limitations of |
| the program if there are any - please be frank and list all |
| problems you know of. --> |
| <sect1 id="bugs"> |
| <title>Known Bugs and Limitations</title> |
| <para> |
| This application has no known bugs. |
| </para> |
| </sect1> |
| |
| |
| <!-- ============= Authors ================================ --> |
| |
| <sect1 id="authors"> |
| <title>Authors</title> |
| <para> |
| <application>MY-GNOME-APP</application> was written by GNOME-HACKER |
| (<email>hacker@gnome.org</email>). To find more information about |
| <application>MY-GNOME-APP</application>, please visit the <ulink |
| url="http://www.my-gnome-app.org" type="http">MY-GNOME-APP Web |
| page</ulink>. Please send all comments, suggestions, and bug |
| reports to the <ulink url="http://bugs.gnome.org" type="http">GNOME |
| bug tracking database</ulink>. (Instructions for submitting bug |
| reports can be found <ulink |
| url="http://bugs.gnome.org/Reporting.html" type="http"> |
| on-line</ulink>.) You can also use <application>Bug Report |
| Tool</application> (<command>bug-buddy</command>), available in the |
| <guisubmenu>Utilities</guisubmenu> submenu of <guimenu>Main |
| Menu</guimenu>, for submitting bug reports. |
| </para> |
| |
| <para> |
| This manual was written by ME |
| (<email>MYNAME@MYADDRESS</email>). Please send all comments and |
| suggestions regarding this manual to the <ulink type="http" |
| url="http://developer.gnome.org/projects/gdp">GNOME Documentation |
| Project</ulink> by sending an email to |
| <email>docs@gnome.org</email>. You can also add your comments online |
| by using the <ulink type="http" |
| url="http://www.gnome.org/gdp/doctable/">GNOME Documentation Status |
| Table</ulink>. |
| </para> |
| |
| <!-- For translations: uncomment this: |
| |
| <para> |
| Latin translation was done by ME |
| (<email>MYNAME@MYADDRESS</email>). Please send all comments and |
| suggestions regarding this translation to SOMEWHERE. |
| </para> |
| |
| --> |
| |
| </sect1> |
| |
| |
| <!-- ============= Application License ============================= --> |
| |
| <sect1 id="license"> |
| <title>License</title> |
| <para> |
| This program is free software; you can redistribute it and/or |
| modify it under the terms of the <citetitle>GNU General Public |
| License</citetitle> as published by the Free Software Foundation; |
| either version 2 of the License, or (at your option) any later |
| version. |
| </para> |
| <para> |
| This program is distributed in the hope that it will be useful, but |
| WITHOUT ANY WARRANTY; without even the implied warranty of |
| MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| <citetitle>GNU General Public License</citetitle> for more details. |
| </para> |
| <para> |
| A copy of the <citetitle>GNU General Public License</citetitle> is |
| included as an appendix to the <citetitle>GNOME Users |
| Guide</citetitle>. You may also obtain a copy of the |
| <citetitle>GNU General Public License</citetitle> from the Free |
| Software Foundation by visiting <ulink type="http" |
| url="http://www.fsf.org">their Web site</ulink> or by writing to |
| <address> |
| Free Software Foundation, Inc. |
| <street>59 Temple Place</street> - Suite 330 |
| <city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode> |
| <country>USA</country> |
| </address> |
| </para> |
| </sect1> |
| </article> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| ]]> |
| |
| |
| </programlisting> |
| </para> |
| </sect1> |
| |
| <!-- ####### Document Templates | Templates 2-1.x: Applet Manual ####### --> |
| |
| <sect1 id="template2-1x"> |
| <title>Template 2: Applet Manual For GNOME 1.x</title> |
| <para> |
| The following templates should be used for all applet |
| manuals in GNOME 1.x releases. You can always get the latest |
| copy of these templates from <ulink type="http" |
| url="http://developer.gnome.org/projects/gdp/templates.html">GDP |
| Documentation Templates</ulink>. Note that the template |
| consists of two files; the first file calls the second as an |
| entity. You should name the first file |
| <filename><replaceable>appletname</replaceable>-applet.sgml</filename> |
| and the second file should be named |
| <filename><replaceable>appletname</replaceable>.sgml</filename>, |
| where |
| <filename><replaceable>appletname</replaceable></filename> is |
| the name of the applet. |
| <programlisting> |
| |
| <![CDATA[ |
| <!DOCTYPE Article PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[ |
| <!entity APPLETNAME.sgml SYSTEM "applet_template_1.sgml"> |
| <!-- Template Version: 1.0.1 (do not remove this line) --> |
| ]> |
| |
| <!-- This is a GNOME documentation template, designed by the GNOME |
| Documentation Project Team. Please use it for writing GNOME |
| documentation, making obvious changes. In particular, all the words |
| written in UPPERCASE (with the exception of GNOME) should be |
| replaced. As for "legalnotice", please leave the reference |
| unchanged,make sure to add/remove trademarks to the list as |
| appropriate for your document. |
| |
| Please don't forget to remove these comments in your final documentation, |
| thanks ;-). |
| --> |
| |
| <article id="index"> <!-- please do not change the id --> |
| |
| <!-- ============= Document Header ============================= --> |
| <artheader> |
| <title>APPLETNAME Applet</title> |
| <copyright> |
| <year>2000</year> |
| <holder>YOURFULLNAME</holder> |
| </copyright> |
| |
| <!-- translators: uncomment this: |
| |
| <copyright> |
| <year>2000</year> |
| <holder>ME-THE-TRANSLATOR (Latin translation)</holder> |
| </copyright> |
| |
| --> |
| |
| <!-- do not put authorname in the header except in copyright - use |
| section "authors" below --> |
| |
| <legalnotice> |
| <para> |
| Permission is granted to copy, distribute and/or modify this |
| document under the terms of the <citetitle>GNU Free Documentation |
| License</citetitle>, 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 <citetitle>GNU Free Documentation License</citetitle> from |
| the Free Software Foundation by visiting <ulink type="http" |
| url="http://www.fsf.org">their Web site</ulink> or by writing to: |
| Free Software Foundation, Inc., 59 Temple Place - Suite 330, |
| Boston, MA 02111-1307, USA. |
| </para> |
| <para> |
| 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. |
| </para> |
| </legalnotice> |
| |
| <releaseinfo> |
| This is version XXX of the APPLETNAME applet manual. |
| </releaseinfo> |
| </artheader> |
| |
| <!-- ============= Document Body ============================= --> |
| |
| &APPLETNAME.sgml; |
| |
| </article> |
| |
| |
| ]]> |
| |
| |
| </programlisting> |
| <programlisting> |
| <![CDATA[ |
| <!-- Template Version: 1.0.1 (do not remove this line) --> |
| |
| <sect1 id="APPLET"> |
| <title>APPLET Applet</title> |
| |
| <para> |
| <application>APPLET</application> applet, shown in <xref |
| linkend="APPLETapplet-fig">, allows you to …. To add this |
| applet to a <interface>Panel</interface>, |
| right-click on the <interface>Panel</interface> and choose |
| <menuchoice> |
| <guimenu>Panel</guimenu> |
| <guisubmenu>Add to panel</guisubmenu> |
| <guisubmenu>Applet</guisubmenu> |
| <guisubmenu>SECTION</guisubmenu> |
| <guimenuitem>APPLET</guimenuitem> |
| </menuchoice>. |
| </para> |
| |
| <figure id="APPLETapplet-fig"> |
| <title>APPLET Applet</title> |
| <screenshot> |
| <screeninfo>APPLET Applet</screeninfo> |
| <graphic format="png" fileref="APPLET_applet" |
| srccredit="YOURNAME"> |
| </graphic> |
| </screenshot> |
| </figure> |
| |
| <!-- ============= Usage ================================ --> |
| <sect2 id="APPLET-usage"> |
| <title>Usage</title> |
| <para> |
| (Place a short description of how to use the applet here.) |
| </para> |
| |
| <para> |
| Right-clicking on the applet brings up a menu containing the |
| following items: |
| <itemizedlist> |
| |
| <listitem> |
| <para> |
| <guimenuitem>Properties…</guimenuitem> — |
| opens the <link linkend="APPLET-prefs"> |
| <guilabel>Properties</guilabel></link> dialog. |
| </para> |
| </listitem> |
| |
| <listitem> |
|