diff options
Diffstat (limited to 'test/relaxng/docbook_0.xml')
| -rw-r--r-- | test/relaxng/docbook_0.xml | 4448 |
1 files changed, 0 insertions, 4448 deletions
diff --git a/test/relaxng/docbook_0.xml b/test/relaxng/docbook_0.xml deleted file mode 100644 index ede051d..0000000 --- a/test/relaxng/docbook_0.xml +++ /dev/null @@ -1,4448 +0,0 @@ -<?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> - <para> - <guimenuitem>Help</guimenuitem> — - displays this document. - </para> - </listitem> - - <listitem> - <para> - <guimenuitem>About…</guimenuitem> — - shows basic information about <application>APPLET - Applet</application>, including the applet's version and the - author's name. - </para> - </listitem> - - </itemizedlist> - </para> - </sect2> - - - <!-- ============= Customization ============================= --> - <sect2 id="APPLET-prefs"> - <title>Customization</title> - <para> - You can customize <application>APPLET</application> - applet by right-clicking on it and choosing - <guimenuitem>Properties…</guimenuitem>. This will open the - <interface>Properties</interface> dialog(shown in <xref - linkend="APPLET-settings-fig">), which allows you to - change various settings. - </para> - - <figure id="APPLET-settings-fig"> - <title>Properties dialog</title> - <screenshot> - <screeninfo>Properties dialog</screeninfo> - <graphic format="png" fileref="APPLET_settings" - srccredit="YOURNAME"> - </graphic> - </screenshot> - </figure> - - <para> - The properties are: - <itemizedlist> - - <listitem> - <para> - (Configuration Item Label) — If this button is - checked…(description) - </para> - </listitem> - - <listitem> - <para> - (Configuration Item Label) — Selecting this - button…(description) - </para> - </listitem> - - <listitem> - <para> - (Configuration Item Label) — Enter the name of - …(description) - </para> - </listitem> - </itemizedlist> - </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> - </sect2> - - - <!-- ============= 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 --> - <sect2 id="bugs"> - <title>Known Bugs and Limitations</title> - <para> - This applet has no known bugs. - </para> - </sect2> - - - <!-- ============= Authors ================================ --> - - <sect2 id="authors"> - <title>Authors</title> - <para> - <application>APPLET</application> was written by GNOME-HACKER - (<email>hacker@gnome.org</email>). 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 submit 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> - - --> - - </sect2> - - - <!-- ============= Application License ============================= --> - - <sect2 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> - </sect2> - - </sect1> - - - - -]]> - - - -</programlisting> - </para> - </sect1> - -<!-- ####### Document Templates | Templates 2-2.x: Applet Manual ####### --> - - <sect1 id="template2-2x"> - <title>Template 2: Applet Manual For GNOME 2.x</title> - <para> - The following templates should be used for all applet - manuals in GNOME 2.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>. - </para> - <para> - Note that this template consists of two files. The first file - is an introductory chapter. You should not modify this - chapter. The second file is the actual applet document, which - you should modify to describe the applet you are documenting. - You can name the first file whatever you like, such as - <filename>gnome-applets.sgml</filename>. Name the second file - according to the applet's name: - <filename><replaceable>appletname</replaceable>-applet.sgml</filename>. - Make sure you update the entity - at the top of the shell document to reflect the new name of - the applet document. - </para> - <para> - <programlisting> -<![CDATA[ -<!DOCTYPE book PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[ -<!ENTITY TEMPLATE-APPLET SYSTEM "gnome-applet-template.sgml.part"> - -]> - -<book id="gnome-applets"> - - <bookinfo> - <title>GNOME Applets</title> - <authorgroup> - <author><firstname>Telsa</firstname><surname>Gwynne</surname></author> - <author><firstname>John</firstname><surname>Fleck</surname></author> - <author><firstname>David</firstname><surname>Mason</surname> - <affiliation><orgname>Red Hat, Inc.</orgname></affiliation> - </author> - <author><firstname>Dan</firstname><surname>Mueth</surname></author> - <author><firstname>Alexander</firstname><surname>Kirillov</surname></author> - </authorgroup> - <edition>GNOME Applets version 0.1 for GNOME 1.1.5</edition> - <pubdate>2000</pubdate> - <copyright> - <year>2000</year> - <holder>Telsa Gwynne, John Fleck, Red Hat Inc., Dan Mueth, and - Alexander Kirillov</holder> - </copyright> - <legalnotice> - <para> - Permission is granted to make and distribute verbatim copies of this - manual provided the copyright notice and this permission notice are - preserved on all copies. - </para> - <para> - Permission is granted to copy and distribute modified versions of - this manual under the conditions for verbatim copying, provided that - the entire resulting derived work is distributed under the terms of a - permission notice identical to this one. - </para> - <para> - Permission is granted to copy and distribute translations of this - manual into another language, under the above conditions for modified - versions, except that this permission notice may be stated in a - translation approved by the Free Software Foundation. - </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> - </bookinfo> - - <!-- #### Introduction ###### --> - <chapter id="applets-intro"> - <title>Introduction</title> - - <!-- #### Intro | What Are Applets? ###### --> - <sect1 id="applets-what-are"> - <title>What Are Applets?</title> - <para> - Applets are one of the most popular and useful objects you can add - to your <interface>Panel</interface> to customize your desktop. - An applet is a small application which runs inside a small area of - your <interface>Panel</interface>. Applets have been written for - a wide range of purposes. Some are very powerful interactive - tools, such as the <application>Tasklist</application> Applet - which allows you to easily - control all of your main applications. Others are simple system - monitors, displaying information such as the amount of power left - in the battery on your laptop (see <application>Battery Charge - Monitor</application>) or weather - information(see <application>GNOME Weather</application>). Some - are simply for amusement(see <application>Fish</application>). - </para> - - <para> - Applets are similar to swallowed applications in that both of them - reside within the <interface>Panel</interface>. However, - swallowed applications are generally applications which were - not designed to run within the <interface>Panel</interface>. - Typically one will swallow an application which already exists in - the main <interface>desktop</interface> area, putting it into your - <interface>Panel</interface>. The application will continue to - run in the <interface>Panel</interface> until you end the - application or unswallow it, placing it back onto the main part of - your desktop when you need to. - </para> - - <para> - <figure id="example-applets-fig"> - <title>Example Applets</title> - <screenshot> - <screeninfo>Example Applets</screeninfo> - <graphic fileref="example_applets" format="png" - srccredit="muet"> - </graphic> - </screenshot> - </figure> - Several example applets are shown in <xref - linkend="example-applets-fig">. From left to right, they are: (1) - <application>Mixer Applet</application>, which allows you to turn - on/off sound and control its volume by clicking on the applet. (2) - <application>Sound Monitor</application> Applet, which displays - the current volume of sound being played and allows you to control - various sound features. (3) <application>GTCD</application> - Applet, a CD player which has all its controls - available in the applet and displays the track and time. (4) - <application>Drive Mount</application> Applet, used to mount and - unmount drives with a single click of the mouse. (5) - <application>Desk Guide</application> which allows you to view - and control multiple virtual screens. (6) - <application>Tasklist</application> Applet which allows you to - control your various windows and applications. - </para> - <para> - There are many other applets to choose from. The rest of this - chapter will explain the basic information to get you started - adding, moving, and removing applets from your - <interface>Panels</interface> and using them. The following - chapters go through each of the standard GNOME applets describing - them in detail. There are also additional applets which can be - downloaded off the Web. See <ulink type="http" - url="http://www.gnome.org/applist/list-martin.phtml">The GNOME - Software Map</ulink> for lists of additional GNOME applications - and applets. - </para> - <para> - As you read through the the rest of this chapter, you should try - adding and removing applets from your <interface>Panel</interface> and - experiment with them freely. - </para> - </sect1> - - <!-- #### Intro | Adding, Moving, and Removing Applets ###### --> - <sect1 id="applet-add-move-replace"> - <title>Adding, Moving, and Removing Applets</title> - - <sect2 id="adding-applets"> - <title>Adding Applets to a Panel</title> - <para> - To add an applet to a <interface>Panel</interface>, right-click - on the <interface>Panel</interface> and select - <menuchoice><guimenu>Panel</guimenu><guisubmenu>Add to panel</guisubmenu> - <guisubmenu>Applet</guisubmenu></menuchoice>. This will show you - the menu of all the applets on your system, divided into - categories. Choosing any applet from this menu will add it to the - <interface>Panel</interface>. - </para> - </sect2> - - <sect2 id="moving-applets"> - <title>Moving Applets In or Between Panels</title> - <para> - It is easy to move applets in a <interface>Panel</interface> or - between two <interface>Panels</interface>. If you have a - three-button mouse, just move the mouse over the applet, depress - the middle mouse button and drag the applet to its new location, - releasing the middle mouse button when you are finished. Note - that you can drag applets within a <interface>Panel</interface> - or between two <interface>Panels</interface> this way. If you - don't have a three-button mouse, just - right-click on the applet and choose - <guimenuitem>Move</guimenuitem>. The cursor will turn into a - cross and the applet will move with your mouse until you press - any mouse button to indicate you are finished moving it. - If, in the course of this movement, it hits - other objects, the behavior depends on the global preferences - you have set for your <interface>Panels</interface> in the - <application>GNOME Control Center</application>: the applet you are - moving can switch places with other objects, "push" all objects - it meets, or "jump" over all other objects without disturbing - them. You can also override the default behavior by holding - <keycap>Shift</keycap> button (for "push" mode), - <keycap>Ctrl</keycap> (for "switched" mode), or - <keycap>Alt</keycap> (for "free" mode, i.e. jumping other other - objects without disturbing them) button while dragging. - </para> - <para> - To change the global Panel preferences, right-click on any applet - or <interface>Panel</interface> and select - <menuchoice> - <guimenu>Panel</guimenu> - <guimenuitem>Global Preferences...</guimenuitem> - </menuchoice>. - The <guilabel>Default movement mode</guilabel> is set under the - <guilabel>Applets</guilabel> tab. - </para> - </sect2> - - <sect2 id="removing-applets"> - <title>Removing Applets from a Panel</title> - <para> - To remove an applet from a <interface>Panel</interface>, - right-click on the applet and select <guimenuitem>Remove from - panel...</guimenuitem>. - </para> - </sect2> - </sect1> - - - <!-- #### Intro | The Right-Click Pop-Up Menu ###### --> - <sect1 id="right-click-pop-up-menu"> - <title>The Right-Click Pop-Up Menu</title> - <para> - Clicking the right mouse button on any applet brings up - a <guimenu>pop-up menu</guimenu>. This - menu always has certain standard menu items in it and - often has additional items which vary depending on the particular - applet. - </para> - <sect2 id="standard-right-click-items"> - <title>Standard Pop-Up Items</title> - <para> - All applets should have the following items in their right-click - <guimenu>pop-up menu</guimenu>: - <variablelist> - <varlistentry> - <term>Remove from panel</term> - <listitem> - <para> - The <guimenuitem>Remove from panel</guimenuitem> menu item - removes the applet from the <interface>Panel</interface>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Move</term> - <listitem> - <para> - After selecting <guimenuitem>Move</guimenuitem>, your mouse - pointer will change appearance (typically to a cross with - arrows in each direction). As you move your mouse, the applet - will move with it. When you have finished moving the applet, - click any mouse button and the applet will anchor in its - current position. Note that applets can be moved between two - <interface>Panels</interface> this way. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Panel</term> - <listitem> - <para> - The <guisubmenu>Panel</guisubmenu> submenu contains various - items and submenus for adding and removing - <interface>Panels</interface> and applets and for changing - the configuration. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>About</term> - <listitem> - <para> - The <guimenuitem>About...</guimenuitem> menu item brings up a - dialogue box containing various information about the applet, - typically including the applet's name, version, author, - copyright, license and desciption. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Help</term> - <listitem> - <para> - The <guimenuitem>Help</guimenuitem> menu item brings up the help - manual for the applet. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - </sect2> - - <sect2 id="applet-properties-dialog"> - <title>The Applet Properties Dialog</title> - <para> - Many applets have customizable properties. These applets will - have a <guimenuitem>Properties...</guimenuitem> menu item in their - right-click <guimenu>pop-up menu</guimenu> which brings up the - <interface>Properties</interface> dialog where you can alter the - appearance or behaviour of the applet. - <figure id="example-props-dialog-fig"> - <title>An Example Applet Properties Dialog</title> - <screenshot> - <screeninfo>An Example Applets Properties Dialog</screeninfo> - <graphic fileref="applet_props_dialog" format="png" - srccredit="muet"> - </graphic> - </screenshot> - </figure> - All <interface>Properties</interface> dialogs have the following - buttons at the bottom of the dialog: - <itemizedlist> - <listitem> - <para> - <guibutton>OK</guibutton> — - Pressing <guibutton>OK</guibutton> will activate any changes - in the properties you have made and close the - <interface>Properties</interface> dialog. - </para> - </listitem> - <listitem> - <para> - <guibutton>Apply</guibutton> — - Pressing <guibutton>Apply</guibutton> at any time will - make your changes active without closing the - <interface>Properties</interface> dialog. This is helpful if - you would like to test the effects of the changes you have - made but may want to continue changing the properties. - </para> - </listitem> - <listitem> - <para> - <guibutton>Close</guibutton> — - Pressing <guibutton>Close</guibutton> will close the - <interface>Properties</interface> dialog. Only changes in the - configuration which were previously applied with the - <guibutton>Apply</guibutton> button will persist. Other - changes will not be made active. - </para> - </listitem> - <listitem> - <para> - <guibutton>Help</guibutton> — - Pressing <guibutton>Help</guibutton> brings up the manual for - the application, opening it to the page describing the - <interface>Properties</interface> dialog. - </para> - </listitem> - </itemizedlist> - </para> - </sect2> - - <sect2 id="common-right-click-items"> - <title>Other Common Pop-Up Items</title> - <para> - Many applets also have one or more of the following items in their - right-click pop-up menu: - <variablelist> - <varlistentry> - <term>Run...</term> - <listitem> - <para> - The <guimenuitem>Run...</guimenuitem> menu item generally - invokes a program which is related to the applet in some way - but which runs in its own window rather than in the - panel. For example: - </para> - <orderedlist> - <listitem> - <para> - The <application>CPU Load</application> applet, which monitors - what programs are running, has a <guimenuitem>Run - gtop...</guimenuitem> menu item. Selecting this menu item - starts <application>GTop</application>, which allows you to - view and control programs which are running. - </para> - </listitem> - <listitem> - <para> - The <application>CD Player</application> applet has a - <guimenuitem>Run gtcd...</guimenuitem> menu item which - starts the GNOME <application>CD Player</application> when - selected, which has more capabilities than the applet. - </para> - </listitem> - </orderedlist> - </listitem> - </varlistentry> - </variablelist> - </para> - </sect2> - </sect1> - - <sect1 id="feedback"> - <title>Feedback</title> - <sect2 id="reporting-bugs"> - <title>Reporting Applet Bugs</title> - <para> - GNOME users are encouraged to report bugs to <ulink type="http" - url="http://bugs.gnome.org">The GNOME Bug Tracking - System</ulink>. The easiest way to submit bugs is to use the - <application>Bug Report Tool</application> program by selecting - <menuchoice> - <guimenu>Main Menu</guimenu> <guisubmenu>Utilities</guisubmenu> - <guimenuitem>Bug Report Tool</guimenuitem> - </menuchoice>. - Be sure to be complete in describing what you did to cause the - bug to surface and, if possible, describe how the developer can - reproduce the the scenario. - </para> - </sect2> - <sect2 id="documentation-feedback"> - <title>Providing Feedback</title> - <para> - GNOME users are welcome to provide suggestions for how - applications and documentation can be improved. Suggestions for - application changes should be submitted using the - <application>Bug Report Tool</application> discussed above. - Suggestions for documentation changes can be emailed directly to - the documentation author (whose email should be included in the - "Authors" section of the document) or by sending an email to - <email>docs@gnome.org</email>. - </para> - </sect2> - <sect2 id="joining-gnome"> - <title>Joining GNOME</title> - <para> - GNOME is a community project, created by hundreds of programmers, - documentation writers, icon design artists, web masters, and - other people, most of whom work on a volunteer basis. New GNOME - contributors are always welcome. To join the GNOME team, visit - these web sites: developers — <ulink type="http" - url="http://developer.gnome.org">The GNOME Development - Site</ulink>, documentation writers — <ulink type="http" - url="http://developer.gnome.org/projects/gdp">The GNOME Documentation - Project</ulink>, icon design artists — <ulink type="http" - url="http://gnome-icons.sourceforge.net/">Gnome Icon Web</ulink>, - general — <ulink type="http" - url="http://developer.gnome.org/helping/">Helping GNOME</ulink>, - or just join the gnome-list email list (see <ulink type="http" - url="http://www.gnome.org/resources/mailing-lists.html">GNOME Mailing - Lists</ulink>) to discuss what you are interested in doing. - </para> - </sect2> - </sect1> - </chapter> - - <!-- ############### Template Applets ##################### --> - <chapter id="template-applets"> - <title>Template Applets</title> - - &TEMPLATE-APPLET - - </chapter> - -</book> - - - - - - - -]]> - </programlisting> - - <programlisting> -<![CDATA[ - - <!-- Please replace everywhere below GNOMEAPPLET with the name of --> - <!-- your applet. Most importantly, all id attributes should start --> - <!-- with the name of your applet - this is necessary to avoid name --> - <!-- conflict among different applets --> - <!-- Please replace YOUR-NAME with your name and YOUR-EMAIL with your email--> - <!-- Please replace HACKER-NAME with the applet author's name and --> - <!-- HACKER-EMAIL with the applet author's email --> - - <!-- You should name your file: GNOMEAPPLET-applet.sgml --> - <!-- Screenshots should be in PNG format and placed in the --> - <!-- same directory as GNOMEAPPLET-applet.sgml --> - - <!-- Applet docs will be merged into <chapter>'s inside a --> - <!-- <book>. Thus, the indentation below (2 spaces before the <sect1>) is --> - <!-- correct.--> - - <!-- Permission is granted to make and distribute verbatim copies of --> - <!-- this manual provided the copyright notice and this permission --> - <!-- notice are preserved on all copies. --> - <!-- --> - <!-- Permission is granted to copy and distribute modified versions of --> - <!-- this manual under the conditions for verbatim copying, provided --> - <!-- that the entire resulting derived work is distributed under the --> - <!-- terms of a permission notice identical to this one. --> - <!-- --> - <!-- Permission is granted to copy and distribute translations of this --> - <!-- manual into another language, under the above conditions for --> - <!-- modified versions, except that this permission notice may be --> - <!-- stated in a translation approved by the Foundation. --> - - <!-- ############### GNOMEAPPLET ############### --> - <sect1 id="GNOMEAPPLET"> - <title>GNOMEAPPLET Applet</title> - - <para> - <application>GNOMEAPPLET</application> applet, shown in <xref - linkend="GNOMEAPPLET-fig">, does this and that. To learn how to - add this applet to a <interface>Panel</interface>, see <xref - linkend="adding-applets">. - </para> - - - <figure id="GNOMEAPPLET-fig"> - <title>GNOMEAPPLET</title> - <screenshot> - <screeninfo>GNOMEAPPLET</screeninfo> - <graphic format="png" fileref="GNOMEAPPLET-fig" srccredit="ME"> - </graphic> - </screenshot> - </figure> - - <sect2 id="GNOMEAPPLET-usage"> - <title>Usage</title> - <para> - This applet does nothing. To use it, just - left-click on it and it will instantly do nothing. - </para> - </sect2> - - <sect2 id="GNOMEAPPLET-right-click"> - <title>Right-Click Pop-Up Menu Items</title> - <para> - In addition to the standard menu items (see <xref - linkend="standard-right-click-items">), the right-click pop-up menu has - the following items: - <itemizedlist> - <listitem> - <para> - <guimenuitem>Properties...</guimenuitem> — This menu - item opens the <interface>Properties</interface> dialog (see - <xref linkend="GNOMEAPPLET-properties">) which allows you to - customize the appearance and behavior of this applet. - </para> - </listitem> - <listitem> - <para> - <guimenuitem>Run Hello World...</guimenuitem> — This - menu item starts the program <application>Hello - World</application>, used to say "hello" to the world. - </para> - </listitem> - </itemizedlist> - </para> - </sect2> - - <sect2 id="GNOMEAPPLET-properties"> - <title>Properties</title> - <para> - You can configure <application>GNOMEAPPLET</application> applet by - right-clicking on the applet and choosing the - <guimenuitem>Properties...</guimenuitem> menu item. This will open the - <interface>Properties</interface> dialog, shown in <xref - linkend="GNOMEAPPLET-properties-fig">. - </para> - <figure id="GNOMEAPPLET-properties-fig"> - <title>Properties Dialog</title> - <screenshot> - <screeninfo>Properties Dialog</screeninfo> - <graphic format="png" fileref="GNOMEAPPLET-properties" srccredit="ME"> - </graphic> - </screenshot> - </figure> - - <para> - To change the color of the applet, click on the - <guibutton>color</guibutton> button. To change other properties, - click on other buttons. - </para> - - <para> - For more information on the <interface>Properties</interface> - dialog, including descriptions of the <guibutton>OK</guibutton>, - <guibutton>Apply</guibutton>, <guibutton>Cancel</guibutton>, and - <guibutton>Help</guibutton> buttons, see <xref - linkend="applet-properties-dialog">. - </para> - </sect2> - - <sect2 id="GNOMEAPPLET-bugs"> - <title> Known Bugs and Limitations</title> - <para> - There are no known bugs in the - <application>GNOMEAPPLET</application> applet. - </para> - </sect2> - - <sect2 id="GNOMEAPPLET-authors"> - <title>Authors</title> - <para> - This applet was writen by HACKER-NAME - <email>HACKER-EMAIL</email>. The documentation for this applet - which you are reading now was written by - YOUR-NAME <email>YOUR-EMAIL</email>. For information on submitting - bug reports and suggestions for improvements, see <xref - linkend="feedback">. - </para> - </sect2> - - </sect1> - - - - - -]]> - - -</programlisting> - </para> - </sect1> - -<!-- ####### Document Templates | Templates 3: Application Help ####### - - <sect1 id="template3"> - <title>Template 2: Application Help</title> - <programlisting> -<![CDATA[(Put sgml here.)]]> </programlisting> - </sect1> - -####### Document Templates | Templates 4: Application Context Sensitive Help ####### - - <sect1 id="template4"> - <title>Template 3: Application Context Sensitive Help</title> - <para> - Context sensitive help is still in development. - </para> - </sect1> - -####### Document Templates | Templates 5: Complete Application: gnome-hello ####### - - <sect1 id="template5"> - <title>Template 4: Complete Application: gnome-hello</title> - <programlisting> -<![CDATA[(Put sgml here.)]]> - </programlisting> - </sect1> - -####### Document Templates | Templates 6: Tutorial ####### - - <sect1 id="template6"> - <title>Template 5: Tutorial</title> - <programlisting> -<![CDATA[(Put sgml here.)]]> - </programlisting> - </sect1>--> - </appendix> - -</article> |