Annotation of embedaddon/libxml2/test/relaxng/docbook_0.xml, revision 1.1
1.1 ! misho 1: <?xml version="1.0"?>
! 2: <!DOCTYPE article [
! 3: <!ENTITY version "1.0.53">
! 4: <!ENTITY mdash "--">
! 5: <!ENTITY hellip "...">
! 6: <!ENTITY copy "©"> <!-- COPYRIGHT SIGN -->
! 7: <!-- replace version above with actual application version number-->
! 8: <!-- Template Version: 1.0.1 (do not remove this line) -->
! 9:
! 10:
! 11:
! 12: <!ENTITY APPLET-TEMPLATE-1x-SHELL SYSTEM
! 13: "templates/applet_template_1-applet.sgml.cdata">
! 14: <!ENTITY APPLET-TEMPLATE-1x SYSTEM
! 15: "templates/applet_template_1.sgml.cdata">
! 16: ]>
! 17:
! 18: <!-- Version: 1.0.1 -->
! 19:
! 20: <article id="index">
! 21: <articleinfo>
! 22:
! 23: <authorgroup>
! 24:
! 25: <author>
! 26: <firstname>David</firstname>
! 27: <surname>Mason</surname>
! 28: <affiliation>
! 29: <orgname>Red Hat, Inc.</orgname>
! 30: <address>
! 31: <email>dcm@redhat.com</email>
! 32: </address>
! 33: </affiliation>
! 34: </author>
! 35:
! 36: <author>
! 37: <firstname>Daniel</firstname>
! 38: <surname>Mueth</surname>
! 39: <affiliation>
! 40: <address>
! 41: <email>d-mueth@uchicago.edu</email>
! 42: </address>
! 43: </affiliation>
! 44: </author>
! 45:
! 46: <author>
! 47: <firstname>Alexander</firstname>
! 48: <surname>Kirillov</surname>
! 49: <affiliation>
! 50: <address>
! 51: <email>kirillov@math.sunysb.edu</email>
! 52: </address>
! 53: </affiliation>
! 54: </author>
! 55:
! 56: </authorgroup>
! 57:
! 58: <releaseinfo>
! 59: This is a pre-release!
! 60: </releaseinfo>
! 61:
! 62: <revhistory>
! 63: <revision>
! 64: <revnumber>
! 65: 0.99
! 66: </revnumber>
! 67: <date>
! 68: 04.10.2000
! 69: </date>
! 70: </revision>
! 71: </revhistory>
! 72:
! 73: <copyright>
! 74: <year>2000</year>
! 75: <holder>Red Hat, Inc., Daniel Mueth, and Alexander Kirillov</holder>
! 76: </copyright>
! 77:
! 78: <legalnotice>
! 79: <para>
! 80: Permission is granted to copy, distribute and/or modify this
! 81: document under the terms of the <citetitle>GNU Free Documentation
! 82: License</citetitle>, Version 1.1 or any later version published
! 83: by the Free Software Foundation with no Invariant Sections, no
! 84: Front-Cover Texts, and no Back-Cover Texts. You may obtain a copy
! 85: of the <citetitle>GNU Free Documentation License</citetitle> from
! 86: the Free Software Foundation by visiting <ulink type="http"
! 87: url="http://www.fsf.org">their Web site</ulink> or by writing to:
! 88: Free Software Foundation, Inc., 59 Temple Place - Suite 330,
! 89: Boston, MA 02111-1307, USA.
! 90: </para>
! 91: <para>
! 92: Many of the names used by companies to distinguish their products and
! 93: services are claimed as trademarks. Where those names appear in any
! 94: GNOME documentation, and those trademarks are made aware to the members
! 95: of the GNOME Documentation Project, the names have been printed in caps
! 96: or initial caps.
! 97: </para>
! 98: </legalnotice>
! 99:
! 100: <title>The GNOME Handbook of Writing Software Documentation</title>
! 101:
! 102: </articleinfo>
! 103:
! 104: <!-- ################# Introduction ############### -->
! 105:
! 106: <sect1 id="intro">
! 107: <title>Introduction</title>
! 108:
! 109: <!-- ####### Introduction | The GNOME Documentation Project ####### -->
! 110:
! 111: <sect2 id="gdp">
! 112: <title>The GNOME Documentation Project</title>
! 113:
! 114: <sect3 id="goals">
! 115: <title>Goals</title>
! 116: <para>
! 117: The GNOME Documentation Project (GDP) aims to provide GNOME
! 118: and GNOME applications with a complete, intuitive, and clear
! 119: documentation system. At the center of the GDP is the
! 120: <application>GNOME Help Browser</application>, which
! 121: presents a unified interface to GNOME-specific documentation
! 122: as well as other Linux documentation such as man pages and
! 123: texinfo documents. The GNOME Help System provides a
! 124: comprehensive view of documentation on a machine by
! 125: dynamically assembling the documentation of GNOME
! 126: applications and components which are installed. The GDP is
! 127: responsible for writing numerous GNOME-related documents,
! 128: both for developers and for users. Developer documentation
! 129: includes <ulink url="http://developer.gnome.org/doc/API/"
! 130: type="http">APIs for the GNOME libraries</ulink>, <ulink
! 131: url="http://developer.gnome.org/doc/whitepapers/"
! 132: type="http"><citetitle>GNOME White
! 133: Papers</citetitle></ulink>, GNOME developer <ulink
! 134: url="http://developer.gnome.org/doc/tutorials/"
! 135: type="http">tutorials</ulink>, the <ulink
! 136: url="http://developer.gnome.org/doc/FAQ/"
! 137: type="http"><citetitle>GNOME Developer
! 138: FAQ</citetitle></ulink>, the <ulink
! 139: url="http://developer.gnome.org" type="http">GNOME
! 140: Developer's Website</ulink>, and <citetitle>GNOME
! 141: Handbook</citetitle>'s, such as the one you are reading.
! 142: User documentation include the <ulink
! 143: url="http://www.gnome.org/learn/"
! 144: type="http"><citetitle>GNOME User's
! 145: Guide</citetitle></ulink>, the <ulink
! 146: url="http://www.gnome.org/learn/"
! 147: type="http"><citetitle>GNOME FAQ</citetitle></ulink>, and
! 148: GNOME application documentation. Most GNOME applications
! 149: have their own manual in addition to context sensitive help.
! 150: </para>
! 151: </sect3>
! 152:
! 153: <sect3 id="joining">
! 154: <title>Joining the GDP</title>
! 155: <para>
! 156: Documenting GNOME and all the numerous GNOME applications is
! 157: a very large project. The GDP is always looking for people
! 158: to help write, update, and edit documentation. If you are
! 159: interested in joining the GDP team, you should join the
! 160: <ulink url="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/">
! 161: <citetitle>gnome-doc-list mailing list</citetitle> </ulink>.
! 162: Read <xref linkend="gettingstarted" />, for help selecting a
! 163: project to work on. Feel free to introduce yourself on the
! 164: gnome-doc-list mailing list and indicate which project you
! 165: intend to work on, or else ask for suggestions of important
! 166: documents which need work done. You may also want to join the
! 167: #docs IRC channel on irc.gnome.org to meet other GDP members
! 168: and discuss any questions you may have. For a list of GDP
! 169: projects and members, see the
! 170: <ulink url="http://developer.gnome.org/projects/gdp">
! 171: <citetitle>GDP Website</citetitle></ulink>.
! 172: </para>
! 173: </sect3>
! 174:
! 175: <sect3 id="collaborating">
! 176: <title>Collaborating with the GDP</title>
! 177: <para>
! 178: GNOME developers, packagers, and translators may not be
! 179: writing GNOME documentation but will want to understand how
! 180: the GNOME documentation system works and will need to
! 181: collaborate with GDP members. This document should help to
! 182: outline the structure of how the GNOME documentation system
! 183: works. Developers who do not write the documentation for
! 184: their applications are encouraged to find a GDP member to
! 185: write the documentation. This is best done by sending an
! 186: email to the <ulink
! 187: url="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/">
! 188: <citetitle>gnome-doc-list mailing list</citetitle> </ulink>
! 189: describing the application, where it can be downloaded from,
! 190: and that the developer(s) would like a GDP member to write
! 191: documentation for the application. The #docs IRC channel on
! 192: irc.gnome.org is another option for contacting GDP members.
! 193: </para>
! 194: </sect3>
! 195: </sect2>
! 196:
! 197: <!-- ####### Introduction | Notation and Conventions ####### -->
! 198:
! 199: <sect2 id="notation">
! 200: <title>Notation and Conventions</title>
! 201: <para>
! 202: This Handbook uses the following notation:
! 203: <informaltable frame="none">
! 204: <tgroup cols="2">
! 205: <tbody>
! 206: <row>
! 207: <entry>
! 208: <filename class="directory">/usr/bin</filename>
! 209: </entry>
! 210: <entry>
! 211: Directory
! 212: </entry>
! 213: </row>
! 214: <row>
! 215: <entry>
! 216: <filename>foo.sgml</filename>
! 217: </entry>
! 218: <entry>
! 219: Filename
! 220: </entry>
! 221: </row>
! 222: <row>
! 223: <entry>
! 224: <command>command</command>
! 225: </entry>
! 226: <entry>
! 227: Command or text that would be typed.
! 228: </entry>
! 229: </row>
! 230: <row>
! 231: <entry>
! 232: <command><replaceable>replaceable</replaceable></command>
! 233: </entry>
! 234: <entry>
! 235: "Variable" text that can be replaced.
! 236: </entry>
! 237: </row>
! 238: <row>
! 239: <entry>
! 240: <literal>Program or Doc Code</literal>
! 241: </entry>
! 242: <entry>Program or document code</entry>
! 243: </row>
! 244: </tbody>
! 245: </tgroup>
! 246: </informaltable>
! 247: </para>
! 248: </sect2>
! 249:
! 250: <!-- ####### Introduction | About This Handbook ####### -->
! 251:
! 252: <sect2 id="about">
! 253: <title>About This Handbook</title>
! 254: <para>
! 255: This Handbook is a guide for both writing documentation for
! 256: GNOME components and applications and for properly binding and
! 257: packaging documentation into GNOME applications.
! 258: </para>
! 259: <para>
! 260: This Handbook, like all GNOME documentation, was written in
! 261: DocBook(SGML) and is available in several formats including
! 262: SGML, HTML, PostScript, and PDF. For the latest version, see
! 263: <ulink
! 264: url="http://developer.gnome.org/projects/gdp/handbook.html">
! 265: <citetitle>Getting The GNOME Handbook of Writing Software
! 266: Documentation</citetitle> </ulink>. Alternately, one may
! 267: download it anonymously from GNOME CVS under <filename
! 268: class="directory">gnome-docu/gdp</filename>.
! 269: </para>
! 270: </sect2>
! 271: </sect1>
! 272:
! 273: <!-- ################# Getting Started ############### -->
! 274:
! 275: <sect1 id="gettingstarted">
! 276: <title>Getting Started Writing GNOME Documentation</title>
! 277:
! 278: <!--####### Getting Started | Selecting A Document ####### -->
! 279:
! 280: <sect2 id="selecting">
! 281: <title>Selecting A Document</title>
! 282:
! 283: <sect3 id="know">
! 284: <title>Document Something You Know</title>
! 285: <para>
! 286: The most frequently asked question of new contributors who
! 287: join the GDP is "which document should I start
! 288: with?". Because most people involved are volunteers, we do
! 289: not <emphasis>assign</emphasis> projects and applications to
! 290: write documents for. The first step is all yours - you must
! 291: decide what about GNOME interests you most and find out if
! 292: it has complete documents or not.
! 293: </para>
! 294: <para>
! 295: It is also important to spend some time with GNOME to make
! 296: sure you are familiar enough with it to be
! 297: <emphasis>authoritative</emphasis> in your writing. The
! 298: best way to do this is to just sit down and play with GNOME
! 299: as much as possible before starting to write.
! 300: </para>
! 301: <para>
! 302: The easiest way to get started is to improve existing
! 303: documentation. If you notice some inaccuracies or omissions
! 304: in the documentation, or you think that you can explain the
! 305: material more clearly, just send your suggestions to the
! 306: author of the original documentation or to the GNOME
! 307: documentation project at <email>docs@gnome.org</email>.
! 308: </para>
! 309: </sect3>
! 310:
! 311: <sect3 id="doctable">
! 312: <title>The GNOME Documentation Status Table</title>
! 313: <para>
! 314: The <citetitle>GDP Documentation Status Table</citetitle>
! 315: (<citetitle>DocTable</citetitle>) (<ulink
! 316: url="http://www.gnome.org/gdp/doctable/"
! 317: type="http">http://www.gnome.org/gdp/doctable/</ulink>) is a
! 318: web page which tracks the status of all the various
! 319: documentation components of GNOME. These components include
! 320: application documentation, internal GNOME component
! 321: documentation, user documentation, and developer
! 322: documentation. For each documentation item, it tracks the
! 323: current status of the documentation, who is working on the
! 324: particular document, where the documentation can be found,
! 325: and provides a forum for the discussion of each item.
! 326: </para>
! 327: <para>
! 328: You should use the <citetitle>DocTable</citetitle> to help
! 329: you select a documentation item which needs work done. Once
! 330: you have selected an item to work on, please register
! 331: yourself as an author so that other authors do not duplicate
! 332: your work and may contact you to help or offer suggestions.
! 333: Also be sure to keep the status icons up-to-date so that
! 334: the GDP team can easily identify which items need additional
! 335: help. The <citetitle>DocTable</citetitle> also allows
! 336: people to make announcements and suggestions and to discuss
! 337: issues in the comments section.
! 338: </para>
! 339: <note>
! 340: <title>Note</title>
! 341: <para>
! 342: Note that the information in the
! 343: <citetitle>DocTable</citetitle> may not always be up-to-date
! 344: or accurate. When you assign yourself to documenting an
! 345: application, make sure you find out the latest status of
! 346: documentation by contacting the application author.
! 347: </para>
! 348: </note>
! 349: </sect3>
! 350: </sect2>
! 351:
! 352: <!-- ####### Getting Started | Installing And Using DocBook ####### -->
! 353:
! 354: <sect2 id="docbook">
! 355: <title>Installing and Using DocBook</title>
! 356: <para>
! 357: All documentation for the GNOME project is written in SGML
! 358: using the DocBook DTD. There are many advantages to using
! 359: this for documentation, not least of which is the single
! 360: source nature of SGML. To contribute to the GDP you should
! 361: learn to use DocBook.
! 362: </para>
! 363: <note>
! 364: <title>NOTE</title>
! 365: <para>
! 366: To get started writing for the GDP you do not need to rush
! 367: out and learn DocBook - if you feel it is too much to handle
! 368: for now, you can submit plain ASCII text to the <ulink
! 369: url="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/">
! 370: <citetitle>gnome-doc-list mailing list</citetitle>
! 371: </ulink>and a volunteer will mark it up for you. Seeing your
! 372: document marked up will also be a great way for you to start
! 373: learning DocBook.
! 374: </para>
! 375: </note>
! 376: <sect3 id="installingdocbook">
! 377: <title>Installing DocBook</title>
! 378: <para>
! 379: Download and install the following <ulink
! 380: url="ftp://sourceware.cygnus.com:/pub/docbook-tools/"
! 381: type="ftp">DocBook Tools packages</ulink>: jade, docbook,
! 382: jadetex, sgml-common, and stylesheets. (RPM users should note
! 383: that jade is platform dependent (eg. i386), while the other packages
! 384: are in the <filename class="directory">noarch</filename>
! 385: directory.) You can find more
! 386: information on DocBook Tools <ulink url="
! 387: http://sourceware.cygnus.com/docbook-tools/"
! 388: type="http">here</ulink>.
! 389: </para>
! 390: <para>
! 391: If you are an <application>Emacs</application> user you may
! 392: want to grab the psgml package as well. This is a major mode
! 393: for editing sgml files in <application>Emacs</application>.
! 394: </para>
! 395: </sect3>
! 396:
! 397: <sect3 id="gdpstylesheets">
! 398: <title>GDP Stylesheets</title>
! 399: <para>
! 400: The GDP uses its own DocBook stylesheets. To use the GDP
! 401: stylesheets, you should download the file
! 402: <filename>gdp-both.dsl</filename> from the <filename
! 403: class="directory">gnome-docu/gdp/dsssl</filename> module in
! 404: CVS (or from <ulink
! 405: url="http://developer.gnome.org/projects/gdp/stylesheets.html">
! 406: GDP Custom DSSSL Stylesheet</ulink>)and copy it
! 407: <!-- into <filename
! 408: class="directory">/usr/lib/sgml/stylesheets</filename>. You
! 409: will need to point DocBook Tools to this stylesheet with the
! 410: <command><option>-d</option></command> option:
! 411: <command>db2html -d /usr/lib/sgml/stylesheets/gdp-both.dsl
! 412: <replaceable>foo.sgml</replaceable></command>. (Creating an
! 413: alias to include this option and path is convenient.)
! 414: Alternately, you could overwrite
! 415: <filename>/usr/lib/sgml/stylesheets/cygnus-both.dsl</filename>
! 416: with <filename>gdp-both.dsl</filename>.
! 417: -->
! 418: over the file
! 419: <filename>/usr/lib/sgml/stylesheets/cygnus-both.dsl</filename>.
! 420: Alternately, you can download and install the
! 421: <ulink url="http://people.redhat.com/dcm/software.html"
! 422: type="http">gnome-doc-tools package</ulink> which will set
! 423: up the stylesheets as well as the DTD discussed below.
! 424: </para>
! 425:
! 426: <!-- <note>
! 427: <para>
! 428: The current version of the DocBook Tools command
! 429: <command>db2ps</command> does not have a
! 430: <command><option>-d</option></command> option. In order to
! 431: create PostScript output, you must overwrite
! 432: <filename>/usr/lib/sgml/stylesheets/cygnus-both.dsl</filename>
! 433: with <filename>gdp-both.dsl</filename>.
! 434: </para>
! 435: </note>
! 436: -->
! 437: </sect3>
! 438:
! 439: <sect3 id="gdpdtd">
! 440: <title>GDP DTD (PNG Image Support)</title>
! 441: <para>
! 442: Due to some license issues involved with the creation of
! 443: gifs, the GNOME Documentation Project has decided to use the
! 444: PNG image format for all images in GNOME documentation. You
! 445: can read more about the issues involved with gifs at <ulink
! 446: url="http://www.gnu.org/philosophy/gif.html"
! 447: type="http">http://www.gnu.org/philosophy/gif.html</ulink>.
! 448: </para>
! 449: <para>
! 450: The current DocBook DTD(3.1) does not include support for
! 451: embedding PNG images in your documents. Since the GDP uses
! 452: many screenshots in its documentation, we use our own
! 453: variation on the DocBook DTD which has PNG image support.
! 454: We encourage everybody to use this DTD instead of the
! 455: default DocBook DTD since your source document header and
! 456: your output document appearance subtly vary between the two
! 457: DTD's. To install the GDP custom DTD with PNG image support
! 458: by hand:
! 459: </para>
! 460: <itemizedlist mark="opencircle">
! 461: <listitem>
! 462: <para>
! 463: Download <ulink
! 464: url="http://www.labs.redhat.com/png/png-support.html">the
! 465: GDP DocBook DTD for PNG support</ulink> and install it
! 466: where you keep your DTD's. (On Red Hat use <filename
! 467: class="directory">/usr/lib/sgml/</filename>.) Note that
! 468: the 3.0 DTD is missing support for the
! 469: <sgmltag><legalnotice></sgmltag> tag, so it is
! 470: recommended that you use version 3.1
! 471: </para>
! 472: </listitem>
! 473: <listitem override="bullet">
! 474: <para>
! 475: Add the new DTD to your SGML CATALOG file. The location
! 476: of your SGML CATALOG file may vary depending upon your
! 477: distribution. (On Red Hat it is usually in
! 478: /usr/lib/sgml/CATALOG.) Add the following line to this
! 479: file:
! 480: <programlisting>
! 481: PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.0//EN" "png-support-3.0.dtd"
! 482: </programlisting>
! 483: If you are using the 3.1 DTD, use:
! 484: <programlisting>
! 485: PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN" "png-support-3.1.dtd"
! 486: </programlisting>
! 487: </para>
! 488: </listitem>
! 489: </itemizedlist>
! 490: <para>
! 491: Alternately, you can download and install the
! 492: <ulink url="http://people.redhat.com/dcm/software.html"
! 493: type="http">gnome-doc-tools package</ulink> which will set
! 494: up the custom stylesheets and DTD for you.
! 495: </para>
! 496: <para>
! 497: To include PNG files in your documents, you will need to
! 498: indicate that you are using this special DTD. To do
! 499: this, use the following headers:
! 500: </para>
! 501: <para>
! 502: Articles:
! 503: <programlisting>
! 504: <![CDATA[<!DOCTYPE Article PUBLIC "-//GNOME//DTD DocBook PNG Variant
! 505: V1.1//EN"[]>]]>
! 506: </programlisting>
! 507: </para>
! 508: <para>
! 509: Books:
! 510: <programlisting>
! 511: <![CDATA[<!DOCTYPE Book PUBLIC "-//GNOME//DTD DocBook PNG Variant
! 512: V1.1//EN"[]>]]>
! 513: </programlisting>
! 514: </para>
! 515:
! 516: </sect3>
! 517:
! 518: <sect3 id="editors">
! 519: <title>Editors</title>
! 520: <para>
! 521: There are many editors on Linux and UNIX systems available
! 522: to you. Which editor you use to work on the sgml documents
! 523: is completely up to you, as long as the editor is able to
! 524: preserve sgml and produce the source in a format that is
! 525: readable by everyone.
! 526: </para>
! 527: <para>
! 528: Probably the two most popular editors available are
! 529: <application>Emacs</application> and
! 530: <application>vi</application>. These and other editors are
! 531: used regularly by members of the GDP. Emacs has a major
! 532: mode, psgml, for editing sgml files which can save you time
! 533: and effort in adding and closing tags. You will find the
! 534: psgml package in DocBook Tools, which is the standard set of
! 535: tools for the GDP. You may find out more about DocBook Tools
! 536: in <xref linkend="installingdocbook" />.
! 537: </para>
! 538: </sect3>
! 539:
! 540: <sect3 id="make-output">
! 541: <title>Creating Something Useful with your Docs</title>
! 542: <para>
! 543: The tools available in DocBook Tools allow you to convert
! 544: your sgml document to many different formats including html
! 545: and Postscript. The primary tool used to do the conversion
! 546: is an application called <application>Jade</application>. In
! 547: most cases you will not have to work directly with
! 548: <application>Jade</application>; Instead, you will use the
! 549: scripts provided by DocBook Tools.
! 550: </para>
! 551: <para>
! 552: To preview your DocBook document, it is easiest to convert
! 553: it to <filename>html</filename>. If you have installed the
! 554: DocBook tools described above, all you have to do is to run
! 555: the command <prompt>$</prompt><command>db2html
! 556: mydocument.sgml</command>. If there are no sgml syntax
! 557: errors, this will create a directory <filename
! 558: class="directory">mydocument</filename> and place the
! 559: resulting html files in it. The title page of the document
! 560: will typically be
! 561: <filename>mydocument/index.html</filename>. If you have
! 562: screenshots in your document, you will have to copy these
! 563: files into the <filename
! 564: class="directory">mydocument</filename> directory by
! 565: hand. You can use any web browser to view your document.
! 566: Note that every time you run <command>db2html</command>, it
! 567: creates the <filename
! 568: class="directory">mydocument</filename> directory over, so
! 569: you will have to copy the screenshots over each time.
! 570: </para>
! 571: <para>
! 572: You can also convert your document to PostScript by running
! 573: the command <prompt>$</prompt><command>db2ps
! 574: mydocument.sgml</command>, after which you can print out or
! 575: view the resulting .ps file.
! 576: </para>
! 577: <note>
! 578: <title>NOTE</title>
! 579: <para>
! 580: The html files you get will not look quite the same as the
! 581: documentation distributed with GNOME unless you have the
! 582: custom stylesheets installed on your machine. DocBook
! 583: Tools' default stylesheets will produce a different look
! 584: to your docs. You can read more about the GDP stylesheets
! 585: in <xref linkend="gdpstylesheets" />.
! 586: </para>
! 587: </note>
! 588: </sect3>
! 589:
! 590: <sect3 id="jadeimages">
! 591: <title>Images in DocBook Tools</title>
! 592: <para>
! 593: If your document uses images you will need to take note of a
! 594: few things that should take place in order for you to make
! 595: use of those images in your output.
! 596: </para>
! 597: <para>
! 598: The DocBook Tools scripts and applications are smart enough
! 599: to know that when you are creating html you will be using
! 600: PNG files and when you are creating Postscript you will be
! 601: using EPS files (you must use EPS with Postscript).
! 602: </para>
! 603: <para>
! 604: Thus, you should never explicitly
! 605: include the extension of the image file, since DocBook
! 606: Tools will automatically insert it for you. For example:
! 607: </para>
! 608: <programlisting>
! 609: <![CDATA[
! 610: <figure>
! 611: <title>My Image</title>
! 612: <screenshot>
! 613: <screeninfo>Sample GNOME Display</screeninfo>
! 614: <graphic format="png" fileref="myfile" srccredit="me">
! 615: </graphic>
! 616: </screenshot>
! 617: </figure>
! 618: ]]> </programlisting>
! 619: <para>
! 620: You will notice in this example that the file
! 621: <filename>myfile.png</filename> was referred to as simply
! 622: <filename>myfile</filename>. Now when you run
! 623: <command>db2html</command> to create an html file, it will
! 624: automatically look for <filename>myfile.png</filename> in
! 625: the directory.
! 626: </para>
! 627: <para>
! 628: If you want to create PostScript ouput, you will need to create an
! 629: EPS version of your image file to be displayed in the
! 630: PostScript file. There is a simple script available which
! 631: allows you to change a PNG image into an EPS file
! 632: easily. You can download this file - img2eps - from <ulink
! 633: url="http://people.redhat.com/dcm/sgml.html"
! 634: type="html">http://people.redhat.com/dcm/sgml.html</ulink>
! 635: (look for the img2eps section). Note that this script is
! 636: included in the gnome-doc-tools package, so if you are using
! 637: this package, you should already have
! 638: <command>img2eps</command> on you system.
! 639: </para>
! 640: </sect3>
! 641:
! 642: <sect3 id="moredocbookinfo">
! 643: <title>Learning DocBook</title>
! 644: <para>
! 645: There are many resources available to help you learn DocBook.
! 646: The following resources on the web are useful for learning
! 647: DocBook:
! 648: </para>
! 649: <itemizedlist mark="bullet">
! 650: <listitem>
! 651: <para>
! 652: <ulink url="http://www.docbook.org"
! 653: type="http">http://www.docbook.org</ulink> - Norman
! 654: Walsh's <citetitle>DocBook: The Definitive
! 655: Guide</citetitle>. Online O'Reilly book on using
! 656: DocBook. Contains an excellent element reference. May be
! 657: too formal for a beginner.
! 658: </para>
! 659: </listitem>
! 660: <listitem>
! 661: <para>
! 662: <ulink
! 663: url="http://www.oswg.org/oswg-nightly/oswg/en_US.ISO_8859-1/articles/DocBook-Intro/docbook-intro/index.html"
! 664: type="http">A Practical Introduction to DocBook</ulink>
! 665: - The Open Source Writers Group's introduction to using
! 666: DocBook. This is an excellent HOW-TO type article on
! 667: getting started.
! 668: </para>
! 669: </listitem>
! 670: <listitem>
! 671: <para>
! 672: <ulink
! 673: url="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro/docbook-intro.html"
! 674: type="http">Getting Going with DocBook: Notes for
! 675: Hackers</ulink> - Mark Galassi's introduction to DocBook
! 676: for hackers. This has to be one of the first
! 677: introductions to DocBook ever - still as good as it ever
! 678: was.
! 679: </para>
! 680: </listitem>
! 681: <listitem>
! 682: <para>
! 683: <ulink type="http" url="http://www.freebsd.org/tutorials/docproj-primer/">
! 684: FreeBSD Documentation Project Primer for New
! 685: Contributors</ulink> - FreeBSD documentation project
! 686: primer. Chapter 4.2 provides a very good introduction to
! 687: writing documentation using DocBook. Note that it also
! 688: describes some custom extensions of DocBook;
! 689: fortunately, they are clearly marked as such.
! 690: </para>
! 691: </listitem>
! 692: </itemizedlist>
! 693: <para>
! 694: Norman Walsh's book is also available in print.
! 695: </para>
! 696: <para>
! 697: The following sections of this document are designed to help
! 698: documentation authors write correct and consistent DocBook:
! 699: </para>
! 700: <itemizedlist mark="bullet">
! 701: <listitem>
! 702: <para>
! 703: <xref linkend="docbookbasics" /> - Descriptions of
! 704: commonly used DocBook tags.
! 705: </para>
! 706: </listitem>
! 707: </itemizedlist>
! 708: <para>
! 709: You may also discuss specific DocBook questions with GDP
! 710: members on the #docs IRC channel at irc.gnome.org and on the
! 711: gnome-doc-list mailing list.
! 712: </para>
! 713: </sect3>
! 714: </sect2>
! 715:
! 716: <!-- ####### Getting Started | GDP Document Examples ####### -->
! 717: <!--
! 718: <sect2 id="examples">
! 719: <title>GDP Document Examples</title>
! 720: <para>
! 721: Examples of various types of GNOME documents are found in
! 722: <xref linkend="examples" />. There is also an example GNOME
! 723: application with documentation called
! 724: <application>gnome-hello</application> in GNOME cvs.
! 725: </para>
! 726: </sect2>
! 727: -->
! 728: <!-- ####### Getting Started | GDP Document Templates ####### -->
! 729:
! 730: <sect2 id="gdptemplates">
! 731: <title>GDP Document Templates</title>
! 732: <para>
! 733: Templates for various types of GNOME documents are found in
! 734: <xref linkend="templates" />. They are kept in CVS in
! 735: gnome-docu/gdp/templates. The easiest source to get them from
! 736: is probably the <ulink
! 737: url="http://developer.gnome.org/projects/gdp/templates.html"
! 738: type="http">GDP
! 739: Document Templates</ulink> web page, which is typically kept
! 740: completely up-to-date with CVS and has a basic description of
! 741: each file from CVS.
! 742: </para>
! 743: </sect2>
! 744:
! 745: <!-- ####### Getting Started | Screenshots ####### -->
! 746:
! 747: <sect2 id="screenshots">
! 748: <title>Screenshots</title>
! 749: <para>
! 750: Most GNOME documents will have screenshots of the particular
! 751: applet, application, GNOME component, or widget being
! 752: discussed. As discussed above in <xref linkend="gdpdtd"/> you
! 753: will need to install the special GDP DocBook DTD which
! 754: supports PNG images, the format used for all images in GNOME
! 755: documentation. For the basic DocBook structure used to insert
! 756: images in a document, see <xref linkend="jadeimages"/> above.
! 757: </para>
! 758: <sect3 id="screenshotappearance">
! 759: <title>Screenshot Appearance</title>
! 760: <para>
! 761: For all screenshots of windows that typically have border
! 762: decorations (e.g. applications and dialogs, but not applets
! 763: in a <interface>panel</interface>), GDP standards dictate
! 764: the appearance of the window. (This is to minimize possible
! 765: confusion to the reader, improve the appearance of GNOME
! 766: documents, and guarantee the screenshot is readable when
! 767: printed.) All screenshots should be taken with the SawFish
! 768: (formerly known as Sawmill) window manager using the
! 769: MicroGui theme and Helvetica 12pt font. (A different window
! 770: manager can be used provided the MicroGui theme is available
! 771: for this window manager and the appearance is identical to
! 772: that when using the SawFish window manager.) The default
! 773: GTK+ theme(gtk) and font (Helvetica 12 pt) should be used
! 774: for all screenshots. If you are unable to provide
! 775: screenshots in this form, you should create screenshots as
! 776: you wish them to appear and send them to the
! 777: <ulink url="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/">
! 778: <citetitle>gnome-doc-list mailing list</citetitle> </ulink>
! 779: requesting a GDP member reproduce these screenshots in the
! 780: correct format and email them to you.
! 781: </para>
! 782: </sect3>
! 783: <sect3 id="screenshottools">
! 784: <title>Screenshot Tools</title>
! 785: <para>
! 786: There are many tools for taking screenshots in
! 787: GNOME/Linux. Perhaps the most convenient is the
! 788: <application>Screen-Shooter Applet</application>. Just click
! 789: on the window icon in the applet and then on the window you
! 790: would like to take a screenshot of. (Note that
! 791: at the time of this writing, PNG images taken by
! 792: screenshooter do not appear properly in
! 793: <application>Netscape</application> or the
! 794: <application>GNOME Help Browser</application>. You
! 795: should save your screenshot as a GIF and
! 796: then use <command>convert filename.gif
! 797: filename.png</command>.) For applets
! 798: in a <interface>Panel</interface>,
! 799: <application>xv</application> can be used to crop the
! 800: screenshot to only include the relevant portion of the
! 801: <interface>Panel</interface>. Note that
! 802: <application>xv</application> and
! 803: <application>gimp</application> can both be used for taking
! 804: screenshots, cropping screenshots, and converting image
! 805: formats.
! 806: </para>
! 807: </sect3>
! 808: <sect3 id="screenshotfiles">
! 809: <title>Screenshot Files</title>
! 810: <para>
! 811: Screenshots should be kept in the main documentation
! 812: directory with your SGML file for applets, or should be
! 813: kept in a directory called "figs" for application and other
! 814: documentation. After you use <command>db2html</command> to
! 815: convert your SGML file to HTML (see <xref
! 816: linkend="make-output"/>), you will need to copy your
! 817: screenshots (either the individual PNG files for applet
! 818: documentation, or the whole "figs" directory for other
! 819: documentation) into the newly created HTML directory. Note
! 820: that every time you use <command>db2html</command> the HTML
! 821: directory is erased and rewritten, so do not store your only
! 822: copy of the screenshots in that directory. If you wish to
! 823: create PostScript or PDF output, you will need to manually
! 824: convert the PNG images to EPS as described in <xref
! 825: linkend="jadeimages"/>, but will not need to copy these
! 826: images from their default location, as they are included
! 827: directly into the output(PostScript of PDF) file.
! 828: </para>
! 829: </sect3>
! 830: </sect2>
! 831:
! 832:
! 833: <!-- ####### Getting Started | Application Bugs ####### -->
! 834:
! 835: <sect2 id="applicationbugs">
! 836: <title>Application Bugs</title>
! 837: <para>
! 838: Documentation authors tend to investigate and test applets and
! 839: applications more thoroughly than most
! 840: users. Often documentation authors will discover one or
! 841: more bugs in the software. These bugs vary from small ones,
! 842: such as mis-spelled words or missing
! 843: <interface>About</interface> dialogs in the menu, to large
! 844: ones which cause the applet to crash. As all users, you
! 845: should be sure to report these bugs so that application
! 846: developers know of them and can fix them. The easiest way to
! 847: submit a bug report is by using the <application>Bug
! 848: Buddy</application> applet which is part of the gnome-applets
! 849: package.
! 850: </para>
! 851: </sect2>
! 852:
! 853:
! 854: <!-- ####### Getting Started | Using CVS ####### -->
! 855:
! 856: <sect2 id="cvs">
! 857: <title>Using CVS</title>
! 858: <para>
! 859: CVS (Concurrent Versions System) is a tool that allows
! 860: multiple developers to concurrently work on a set of
! 861: documents, keeping track of the modifications made by each
! 862: person. The files are stored on a server and each developer
! 863: checks files out, modifies them, and then checks in their
! 864: modified version of the files. Many GNOME programs and
! 865: documents are stored in CVS. The GNOME CVS server allows
! 866: users to anonymously check out CVS files. Most GDP members
! 867: will need to use anonymous CVS to download the most up-to-date
! 868: version of documentation or programs. Modified documents will
! 869: typically be emailed to the the application developer. Core
! 870: GDP members may also be granted login CVS privileges so they
! 871: may commit modified files directly to CVS.
! 872: </para>
! 873:
! 874: <sect3 id="anonymouscvs">
! 875: <title>Anonymous CVS</title>
! 876: <para>
! 877: To anonymously check out documents from CVS, you must first
! 878: log in. From the bash shell, you should set your CVSROOT
! 879: shell variable with <command> export
! 880: CVSROOT=':pserver:anonymous@anoncvs.gnome.org:/cvs/gnome'</command>
! 881: and then login with <command>cvs login</command>(there is no
! 882: password, just hit return). As an example, we will use the
! 883: "gnome-docu/gdp" module which contains this and several
! 884: other documents. To check these documents out for the first
! 885: time, type <command>cvs -z3 checkout
! 886: gnome-docu/gdp</command>. After you have this document
! 887: checked out and you would like to download any updates on
! 888: the CVS server, use <command>cvs -z3 update -Pd</command>.
! 889: </para>
! 890: </sect3>
! 891:
! 892: <sect3 id="logincvs">
! 893: <title>Login CVS</title> <para> If you have been given a
! 894: login for the GNOME CVS server, you may commit your file
! 895: modifications to CVS. Be sure to read the following section
! 896: on CVS etiquette before making any commits to CVS. To log in
! 897: to the CVS server as user
! 898: <command><replaceable>username</replaceable></command> with a
! 899: password, you must first set your CVSROOT shell variable with
! 900: <command> export
! 901: CVSROOT=':pserver:<replaceable>username</replaceable>@cvs.gnome.org:/cvs/gnome'</command>.
! 902: Log in with <command>cvs login</command> and enter your
! 903: password. You may check out and update modules as described
! 904: above for anonymous CVS access. As a login CVS user, you may
! 905: also check modified versions of a file into the CVS server.
! 906: To check
! 907: <command><replaceable>filename</replaceable></command> into
! 908: the CVS server, type <command>cvs -z3 commit
! 909: <replaceable>filename</replaceable></command>. You will be
! 910: given a vi editor window to type in a brief log entry,
! 911: summarizing your changes. The default editor can be changed
! 912: using the <varname>EDITOR</varname> environment variable or
! 913: with the <command><option>-e</option></command> option. You
! 914: may also check in any modifications to files in the working
! 915: directory and subdirectories using <command>cvs -z3
! 916: commit</command>. To
! 917: add a new file to the CVS server, use <command>cvs -z3 add
! 918: <replaceable>filename</replaceable></command>, followed by the
! 919: commit command.
! 920: </para>
! 921: </sect3>
! 922:
! 923: <sect3 id="cvsetiquette">
! 924: <title>CVS Etiquette</title>
! 925: <para>
! 926: Because files in CVS are typically used and modified by
! 927: multiple developers and documentation authors, users should
! 928: exercise a few simple practices out of courtesy towards the
! 929: other CVS users and the project leader. First, you should
! 930: not make CVS commits to a package without first discussing
! 931: your plans with the project leader. This way, the project
! 932: leader knows who is modifying the files and generally, what
! 933: sort of changes/development is being done. Also, whenever a
! 934: CVS user commits a file to CVS, they should make an entry in
! 935: the CVS log and in the <filename>ChangeLog</filename> so
! 936: that other users know who is making modifications and what
! 937: is being modified. When modifying files created by others,
! 938: you should follow the indentation scheme used by the initial
! 939: author.
! 940: </para>
! 941: </sect3>
! 942: </sect2>
! 943: </sect1>
! 944:
! 945: <!-- ################# The GNOME Documentation System###############
! 946: -->
! 947:
! 948: <sect1 id="gnomedocsystem">
! 949: <title>The GNOME Documentation System</title>
! 950:
! 951: <!-- ####### The GNOME Documentation System | The GNOME Help Browser
! 952: ####### -->
! 953:
! 954: <sect2 id="gnomehelpbrowser">
! 955: <title>The GNOME Help Browser</title>
! 956: <para>
! 957: At the core of the GNOME help system is the <application>GNOME
! 958: Help Browser</application>. The <application>Help
! 959: Browser</application> provides a unified interface to several
! 960: distinct documentation systems on Linux/Unix systems: man
! 961: pages, texinfo pages, Linux Documentation Project(LDP)
! 962: documents, GNOME application documentation, and other GNOME
! 963: documents.
! 964: </para>
! 965: <para>
! 966: The <application>GNOME Help Browser</application> works by
! 967: searching standard directories for documents which are to be
! 968: presented. Thus, the documentation that appears in the GHB is
! 969: specific to each computer and will typically only represent
! 970: software that is installed on the computer.
! 971: </para>
! 972: </sect2>
! 973:
! 974: <!-- ####### The GNOME Documentation System | The GNOME Help Browser
! 975: ####### -->
! 976:
! 977: <sect2 id="gnomehelpbrowser2">
! 978: <title>The GNOME Help Browser (GNOME-2.0)</title> <para> In
! 979: GNOME 2.0, the <application>GNOME Help Browser</application>
! 980: will be replaced by <application>Nautilus</application>.
! 981: Nautilus will be the file manager/graphical shell for GNOME 2.0
! 982: and will also implement a more sophisticated help system than
! 983: that used by the <application>GNOME Help Browser</application>
! 984: used in GNOME 1.0. It will read and display DocBook files
! 985: directly, avoiding the need for duplicating documents in both
! 986: DocBook and HTML formats. Its display engine for DocBook will
! 987: be much faster than running <application>jade</application> to
! 988: convert to HTML for rendering. Because it uses the original
! 989: DocBook source for documentation, it will be possible to do more
! 990: sophisticated searching using the meta information included in
! 991: the documents. And since Nautilus is a virtual file system
! 992: layer which is Internet-capable, it will be able to find and
! 993: display documents which are on the web as well as those on the
! 994: local file system. For more information on
! 995: <application>Nautilus</application>, visit the #nautilus IRC
! 996: channel on irc.gnome.org. </para>
! 997: </sect2>
! 998:
! 999: <!-- ####### The GNOME Documentation System | GNOME On-The-Fly
! 1000: Documentation Generation ####### -->
! 1001:
! 1002: <sect2 id="gnomehelponthefly">
! 1003: <title>Dynamic Document Synthesis(GNOME-2.0)</title>
! 1004: <para>
! 1005: GNOME uses the documentation presented by all the various
! 1006: GNOME components and applications installed on the system to
! 1007: present a complete and customized documentation environment
! 1008: describing only components which are currently installed on a
! 1009: users system. Some of this documentation, such as the manuals
! 1010: for applets, will be combined in such a way that it appears to
! 1011: be a single document.
! 1012: </para>
! 1013: <para>
! 1014: By using such a system, you can be sure that any GNOME app you
! 1015: install that has documentation will show up in the index,
! 1016: table of contents, any search you do in the help browser.
! 1017: </para>
! 1018: </sect2>
! 1019:
! 1020: <!-- ####### The GNOME Documentation System | The GNOME Documentation
! 1021: Components ####### -->
! 1022:
! 1023: <sect2 id="gnomehelpcomponents">
! 1024: <title>The GNOME Documentation Components</title>
! 1025:
! 1026: <sect3 id="applicationmanualsintro">
! 1027: <title>Application Manuals</title>
! 1028: <para>
! 1029: Every GNOME application should have an application manual.
! 1030: An application manual is a document specific to the
! 1031: particular application which explains the various windows
! 1032: and features of the application. Application Manuals
! 1033: typically use screenshots (PNG format) for clarity. Writing
! 1034: application manuals is discussed in more detail in <xref
! 1035: linkend="writingapplicationmanuals" /> below.
! 1036: </para>
! 1037: </sect3>
! 1038:
! 1039: <sect3 id="applicationhelpintro">
! 1040: <title>Application Help</title>
! 1041: <para>
! 1042: Applications should have a <guibutton>Help</guibutton>
! 1043: button on screens on which users may need help. These
! 1044: <guibutton>Help</guibutton> buttons should pull up the
! 1045: default help browser, determined by the
! 1046: <varname>ghelp</varname> URL Handler (configured using the
! 1047: <application>Control Center</application>), typically the
! 1048: <application>GNOME Help Browser</application>. The help
! 1049: browser should show either the first page of the application
! 1050: manual, or else the relevant page thereof. Application help
! 1051: is described in more detail in <xref
! 1052: linkend="applicationhelpbuttons" /> below.
! 1053: </para>
! 1054: </sect3>
! 1055:
! 1056: <sect3 id="contextsensitivehelpintro">
! 1057: <title>Application Context Sensitive Help (coming in
! 1058: GNOME-2.0)</title>
! 1059: <para>
! 1060: Context sensitive help is a system which will allow the user
! 1061: to query any part (button, widget, etc.) of an application
! 1062: window. This is done by either entering a CS Help mode by
! 1063: clicking on an icon or by right clicking on the application
! 1064: part and selecting "What's This" or whatever is decided on
! 1065: at the time. Context sensitive help is described in more
! 1066: detail in <xref linkend="writingcontextsensitivehelp" />
! 1067: below.
! 1068: </para>
! 1069: </sect3>
! 1070:
! 1071: <sect3 id="userguide">
! 1072: <title>The GNOME User Guide</title>
! 1073: <para>
! 1074: The <citetitle>GNOME User Guide</citetitle> describes the
! 1075: GNOME desktop environment and core components of GNOME such
! 1076: as the <application>panel</application> and
! 1077: <application>control center</application>. In GNOME 1.x this
! 1078: was the main and only source of documentation. In GNOME 2.0
! 1079: this will become a document for the web and for printing
! 1080: that is derived from various parts chosen in the system that
! 1081: are necessary for the new user to understand.
! 1082: </para>
! 1083: </sect3>
! 1084:
! 1085: <sect3 id="userdocs">
! 1086: <title>User Documents</title>
! 1087: <para>
! 1088: Aside from the <citetitle>GNOME User Guide</citetitle>,
! 1089: there are several other documents to help GNOME users learn
! 1090: GNOME, including the <citetitle>GNOME FAQ</citetitle>,
! 1091: <citetitle>GNOME Installation and Configuration
! 1092: Guide</citetitle>, and the <citetitle>GNOME Administrators
! 1093: Guide</citetitle>.
! 1094: </para>
! 1095: </sect3>
! 1096:
! 1097: <sect3 id="developerdocs">
! 1098: <title>Developer Documents</title>
! 1099: <para>
! 1100: There are many White Papers, Tutorials, HOWTO's and FAQ's to
! 1101: make programming GNOME and GNOME applications as easy as
! 1102: possible.
! 1103: </para>
! 1104: <para>
! 1105: API documentation is also available for the GNOME libraries. This is
! 1106: detailed documentation of the code that is used to build GNOME
! 1107: apps. You can keep up with the GNOME API docs on the <ulink
! 1108: url="http://developer.gnome.org/doc/API/" type="http">GNOME API
! 1109: Reference</ulink> page.
! 1110: </para>
! 1111: </sect3>
! 1112:
! 1113: <sect3 id="projectdocs">
! 1114: <title>Project Documents</title>
! 1115: <para>
! 1116: Some GNOME projects have documentation to maintain
! 1117: consistency in their product and to help new contributors
! 1118: get up to speed quickly. Among these are the GDP documents,
! 1119: such as the one you are reading now.
! 1120: </para>
! 1121: </sect3>
! 1122: </sect2>
! 1123: </sect1>
! 1124:
! 1125:
! 1126: <!-- ################# DocBook Basics ############### -->
! 1127:
! 1128: <sect1 id="docbookbasics">
! 1129: <title>DocBook Basics </title>
! 1130: <!-- ####### DocBook Basics | Introduction to DocBook ####### -->
! 1131:
! 1132: <sect2 id="introtodocbook">
! 1133: <title>Introduction to DocBook</title>
! 1134: <para>
! 1135: To understand DocBook, a basic understanding of SGML is
! 1136: helpful. SGML stands for Standard General Markup Language and
! 1137: is one of the first markup languages every created. HTML is
! 1138: actually derived from SGML and XML is a subset of SGML. SGML
! 1139: uses what is called a Document Type Definition to specify
! 1140: <emphasis>elements</emphasis> which are contained between
! 1141: brackets, < and >. Text is marked by both beginning and
! 1142: ending elements, for example in the DocBook DTD, one denotes a
! 1143: title with <sgmltag><title></sgmltag>The
! 1144: Title<sgmltag></title></sgmltag>.
! 1145: </para>
! 1146: <para>
! 1147: The DTD (in the case of the GDP, DocBook) defines rules for how the
! 1148: elements can be used. For example, if one element can only be used when
! 1149: embedded within another, this is defined in the DTD.
! 1150: </para>
! 1151: <para>
! 1152: An SGML file is just a plain ASCII file containing the text
! 1153: with the markup specified above. To convert it to some easily
! 1154: readable format, you need special tools. The GDP uses <emphasis>DocBook
! 1155: Tools</emphasis>, a free package of utilities for working with DocBook
! 1156: which includes <emphasis>Jade</emphasis>, which does the SGML/DSSL
! 1157: parsing. You can read more about DocBook Tools in <xref
! 1158: linkend="installingdocbook" />.
! 1159: </para>
! 1160: <para>
! 1161: The final appearance of the output (e.g. PostScript or HTML)
! 1162: is determined by a
! 1163: <emphasis>stylesheet</emphasis>. Stylesheets are files,
! 1164: written in a special language (DSSSL — Document Style
! 1165: Semantics and Specification Language), which specify the
! 1166: appearance of various DocBook elements, for example,
! 1167: what fonts to use for titles and various inline elements, page
! 1168: numbering style, and much more. DocBook tools come with a
! 1169: collection of stylesheets (Norman Walsh's modular
! 1170: stylesheets); GNOME Document Project uses some customized
! 1171: version of this stylesheets — see <xref
! 1172: linkend="gdpstylesheets"/>.
! 1173: </para>
! 1174: <para>
! 1175: The advantage of specifying the <emphasis>structure</emphasis>
! 1176: of a document with SGML instead of specifying the
! 1177: <emphasis>appearance</emphasis> of the document with a typical
! 1178: word processor, or with html, is that the resulting document
! 1179: can be processed in a variety of ways using the structural
! 1180: information. Whereas formatting a document for appearance
! 1181: assumes a medium (typically written text on a standard-sized
! 1182: piece of paper), SGML can be processed to produce output for a
! 1183: large variety of media such as text, postscript, HTML,
! 1184: Braille, audio, and potentially many other formats.
! 1185: </para>
! 1186: <para>
! 1187: Using 'content' as the elements to define the text of a document also
! 1188: allows for search engines to make use of the actual elements to make a
! 1189: "smarter search". For example, if you are searching for all documents
! 1190: written by the author "Susie" your search engine could be made smart
! 1191: enough to only search <author> elements, making for a faster and more
! 1192: accurate search.
! 1193: </para>
! 1194: <para>
! 1195: Since the overall appearance of the output is determined not by the DTD
! 1196: or the SGML document, but rather by a stylesheet, the appearance of a
! 1197: document can be easily changed just by changing the stylesheet. This
! 1198: allows everyone in the project to create documents that all look the
! 1199: same.
! 1200: </para>
! 1201: <para>
! 1202: As stated before, the GDP uses the DocBook DTD. For a list of
! 1203: introductory and reference resources on DocBook, see <xref
! 1204: linkend="resources" />. The following sections also provide
! 1205: convenient instructions on which markup tags to use in various
! 1206: circumstances. Be sure to read <xref linkend="conventions" />
! 1207: for GDP documentation-specific guidelines.
! 1208: </para>
! 1209: </sect2>
! 1210:
! 1211: <!-- ###### DocBook Basics | XML and SGML ########-->
! 1212: <sect2 id="xml">
! 1213: <title>XML and SGML</title>
! 1214:
! 1215: <para> In not so distant future (probably before GNOME 2.0),
! 1216: DocBook itself and GNOME Documentation project will migrate from
! 1217: SGML to XML. This transition should be relatively painless:
! 1218: (almost) all DocBook tags will remain the same. However, XML has
! 1219: stricter syntax rules than SGML; thus, some constructions which
! 1220: are valid in SGML will not be valid in XML. Therefore, to be
! 1221: ready for this transistion, it is <emphasis>strongly
! 1222: advised</emphasis> that the documentation writers conform to XML
! 1223: syntax rules. Here are most important differences:
! 1224: </para>
! 1225:
! 1226: <variablelist>
! 1227: <varlistentry>
! 1228: <term> <emphasis>Minimization</emphasis></term>
! 1229: <listitem>
! 1230:
! 1231: <para>
! 1232: It is possible with some implementations of SGML to use
! 1233: minimizations to close elements in a document by using
! 1234: </>, for example:
! 1235: <literal><sgmltag><title></sgmltag>The
! 1236: Title<sgmltag></></sgmltag></literal>. This is not
! 1237: allowed in XML. You can use <command>sgmlnorm</command> command,
! 1238: included in DocBook Tools package, to expand minimized tags;
! 1239: if you are using <application>Emacs</application> with psgml
! 1240: mode, you can also use menu command
! 1241: <menuchoice>
! 1242: <guimenu>Modify</guimenu>
! 1243: <guimenuitem>Normalize</guimenuitem>
! 1244: </menuchoice>.
! 1245: </para>
! 1246: </listitem>
! 1247: </varlistentry>
! 1248: <varlistentry>
! 1249: <term> <emphasis>Self-closing tags</emphasis></term>
! 1250: <listitem>
! 1251:
! 1252: <para>
! 1253: Also, in SGML some tags are allowed not to have closing
! 1254: tags. For example, it is legal for
! 1255: <sgmltag><xref></sgmltag> not to have a closing tag:
! 1256: <literal><sgmltag><xref
! 1257: linkend="someid"></sgmltag></literal>. In
! 1258: XML, it is illegal; instead, you should use
! 1259: <literal><sgmltag><xref
! 1260: linkend="someid"/></sgmltag></literal> (note the
! 1261: slash!).
! 1262: </para>
! 1263: </listitem>
! 1264: </varlistentry>
! 1265:
! 1266: <varlistentry>
! 1267: <term> <emphasis>Case sensitive tags</emphasis></term>
! 1268: <listitem>
! 1269: <para>
! 1270: In XML, unlike SGML, tags are case-senstive
! 1271: <sgmltag><title></sgmltag> and
! 1272: <sgmltag><TITLE></sgmltag> are different tags!
! 1273: Therefore, please always use lowercase tags (except for
! 1274: things like <literal>DOCTYPE, CDATA</literal> and
! 1275: <literal>ENTITY</literal>, which are not DocBook tags).
! 1276: </para>
! 1277: </listitem>
! 1278: </varlistentry>
! 1279:
! 1280:
! 1281:
! 1282: </variablelist>
! 1283: </sect2>
! 1284:
! 1285:
! 1286:
! 1287: <!-- ####### DocBook Basics | Structure Elements ####### -->
! 1288:
! 1289:
! 1290: <sect2 id="structure"> <title> Structure Elements</title>
! 1291:
! 1292: <sect3 id="section">
! 1293: <title>Sections and paragraphs</title>
! 1294: <para>
! 1295: Top-level element of a book body must be
! 1296: <sgmltag><chapter></sgmltag>; it may contain one or more
! 1297: <sgmltag><sect1></sgmltag>, each of them may contain
! 1298: <sgmltag><sect2></sgmltag> and so on up to
! 1299: <sgmltag><sect5></sgmltag>. The top-level element of an
! 1300: article body is always
! 1301: <sgmltag><sect1></sgmltag>. Regardless of which elements
! 1302: you use, give each structural element a unique id, so that
! 1303: you can link to it. For usage example, see the template.
! 1304: </para>
! 1305: <para> Please try to avoid using deeply nested sections; for
! 1306: most situations, <sgmltag><sect1></sgmltag> and
! 1307: <sgmltag><sect2></sgmltag> should be sufficient. If not,
! 1308: you probably should split your <sgmltag><sect1></sgmltag>
! 1309: into several smaller ones.
! 1310: </para>
! 1311: <para> Use the tag <sgmltag><para></sgmltag> for
! 1312: paragraphs, even if there is only one paragraph in a
! 1313: section—see template for examples.
! 1314: </para>
! 1315: </sect3>
! 1316:
! 1317: <sect3 id="notes">
! 1318: <title>Notes, Warnings, And Tips</title>
! 1319: <para>
! 1320: For notes, tips, warnings, and important information, which
! 1321: should be set apart from the main text (usually as a
! 1322: paragraph with some warning sign on the margin), use tags
! 1323: <sgmltag><note></sgmltag>, <sgmltag><tip></sgmltag>,
! 1324: <sgmltag><warning></sgmltag>,
! 1325: <sgmltag><important></sgmltag> respectively. For example:
! 1326: <programlisting>
! 1327: <![CDATA[
! 1328: <tip>
! 1329: <title>TIP</title>
! 1330: <para>
! 1331: To speed up program compilation, use <application>gcc</application>
! 1332: compiler with Pentium optimization.
! 1333: </para>
! 1334: </tip>]]> </programlisting> produces
! 1335: </para>
! 1336: <tip id="extip">
! 1337: <title>TIP</title>
! 1338: <para>
! 1339: To speed up program compilation, use
! 1340: <application>gcc</application> compiler with Pentium
! 1341: optimization. </para>
! 1342: </tip>
! 1343: <para>
! 1344: Note that this should not be inside a
! 1345: <sgmltag><para></sgmltag> but between paragraphs.
! 1346: </para>
! 1347: </sect3>
! 1348: <sect3 id="figures">
! 1349: <title> Screenshots and other figures</title>
! 1350: <para>
! 1351: To include screenshots and other figures, use the following
! 1352: tags:
! 1353:
! 1354: <programlisting>
! 1355: <![CDATA[
! 1356: <figure id="shot1">
! 1357: <title>Screenshot</title>
! 1358: <screenshot>
! 1359: <screeninfo>Screenshot of a program</screeninfo>
! 1360: <graphic format="PNG" fileref="figures/example_screenshot" srccredit="ME">
! 1361: </graphic>
! 1362: </screenshot>
! 1363: </figure>]]>
! 1364: </programlisting>
! 1365: replacing <filename>example_screenshot</filename> with the
! 1366: actual file name (without extension). The result will look like this:
! 1367:
! 1368: <figure id="shot1">
! 1369: <title>Screenshot</title>
! 1370: <screenshot>
! 1371: <screeninfo>Screenshot of a program</screeninfo>
! 1372: <graphic format="PNG"
! 1373: fileref="figures/example_screenshot" srccredit="ME"/>
! 1374:
! 1375: </screenshot>
! 1376: </figure>
! 1377: </para>
! 1378: <note>
! 1379: <title>NOTE</title>
! 1380: <para>
! 1381: Notice in this example that the screenshot file name does
! 1382: not include the file type extension — to find out
! 1383: why, please read <xref linkend="jadeimages" />.
! 1384: </para>
! 1385: </note>
! 1386: </sect3>
! 1387: <sect3 id="listing">
! 1388: <title>Program listings and terminal session</title> <para>
! 1389: To show a file fragment—for example, program
! 1390: listing—use <sgmltag><programlisting></sgmltag> tag:
! 1391: <programlisting>
! 1392: <![CDATA[
! 1393: <programlisting>
! 1394: [Desktop Entry]
! 1395: Name=Gnumeric spreadsheet
! 1396: Exec=gnumeric
! 1397: Icon=gnome-gnumeric.png
! 1398: Terminal=0
! 1399: Type=Application
! 1400: </programlisting>]]>
! 1401: </programlisting>
! 1402: which produces
! 1403: <programlisting>
! 1404: [Desktop Entry]
! 1405: Name=Gnumeric spreadsheet
! 1406: Exec=gnumeric
! 1407: Icon=gnome-gnumeric.png
! 1408: Terminal=0
! 1409: Type=Application
! 1410: </programlisting>
! 1411: As a matter of fact, all examples in this document were
! 1412: produced using <sgmltag><programlisting></sgmltag>.
! 1413: </para>
! 1414: <para>
! 1415: To show a record of terminal session—i.e., sequence of
! 1416: commands entered at the command line—use
! 1417: <sgmltag><screen></sgmltag> tag:
! 1418: <programlisting>
! 1419: <![CDATA[
! 1420: <screen>
! 1421: <prompt>bash$</prompt><userinput>make love</userinput>
! 1422: make: *** No rule to make target `love'. Stop.
! 1423: </screen>]]>
! 1424: </programlisting>
! 1425: which produces
! 1426: <screen>
! 1427: <prompt>bash$</prompt><userinput>make love</userinput>
! 1428: make: *** No rule to make target `love'. Stop.
! 1429: </screen>
! 1430: Note the use of tags <sgmltag><prompt></sgmltag> and
! 1431: <sgmltag><userinput></sgmltag> for marking system prompt
! 1432: and commands entered by user.
! 1433: <note>
! 1434: <title>NOTE</title>
! 1435: <para>
! 1436: Note that both <sgmltag><programlisting></sgmltag>
! 1437: and <sgmltag><screen></sgmltag> preserve linebreaks,
! 1438: but interpret SGML tags (unlike LaTeX
! 1439: <markup>verbatim</markup> environment). Take a look at
! 1440: the source of this document to see how you can have SGML
! 1441: tags literally shown but not interpreted,
! 1442: </para>
! 1443: </note>
! 1444: </para>
! 1445: </sect3>
! 1446: <sect3 id="lists">
! 1447: <title> Lists</title>
! 1448: <para>
! 1449: The most common list types in DocBook are
! 1450: <sgmltag><itemizedlist></sgmltag>,
! 1451: <sgmltag><orderedlist></sgmltag>, and
! 1452: <sgmltag><variablelist></sgmltag>.
! 1453: </para>
! 1454: <variablelist>
! 1455: <varlistentry>
! 1456: <term> <sgmltag><itemizedlist></sgmltag></term>
! 1457: <listitem><para>
! 1458: This is the simplest unnumbered list, parallel to
! 1459: <sgmltag><ul></sgmltag> in HTML. Here is an example:
! 1460: <programlisting>
! 1461: <![CDATA[
! 1462: <itemizedlist>
! 1463: <listitem>
! 1464: <para>
! 1465: <guilabel>Show backup files</guilabel> — This will
! 1466: show any backup file that might be on your system.
! 1467: </para>
! 1468: </listitem>
! 1469: <listitem>
! 1470: <para>
! 1471: <guilabel>Show hidden files</guilabel> — This will
! 1472: show all "dot files" or files that begin with a dot. This
! 1473: files typically include configuration files and directories.
! 1474: </para>
! 1475: </listitem>
! 1476: <listitem>
! 1477: <para>
! 1478: <guilabel>Mix files and directories</guilabel> — This
! 1479: option will display files and directories in the order you
! 1480: sort them instead of
! 1481: always having directories shown above files.
! 1482: </para>
! 1483: </listitem>
! 1484: </itemizedlist>
! 1485: ]]>
! 1486: </programlisting>
! 1487: and output:
! 1488: </para>
! 1489: <itemizedlist>
! 1490: <listitem>
! 1491: <para>
! 1492: <guilabel>Show backup files</guilabel> —
! 1493: This will show any backup file that might be on
! 1494: your system.
! 1495: </para>
! 1496: </listitem>
! 1497:
! 1498: <listitem>
! 1499: <para>
! 1500: <guilabel>Show hidden files</guilabel> —
! 1501: This will show all "dot files" or files that
! 1502: begin with a dot. This files typically include
! 1503: configuration files and directories.
! 1504: </para>
! 1505: </listitem>
! 1506:
! 1507: <listitem>
! 1508: <para>
! 1509: <guilabel>Mix files and directories</guilabel>
! 1510: — This option will display files and
! 1511: directories in the order you sort them instead
! 1512: of always having directories shown above files.
! 1513: </para>
! 1514: </listitem>
! 1515: </itemizedlist>
! 1516: <para> Note the use of <sgmltag>&mdash;</sgmltag>
! 1517: for long dash (see <xref linkend="specsymb" />). Also,
! 1518: please note that the result looks much nicer because the
! 1519: terms being explained (<guilabel>Show backup
! 1520: files</guilabel>, etc.) are set in a different font. In
! 1521: this case, it was achieved by using <link
! 1522: linkend="gui"><sgmltag><guilabel></sgmltag></link>
! 1523: tag. In other cases, use appropriate tags such as
! 1524: <link linkend="gui"><sgmltag><guimenuitem></sgmltag></link>,
! 1525: <link
! 1526: linkend="filenames"><sgmltag><command></sgmltag></link>,
! 1527: or — if none of
! 1528: this applies — use
! 1529: <link linkend="gui"><sgmltag><emphasis></sgmltag></link>.
! 1530: </para>
! 1531: </listitem>
! 1532: </varlistentry>
! 1533: <varlistentry>
! 1534: <term> <sgmltag><orderedlist></sgmltag></term>
! 1535: <listitem><para>
! 1536: This list is completely analogous to
! 1537: <sgmltag><itemizedlist></sgmltag> and has the same
! 1538: syntax, but it produces numbered list. By default,
! 1539: this list uses Arabic numerals for numbering entries;
! 1540: you can override this using <sgmltag>numeration</sgmltag>,
! 1541: for example <sgmltag><orderedlist
! 1542: numeration="lowerroman"></sgmltag>. Possible values of
! 1543: these attribute are <sgmltag>arabic</sgmltag>,
! 1544: <sgmltag>upperalpha</sgmltag>,
! 1545: <sgmltag>loweralpha</sgmltag>,
! 1546: <sgmltag>upperroman</sgmltag>,
! 1547: <sgmltag>lowerroman</sgmltag>.
! 1548: </para></listitem>
! 1549: </varlistentry>
! 1550:
! 1551: <varlistentry>
! 1552: <term> <sgmltag><variablelist></sgmltag></term>
! 1553: <listitem><para> This list is used when each entry is
! 1554: rather long, so it should be formatted as a block of text
! 1555: with some subtitle, like a small subsection. The
! 1556: <sgmltag><variablelist></sgmltag> is more complicated
! 1557: than itemizedlists, but for larger blocks of text, or when
! 1558: you're explaining or defining something, it's best to use
! 1559: them. Their greatest advantage is that it's easier for a
! 1560: computer to search. The lines you are reading now were
! 1561: produced by <sgmltag><variablelist></sgmltag>. The
! 1562: source looked liked this:
! 1563: <programlisting>
! 1564: <![CDATA[
! 1565: <variablelist>
! 1566: <varlistentry>
! 1567: <term> <sgmltag><itemizedlist></sgmltag></term>
! 1568: <listitem><para>
! 1569: This is the simplest unnumbered list, parallel to
! 1570: <sgmltag><ul></sgmltag> in HTML. Here is an example:...
! 1571: </para></listitem>
! 1572: </varlistentry>
! 1573: <varlistentry>
! 1574: <term> <sgmltag><orderedlist></sgmltag></term>
! 1575: <listitem><para>
! 1576: This list is completely analogous to
! 1577: <sgmltag><itemizedlist></sgmltag>
! 1578: </para></listitem>
! 1579: </varlistentry>
! 1580: <varlistentry>
! 1581: <term> <sgmltag><variablelist></sgmltag></term>
! 1582: <listitem><para>
! 1583: This list is used when each entry is rather long,...
! 1584: </para></listitem>
! 1585: </varlistentry>
! 1586: </variablelist>
! 1587: ]]>
! 1588: </programlisting>
! 1589: </para>
! 1590: </listitem>
! 1591: </varlistentry>
! 1592: </variablelist>
! 1593: <para>
! 1594: Lists can be nested; in this case, the stylesheets
! 1595: are smart enough to change the numeration (for
! 1596: <sgmltag><orderedlist></sgmltag>) or marks of each entry
! 1597: (in <sgmltag><itemizedlist></sgmltag>) for sub-lists
! 1598: </para>
! 1599: </sect3>
! 1600:
! 1601: </sect2>
! 1602:
! 1603: <!-- ####### DocBook Basics | Inline Elements ####### -->
! 1604:
! 1605: <sect2 id="inline">
! 1606: <title>Inline Elements</title>
! 1607:
! 1608: <sect3 id="gui">
! 1609: <title>GUI elements</title>
! 1610: <itemizedlist>
! 1611: <listitem>
! 1612: <para>
! 1613: <sgmltag><guibutton></sgmltag> — used for
! 1614: buttons, including checkbuttons and radio buttons
! 1615: </para>
! 1616: </listitem>
! 1617:
! 1618: <listitem>
! 1619: <para>
! 1620: <sgmltag><guimenu></sgmltag>,
! 1621: <sgmltag><guisubmenu></sgmltag> —used for
! 1622: top-level menus and submenus
! 1623: respectively, for example <literal><![CDATA[
! 1624: <guisubmenu>Utilities</guisubmenu> submenu of the
! 1625: <guimenu>Main Menu</guimenu>]]></literal>
! 1626: </para>
! 1627: </listitem>
! 1628:
! 1629: <listitem>
! 1630: <para>
! 1631: <sgmltag><guimenuitem></sgmltag>—an entry in a
! 1632: menu
! 1633: </para>
! 1634: </listitem>
! 1635:
! 1636: <listitem>
! 1637: <para>
! 1638: <sgmltag><guiicon></sgmltag>—an icon
! 1639: </para>
! 1640: </listitem>
! 1641:
! 1642: <listitem>
! 1643: <para>
! 1644: <sgmltag><guilabel></sgmltag>—for items which have
! 1645: labels, like tabs, or bounding boxes.
! 1646: </para>
! 1647: </listitem>
! 1648: <listitem>
! 1649: <para>
! 1650: <sgmltag><interface></sgmltag>— for most everything
! 1651: else... a window, a dialog box, the Panel, etc.
! 1652: </para>
! 1653: </listitem>
! 1654: </itemizedlist>
! 1655: <para>
! 1656: If you need to refer to a sequence of menu choices, such as
! 1657: <menuchoice>
! 1658: <guimenu>Main Menu</guimenu>
! 1659: <guisubmenu>Utilities</guisubmenu> <guimenuitem>GNOME
! 1660: terminal</guimenuitem>
! 1661: </menuchoice>
! 1662: there is a special construction for this, too:
! 1663: <programlisting>
! 1664: <![CDATA[
! 1665: <menuchoice>
! 1666: <guimenu>Main Menu</guimenu> <guisubmenu>Utilities</guisubmenu>
! 1667: <guimenuitem>GNOME terminal</guimenuitem> </menuchoice>]]>
! 1668: </programlisting>
! 1669: </para>
! 1670: </sect3>
! 1671:
! 1672: <sect3 id="links">
! 1673: <title>Links and references</title>
! 1674: <para>
! 1675: To refer to another place in the same document, you can use
! 1676: tags <sgmltag><xref></sgmltag> and
! 1677: <sgmltag><link></sgmltag>. The first of them
! 1678: automatically inserts the full name of the element you refer
! 1679: to (section, figure, etc.), while the second just creates a
! 1680: link (in HTML output). Here is an example:
! 1681: <programlisting>
! 1682: <![CDATA[An example of a <link linkend="extip">tip</link> was given in
! 1683: <xref linkend="notes" />. ]]>
! 1684: </programlisting>
! 1685: which produces: An example of a <link
! 1686: linkend="extip">tip</link> was given in <xref
! 1687: linkend="notes" />.
! 1688: </para>
! 1689: <para>
! 1690: Here <sgmltag>notes</sgmltag> and <sgmltag>extip</sgmltag>
! 1691: are the id attributes of <xref linkend="notes" /> and of the
! 1692: example of a tip in it.
! 1693: </para>
! 1694: <para> To produce a link to an external source, such as a
! 1695: Web page or a local file, use <sgmltag><ulink></sgmltag>
! 1696: tag, for example:
! 1697: <programlisting>
! 1698: <![CDATA[ To find more about GNOME, please visit <ulink type="http"
! 1699: url="http://www.gnome.org">GNOME Web page</ulink> ]]>
! 1700: </programlisting>
! 1701: which produces: To find more about GNOME, please visit
! 1702: <ulink type="http" url="http://www.gnome.org">The GNOME Web
! 1703: Site</ulink> You can use any of the standard URL types, such
! 1704: as <literal>http, ftp, file, telnet, mailto</literal> (in
! 1705: most cases, however, use of <literal>mailto</literal> is
! 1706: unnecessary—see discussion of
! 1707: <sgmltag><email></sgmltag> tag).
! 1708: </para>
! 1709: </sect3>
! 1710:
! 1711: <sect3 id="filenames"> <title>Filenames, commands, and other
! 1712: computer-related things</title>
! 1713: <para>
! 1714: Here are some tags used to describe operating system-related
! 1715: things:
! 1716: </para>
! 1717: <itemizedlist>
! 1718: <listitem>
! 1719: <para> <sgmltag><filename></sgmltag> — used
! 1720: for filenames,
! 1721: e.g.<sgmltag><filename></sgmltag>
! 1722: foo.sgml
! 1723: <sgmltag></filename></sgmltag>
! 1724: produces: <filename>foo.sgml</filename>.
! 1725: </para>
! 1726: </listitem>
! 1727: <listitem>
! 1728: <para> <sgmltag><filename
! 1729: class="directory"></sgmltag> — used for
! 1730: directories, e.g.<sgmltag><filename
! 1731: class="directory"></sgmltag>/usr/bin
! 1732: <sgmltag></filename></sgmltag>
! 1733: produces: <filename
! 1734: class="directory">/usr/bin</filename>.
! 1735: </para>
! 1736: </listitem>
! 1737: <listitem>
! 1738: <para>
! 1739: <sgmltag><application></sgmltag> — used for
! 1740: application names,
! 1741: e.g. <sgmltag><application></sgmltag>Gnumeric
! 1742: <sgmltag></application></sgmltag> produces:
! 1743: <application>Gnumeric</application>.
! 1744: </para>
! 1745: </listitem>
! 1746: <listitem>
! 1747: <para>
! 1748: <sgmltag><envar></sgmltag> — used for
! 1749: environment variables, e.g.
! 1750: <sgmltag><envar></sgmltag>PATH<sgmltag></envar></sgmltag>.
! 1751: </para>
! 1752: </listitem>
! 1753:
! 1754: <listitem>
! 1755: <para>
! 1756: <sgmltag><command></sgmltag> — used for
! 1757: commands entered on command line, e.g.
! 1758: <sgmltag><command></sgmltag>make install
! 1759: <sgmltag></command></sgmltag> produces:
! 1760: <command>make install</command>.
! 1761: </para>
! 1762: </listitem>
! 1763: <listitem>
! 1764: <para>
! 1765: <sgmltag><replaceable></sgmltag> — used for
! 1766: replaceable text, e.g.
! 1767: <sgmltag><command></sgmltag>db2html<sgmltag><replaceable></sgmltag>
! 1768: foo.sgml
! 1769: <sgmltag></replaceable></sgmltag><sgmltag></command></sgmltag>
! 1770: produces: <command>db2html
! 1771: <replaceable>foo.sgml</replaceable></command>.
! 1772: </para>
! 1773: </listitem>
! 1774: </itemizedlist>
! 1775: </sect3>
! 1776:
! 1777: <sect3 id="keys">
! 1778: <title>Keyboard input</title>
! 1779: <para> To mark up text input by the user, use
! 1780: <sgmltag><userinput></sgmltag>.
! 1781: </para>
! 1782: <para> To mark keystrokes such as shortcuts and other
! 1783: commands, use <sgmltag><keycap></sgmltag>.
! 1784: This is used for marking up what is printed on the top
! 1785: of the physical key on the keyboard. There are a couple of
! 1786: other tags for keys, too: <sgmltag><keysym></sgmltag>
! 1787: and <sgmltag><keycode></sgmltag>. However you are
! 1788: unlikely to need these for most documentation. For reference,
! 1789: <sgmltag><keysym></sgmltag> is for the <quote>symbolic
! 1790: name</quote> of a key. <sgmltag><keycode></sgmltag> is
! 1791: for the <quote>scan code</quote> of a key. These are not
! 1792: terms commonly required in <acronym>GNOME</acronym> documentation,
! 1793: although <sgmltag><keysym></sgmltag> is useful for marking
! 1794: up control codes.
! 1795: </para>
! 1796: <para>
! 1797: To mark up a combination of keystrokes, use the
! 1798: <sgmltag><keycombo></sgmltag> wrapper:
! 1799: <programlisting>
! 1800: <![CDATA[
! 1801: <keycombo>
! 1802: <keycap>Ctrl</keycap>
! 1803: <keycap>Alt</keycap>
! 1804: <keycap>F1</keycap>
! 1805: </keycombo>]]>
! 1806: </programlisting>
! 1807: </para>
! 1808: <para>
! 1809: Finally, if you want to show a shortcut for some menu
! 1810: command, here are the appropriate tags (rather long):
! 1811: <programlisting>
! 1812: <![CDATA[
! 1813: <menuchoice>
! 1814: <shortcut>
! 1815: <keycombo><keycap>Ctrl</keycap><keycap>q</keycap></keycombo>
! 1816: </shortcut>
! 1817: <guimenuitem> Quit</guimenuitem>
! 1818: </menuchoice>]]>
! 1819: </programlisting>
! 1820: which produces simply
! 1821: <menuchoice>
! 1822: <shortcut> <keysym>Ctrl-q</keysym> </shortcut>
! 1823: <guimenuitem> Quit</guimenuitem>
! 1824: </menuchoice>
! 1825: </para>
! 1826: </sect3>
! 1827:
! 1828: <sect3 id="email">
! 1829: <title>E-mail addresses</title> <para> To mark up e-mail
! 1830: address, use <sgmltag><email></sgmltag>:
! 1831: <programlisting>
! 1832: <![CDATA[ The easiest way to get in touch with me is by e-mail
! 1833: (<email>me@mydomain.com</email>)]]>
! 1834: </programlisting>
! 1835: which produces: The easiest way to get in touch with me is
! 1836: by e-mail (<email>me@mydomain.com</email>) Note that
! 1837: <sgmltag><email></sgmltag> automatically produces a link
! 1838: in html version.
! 1839: </para>
! 1840: </sect3>
! 1841:
! 1842: <sect3 id="specsymb">
! 1843: <title> Special symbols </title>
! 1844: <para>
! 1845: DocBook also provides special means for entering
! 1846: typographic symbols which can not be entered directly
! 1847: form the keyboard (such as copyright sign). This is done using
! 1848: <emphasis>entities</emphasis>, which is SGML analogue of
! 1849: macros, or commands, of LaTeX. They generally have the form
! 1850: <sgmltag>&entityname;</sgmltag>. Note that the semicolon
! 1851: is required.
! 1852: </para>
! 1853: <para>
! 1854: here is partial list of most commonly used enitites:
! 1855: </para>
! 1856: <itemizedlist>
! 1857: <listitem><para>
! 1858: <sgmltag>&amp;</sgmltag> — ampersend (&)
! 1859: </para></listitem>
! 1860: <listitem><para>
! 1861: <sgmltag>&lt;</sgmltag> — left angle bracket (<)
! 1862: </para></listitem>
! 1863: <listitem><para>
! 1864: <sgmltag>&copy;</sgmltag> — copyright sign (©)
! 1865: </para></listitem>
! 1866: <listitem><para>
! 1867: <sgmltag>&mdash;</sgmltag> — long dash (—)
! 1868: </para></listitem>
! 1869: <listitem><para>
! 1870: <sgmltag>&hellip;</sgmltag> — ellipsis (…)
! 1871: </para></listitem>
! 1872: </itemizedlist>
! 1873: <para>
! 1874: Note that the actual look of the resulting symbols depends
! 1875: on the fonts used by your browser; for example, it might
! 1876: happen that long dash (<sgmltag>&mdash;</sgmltag>) looks
! 1877: exactly like the usual dash (-). However, in the PostScript
! 1878: (and thus, in print) the output will look markedly better if
! 1879: you use appropriate tags.
! 1880: </para>
! 1881: </sect3>
! 1882: </sect2>
! 1883: </sect1>
! 1884:
! 1885: <!-- ################# GDP Documentation Conventions ############### -->
! 1886:
! 1887: <sect1 id="conventions">
! 1888: <title>GDP Documentation Conventions </title>
! 1889:
! 1890: <!-- ####### GDP Documentation Conventions | All Documentation ####### -->
! 1891:
! 1892: <sect2 id="conventionsalldocs">
! 1893: <title>Conventions for All GDP Documentation</title>
! 1894: <sect3 id="xmlcomp">
! 1895: <title> XML compatibility </title>
! 1896: <para>
! 1897: All GNOME documentation should conform to XML syntax
! 1898: requirements, which are stricter than SGML ones — see
! 1899: <xref linkend="xml" /> for more informaion.
! 1900: </para>
! 1901: </sect3>
! 1902:
! 1903: <sect3 id="authorsnames">
! 1904: <title> Authors' names</title>
! 1905: <para>
! 1906: All GNOME documentation should contain the names of both the
! 1907: application authors and documentation authors, as well as a
! 1908: link to the application web page (if it exists) and
! 1909: information for bug submission — see templates for an
! 1910: example.
! 1911: </para>
! 1912: </sect3>
! 1913: </sect2>
! 1914:
! 1915: <!-- ####### GDP Documentation Conventions | All Documentation ####### -->
! 1916:
! 1917: <sect2 id="conventionsappdocs">
! 1918: <title>Conventions for Application Documentation</title>
! 1919:
! 1920: <sect3 id="applicationversionid">
! 1921: <title>Application Version Identification</title>
! 1922: <para>
! 1923: Application documentation should identify the version of the
! 1924: application for which the documentation is written:
! 1925: <programlisting>
! 1926: <![CDATA[
! 1927: <sect1 id="intro">
! 1928: <title>Introduction</title>
! 1929: <para>
! 1930: blah-blah-blah This document describes version 1.0.53 of gfoo.
! 1931: </para>
! 1932: </sect1>]]>
! 1933: </programlisting>
! 1934: </para>
! 1935: </sect3>
! 1936: <sect3 id="license">
! 1937: <title> Copyright information </title>
! 1938: <para> Application
! 1939: documentation should contain a copyright notice, stating the
! 1940: licensing terms. It is suggested that you use the GNU Free
! 1941: Documentation License. You could also use some other license
! 1942: allowing free redistribution, such as GPL or Open Content
! 1943: license. If documentation uses some trademarks (such as UNIX,
! 1944: Linux, Windows, etc.), proper legal junk should also be
! 1945: included (see templates).
! 1946: </para>
! 1947: </sect3>
! 1948: <sect3 id="license2">
! 1949: <title>Software license</title>
! 1950: <para>
! 1951: All GNOME applications must contain information about the
! 1952: license (for software, not for documentation), either in the
! 1953: "About" box or in the manual.
! 1954: </para>
! 1955: </sect3>
! 1956:
! 1957: <sect3 id="bugtraq">
! 1958: <title> Bug reporting</title>
! 1959: <para>
! 1960: Application documentation should give an address for
! 1961: reporting bugs and for submitting comments about the
! 1962: documentaion (see templates for an example).
! 1963: </para>
! 1964: </sect3>
! 1965: </sect2>
! 1966: </sect1>
! 1967:
! 1968: <!-- ################# Writing Application Manuals ###############-->
! 1969:
! 1970: <sect1 id="writingapplicationmanuals">
! 1971: <title>Writing Application and Applet Manuals</title>
! 1972: <para>
! 1973: Every GNOME application or applet should have a manual specific
! 1974: to that particular application. This manual should be a complete
! 1975: and authoritative guide. The manual should describe what the
! 1976: program does and how to use it. Manuals will typically describe
! 1977: each window or panel presented to the user using screenshots (in
! 1978: PNG format only) when appropriate. They should also describe
! 1979: each feature and preference option available.
! 1980: </para>
! 1981: <note>
! 1982: <title>Documentation Availability</title>
! 1983: <para>
! 1984: Applications and applets should not rely on documentation
! 1985: which is only available on the internet. All manuals and
! 1986: other documentation should be packaged with the application or
! 1987: applet and be made available to the user through the standard
! 1988: GNOME help system methods described below.
! 1989: </para>
! 1990: </note>
! 1991: <para> Application manuals should be based on the template in
! 1992: <xref linkend="template1" />. Applet manuals should be based on
! 1993: the templates in <xref linkend="template2-1x" /> for GNOME
! 1994: versions 1.x and the templates in <xref linkend="template2-2x" />
! 1995: for GNOME versions 2.x.
! 1996: </para>
! 1997: <note>
! 1998: <title>Manuals For Large Applications</title>
! 1999: <para>
! 2000: Manuals for very large applications, such as GNOME Workshop
! 2001: components should be a <sgmltag><book></sgmltag> (and thus
! 2002: use <sgmltag><chapter></sgmltag> for each primary section)
! 2003: , instead of <sgmltag><article></sgmltag> which most
! 2004: applications use(with each primary section being a
! 2005: <sgmltag><sect1></sgmltag>).
! 2006: </para>
! 2007: </note>
! 2008: <note>
! 2009: <title>Applet Manuals in GNOME 2.0</title>
! 2010: <para>
! 2011: Note that applet manuals in GNOME 2.0 are treated in a special
! 2012: way. The manuals for all applets are merged into a single
! 2013: virtual document by Nautilus. For this reason, the header
! 2014: information for applet manuals is omitted and the first
! 2015: section of each applet is
! 2016: <sgmltag><sect1></sgmltag>. Applet manuals will typically
! 2017: have several sections, each of which is
! 2018: <sgmltag><sect2></sgmltag>.
! 2019: </para>
! 2020: </note>
! 2021: <para>
! 2022: Application manuals should be made available by having a
! 2023: "Manual" entry in the <guimenu>Help</guimenu> pull-down menu
! 2024: at the top of the
! 2025: application, as described in <xref linkend="listingdocsinhelpmenu" />.
! 2026: Applets should make their manuals available by
! 2027: right-clicking on the applet.
! 2028: </para>
! 2029: </sect1>
! 2030:
! 2031:
! 2032: <!-- ############### Listing Documents in the Help Menu ############# -->
! 2033:
! 2034: <sect1 id="listingdocsinhelpmenu">
! 2035: <title>Listing Documents in the Help Menu</title>
! 2036:
! 2037: <note>
! 2038: <title>Developer Information</title>
! 2039: <para>
! 2040: This section is for developers. Documentation authors
! 2041: generally do not need to know this material.
! 2042: </para>
! 2043: </note>
! 2044: <para>
! 2045: Typically the application manual and possibly additional help
! 2046: documents will be made available to the user under the
! 2047: <guimenu>Help</guimenu> menu at the top right of the
! 2048: application. To do this, you must first write a
! 2049: <filename>topic.dat</filename> file. The format for this file is:
! 2050: <programlisting>
! 2051: One line for each 'topic'.
! 2052:
! 2053: Two columns, as defined by perl -e 'split(/\s+/,$aline,2)'
! 2054:
! 2055: First column is the HTML file (and optional section) for the topic,
! 2056: relative to the app's help file dir.
! 2057:
! 2058: Second column is the user-visible topic name.
! 2059: </programlisting>
! 2060: For example, <application>Gnumeric</application>'s
! 2061: <filename>topic.dat</filename> file is:
! 2062: <programlisting>
! 2063: gnumeric.html Gnumeric manual
! 2064: function-reference.html Gnumeric function reference
! 2065: </programlisting>
! 2066: When the application is installed, the
! 2067: <filename>topic.dat</filename> file should be placed in the
! 2068: <filename
! 2069: class="directory">$prefix/share/gnome/help/<replaceable>appname</replaceable>/C/</filename> directory
! 2070: where <replaceable>appname</replaceable> is replaced by the
! 2071: application's name. The application documentation (converted
! 2072: from SGML into HTML with <command>db2html</command>) should be
! 2073: placed in this directory too.
! 2074: </para>
! 2075: <note>
! 2076: <para>
! 2077: If the help files are not present in the correct directory, the
! 2078: menu items will NOT appear when the program is run.
! 2079: </para>
! 2080: </note>
! 2081: <para>
! 2082: The <filename>topic.dat</filename> file is used by the GNOME
! 2083: menu building code to generate the <guimenu>Help</guimenu>
! 2084: menu. When you define your menu:
! 2085: <programlisting>
! 2086: GnomeUIInfo helpmenu[] = {
! 2087: {GNOME_APP_UI_ITEM,
! 2088: N_("About"), N_("Info about this program"),
! 2089: about_cb, NULL, NULL,
! 2090: GNOME_APP_PIXMAP_STOCK, GNOME_STOCK_MENU_ABOUT,
! 2091: 0, 0, NULL},
! 2092: GNOMEUIINFO_SEPARATOR,
! 2093: GNOMEUIINFO_HELP("<emphasis>appname</emphasis>"),
! 2094: GNOMEUIINFO_END
! 2095: };
! 2096: </programlisting>
! 2097: the line specifying <varname>GNOMEUIINFO_HELP</varname> causes
! 2098: GNOME to create a menu entry which is tied to the documentation
! 2099: in the directory mentioned above. Also, all the topics in the
! 2100: <filename>topic.dat</filename> file will get menu entries in the
! 2101: <guimenu>Help</guimenu> menu. When the user selects any of these
! 2102: topics from the <guimenu>Help</guimenu> menu, a help browser
! 2103: will be started with the associated HTML documentation.
! 2104: </para>
! 2105: </sect1>
! 2106:
! 2107:
! 2108: <!-- ################# Application Help Buttons ############### -->
! 2109:
! 2110: <sect1 id="applicationhelpbuttons">
! 2111: <title>Application Help Buttons</title>
! 2112:
! 2113: <note>
! 2114: <title>Developer Information</title>
! 2115: <para>
! 2116: This section is for developers. Documentation authors
! 2117: generally do not need to know this material.
! 2118: </para>
! 2119: </note>
! 2120: <para>
! 2121: Most GNOME applications will have <guibutton>Help</guibutton>
! 2122: buttons. These are most often seen in Preference windows. (All
! 2123: Preference windows should have <guibutton>Help</guibutton>
! 2124: buttons.) Most <guibutton>Help</guibutton> buttons will connect
! 2125: to the application manual, although some may connect to special
! 2126: documents. Because the <guibutton>Help</guibutton> buttons do
! 2127: not generally have their own special documentation, the
! 2128: documentation author(s) do not need to do very much. However,
! 2129: the application author must be careful to guarantee that the
! 2130: application correctly opens the help documentation when the
! 2131: <guibutton>Help</guibutton> buttons are pressed.
! 2132: </para>
! 2133: <para>
! 2134: To make the Help buttons call the correct document in the GNOME Help
! 2135: Browser the developer should add code based on the following example:
! 2136: </para>
! 2137: <programlisting>
! 2138: gchar *tmp;
! 2139: tmp = gnome_help_file_find_file ("module", "page.html");
! 2140: if (tmp) {
! 2141: gnome_help_goto(0, tmp);
! 2142: g_free(tmp);
! 2143: }
! 2144: </programlisting>
! 2145: <note>
! 2146: <title>NOTE</title>
! 2147: <para>
! 2148: The example above is in the C language, please refer to other
! 2149: documentation or forums for other GNOME language bindings.
! 2150: </para>
! 2151: </note>
! 2152: </sect1>
! 2153:
! 2154: <!-- ################# Packaging Applet Documentation ############### -->
! 2155:
! 2156: <sect1 id="packagingappletdocs">
! 2157: <title>Packaging Applet Documentation</title>
! 2158: <sect2 id="appletfiles">
! 2159: <title>Applet Documentation Files</title>
! 2160: <para>
! 2161: In GNOME 2.0 each applet will have its own documentation
! 2162: installed separately, and the GNOME 2.0 help
! 2163: browser (<application>Nautilus</application>) will dynamically
! 2164: merge the applet documents into a single virtual book
! 2165: called <citetitle>GNOME Applets</citetitle>. During the
! 2166: transitionary stage between GNOME 1.0 and GNOME 2.0, each
! 2167: applet in the gnome-applets package has its own manual(stored
! 2168: with the applet in CVS), but they are merged together manually
! 2169: to create the <citetitle>GNOME Applets</citetitle> book before
! 2170: distribution. Telsa
! 2171: <email>hobbit@aloss.ukuu.org.uk</email> is the maintainer of
! 2172: this document. Applet documentation should be sent to Telsa
! 2173: (or placed in CVS) who will make sure they are correctly
! 2174: packaged with the applets. The applet author should be
! 2175: contacted to modify the menu items and help buttons to bind to
! 2176: the applet documentation if necessary.
! 2177: </para>
! 2178: <para>
! 2179: Images which are part of the applet documentation should be in
! 2180: PNG format and should reside in the same directory as the SGML
! 2181: document file in CVS(gnome-applets/APPLETNAME/help/C).
! 2182: </para>
! 2183: <para>
! 2184: Applets which are not part of the gnome-applets package must
! 2185: package their documentation with the particular applet
! 2186: package. They should use the same applet template as other
! 2187: applets. However, the <sgmltag><xref></sgmltag> links to
! 2188: the introductory chapter of the <citetitle>GNOME
! 2189: Applets</citetitle> book must be removed (as the 1.x
! 2190: <application>GNOME Help Browser</application> does not allow
! 2191: you to create links between separate documents) and replaced
! 2192: with suitable text. Note that since this document is not part
! 2193: of the <citetitle>GNOME Applets</citetitle> book, you must
! 2194: remember to add <sgmltag><legalnotice></sgmltag> and
! 2195: <sgmltag><copyright></sgmltag> sections.
! 2196: </para>
! 2197: </sect2>
! 2198:
! 2199: <sect2 id="appletmenu">
! 2200: <title>Adding Documentation to an Applet Menu</title>
! 2201: <note>
! 2202: <title>Developer Information</title>
! 2203: <para>
! 2204: This section is for developers. Documentation authors
! 2205: generally do not need to know this material.
! 2206: </para>
! 2207: </note>
! 2208: <para>
! 2209: Applets should have <guimenu>About</guimenu> and
! 2210: <guimenu>Manual</guimenu> menu items, typically as the first
! 2211: and second top-most items in the menu respectively. This
! 2212: section describes how the developer creates these menu items
! 2213: and links them to the documentation.
! 2214: </para>
! 2215: <para>
! 2216: To add an applet's manual to its applet menu, use:
! 2217: <programlisting>
! 2218: /* add an item to the applet menu */
! 2219: applet_widget_register_callback(APPLET_WIDGET(applet), "manual",
! 2220: _("Manual"), &open_manual, NULL);
! 2221: </programlisting>
! 2222: Here the second argument is an arbitrary name for the
! 2223: callback, the third argument is the label which will appear
! 2224: when the user right clicks on the applet, and the fourth
! 2225: argument is the callback function.
! 2226: </para>
! 2227: <para>
! 2228: You will need to write a simple callback function to open the
! 2229: help browser to the appropriate document. This is done using
! 2230: the <function>gnome_help_file_find_file</function> function,
! 2231: as described in <xref linkend="applicationhelpbuttons" />.
! 2232: </para>
! 2233: <para>
! 2234: You will also want to add an <guimenu>About</guimenu> menu
! 2235: item to the applet's menu. This is a
! 2236: stock menu item and is done:
! 2237: <programlisting>
! 2238: applet_widget_register_stock_callback (APPLET_WIDGET(applet), "about",
! 2239: GNOME_STOCK_MENU_ABOUT, _("About"), &my_applet_cb_about,
! 2240: NULL);
! 2241: </programlisting>
! 2242: </para>
! 2243: <para>
! 2244: More information can be found at <ulink type="http"
! 2245: url="http://developer.gnome.org/doc/tutorials/applet/index.html">Writing
! 2246: GNOME panel applets using the GTK+/GTK-- widget set</ulink>.
! 2247: </para>
! 2248: </sect2>
! 2249: </sect1>
! 2250:
! 2251:
! 2252: <!-- ################# Writing Context Sensitive Help ###############
! 2253: -->
! 2254:
! 2255: <sect1 id="writingcontextsensitivehelp">
! 2256: <title>Writing Context Sensitive Help (coming in GNOME-2.0)</title>
! 2257: <para>
! 2258: Context sensitive help, also known as "pop-up" help, will allow
! 2259: a user to obtain help information about specific buttons or
! 2260: parts of an application.
! 2261: </para>
! 2262: <para>
! 2263: Context sensitive help is still under development and not all
! 2264: the details are available at this time. However, the basics can
! 2265: be shown here so that you can understand how the system will
! 2266: work.
! 2267: </para>
! 2268: <para>
! 2269: The Context Sensitive Help system is designed to allow the
! 2270: developer to give an id to a particular portion of the User
! 2271: Interface, for example, a button. Once the interface is complete
! 2272: a Perl script can then be run against the interface code to
! 2273: create a "map" file. This map file allows the developer or
! 2274: writer to associate particular paragraph sections from an XML
! 2275: document to the interface items.
! 2276: </para>
! 2277: <para>
! 2278: The XML used for the document is a small XML DTD that is being
! 2279: developed to use the same tags (albeit, much fewer) as DocBook
! 2280: so that writers do not have to re-learn a new DTD.
! 2281: </para>
! 2282: <para>
! 2283: Once the document is written and map file is complete, when the
! 2284: user launches context sensitive help on the interface (either by
! 2285: pressing a button and then clicking on the interface item they
! 2286: want information on, or by right mouse clicking on the interface
! 2287: item and selecting a pop-up menu item like "What's This") a
! 2288: small transient window will appear with brief but detailed
! 2289: information on the interface item.
! 2290: </para>
! 2291: </sect1>
! 2292:
! 2293: <!-- ################# Referring to Other GNOME Documentation
! 2294: ############# -->
! 2295:
! 2296: <sect1 id="referring">
! 2297: <title>Referring to Other GNOME Documentation (coming in
! 2298: GNOME-2.0)</title>
! 2299: <para>
! 2300: In the GNOME 2.0 Help System, you will be able to create links
! 2301: from one document to another. The exact mechanism for doing
! 2302: this is in development.
! 2303: </para>
! 2304: </sect1>
! 2305:
! 2306:
! 2307: <!-- ################# Basics of Documentation Style ############### -->
! 2308:
! 2309: <sect1 id="basics">
! 2310: <title>Basics of Documentation Style</title>
! 2311: <para>
! 2312: Most people have never enjoyed reading a software manual, and
! 2313: they probably never will. Many times, they'll read the
! 2314: documentation only when they run into problems, and they'll be
! 2315: frustrated and upset before they even read a word. On the
! 2316: other hand, some readers will read the manual all the way
! 2317: through, or at least look at the introduction before they
! 2318: start. Your document might serve as a reference for an expert
! 2319: or a guide to a beginner, and it must have enough depth to
! 2320: satisfy the first without overwhelming the second. Ideally, it
! 2321: will serve beginners as they <emphasis>become</emphasis>
! 2322: experts. Remember, your goal is to produce <emphasis>complete,
! 2323: intuitive and clear</emphasis> documentation.
! 2324: </para>
! 2325: <para>
! 2326: In order to write useful documentation, you'll have to know who
! 2327: your audience is likely to be. Then, you can look for the
! 2328: problems they're likely to run into, and solve them. It will
! 2329: also help if you focus on the tasks users will perform, and
! 2330: group features accordingly, rather than simply describing
! 2331: features at random.
! 2332: </para>
! 2333:
! 2334: <!-- *********** Basics of Documentation Style: planning -->
! 2335:
! 2336: <sect2 id="styleplanning">
! 2337: <title>Planning</title>
! 2338: <para>
! 2339: Begin documenting by learning how to use the application and
! 2340: reading over any existing documentation. Pay attention to
! 2341: places where your document will differ from the template. It
! 2342: may help to develop a document skeleton: a valid XML or SGML
! 2343: document that has little or no content. For very large
! 2344: applications, you will need to make significant departures
! 2345: from the templates, since you'll be using the
! 2346: <sgmltag><book></sgmltag> tag instead of
! 2347: <sgmltag><chapter></sgmltag> or
! 2348: <sgmltag><article></sgmltag>.
! 2349: </para>
! 2350: </sect2>
! 2351:
! 2352:
! 2353: <!-- ####### Basics of Documentation Style | Balance ####### -->
! 2354: <sect2 id="balance">
! 2355: <title>Achieving a Balanced Style</title>
! 2356:
! 2357: <para>
! 2358: Just as you need to juggle expert and novice readers,
! 2359: you'll have to juggle a number of other extremes as you write:
! 2360: <itemizedlist>
! 2361: <listitem>
! 2362: <para>
! 2363: Documents should be complete, yet concise. You should
! 2364: describe every feature, but you'll have decide how much
! 2365: detail is really necessary. It's not, for example,
! 2366: necessary to describe every button and form field in a
! 2367: dialog box, but you should make sure that your readers
! 2368: know how to bring up the dialog and what it does. If
! 2369: you spend fewer words on the obvious, you can spend more
! 2370: time clarifying the ambiguous labels and explaining
! 2371: items that are more complex.
! 2372: </para>
! 2373: </listitem>
! 2374: <listitem>
! 2375: <para>
! 2376: Be engaging and friendly, yet professional. Games
! 2377: documents may be less formal than productivity
! 2378: application documents (people don't
! 2379: <emphasis>use</emphasis> games, they
! 2380: <emphasis>play</emphasis> them), but all of them should
! 2381: maintain a standard of style which holds the reader's
! 2382: interest without resorting to jokes and untranslatable
! 2383: allusions or puns.
! 2384: </para>
! 2385: </listitem>
! 2386:
! 2387: <listitem>
! 2388: <para>
! 2389: Examples, tips, notes, and screenshots are useful to
! 2390: break up long stretches of text, but too many can get in
! 2391: the way, and make your documents too choppy to read.
! 2392: It's good to provide a screenshot of any dialog windows
! 2393: a user might run into, but if a dialog box has several
! 2394: tabs, it's not usually necessary to have one for each.
! 2395: </para>
! 2396: </listitem>
! 2397:
! 2398: <listitem>
! 2399: <para>
! 2400: The GDP strives to have all of its documentation conform
! 2401: to certain standards of style and content, but every
! 2402: document (and every writer) is different. You will need
! 2403: to use your judgement, and write documents to fit with
! 2404: the rest of the project, without compromising the
! 2405: individual needs of your subject, or your own
! 2406: individuality as a writer.
! 2407: </para>
! 2408: </listitem>
! 2409:
! 2410: </itemizedlist>
! 2411: </para>
! 2412: </sect2>
! 2413:
! 2414:
! 2415: <!-- ####### Basics of Documentation Style | Structure ####### -->
! 2416:
! 2417: <sect2 id="stylestructure">
! 2418: <title>Structure</title>
! 2419: <para>
! 2420: In general, you won't have to worry too much about structure,
! 2421: because the templates provide you with an excellent example.
! 2422: As a general rule, try to follow that structural example.
! 2423: That means using links, hierarchical nesting, and, if
! 2424: necessary, a glossary or index. You probably won't need to
! 2425: use every available structural tag, but take advantage of
! 2426: what DocBook provides you.
! 2427: </para>
! 2428: <para>
! 2429: As to linking, there's some disagreement about whether to use
! 2430: <sgmltag><xref></sgmltag> <sgmltag><link></sgmltag>
! 2431: when you make links within your documents. You'll have to
! 2432: decide, based on the different ways that they are presented
! 2433: in output, which is more appropriate given the context.
! 2434: Regardless of which you use, you should not forget to use
! 2435: them. Help your readers find information that relevant to
! 2436: the issue at hand.
! 2437: </para>
! 2438: <para>
! 2439: The table of contents will be generated automatically, but
! 2440: you will probably have to develop your own index if you wish
! 2441: to have one. The Nautilus Help Browser will have new, and
! 2442: currently unknown, indexing capabilities, so index style and
! 2443: structure are still under discussion. The GNOME User's Guide
! 2444: will contain a glossary in its next versions; unless you're
! 2445: writing a<sgmltag><book></sgmltag>, it will probably be best to
! 2446: contribute to that rather than developing your own.
! 2447: </para>
! 2448: </sect2>
! 2449: <!-- ####### Basics of Documentation Style | Grammar & Spelling ####### -->
! 2450:
! 2451: <sect2 id="stylegrammar">
! 2452: <title>Grammar and Spelling</title>
! 2453: <para>
! 2454: Nobody expects you to be perfect; they just expect the
! 2455: documentation for their software to be error-free. That means
! 2456: that, in the same way that developers look for bugs and accept
! 2457: bug reports, writers must check for errors in their documents.
! 2458: Poor grammar, bad spelling, and gross technical errors in
! 2459: draft documents are fine. However, if those problems show up
! 2460: in a "real" release, they can count against the credibility of
! 2461: GNOME and Linux. They'll also make you look bad.
! 2462: </para>
! 2463: <para>
! 2464: There is no substitute for a human proofreader; use a
! 2465: spell-check program, then read it over yourself, and then find
! 2466: someone else to help you. Other GDP members are, of course,
! 2467: willing and able to help you, but non-writers are often at
! 2468: least as helpful.
! 2469: </para>
! 2470: <para>
! 2471: Proofreading documents is both a also a good way to
! 2472: familiarize yourself with documentation, and it certainly
! 2473: makes you valuable to the GDP. Help other writers proof their
! 2474: documents, and they will help you with yours.
! 2475: </para>
! 2476: </sect2>
! 2477: </sect1>
! 2478:
! 2479: <!-- ################# Teamwork ############### -->
! 2480:
! 2481: <sect1 id="teamwork">
! 2482: <title>Teamwork</title> <!-- ####### Teamwork | Working With The
! 2483: GDP Team ####### -->
! 2484:
! 2485: <sect2 id="teamworkgdp">
! 2486: <title>Working With The GDP Team</title>
! 2487: <para>
! 2488: The GDP team is a valuable resource for any documentation
! 2489: author. GDP members can answer most questions documentation
! 2490: authors have during the course of their work. It is also
! 2491: important to make sure you are not duplicating work of other
! 2492: GDP members by visiting the <citetitle>GDP Documentation
! 2493: Status Table</citetitle> (<ulink
! 2494: url="http://www.gnome.org/gdp/doctable/"
! 2495: type="http">http://www.gnome.org/gdp/doctable/</ulink>) and
! 2496: assigning a documentation item to yourself. This table also
! 2497: provides a forum for making suggestions and announcements for
! 2498: each documentation item. The best way to get in touch with
! 2499: GDP members is on the #docs IRC channel at irc.gnome.org or
! 2500: else by emailing the <ulink type="http"
! 2501: url="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/">
! 2502: <citetitle>gnome-doc-list mailing list</citetitle></ulink>.
! 2503: </para>
! 2504: <para>
! 2505: After an author has finished a document (or even a draft
! 2506: version of the document), it is a good idea to ask a member of
! 2507: the GDP team to read the document, checking it for grammar,
! 2508: proper DocBook markup, and clarity. One may typically find
! 2509: another author to do this by either asking on the #docs IRC
! 2510: channel at irc.gnome.org or by emailing the <ulink type="http"
! 2511: url="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/">
! 2512: <citetitle>gnome-doc-list mailing list</citetitle></ulink>.
! 2513: </para>
! 2514: </sect2>
! 2515:
! 2516: <!-- ####### Teamwork | Working With Developers ####### -->
! 2517:
! 2518: <sect2 id="teamworkdevelopers">
! 2519: <title>Working With Developers</title>
! 2520: <para>
! 2521: Writing documentation typically involves a certain amount of
! 2522: interaction with the developers of GNOME or the application
! 2523: which is being documented. Often a document author will need
! 2524: to ask the developer technical questions during the course of
! 2525: writing a document. After the document is finished, it is good
! 2526: idea to ask the developer to read the document to make sure it
! 2527: is technically correct. The documentation author should also
! 2528: make sure that the application author correctly binds and
! 2529: packages the documentation with the application.
! 2530: </para>
! 2531: </sect2>
! 2532:
! 2533: <!-- ####### Teamwork | Working With Users #######
! 2534:
! 2535: <sect2 id="teamworkusers">
! 2536: <title>Working With Users</title>
! 2537: <para>
! 2538: Some document authors may wish to get feedback on their
! 2539: documents directly from users. This may be done by ...
! 2540: </para>
! 2541: </sect2>-->
! 2542: </sect1>
! 2543:
! 2544: <!-- ################# Finishing a Document ############### -->
! 2545:
! 2546: <sect1 id="finishing">
! 2547: <title>Finishing A Document</title>
! 2548:
! 2549: <!-- ####### Finishing a Document | Editting the Document ####### -->
! 2550:
! 2551: <sect2 id="editting">
! 2552: <title>Editing The Document</title>
! 2553: <para>
! 2554: When the document is finished, the document should be edited
! 2555: by another member of the GDP for spelling, clarity, and
! 2556: DocBook markup. It should also be read by an application
! 2557: author to make sure the document is technically accurate.
! 2558: </para>
! 2559: </sect2>
! 2560:
! 2561: <!-- ####### Finishing a Document | Submitting the Document ####### -->
! 2562:
! 2563: <sect2 id="submitting">
! 2564: <title>Submitting The Document</title>
! 2565: <para>
! 2566: After the document has been edited and checked for technical
! 2567: accuracy, it is ready to be combined with the application or
! 2568: documentation package. This is typically done by passing the
! 2569: document to the application or package developer. In some
! 2570: cases, the documents can be committed directly into CVS,
! 2571: however this should only be done after obtaining permission to
! 2572: make CVS commits from the developer. Note that in many cases,
! 2573: the application may need to be modified to correctly link to
! 2574: the documentation. The packaging system (tarballs and binary
! 2575: packages) may also need to be modified to include the
! 2576: documentation in the package. Generally, this should be done
! 2577: by the developers.
! 2578: </para>
! 2579: <para>
! 2580: The final step is to email the GNOME Translation Team at
! 2581: <email>gnome-i18n@nuclecu.unam.mx</email> to notify them that
! 2582: there is a new document for them to translate.
! 2583: </para>
! 2584: </sect2>
! 2585: </sect1>
! 2586:
! 2587: <!-- ################# Resources ############### -->
! 2588:
! 2589: <sect1 id="resources">
! 2590: <title>Resources</title>
! 2591: <!-- ####### Resources | Resources on the Web ####### -->
! 2592:
! 2593: <sect2 id="resourcesweb">
! 2594: <title>Resources On The Web</title> <para> The <ulink
! 2595: type="http" url="http://developer.gnome.org/projects/gdp/">GNOME
! 2596: Documentation Project Web page</ulink> lists current GDP
! 2597: projects and members.
! 2598: </para>
! 2599: <para>
! 2600: The <ulink url="http://www.gnome.org/gdp/doctable/"
! 2601: type="http">GDP Documentation Status Table</ulink> tracks the
! 2602: status of all the various documentation components of GNOME.
! 2603: </para>
! 2604: <para>
! 2605: Norman Walsh's <ulink url="http://www.docbook.org"
! 2606: type="http"> <citetitle>DocBook: The Definitive
! 2607: Guide</citetitle></ulink> in an excellent book on DocBook,
! 2608: available both online and in print.
! 2609: </para>
! 2610: </sect2>
! 2611:
! 2612: <!-- ####### Resources | Books ####### -->
! 2613:
! 2614: <sect2 id="resourcesbooks">
! 2615: <title>Books</title>
! 2616: <para>
! 2617: Docbook: The Definitive Guide is available in both printed
! 2618: form and on the web at:
! 2619: <ulink url="http://www.docbook.org/tdg/index.html">
! 2620: <citetitle>Docbook: The Definitive Guide</citetitle>
! 2621: </ulink>
! 2622: </para>
! 2623: </sect2>
! 2624:
! 2625: <!-- ####### Resources | Mailing Lists ####### -->
! 2626:
! 2627: <sect2 id="mailinglists">
! 2628: <title>Mailing Lists</title>
! 2629: <para>
! 2630: The <emphasis>gnome-docs-list</emphasis> mailing list is the
! 2631: main discussion area for all contributors to the GNOME
! 2632: Documentation Project. You can find out how to subscribe to
! 2633: this list on <ulink
! 2634: url="http://www.gnome.org/resources/mailing-lists.html"
! 2635: type="http">GNOME Mailing Lists</ulink>. This is a rather
! 2636: low-volume list, so you will not be flooded with messages.
! 2637: </para>
! 2638: </sect2>
! 2639:
! 2640: <!-- ####### Resources | IRC ####### -->
! 2641:
! 2642: <sect2 id="irc">
! 2643: <title>IRC</title>
! 2644: <para>
! 2645: Internet Relay Chat (IRC) is a fast and easy way to get in
! 2646: touch with other GDP members. There are generally at least a
! 2647: few members here who can answer questions or discuss
! 2648: documentation issues. The IRC channel is #docs at
! 2649: irc.gnome.org.
! 2650: </para>
! 2651: </sect2>
! 2652: </sect1>
! 2653:
! 2654: <!-- ################# Example Docs ###############
! 2655:
! 2656: <appendix id="exampledocs">
! 2657: <title>Example Docs</title>
! 2658:
! 2659: ####### Example Docs | Example 1: Application Manual #######
! 2660:
! 2661: <sect1 id="ex1">
! 2662: <title>Example 1: Application Manual</title>
! 2663: <programlisting>
! 2664: <![CDATA[ (Put sgml here.)]]> </programlisting>
! 2665: </sect1>
! 2666:
! 2667: ####### Example Docs | Example 2: Applet Manual #######
! 2668:
! 2669: <sect1 id="ex2">
! 2670: <title>Example 2: Applet Manual</title>
! 2671: <programlisting>
! 2672: <![CDATA[(Put sgml here.)]]> </programlisting>
! 2673: </sect1>
! 2674:
! 2675: ##### Example Docs | Example 3: Application Context Sensitive Help ####
! 2676:
! 2677: <sect1 id="ex3">
! 2678: <title>Example 3: Application Context Sensitive Help</title>
! 2679: <programlisting>
! 2680: <![CDATA[(Put sgml here.)]]> </programlisting>
! 2681: </sect1>
! 2682:
! 2683: ####### Example Docs | Example 4: Complete Application: gnome-hello #######
! 2684:
! 2685: <sect1 id="ex4">
! 2686: <title>Example 4: Complete Application: gnome-hello</title>
! 2687: <programlisting>
! 2688: <![CDATA[(Put sgml here.)]]> </programlisting>
! 2689: </sect1>
! 2690:
! 2691: ####### Example Docs | Example 5: Tutorial #######
! 2692:
! 2693: <sect1 id="ex5">
! 2694: <title>Example 5: Tutorial</title>
! 2695: <programlisting>
! 2696: <![CDATA[(Put sgml here.)]]> </programlisting>
! 2697: </sect1>
! 2698: </appendix>-->
! 2699:
! 2700: <!-- ################# Document Templates ############### -->
! 2701:
! 2702: <appendix id="templates">
! 2703: <title>Document Templates</title>
! 2704: <!-- ####### Document Templates | Templates 1: Application Manual ####### -->
! 2705:
! 2706: <sect1 id="template1">
! 2707: <title>Template 1: Application Manual</title>
! 2708: <para>
! 2709: The following template should be used for all application
! 2710: manuals. You can always get the latest copy of this
! 2711: template from <ulink type="http"
! 2712: url="http://developer.gnome.org/projects/gdp/templates.html">GDP
! 2713: Documentation Templates</ulink>.
! 2714: <programlisting>
! 2715:
! 2716: <![CDATA[
! 2717: <!DOCTYPE Article PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
! 2718: <!-- if not using PNG graphic, replace reference above with
! 2719: .....PUBLIC "-//OASIS//DTD DocBook V3.1//EN"[
! 2720: -->
! 2721: <!ENTITY version "1.0.53">
! 2722: <!-- replace version above with actual application version number-->
! 2723: <!-- Template Version: 1.0.1 (do not remove this line) -->
! 2724: ]>
! 2725:
! 2726:
! 2727: <!-- This is a GNOME documentation template, designed by the GNOME
! 2728: Documentation Project Team. Please use it for writing GNOME
! 2729: documentation, making obvious changes. In particular, all the words
! 2730: written in UPPERCASE (with the exception of GNOME) should be
! 2731: replaced. As for "legalnotice", please leave the reference
! 2732: unchanged.
! 2733:
! 2734: Remember that this is a guide, rather than a perfect model to follow
! 2735: slavishly. Make your manual logical and readable. And don't forget
! 2736: to remove these comments in your final documentation! ;-)
! 2737: -->
! 2738:
! 2739: <!-- =============Document Header ============================= -->
! 2740:
! 2741: <article id="index"> <!-- please do not change the id -->
! 2742:
! 2743: <artheader>
! 2744: <title>MY-GNOME-APP</title>
! 2745: <copyright>
! 2746: <year>2000</year>
! 2747: <holder>ME-THE-AUTHOR</holder>
! 2748: </copyright>
! 2749:
! 2750: <!-- translators: uncomment this:
! 2751:
! 2752: <copyright>
! 2753: <year>2000</year>
! 2754: <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
! 2755: </copyright>
! 2756:
! 2757: -->
! 2758:
! 2759: <!-- do not put authorname in the header except in copyright - use
! 2760: section "authors" below -->
! 2761:
! 2762: <legalnotice>
! 2763: <para>
! 2764: Permission is granted to copy, distribute and/or modify this
! 2765: document under the terms of the <citetitle>GNU Free
! 2766: Documentation License</citetitle>, Version 1.1 or any later
! 2767: version published by the Free Software Foundation with no
! 2768: Invariant Sections, no Front-Cover Texts, and no Back-Cover
! 2769: Texts. You may obtain a copy of the <citetitle>GNU Free
! 2770: Documentation License</citetitle> from the Free Software
! 2771: Foundation by visiting <ulink type="http"
! 2772: url="http://www.fsf.org">their Web site</ulink> or by writing
! 2773: to: Free Software Foundation, Inc., 59 Temple Place - Suite
! 2774: 330, Boston, MA 02111-1307, USA.
! 2775: </para>
! 2776: <para>
! 2777: Many of the names used by companies to distinguish their
! 2778: products and services are claimed as trademarks. Where those
! 2779: names appear in any GNOME documentation, and those trademarks
! 2780: are made aware to the members of the GNOME Documentation
! 2781: Project, the names have been printed in caps or initial caps.
! 2782: </para>
! 2783: </legalnotice>
! 2784:
! 2785: <!-- this is the version of manual, not application -->
! 2786: <releaseinfo>
! 2787: This is version 1.0 of MY-GNOME-APP manual.
! 2788: </releaseinfo>
! 2789:
! 2790: </artheader>
! 2791:
! 2792: <!-- ============= Document Body ============================= -->
! 2793:
! 2794: <!-- ============= Introduction ============================== -->
! 2795: <sect1 id="intro">
! 2796: <title>Introduction</title>
! 2797:
! 2798: <para>
! 2799: <application>MY-GNOME-APP</application> is an application which
! 2800: proves mathematical theorems. It has all the basic features
! 2801: expected from a mathematical theorem prover, as well as a number
! 2802: of advanced ones, such as proof by confusion. In fact, many of
! 2803: the proofs produced by <application>MY-GNOME-APP</application>
! 2804: are so complex that they are capable of proving almost anything
! 2805: with a virtually null likelihood of being disproven. It also has
! 2806: the very popular predecessor of proof by confusion, proof by
! 2807: dialog, first implemented by Plato.
! 2808: </para>
! 2809: <para>
! 2810: It also allows you to save and print theorem proofs and to add
! 2811: comments to the proofs it produces.
! 2812: </para>
! 2813:
! 2814: <para>
! 2815: To run <application>MY-GNOME-APP</application>, select
! 2816: <menuchoice>
! 2817: <guisubmenu>SUBMENU</guisubmenu>
! 2818: <guimenuitem>MY-GNOME-APP</guimenuitem>
! 2819: </menuchoice>
! 2820: from the <guimenu>Main Menu</guimenu>, or type
! 2821: <command>MYGNOMEAPP</command> on the command line.
! 2822: </para>
! 2823:
! 2824: <para>
! 2825: <application>MY-GNOME-APP</application> is included in the
! 2826: <filename>GNOME-PACKAGE</filename> package, which is part of the
! 2827: GNOME desktop environment. This document describes version
! 2828: &version; of <application>MY-GNOME-APP</application>.
! 2829: </para>
! 2830: </sect1>
! 2831:
! 2832:
! 2833: <!-- ================ Usage ================================ -->
! 2834: <!-- This section should describe basic usage of the application. -->
! 2835:
! 2836: <sect1 id="usage">
! 2837: <title>Using MY-GNOME-APP</title>
! 2838: <para>
! 2839: <application>MY-GNOME-APP</application> can be used to produce a
! 2840: perfect proof of <emphasis>any</emphasis> mathematical theorem
! 2841: (provided, of course, that this theorem is correct), thus
! 2842: providing for new users an easy-to-use graphical interface to
! 2843: modern mathematics. This section describes basic usage of
! 2844: <application>MY-GNOME-APP</application>.
! 2845: </para>
! 2846:
! 2847: <!-- ========= Basic Usage =========================== -->
! 2848: <sect2 id="mainwin">
! 2849: <title>Basic usage</title>
! 2850: <para>
! 2851: Starting <application>MY-GNOME-APP</application> opens the
! 2852: <interface>Main window</interface>, shown in <xref
! 2853: linkend="mainwindow-fig">. The window is at first empty.
! 2854:
! 2855: <!-- ==== Figure ==== -->
! 2856: <figure id="mainwindow-fig">
! 2857: <title>MY-GNOME-APP Main Window</title>
! 2858: <screenshot>
! 2859: <screeninfo>MY-GNOME-APP Main Window</screeninfo>
! 2860: <graphic fileref="SCREENSHOT" format="png" srccredit="ME">
! 2861: </graphic>
! 2862: </screenshot>
! 2863: </figure>
! 2864: <!-- ==== End of Figure ==== -->
! 2865: </para>
! 2866:
! 2867:
! 2868: <!-- For this app, one could put "proving" or "edit" (probably even
! 2869: both of them) as sect2's seperate from the main window
! 2870: section. Since they were both so closely involved with the main
! 2871: window, I decided to have them as sect3's isntead. Judgement
! 2872: call. -->
! 2873:
! 2874: <sect3 id="proving">
! 2875: <title>Proving a Theorem</title>
! 2876: <para>
! 2877: To get a proof of a theorem, select
! 2878: <menuchoice>
! 2879: <guisubmenu>File</guisubmenu>
! 2880: <guimenuitem>New</guimenuitem>
! 2881: </menuchoice>,
! 2882: which will
! 2883: bring up the <interface>New Proof</interface> dialog box.
! 2884: Enter the statement of the theorem in the
! 2885: <guilabel>Theorem statement</guilabel> field, select your
! 2886: desired proof type from the drop-down menu, and and press
! 2887: <guibutton>Prove!</guibutton>.
! 2888: </para>
! 2889: <para>
! 2890: If <application>MY-GNOME-APP</application> cannot prove the
! 2891: theorem by the method you have chosen, or if you have not
! 2892: selected a proof type at all,
! 2893: <application>MY-GNOME-APP</application> will attempt to
! 2894: choose the one that it thinks is most conclusive. In order,
! 2895: it will attempt to prove the theorem with the following techniques:
! 2896:
! 2897: <variablelist>
! 2898: <varlistentry>
! 2899: <term>Deduction</term>
! 2900: <listitem>
! 2901: <para>
! 2902: This is a proof method that is generally accepted
! 2903: for full credit by Logic professors.
! 2904: </para>
! 2905: </listitem>
! 2906: </varlistentry>
! 2907: <varlistentry>
! 2908: <term>Induction</term>
! 2909: <listitem>
! 2910: <para>
! 2911: This logical style will also earn you full credit on
! 2912: your homework.
! 2913: </para>
! 2914: </listitem>
! 2915: </varlistentry>
! 2916: <varlistentry>
! 2917: <term>Dialog</term>
! 2918: <listitem>
! 2919: <para>
! 2920: This logical method is best for Philosophy classes,
! 2921: and will probably only merit partial credit on Logic
! 2922: or Mathematics homework.
! 2923: </para>
! 2924: </listitem>
! 2925: </varlistentry>
! 2926: <varlistentry>
! 2927: <term>Confusion</term>
! 2928: <listitem>
! 2929: <para>
! 2930: Suitable only for political debates, battles of wits
! 2931: against the unarmed, and Philosophy classes focusing
! 2932: on the works of Kant. Use with caution.
! 2933: </para>
! 2934: </listitem>
! 2935: </varlistentry>
! 2936: </variablelist>
! 2937: </para>
! 2938:
! 2939: <!-- You might want to include a note, warning, or tip, e.g. -->
! 2940:
! 2941: <warning>
! 2942: <title>Proving Incorrect Theorms</title>
! 2943: <para>
! 2944: <application>MY-GNOME-APP</application> cannot prove
! 2945: incorrect theorems. If the theorem you have entered is not
! 2946: demonstrably true, you will get a message to that effect
! 2947: in the main window. To disprove a theorem, ask
! 2948: <application>MY-GNOME-APP</application> to prove its
! 2949: logical inverse.
! 2950: </para>
! 2951: </warning>
! 2952: </sect3>
! 2953: <sect3 id="editing">
! 2954: <title>Editing Proofs</title>
! 2955: <para>
! 2956: Once you have proven the theorem, it will be displayed in
! 2957: the <interface>main window</interface>. There, you can read
! 2958: it over, choose text styles for different portions of it,
! 2959: and make comments on it. This section will guide you through
! 2960: that process.
! 2961: </para>
! 2962: <para>
! 2963: To alter text styles, first select the statement you wish to
! 2964: change by clicking on it once. You can select several
! 2965: statements by Then, choose the style you want to apply from
! 2966: the <guisubmenu>Style</guisubmenu> submenu of the
! 2967: <guimenu>Edit</guimenu> menu.
! 2968: <application>MY-GNOME-APP</application> will convert the
! 2969: text to that style.
! 2970: </para>
! 2971: <para>
! 2972: You can also enter comments on a statement by selecting that
! 2973: statement, and then beginning to type. Comments will appear
! 2974: after the statement you have selected.
! 2975: </para>
! 2976:
! 2977: <note>
! 2978: <title>Altering The Proofs Themselves</title>
! 2979: <para>
! 2980: <application>MY-GNOME-APP</application> does not allow you
! 2981: to alter a proof it has produced itself. You can, save
! 2982: your proof as a plain text file (using the
! 2983: <guimenuitem>Save as...</guimenuitem> menu), and alter it
! 2984: that way. Be aware, however, that
! 2985: <application>MY-GNOME-APP</application> uses its own file
! 2986: format for saved proofs, and cannot re-open a file unless
! 2987: it is in the .mga format.
! 2988: </para>
! 2989: </note>
! 2990: </sect3>
! 2991:
! 2992:
! 2993: <!-- If there are other functions performed from the main window,
! 2994: they belong here. -->
! 2995:
! 2996: </sect2>
! 2997:
! 2998: <!-- =========================================================
! 2999: Additional Sect2's should describe additional windows, such as
! 3000: larger dialog boxes, or functionality that differs significantly
! 3001: from the most immediate functions of the application. Make the
! 3002: structure logical.
! 3003: ============================================================= -->
! 3004:
! 3005:
! 3006: <sect2 id="toolbar">
! 3007: <title>Toolbar</title>
! 3008: <para>
! 3009: The toolbar (shown in <xref linkend="figure-usage-toolbar">)
! 3010: provides access to several commonly used routines.
! 3011: <figure id="figure-usage-toolbar">
! 3012: <title>MY-GNOME-APP Toolbar</title>
! 3013: <screenshot>
! 3014: <screeninfo>MY-GNOME-APP Toolbar</screeninfo>
! 3015: <graphic fileref="usage-toolbar.png" format="png"></graphic>
! 3016: </screenshot>
! 3017: </figure>
! 3018: <variablelist>
! 3019: <varlistentry>
! 3020: <term>New</term>
! 3021: <listitem>
! 3022: <para>
! 3023: Brings up the <interface>New Theorem</interface>
! 3024: dialog.
! 3025: </para>
! 3026: </listitem>
! 3027: </varlistentry>
! 3028: <varlistentry>
! 3029: <term>Open</term>
! 3030: <listitem>
! 3031: <para>
! 3032: Open an exisiting theorem you want to prove, or a
! 3033: completed proof you wish to print or format.
! 3034: </para>
! 3035: </listitem>
! 3036: </varlistentry>
! 3037: <varlistentry>
! 3038: <term>Save</term>
! 3039: <listitem>
! 3040: <para>
! 3041: Save the current theorem permanently in a
! 3042: file.
! 3043: </para>
! 3044: </listitem>
! 3045: </varlistentry>
! 3046: </variablelist>
! 3047: </para>
! 3048: </sect2>
! 3049: <!-- ========= Menus =========================== -->
! 3050:
! 3051: <sect2 id="menubar">
! 3052:
! 3053: <!-- Describing the menubar ensures comprehensive feature
! 3054: coverage. Nest itemizedlists inside variablelists so that each
! 3055: menu is easily located by indexing software. Proper indentation
! 3056: makes it easier! -->
! 3057:
! 3058: <title>Menus</title>
! 3059: <para>
! 3060: The menu bar, located at the top of the <interface>Main
! 3061: Window</interface>, contains the following menus:
! 3062: </para>
! 3063: <variablelist>
! 3064: <varlistentry>
! 3065: <term><guimenu>File</guimenu></term>
! 3066: <listitem>
! 3067: <para>
! 3068: This menu contains:
! 3069: <itemizedlist>
! 3070: <listitem>
! 3071: <para>
! 3072: <menuchoice>
! 3073: <shortcut>
! 3074: <keycap>F3</keycap>
! 3075: </shortcut>
! 3076: <guimenuitem>Open</guimenuitem>
! 3077: </menuchoice>
! 3078: — This opens a file which is saved on your computer.
! 3079: </para>
! 3080: </listitem>
! 3081: <listitem>
! 3082: <para>
! 3083: <menuchoice>
! 3084: <shortcut>
! 3085: <keycombo><keycap>Ctrl</keycap><keycap>S</keycap></keycombo>
! 3086: </shortcut>
! 3087: <guimenuitem>Save</guimenuitem>
! 3088: </menuchoice>
! 3089: — This saves your file.
! 3090: </para>
! 3091: </listitem>
! 3092: <listitem>
! 3093: <para>
! 3094: <menuchoice>
! 3095: <shortcut>
! 3096: <keycombo><keycap>Ctrl</keycap><keycap>W</keycap></keycombo>
! 3097: </shortcut>
! 3098: <guimenuitem>Close</guimenuitem>
! 3099: </menuchoice>
! 3100: — This closes your file.
! 3101: </para>
! 3102: </listitem>
! 3103: <listitem>
! 3104: <para>
! 3105: <menuchoice>
! 3106: <shortcut>
! 3107: <keycombo><keycap>Ctrl</keycap><keycap>Q</keycap></keycombo>
! 3108: </shortcut>
! 3109: <guimenuitem>Exit</guimenuitem>
! 3110: </menuchoice>
! 3111: — This quits the application.
! 3112: </para>
! 3113: </listitem>
! 3114: </itemizedlist>
! 3115: </para>
! 3116: </listitem>
! 3117: </varlistentry>
! 3118:
! 3119: <varlistentry>
! 3120: <term><guimenu>Edit</guimenu></term>
! 3121: <listitem>
! 3122: <para>
! 3123: This menu contains:
! 3124: <itemizedlist>
! 3125: <listitem>
! 3126: <para>
! 3127: <menuchoice>
! 3128: <shortcut>
! 3129: <keycombo><keycap>Ctrl</keycap><keycap>X</keycap></keycombo>
! 3130: </shortcut>
! 3131: <guimenuitem>Cut</guimenuitem>
! 3132: </menuchoice>
! 3133: — This removes any text or data which is selected and
! 3134: places it in the buffer.
! 3135: </para>
! 3136: </listitem>
! 3137: <listitem>
! 3138: <para>
! 3139: <menuchoice>
! 3140: <shortcut>
! 3141: <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo>
! 3142: </shortcut>
! 3143: <guimenuitem>Copy</guimenuitem>
! 3144: </menuchoice>
! 3145: — This copies any text or data which is selected into
! 3146: the buffer.
! 3147: </para>
! 3148: </listitem>
! 3149: <listitem>
! 3150: <para>
! 3151: <menuchoice>
! 3152: <shortcut>
! 3153: <keycombo><keycap>Ctrl</keycap><keycap>V</keycap></keycombo>
! 3154: </shortcut>
! 3155: <guimenuitem>Paste</guimenuitem>
! 3156: </menuchoice>
! 3157: — This pastes any text or data which is copied into
! 3158: the buffer.
! 3159: </para>
! 3160: </listitem>
! 3161: <listitem>
! 3162: <para>
! 3163: <guimenuitem>COMMAND1…</guimenuitem>
! 3164: — This opens the <interface>COMMAND1</interface>
! 3165: dialog, which is used to ....
! 3166: </para>
! 3167: </listitem>
! 3168: <listitem>
! 3169: <para>
! 3170: <guimenuitem>COMMAND2</guimenuitem>
! 3171: — This ....
! 3172: </para>
! 3173: </listitem>
! 3174: </itemizedlist>
! 3175: </para>
! 3176: </listitem>
! 3177: </varlistentry>
! 3178:
! 3179:
! 3180: <varlistentry>
! 3181: <term><guimenu>Settings</guimenu></term>
! 3182: <listitem>
! 3183: <para>
! 3184: This menu contains:
! 3185: <itemizedlist>
! 3186: <listitem>
! 3187: <para>
! 3188: <guimenuitem>Preferences…</guimenuitem>
! 3189: — This opens the <link
! 3190: linkend="prefs"><interface>Preferences
! 3191: Dialog</interface></link>, which allows you to configure
! 3192: many settings.
! 3193: </para>
! 3194: </listitem>
! 3195: <listitem>
! 3196: <para>
! 3197: <guimenuitem>COMMAND3</guimenuitem> —
! 3198: This command does something.
! 3199: </para>
! 3200: </listitem>
! 3201: </itemizedlist>
! 3202: </para>
! 3203: </listitem>
! 3204: </varlistentry>
! 3205:
! 3206: <varlistentry>
! 3207: <term><guimenu>Help</guimenu></term>
! 3208: <listitem>
! 3209: <para>
! 3210: This menu contains:
! 3211: <itemizedlist>
! 3212: <listitem>
! 3213: <para>
! 3214: <guimenuitem>Manual</guimenuitem> — This
! 3215: opens the <application>GNOME Help
! 3216: Browser</application> and displays this manual.
! 3217: </para>
! 3218: </listitem>
! 3219:
! 3220: <listitem>
! 3221: <para>
! 3222: <guimenuitem>About</guimenuitem> — This
! 3223: opens the <interface>About</interface> dialog
! 3224: which shows basic information about
! 3225: <application>MY-GNOME-APP</application>, such as
! 3226: the author's name, the application version number,
! 3227: and the URL for the application's Web page if one
! 3228: exists.
! 3229: </para>
! 3230: </listitem>
! 3231: </itemizedlist>
! 3232: </para>
! 3233: </listitem>
! 3234: </varlistentry>
! 3235: </variablelist>
! 3236: </sect2>
! 3237: </sect1>
! 3238:
! 3239:
! 3240:
! 3241: <!-- ============= Customization ============================= -->
! 3242:
! 3243: <sect1 id="prefs">
! 3244: <title>Customization</title>
! 3245: <para>
! 3246: To change the application settings, select
! 3247: <menuchoice>
! 3248: <guimenu>Settings</guimenu>
! 3249: <guimenuitem>Preferences...</guimenuitem>
! 3250: </menuchoice>. This opens the
! 3251: <interface>Preferences</interface> dialog, shown in <xref
! 3252: linkend="preferences-fig">.
! 3253: </para>
! 3254:
! 3255: <figure id="preferences-fig">
! 3256: <title>Preferences Dialog</title>
! 3257: <screenshot>
! 3258: <screeninfo>Preferences Dialog</screeninfo>
! 3259: <graphic fileref="SCREENSHOT" format="png"
! 3260: srccredit="ME">
! 3261: </graphic>
! 3262: </screenshot>
! 3263: </figure>
! 3264:
! 3265: <para>
! 3266: The properties in the <guilabel>PREFSTABNAME</guilabel> tab are:
! 3267:
! 3268: <!--many people use itemizedlists in cases like this. Variablelists
! 3269: are more appropriate -->
! 3270:
! 3271: <variablelist>
! 3272: <varlistentry>
! 3273: <term> <guilabel>Default Text Style</guilabel></term>
! 3274: <listitem>
! 3275: <para>
! 3276: Select the default text style for statements in your
! 3277: proof. You can still change the style for individual
! 3278: proofs or sections of a proof at a later date.
! 3279: </para>
! 3280: </listitem>
! 3281: </varlistentry>
! 3282: <varlistentry>
! 3283: <term>(Configuration Item Label)</term>
! 3284: <listitem>
! 3285: <para>
! 3286: (Description of Configuration)
! 3287: </para>
! 3288: </listitem>
! 3289: </varlistentry>
! 3290: <varlistentry>
! 3291: <term>(Configuration Item Label)</term>
! 3292: <listitem>
! 3293: <para>
! 3294: (Description of Configuration)
! 3295: </para>
! 3296: </listitem>
! 3297: </varlistentry>
! 3298: </variablelist>
! 3299: </para>
! 3300:
! 3301: <para>
! 3302: The properties in the <guilabel>SECONDTABNAME</guilabel> tab are:
! 3303: <variablelist>
! 3304: <varlistentry>
! 3305: <term>(Configuration Item Label)</term>
! 3306: <listitem>
! 3307: <para>
! 3308: (Description of Configuration)
! 3309: </para>
! 3310: </listitem>
! 3311: </varlistentry>
! 3312: <varlistentry>
! 3313: <term>(Configuration Item Label)</term>
! 3314: <listitem>
! 3315: <para>
! 3316: (Description of Configuration)
! 3317: </para>
! 3318: </listitem>
! 3319: </varlistentry>
! 3320: </variablelist>
! 3321: </para>
! 3322:
! 3323: <para>
! 3324: After you have made all the changes you want, click on
! 3325: <guibutton>OK</guibutton> to apply the changes and close the
! 3326: <interface>Properties</interface> dialog. To cancel the changes
! 3327: and return to previous values, click the
! 3328: <guibutton>Close</guibutton> button.
! 3329: </para>
! 3330:
! 3331: </sect1>
! 3332:
! 3333:
! 3334: <!-- ============= Various Sections ============================= -->
! 3335:
! 3336: <!-- Here you should add, if necessary, several more sect1's,
! 3337: describing other windows (besides the main one), file formats,
! 3338: preferences dialogs, etc. as appropriate. Try not to make any of
! 3339: these sections too long. -->
! 3340:
! 3341:
! 3342: <!-- ============= Bugs ================================== -->
! 3343: <!-- This section should describe known bugs and limitations of
! 3344: the program if there are any - please be frank and list all
! 3345: problems you know of. -->
! 3346: <sect1 id="bugs">
! 3347: <title>Known Bugs and Limitations</title>
! 3348: <para>
! 3349: This application has no known bugs.
! 3350: </para>
! 3351: </sect1>
! 3352:
! 3353:
! 3354: <!-- ============= Authors ================================ -->
! 3355:
! 3356: <sect1 id="authors">
! 3357: <title>Authors</title>
! 3358: <para>
! 3359: <application>MY-GNOME-APP</application> was written by GNOME-HACKER
! 3360: (<email>hacker@gnome.org</email>). To find more information about
! 3361: <application>MY-GNOME-APP</application>, please visit the <ulink
! 3362: url="http://www.my-gnome-app.org" type="http">MY-GNOME-APP Web
! 3363: page</ulink>. Please send all comments, suggestions, and bug
! 3364: reports to the <ulink url="http://bugs.gnome.org" type="http">GNOME
! 3365: bug tracking database</ulink>. (Instructions for submitting bug
! 3366: reports can be found <ulink
! 3367: url="http://bugs.gnome.org/Reporting.html" type="http">
! 3368: on-line</ulink>.) You can also use <application>Bug Report
! 3369: Tool</application> (<command>bug-buddy</command>), available in the
! 3370: <guisubmenu>Utilities</guisubmenu> submenu of <guimenu>Main
! 3371: Menu</guimenu>, for submitting bug reports.
! 3372: </para>
! 3373:
! 3374: <para>
! 3375: This manual was written by ME
! 3376: (<email>MYNAME@MYADDRESS</email>). Please send all comments and
! 3377: suggestions regarding this manual to the <ulink type="http"
! 3378: url="http://developer.gnome.org/projects/gdp">GNOME Documentation
! 3379: Project</ulink> by sending an email to
! 3380: <email>docs@gnome.org</email>. You can also add your comments online
! 3381: by using the <ulink type="http"
! 3382: url="http://www.gnome.org/gdp/doctable/">GNOME Documentation Status
! 3383: Table</ulink>.
! 3384: </para>
! 3385:
! 3386: <!-- For translations: uncomment this:
! 3387:
! 3388: <para>
! 3389: Latin translation was done by ME
! 3390: (<email>MYNAME@MYADDRESS</email>). Please send all comments and
! 3391: suggestions regarding this translation to SOMEWHERE.
! 3392: </para>
! 3393:
! 3394: -->
! 3395:
! 3396: </sect1>
! 3397:
! 3398:
! 3399: <!-- ============= Application License ============================= -->
! 3400:
! 3401: <sect1 id="license">
! 3402: <title>License</title>
! 3403: <para>
! 3404: This program is free software; you can redistribute it and/or
! 3405: modify it under the terms of the <citetitle>GNU General Public
! 3406: License</citetitle> as published by the Free Software Foundation;
! 3407: either version 2 of the License, or (at your option) any later
! 3408: version.
! 3409: </para>
! 3410: <para>
! 3411: This program is distributed in the hope that it will be useful, but
! 3412: WITHOUT ANY WARRANTY; without even the implied warranty of
! 3413: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
! 3414: <citetitle>GNU General Public License</citetitle> for more details.
! 3415: </para>
! 3416: <para>
! 3417: A copy of the <citetitle>GNU General Public License</citetitle> is
! 3418: included as an appendix to the <citetitle>GNOME Users
! 3419: Guide</citetitle>. You may also obtain a copy of the
! 3420: <citetitle>GNU General Public License</citetitle> from the Free
! 3421: Software Foundation by visiting <ulink type="http"
! 3422: url="http://www.fsf.org">their Web site</ulink> or by writing to
! 3423: <address>
! 3424: Free Software Foundation, Inc.
! 3425: <street>59 Temple Place</street> - Suite 330
! 3426: <city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>
! 3427: <country>USA</country>
! 3428: </address>
! 3429: </para>
! 3430: </sect1>
! 3431: </article>
! 3432:
! 3433:
! 3434:
! 3435:
! 3436:
! 3437:
! 3438:
! 3439:
! 3440:
! 3441: ]]>
! 3442:
! 3443:
! 3444: </programlisting>
! 3445: </para>
! 3446: </sect1>
! 3447:
! 3448: <!-- ####### Document Templates | Templates 2-1.x: Applet Manual ####### -->
! 3449:
! 3450: <sect1 id="template2-1x">
! 3451: <title>Template 2: Applet Manual For GNOME 1.x</title>
! 3452: <para>
! 3453: The following templates should be used for all applet
! 3454: manuals in GNOME 1.x releases. You can always get the latest
! 3455: copy of these templates from <ulink type="http"
! 3456: url="http://developer.gnome.org/projects/gdp/templates.html">GDP
! 3457: Documentation Templates</ulink>. Note that the template
! 3458: consists of two files; the first file calls the second as an
! 3459: entity. You should name the first file
! 3460: <filename><replaceable>appletname</replaceable>-applet.sgml</filename>
! 3461: and the second file should be named
! 3462: <filename><replaceable>appletname</replaceable>.sgml</filename>,
! 3463: where
! 3464: <filename><replaceable>appletname</replaceable></filename> is
! 3465: the name of the applet.
! 3466: <programlisting>
! 3467:
! 3468: <![CDATA[
! 3469: <!DOCTYPE Article PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
! 3470: <!entity APPLETNAME.sgml SYSTEM "applet_template_1.sgml">
! 3471: <!-- Template Version: 1.0.1 (do not remove this line) -->
! 3472: ]>
! 3473:
! 3474: <!-- This is a GNOME documentation template, designed by the GNOME
! 3475: Documentation Project Team. Please use it for writing GNOME
! 3476: documentation, making obvious changes. In particular, all the words
! 3477: written in UPPERCASE (with the exception of GNOME) should be
! 3478: replaced. As for "legalnotice", please leave the reference
! 3479: unchanged,make sure to add/remove trademarks to the list as
! 3480: appropriate for your document.
! 3481:
! 3482: Please don't forget to remove these comments in your final documentation,
! 3483: thanks ;-).
! 3484: -->
! 3485:
! 3486: <article id="index"> <!-- please do not change the id -->
! 3487:
! 3488: <!-- ============= Document Header ============================= -->
! 3489: <artheader>
! 3490: <title>APPLETNAME Applet</title>
! 3491: <copyright>
! 3492: <year>2000</year>
! 3493: <holder>YOURFULLNAME</holder>
! 3494: </copyright>
! 3495:
! 3496: <!-- translators: uncomment this:
! 3497:
! 3498: <copyright>
! 3499: <year>2000</year>
! 3500: <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
! 3501: </copyright>
! 3502:
! 3503: -->
! 3504:
! 3505: <!-- do not put authorname in the header except in copyright - use
! 3506: section "authors" below -->
! 3507:
! 3508: <legalnotice>
! 3509: <para>
! 3510: Permission is granted to copy, distribute and/or modify this
! 3511: document under the terms of the <citetitle>GNU Free Documentation
! 3512: License</citetitle>, Version 1.1 or any later version published
! 3513: by the Free Software Foundation with no Invariant Sections, no
! 3514: Front-Cover Texts, and no Back-Cover Texts. You may obtain a copy
! 3515: of the <citetitle>GNU Free Documentation License</citetitle> from
! 3516: the Free Software Foundation by visiting <ulink type="http"
! 3517: url="http://www.fsf.org">their Web site</ulink> or by writing to:
! 3518: Free Software Foundation, Inc., 59 Temple Place - Suite 330,
! 3519: Boston, MA 02111-1307, USA.
! 3520: </para>
! 3521: <para>
! 3522: Many of the names used by companies to distinguish their products and
! 3523: services are claimed as trademarks. Where those names appear in any
! 3524: GNOME documentation, and those trademarks are made aware to the members
! 3525: of the GNOME Documentation Project, the names have been printed in caps
! 3526: or initial caps.
! 3527: </para>
! 3528: </legalnotice>
! 3529:
! 3530: <releaseinfo>
! 3531: This is version XXX of the APPLETNAME applet manual.
! 3532: </releaseinfo>
! 3533: </artheader>
! 3534:
! 3535: <!-- ============= Document Body ============================= -->
! 3536:
! 3537: &APPLETNAME.sgml;
! 3538:
! 3539: </article>
! 3540:
! 3541:
! 3542: ]]>
! 3543:
! 3544:
! 3545: </programlisting>
! 3546: <programlisting>
! 3547: <![CDATA[
! 3548: <!-- Template Version: 1.0.1 (do not remove this line) -->
! 3549:
! 3550: <sect1 id="APPLET">
! 3551: <title>APPLET Applet</title>
! 3552:
! 3553: <para>
! 3554: <application>APPLET</application> applet, shown in <xref
! 3555: linkend="APPLETapplet-fig">, allows you to …. To add this
! 3556: applet to a <interface>Panel</interface>,
! 3557: right-click on the <interface>Panel</interface> and choose
! 3558: <menuchoice>
! 3559: <guimenu>Panel</guimenu>
! 3560: <guisubmenu>Add to panel</guisubmenu>
! 3561: <guisubmenu>Applet</guisubmenu>
! 3562: <guisubmenu>SECTION</guisubmenu>
! 3563: <guimenuitem>APPLET</guimenuitem>
! 3564: </menuchoice>.
! 3565: </para>
! 3566:
! 3567: <figure id="APPLETapplet-fig">
! 3568: <title>APPLET Applet</title>
! 3569: <screenshot>
! 3570: <screeninfo>APPLET Applet</screeninfo>
! 3571: <graphic format="png" fileref="APPLET_applet"
! 3572: srccredit="YOURNAME">
! 3573: </graphic>
! 3574: </screenshot>
! 3575: </figure>
! 3576:
! 3577: <!-- ============= Usage ================================ -->
! 3578: <sect2 id="APPLET-usage">
! 3579: <title>Usage</title>
! 3580: <para>
! 3581: (Place a short description of how to use the applet here.)
! 3582: </para>
! 3583:
! 3584: <para>
! 3585: Right-clicking on the applet brings up a menu containing the
! 3586: following items:
! 3587: <itemizedlist>
! 3588:
! 3589: <listitem>
! 3590: <para>
! 3591: <guimenuitem>Properties…</guimenuitem> —
! 3592: opens the <link linkend="APPLET-prefs">
! 3593: <guilabel>Properties</guilabel></link> dialog.
! 3594: </para>
! 3595: </listitem>
! 3596:
! 3597: <listitem>
! 3598: <para>
! 3599: <guimenuitem>Help</guimenuitem> —
! 3600: displays this document.
! 3601: </para>
! 3602: </listitem>
! 3603:
! 3604: <listitem>
! 3605: <para>
! 3606: <guimenuitem>About…</guimenuitem> —
! 3607: shows basic information about <application>APPLET
! 3608: Applet</application>, including the applet's version and the
! 3609: author's name.
! 3610: </para>
! 3611: </listitem>
! 3612:
! 3613: </itemizedlist>
! 3614: </para>
! 3615: </sect2>
! 3616:
! 3617:
! 3618: <!-- ============= Customization ============================= -->
! 3619: <sect2 id="APPLET-prefs">
! 3620: <title>Customization</title>
! 3621: <para>
! 3622: You can customize <application>APPLET</application>
! 3623: applet by right-clicking on it and choosing
! 3624: <guimenuitem>Properties…</guimenuitem>. This will open the
! 3625: <interface>Properties</interface> dialog(shown in <xref
! 3626: linkend="APPLET-settings-fig">), which allows you to
! 3627: change various settings.
! 3628: </para>
! 3629:
! 3630: <figure id="APPLET-settings-fig">
! 3631: <title>Properties dialog</title>
! 3632: <screenshot>
! 3633: <screeninfo>Properties dialog</screeninfo>
! 3634: <graphic format="png" fileref="APPLET_settings"
! 3635: srccredit="YOURNAME">
! 3636: </graphic>
! 3637: </screenshot>
! 3638: </figure>
! 3639:
! 3640: <para>
! 3641: The properties are:
! 3642: <itemizedlist>
! 3643:
! 3644: <listitem>
! 3645: <para>
! 3646: (Configuration Item Label) — If this button is
! 3647: checked…(description)
! 3648: </para>
! 3649: </listitem>
! 3650:
! 3651: <listitem>
! 3652: <para>
! 3653: (Configuration Item Label) — Selecting this
! 3654: button…(description)
! 3655: </para>
! 3656: </listitem>
! 3657:
! 3658: <listitem>
! 3659: <para>
! 3660: (Configuration Item Label) — Enter the name of
! 3661: …(description)
! 3662: </para>
! 3663: </listitem>
! 3664: </itemizedlist>
! 3665: </para>
! 3666:
! 3667: <para>
! 3668: After you have made all the changes you want, click on
! 3669: <guibutton>OK</guibutton> to apply the changes and close the
! 3670: <interface>Properties</interface> dialog. To cancel the changes
! 3671: and return to previous values, click the
! 3672: <guibutton>Close</guibutton> button.
! 3673: </para>
! 3674: </sect2>
! 3675:
! 3676:
! 3677: <!-- ============= Bugs ================================== -->
! 3678: <!-- This section should describe known bugs and limitations of
! 3679: the program if there are any - please be frank and list all
! 3680: problems you know of -->
! 3681: <sect2 id="bugs">
! 3682: <title>Known Bugs and Limitations</title>
! 3683: <para>
! 3684: This applet has no known bugs.
! 3685: </para>
! 3686: </sect2>
! 3687:
! 3688:
! 3689: <!-- ============= Authors ================================ -->
! 3690:
! 3691: <sect2 id="authors">
! 3692: <title>Authors</title>
! 3693: <para>
! 3694: <application>APPLET</application> was written by GNOME-HACKER
! 3695: (<email>hacker@gnome.org</email>). Please send all comments,
! 3696: suggestions, and bug
! 3697: reports to the <ulink url="http://bugs.gnome.org" type="http">GNOME
! 3698: bug tracking database</ulink>. (Instructions for submitting bug
! 3699: reports can be found <ulink
! 3700: url="http://bugs.gnome.org/Reporting.html" type="http">
! 3701: on-line</ulink>. You can also use <application>Bug Report
! 3702: Tool</application> (<command>bug-buddy</command>), available in the
! 3703: <guisubmenu>Utilities</guisubmenu> submenu of <guimenu>Main
! 3704: Menu</guimenu>, for submitting bug reports.
! 3705: </para>
! 3706:
! 3707: <para>
! 3708: This manual was written by ME
! 3709: (<email>MYNAME@MYADDRESS</email>). Please send all comments and
! 3710: suggestions regarding this manual to the <ulink type="http"
! 3711: url="http://developer.gnome.org/projects/gdp">GNOME Documentation
! 3712: Project</ulink> by sending an email to
! 3713: <email>docs@gnome.org</email>. You can also submit comments online
! 3714: by using the <ulink type="http"
! 3715: url="http://www.gnome.org/gdp/doctable/">GNOME Documentation
! 3716: Status Table</ulink>.
! 3717: </para>
! 3718:
! 3719: <!-- For translations: uncomment this:
! 3720:
! 3721: <para>
! 3722: Latin translation was done by ME
! 3723: (<email>MYNAME@MYADDRESS</email>). Please send all comments and
! 3724: suggestions regarding this translation to SOMEWHERE.
! 3725: </para>
! 3726:
! 3727: -->
! 3728:
! 3729: </sect2>
! 3730:
! 3731:
! 3732: <!-- ============= Application License ============================= -->
! 3733:
! 3734: <sect2 id="license">
! 3735: <title>License</title>
! 3736: <para>
! 3737: This program is free software; you can redistribute it and/or
! 3738: modify it under the terms of the <citetitle>GNU General Public
! 3739: License</citetitle> as published by the Free Software Foundation;
! 3740: either version 2 of the License, or (at your option) any later
! 3741: version.
! 3742: </para>
! 3743: <para>
! 3744: This program is distributed in the hope that it will be useful, but
! 3745: WITHOUT ANY WARRANTY; without even the implied warranty of
! 3746: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
! 3747: <citetitle>GNU General Public License</citetitle> for more details.
! 3748: </para>
! 3749: <para>
! 3750: A copy of the <citetitle>GNU General Public License</citetitle> is
! 3751: included as an appendix to the <citetitle>GNOME Users
! 3752: Guide</citetitle>. You may also obtain a copy of the
! 3753: <citetitle>GNU General Public License</citetitle> from the Free
! 3754: Software Foundation by visiting <ulink type="http"
! 3755: url="http://www.fsf.org">their Web site</ulink> or by writing to
! 3756: <address>
! 3757: Free Software Foundation, Inc.
! 3758: <street>59 Temple Place</street> - Suite 330
! 3759: <city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>
! 3760: <country>USA</country>
! 3761: </address>
! 3762: </para>
! 3763: </sect2>
! 3764:
! 3765: </sect1>
! 3766:
! 3767:
! 3768:
! 3769:
! 3770: ]]>
! 3771:
! 3772:
! 3773:
! 3774: </programlisting>
! 3775: </para>
! 3776: </sect1>
! 3777:
! 3778: <!-- ####### Document Templates | Templates 2-2.x: Applet Manual ####### -->
! 3779:
! 3780: <sect1 id="template2-2x">
! 3781: <title>Template 2: Applet Manual For GNOME 2.x</title>
! 3782: <para>
! 3783: The following templates should be used for all applet
! 3784: manuals in GNOME 2.x releases. You can always get the latest
! 3785: copy of these templates from <ulink type="http"
! 3786: url="http://developer.gnome.org/projects/gdp/templates.html">GDP
! 3787: Documentation Templates</ulink>.
! 3788: </para>
! 3789: <para>
! 3790: Note that this template consists of two files. The first file
! 3791: is an introductory chapter. You should not modify this
! 3792: chapter. The second file is the actual applet document, which
! 3793: you should modify to describe the applet you are documenting.
! 3794: You can name the first file whatever you like, such as
! 3795: <filename>gnome-applets.sgml</filename>. Name the second file
! 3796: according to the applet's name:
! 3797: <filename><replaceable>appletname</replaceable>-applet.sgml</filename>.
! 3798: Make sure you update the entity
! 3799: at the top of the shell document to reflect the new name of
! 3800: the applet document.
! 3801: </para>
! 3802: <para>
! 3803: <programlisting>
! 3804: <![CDATA[
! 3805: <!DOCTYPE book PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
! 3806: <!ENTITY TEMPLATE-APPLET SYSTEM "gnome-applet-template.sgml.part">
! 3807:
! 3808: ]>
! 3809:
! 3810: <book id="gnome-applets">
! 3811:
! 3812: <bookinfo>
! 3813: <title>GNOME Applets</title>
! 3814: <authorgroup>
! 3815: <author><firstname>Telsa</firstname><surname>Gwynne</surname></author>
! 3816: <author><firstname>John</firstname><surname>Fleck</surname></author>
! 3817: <author><firstname>David</firstname><surname>Mason</surname>
! 3818: <affiliation><orgname>Red Hat, Inc.</orgname></affiliation>
! 3819: </author>
! 3820: <author><firstname>Dan</firstname><surname>Mueth</surname></author>
! 3821: <author><firstname>Alexander</firstname><surname>Kirillov</surname></author>
! 3822: </authorgroup>
! 3823: <edition>GNOME Applets version 0.1 for GNOME 1.1.5</edition>
! 3824: <pubdate>2000</pubdate>
! 3825: <copyright>
! 3826: <year>2000</year>
! 3827: <holder>Telsa Gwynne, John Fleck, Red Hat Inc., Dan Mueth, and
! 3828: Alexander Kirillov</holder>
! 3829: </copyright>
! 3830: <legalnotice>
! 3831: <para>
! 3832: Permission is granted to make and distribute verbatim copies of this
! 3833: manual provided the copyright notice and this permission notice are
! 3834: preserved on all copies.
! 3835: </para>
! 3836: <para>
! 3837: Permission is granted to copy and distribute modified versions of
! 3838: this manual under the conditions for verbatim copying, provided that
! 3839: the entire resulting derived work is distributed under the terms of a
! 3840: permission notice identical to this one.
! 3841: </para>
! 3842: <para>
! 3843: Permission is granted to copy and distribute translations of this
! 3844: manual into another language, under the above conditions for modified
! 3845: versions, except that this permission notice may be stated in a
! 3846: translation approved by the Free Software Foundation.
! 3847: </para>
! 3848: <para>
! 3849: Many of the names used by companies to distinguish their products and
! 3850: services are claimed as trademarks. Where those names appear in any
! 3851: GNOME documentation, and those trademarks are made aware to the members
! 3852: of the GNOME Documentation Project, the names have been printed in caps
! 3853: or initial caps.
! 3854: </para>
! 3855: </legalnotice>
! 3856: </bookinfo>
! 3857:
! 3858: <!-- #### Introduction ###### -->
! 3859: <chapter id="applets-intro">
! 3860: <title>Introduction</title>
! 3861:
! 3862: <!-- #### Intro | What Are Applets? ###### -->
! 3863: <sect1 id="applets-what-are">
! 3864: <title>What Are Applets?</title>
! 3865: <para>
! 3866: Applets are one of the most popular and useful objects you can add
! 3867: to your <interface>Panel</interface> to customize your desktop.
! 3868: An applet is a small application which runs inside a small area of
! 3869: your <interface>Panel</interface>. Applets have been written for
! 3870: a wide range of purposes. Some are very powerful interactive
! 3871: tools, such as the <application>Tasklist</application> Applet
! 3872: which allows you to easily
! 3873: control all of your main applications. Others are simple system
! 3874: monitors, displaying information such as the amount of power left
! 3875: in the battery on your laptop (see <application>Battery Charge
! 3876: Monitor</application>) or weather
! 3877: information(see <application>GNOME Weather</application>). Some
! 3878: are simply for amusement(see <application>Fish</application>).
! 3879: </para>
! 3880:
! 3881: <para>
! 3882: Applets are similar to swallowed applications in that both of them
! 3883: reside within the <interface>Panel</interface>. However,
! 3884: swallowed applications are generally applications which were
! 3885: not designed to run within the <interface>Panel</interface>.
! 3886: Typically one will swallow an application which already exists in
! 3887: the main <interface>desktop</interface> area, putting it into your
! 3888: <interface>Panel</interface>. The application will continue to
! 3889: run in the <interface>Panel</interface> until you end the
! 3890: application or unswallow it, placing it back onto the main part of
! 3891: your desktop when you need to.
! 3892: </para>
! 3893:
! 3894: <para>
! 3895: <figure id="example-applets-fig">
! 3896: <title>Example Applets</title>
! 3897: <screenshot>
! 3898: <screeninfo>Example Applets</screeninfo>
! 3899: <graphic fileref="example_applets" format="png"
! 3900: srccredit="muet">
! 3901: </graphic>
! 3902: </screenshot>
! 3903: </figure>
! 3904: Several example applets are shown in <xref
! 3905: linkend="example-applets-fig">. From left to right, they are: (1)
! 3906: <application>Mixer Applet</application>, which allows you to turn
! 3907: on/off sound and control its volume by clicking on the applet. (2)
! 3908: <application>Sound Monitor</application> Applet, which displays
! 3909: the current volume of sound being played and allows you to control
! 3910: various sound features. (3) <application>GTCD</application>
! 3911: Applet, a CD player which has all its controls
! 3912: available in the applet and displays the track and time. (4)
! 3913: <application>Drive Mount</application> Applet, used to mount and
! 3914: unmount drives with a single click of the mouse. (5)
! 3915: <application>Desk Guide</application> which allows you to view
! 3916: and control multiple virtual screens. (6)
! 3917: <application>Tasklist</application> Applet which allows you to
! 3918: control your various windows and applications.
! 3919: </para>
! 3920: <para>
! 3921: There are many other applets to choose from. The rest of this
! 3922: chapter will explain the basic information to get you started
! 3923: adding, moving, and removing applets from your
! 3924: <interface>Panels</interface> and using them. The following
! 3925: chapters go through each of the standard GNOME applets describing
! 3926: them in detail. There are also additional applets which can be
! 3927: downloaded off the Web. See <ulink type="http"
! 3928: url="http://www.gnome.org/applist/list-martin.phtml">The GNOME
! 3929: Software Map</ulink> for lists of additional GNOME applications
! 3930: and applets.
! 3931: </para>
! 3932: <para>
! 3933: As you read through the the rest of this chapter, you should try
! 3934: adding and removing applets from your <interface>Panel</interface> and
! 3935: experiment with them freely.
! 3936: </para>
! 3937: </sect1>
! 3938:
! 3939: <!-- #### Intro | Adding, Moving, and Removing Applets ###### -->
! 3940: <sect1 id="applet-add-move-replace">
! 3941: <title>Adding, Moving, and Removing Applets</title>
! 3942:
! 3943: <sect2 id="adding-applets">
! 3944: <title>Adding Applets to a Panel</title>
! 3945: <para>
! 3946: To add an applet to a <interface>Panel</interface>, right-click
! 3947: on the <interface>Panel</interface> and select
! 3948: <menuchoice><guimenu>Panel</guimenu><guisubmenu>Add to panel</guisubmenu>
! 3949: <guisubmenu>Applet</guisubmenu></menuchoice>. This will show you
! 3950: the menu of all the applets on your system, divided into
! 3951: categories. Choosing any applet from this menu will add it to the
! 3952: <interface>Panel</interface>.
! 3953: </para>
! 3954: </sect2>
! 3955:
! 3956: <sect2 id="moving-applets">
! 3957: <title>Moving Applets In or Between Panels</title>
! 3958: <para>
! 3959: It is easy to move applets in a <interface>Panel</interface> or
! 3960: between two <interface>Panels</interface>. If you have a
! 3961: three-button mouse, just move the mouse over the applet, depress
! 3962: the middle mouse button and drag the applet to its new location,
! 3963: releasing the middle mouse button when you are finished. Note
! 3964: that you can drag applets within a <interface>Panel</interface>
! 3965: or between two <interface>Panels</interface> this way. If you
! 3966: don't have a three-button mouse, just
! 3967: right-click on the applet and choose
! 3968: <guimenuitem>Move</guimenuitem>. The cursor will turn into a
! 3969: cross and the applet will move with your mouse until you press
! 3970: any mouse button to indicate you are finished moving it.
! 3971: If, in the course of this movement, it hits
! 3972: other objects, the behavior depends on the global preferences
! 3973: you have set for your <interface>Panels</interface> in the
! 3974: <application>GNOME Control Center</application>: the applet you are
! 3975: moving can switch places with other objects, "push" all objects
! 3976: it meets, or "jump" over all other objects without disturbing
! 3977: them. You can also override the default behavior by holding
! 3978: <keycap>Shift</keycap> button (for "push" mode),
! 3979: <keycap>Ctrl</keycap> (for "switched" mode), or
! 3980: <keycap>Alt</keycap> (for "free" mode, i.e. jumping other other
! 3981: objects without disturbing them) button while dragging.
! 3982: </para>
! 3983: <para>
! 3984: To change the global Panel preferences, right-click on any applet
! 3985: or <interface>Panel</interface> and select
! 3986: <menuchoice>
! 3987: <guimenu>Panel</guimenu>
! 3988: <guimenuitem>Global Preferences...</guimenuitem>
! 3989: </menuchoice>.
! 3990: The <guilabel>Default movement mode</guilabel> is set under the
! 3991: <guilabel>Applets</guilabel> tab.
! 3992: </para>
! 3993: </sect2>
! 3994:
! 3995: <sect2 id="removing-applets">
! 3996: <title>Removing Applets from a Panel</title>
! 3997: <para>
! 3998: To remove an applet from a <interface>Panel</interface>,
! 3999: right-click on the applet and select <guimenuitem>Remove from
! 4000: panel...</guimenuitem>.
! 4001: </para>
! 4002: </sect2>
! 4003: </sect1>
! 4004:
! 4005:
! 4006: <!-- #### Intro | The Right-Click Pop-Up Menu ###### -->
! 4007: <sect1 id="right-click-pop-up-menu">
! 4008: <title>The Right-Click Pop-Up Menu</title>
! 4009: <para>
! 4010: Clicking the right mouse button on any applet brings up
! 4011: a <guimenu>pop-up menu</guimenu>. This
! 4012: menu always has certain standard menu items in it and
! 4013: often has additional items which vary depending on the particular
! 4014: applet.
! 4015: </para>
! 4016: <sect2 id="standard-right-click-items">
! 4017: <title>Standard Pop-Up Items</title>
! 4018: <para>
! 4019: All applets should have the following items in their right-click
! 4020: <guimenu>pop-up menu</guimenu>:
! 4021: <variablelist>
! 4022: <varlistentry>
! 4023: <term>Remove from panel</term>
! 4024: <listitem>
! 4025: <para>
! 4026: The <guimenuitem>Remove from panel</guimenuitem> menu item
! 4027: removes the applet from the <interface>Panel</interface>.
! 4028: </para>
! 4029: </listitem>
! 4030: </varlistentry>
! 4031:
! 4032: <varlistentry>
! 4033: <term>Move</term>
! 4034: <listitem>
! 4035: <para>
! 4036: After selecting <guimenuitem>Move</guimenuitem>, your mouse
! 4037: pointer will change appearance (typically to a cross with
! 4038: arrows in each direction). As you move your mouse, the applet
! 4039: will move with it. When you have finished moving the applet,
! 4040: click any mouse button and the applet will anchor in its
! 4041: current position. Note that applets can be moved between two
! 4042: <interface>Panels</interface> this way.
! 4043: </para>
! 4044: </listitem>
! 4045: </varlistentry>
! 4046:
! 4047: <varlistentry>
! 4048: <term>Panel</term>
! 4049: <listitem>
! 4050: <para>
! 4051: The <guisubmenu>Panel</guisubmenu> submenu contains various
! 4052: items and submenus for adding and removing
! 4053: <interface>Panels</interface> and applets and for changing
! 4054: the configuration.
! 4055: </para>
! 4056: </listitem>
! 4057: </varlistentry>
! 4058:
! 4059: <varlistentry>
! 4060: <term>About</term>
! 4061: <listitem>
! 4062: <para>
! 4063: The <guimenuitem>About...</guimenuitem> menu item brings up a
! 4064: dialogue box containing various information about the applet,
! 4065: typically including the applet's name, version, author,
! 4066: copyright, license and desciption.
! 4067: </para>
! 4068: </listitem>
! 4069: </varlistentry>
! 4070:
! 4071: <varlistentry>
! 4072: <term>Help</term>
! 4073: <listitem>
! 4074: <para>
! 4075: The <guimenuitem>Help</guimenuitem> menu item brings up the help
! 4076: manual for the applet.
! 4077: </para>
! 4078: </listitem>
! 4079: </varlistentry>
! 4080: </variablelist>
! 4081: </para>
! 4082: </sect2>
! 4083:
! 4084: <sect2 id="applet-properties-dialog">
! 4085: <title>The Applet Properties Dialog</title>
! 4086: <para>
! 4087: Many applets have customizable properties. These applets will
! 4088: have a <guimenuitem>Properties...</guimenuitem> menu item in their
! 4089: right-click <guimenu>pop-up menu</guimenu> which brings up the
! 4090: <interface>Properties</interface> dialog where you can alter the
! 4091: appearance or behaviour of the applet.
! 4092: <figure id="example-props-dialog-fig">
! 4093: <title>An Example Applet Properties Dialog</title>
! 4094: <screenshot>
! 4095: <screeninfo>An Example Applets Properties Dialog</screeninfo>
! 4096: <graphic fileref="applet_props_dialog" format="png"
! 4097: srccredit="muet">
! 4098: </graphic>
! 4099: </screenshot>
! 4100: </figure>
! 4101: All <interface>Properties</interface> dialogs have the following
! 4102: buttons at the bottom of the dialog:
! 4103: <itemizedlist>
! 4104: <listitem>
! 4105: <para>
! 4106: <guibutton>OK</guibutton> —
! 4107: Pressing <guibutton>OK</guibutton> will activate any changes
! 4108: in the properties you have made and close the
! 4109: <interface>Properties</interface> dialog.
! 4110: </para>
! 4111: </listitem>
! 4112: <listitem>
! 4113: <para>
! 4114: <guibutton>Apply</guibutton> —
! 4115: Pressing <guibutton>Apply</guibutton> at any time will
! 4116: make your changes active without closing the
! 4117: <interface>Properties</interface> dialog. This is helpful if
! 4118: you would like to test the effects of the changes you have
! 4119: made but may want to continue changing the properties.
! 4120: </para>
! 4121: </listitem>
! 4122: <listitem>
! 4123: <para>
! 4124: <guibutton>Close</guibutton> —
! 4125: Pressing <guibutton>Close</guibutton> will close the
! 4126: <interface>Properties</interface> dialog. Only changes in the
! 4127: configuration which were previously applied with the
! 4128: <guibutton>Apply</guibutton> button will persist. Other
! 4129: changes will not be made active.
! 4130: </para>
! 4131: </listitem>
! 4132: <listitem>
! 4133: <para>
! 4134: <guibutton>Help</guibutton> —
! 4135: Pressing <guibutton>Help</guibutton> brings up the manual for
! 4136: the application, opening it to the page describing the
! 4137: <interface>Properties</interface> dialog.
! 4138: </para>
! 4139: </listitem>
! 4140: </itemizedlist>
! 4141: </para>
! 4142: </sect2>
! 4143:
! 4144: <sect2 id="common-right-click-items">
! 4145: <title>Other Common Pop-Up Items</title>
! 4146: <para>
! 4147: Many applets also have one or more of the following items in their
! 4148: right-click pop-up menu:
! 4149: <variablelist>
! 4150: <varlistentry>
! 4151: <term>Run...</term>
! 4152: <listitem>
! 4153: <para>
! 4154: The <guimenuitem>Run...</guimenuitem> menu item generally
! 4155: invokes a program which is related to the applet in some way
! 4156: but which runs in its own window rather than in the
! 4157: panel. For example:
! 4158: </para>
! 4159: <orderedlist>
! 4160: <listitem>
! 4161: <para>
! 4162: The <application>CPU Load</application> applet, which monitors
! 4163: what programs are running, has a <guimenuitem>Run
! 4164: gtop...</guimenuitem> menu item. Selecting this menu item
! 4165: starts <application>GTop</application>, which allows you to
! 4166: view and control programs which are running.
! 4167: </para>
! 4168: </listitem>
! 4169: <listitem>
! 4170: <para>
! 4171: The <application>CD Player</application> applet has a
! 4172: <guimenuitem>Run gtcd...</guimenuitem> menu item which
! 4173: starts the GNOME <application>CD Player</application> when
! 4174: selected, which has more capabilities than the applet.
! 4175: </para>
! 4176: </listitem>
! 4177: </orderedlist>
! 4178: </listitem>
! 4179: </varlistentry>
! 4180: </variablelist>
! 4181: </para>
! 4182: </sect2>
! 4183: </sect1>
! 4184:
! 4185: <sect1 id="feedback">
! 4186: <title>Feedback</title>
! 4187: <sect2 id="reporting-bugs">
! 4188: <title>Reporting Applet Bugs</title>
! 4189: <para>
! 4190: GNOME users are encouraged to report bugs to <ulink type="http"
! 4191: url="http://bugs.gnome.org">The GNOME Bug Tracking
! 4192: System</ulink>. The easiest way to submit bugs is to use the
! 4193: <application>Bug Report Tool</application> program by selecting
! 4194: <menuchoice>
! 4195: <guimenu>Main Menu</guimenu> <guisubmenu>Utilities</guisubmenu>
! 4196: <guimenuitem>Bug Report Tool</guimenuitem>
! 4197: </menuchoice>.
! 4198: Be sure to be complete in describing what you did to cause the
! 4199: bug to surface and, if possible, describe how the developer can
! 4200: reproduce the the scenario.
! 4201: </para>
! 4202: </sect2>
! 4203: <sect2 id="documentation-feedback">
! 4204: <title>Providing Feedback</title>
! 4205: <para>
! 4206: GNOME users are welcome to provide suggestions for how
! 4207: applications and documentation can be improved. Suggestions for
! 4208: application changes should be submitted using the
! 4209: <application>Bug Report Tool</application> discussed above.
! 4210: Suggestions for documentation changes can be emailed directly to
! 4211: the documentation author (whose email should be included in the
! 4212: "Authors" section of the document) or by sending an email to
! 4213: <email>docs@gnome.org</email>.
! 4214: </para>
! 4215: </sect2>
! 4216: <sect2 id="joining-gnome">
! 4217: <title>Joining GNOME</title>
! 4218: <para>
! 4219: GNOME is a community project, created by hundreds of programmers,
! 4220: documentation writers, icon design artists, web masters, and
! 4221: other people, most of whom work on a volunteer basis. New GNOME
! 4222: contributors are always welcome. To join the GNOME team, visit
! 4223: these web sites: developers — <ulink type="http"
! 4224: url="http://developer.gnome.org">The GNOME Development
! 4225: Site</ulink>, documentation writers — <ulink type="http"
! 4226: url="http://developer.gnome.org/projects/gdp">The GNOME Documentation
! 4227: Project</ulink>, icon design artists — <ulink type="http"
! 4228: url="http://gnome-icons.sourceforge.net/">Gnome Icon Web</ulink>,
! 4229: general — <ulink type="http"
! 4230: url="http://developer.gnome.org/helping/">Helping GNOME</ulink>,
! 4231: or just join the gnome-list email list (see <ulink type="http"
! 4232: url="http://www.gnome.org/resources/mailing-lists.html">GNOME Mailing
! 4233: Lists</ulink>) to discuss what you are interested in doing.
! 4234: </para>
! 4235: </sect2>
! 4236: </sect1>
! 4237: </chapter>
! 4238:
! 4239: <!-- ############### Template Applets ##################### -->
! 4240: <chapter id="template-applets">
! 4241: <title>Template Applets</title>
! 4242:
! 4243: &TEMPLATE-APPLET
! 4244:
! 4245: </chapter>
! 4246:
! 4247: </book>
! 4248:
! 4249:
! 4250:
! 4251:
! 4252:
! 4253:
! 4254:
! 4255: ]]>
! 4256: </programlisting>
! 4257:
! 4258: <programlisting>
! 4259: <![CDATA[
! 4260:
! 4261: <!-- Please replace everywhere below GNOMEAPPLET with the name of -->
! 4262: <!-- your applet. Most importantly, all id attributes should start -->
! 4263: <!-- with the name of your applet - this is necessary to avoid name -->
! 4264: <!-- conflict among different applets -->
! 4265: <!-- Please replace YOUR-NAME with your name and YOUR-EMAIL with your email-->
! 4266: <!-- Please replace HACKER-NAME with the applet author's name and -->
! 4267: <!-- HACKER-EMAIL with the applet author's email -->
! 4268:
! 4269: <!-- You should name your file: GNOMEAPPLET-applet.sgml -->
! 4270: <!-- Screenshots should be in PNG format and placed in the -->
! 4271: <!-- same directory as GNOMEAPPLET-applet.sgml -->
! 4272:
! 4273: <!-- Applet docs will be merged into <chapter>'s inside a -->
! 4274: <!-- <book>. Thus, the indentation below (2 spaces before the <sect1>) is -->
! 4275: <!-- correct.-->
! 4276:
! 4277: <!-- Permission is granted to make and distribute verbatim copies of -->
! 4278: <!-- this manual provided the copyright notice and this permission -->
! 4279: <!-- notice are preserved on all copies. -->
! 4280: <!-- -->
! 4281: <!-- Permission is granted to copy and distribute modified versions of -->
! 4282: <!-- this manual under the conditions for verbatim copying, provided -->
! 4283: <!-- that the entire resulting derived work is distributed under the -->
! 4284: <!-- terms of a permission notice identical to this one. -->
! 4285: <!-- -->
! 4286: <!-- Permission is granted to copy and distribute translations of this -->
! 4287: <!-- manual into another language, under the above conditions for -->
! 4288: <!-- modified versions, except that this permission notice may be -->
! 4289: <!-- stated in a translation approved by the Foundation. -->
! 4290:
! 4291: <!-- ############### GNOMEAPPLET ############### -->
! 4292: <sect1 id="GNOMEAPPLET">
! 4293: <title>GNOMEAPPLET Applet</title>
! 4294:
! 4295: <para>
! 4296: <application>GNOMEAPPLET</application> applet, shown in <xref
! 4297: linkend="GNOMEAPPLET-fig">, does this and that. To learn how to
! 4298: add this applet to a <interface>Panel</interface>, see <xref
! 4299: linkend="adding-applets">.
! 4300: </para>
! 4301:
! 4302:
! 4303: <figure id="GNOMEAPPLET-fig">
! 4304: <title>GNOMEAPPLET</title>
! 4305: <screenshot>
! 4306: <screeninfo>GNOMEAPPLET</screeninfo>
! 4307: <graphic format="png" fileref="GNOMEAPPLET-fig" srccredit="ME">
! 4308: </graphic>
! 4309: </screenshot>
! 4310: </figure>
! 4311:
! 4312: <sect2 id="GNOMEAPPLET-usage">
! 4313: <title>Usage</title>
! 4314: <para>
! 4315: This applet does nothing. To use it, just
! 4316: left-click on it and it will instantly do nothing.
! 4317: </para>
! 4318: </sect2>
! 4319:
! 4320: <sect2 id="GNOMEAPPLET-right-click">
! 4321: <title>Right-Click Pop-Up Menu Items</title>
! 4322: <para>
! 4323: In addition to the standard menu items (see <xref
! 4324: linkend="standard-right-click-items">), the right-click pop-up menu has
! 4325: the following items:
! 4326: <itemizedlist>
! 4327: <listitem>
! 4328: <para>
! 4329: <guimenuitem>Properties...</guimenuitem> — This menu
! 4330: item opens the <interface>Properties</interface> dialog (see
! 4331: <xref linkend="GNOMEAPPLET-properties">) which allows you to
! 4332: customize the appearance and behavior of this applet.
! 4333: </para>
! 4334: </listitem>
! 4335: <listitem>
! 4336: <para>
! 4337: <guimenuitem>Run Hello World...</guimenuitem> — This
! 4338: menu item starts the program <application>Hello
! 4339: World</application>, used to say "hello" to the world.
! 4340: </para>
! 4341: </listitem>
! 4342: </itemizedlist>
! 4343: </para>
! 4344: </sect2>
! 4345:
! 4346: <sect2 id="GNOMEAPPLET-properties">
! 4347: <title>Properties</title>
! 4348: <para>
! 4349: You can configure <application>GNOMEAPPLET</application> applet by
! 4350: right-clicking on the applet and choosing the
! 4351: <guimenuitem>Properties...</guimenuitem> menu item. This will open the
! 4352: <interface>Properties</interface> dialog, shown in <xref
! 4353: linkend="GNOMEAPPLET-properties-fig">.
! 4354: </para>
! 4355: <figure id="GNOMEAPPLET-properties-fig">
! 4356: <title>Properties Dialog</title>
! 4357: <screenshot>
! 4358: <screeninfo>Properties Dialog</screeninfo>
! 4359: <graphic format="png" fileref="GNOMEAPPLET-properties" srccredit="ME">
! 4360: </graphic>
! 4361: </screenshot>
! 4362: </figure>
! 4363:
! 4364: <para>
! 4365: To change the color of the applet, click on the
! 4366: <guibutton>color</guibutton> button. To change other properties,
! 4367: click on other buttons.
! 4368: </para>
! 4369:
! 4370: <para>
! 4371: For more information on the <interface>Properties</interface>
! 4372: dialog, including descriptions of the <guibutton>OK</guibutton>,
! 4373: <guibutton>Apply</guibutton>, <guibutton>Cancel</guibutton>, and
! 4374: <guibutton>Help</guibutton> buttons, see <xref
! 4375: linkend="applet-properties-dialog">.
! 4376: </para>
! 4377: </sect2>
! 4378:
! 4379: <sect2 id="GNOMEAPPLET-bugs">
! 4380: <title> Known Bugs and Limitations</title>
! 4381: <para>
! 4382: There are no known bugs in the
! 4383: <application>GNOMEAPPLET</application> applet.
! 4384: </para>
! 4385: </sect2>
! 4386:
! 4387: <sect2 id="GNOMEAPPLET-authors">
! 4388: <title>Authors</title>
! 4389: <para>
! 4390: This applet was writen by HACKER-NAME
! 4391: <email>HACKER-EMAIL</email>. The documentation for this applet
! 4392: which you are reading now was written by
! 4393: YOUR-NAME <email>YOUR-EMAIL</email>. For information on submitting
! 4394: bug reports and suggestions for improvements, see <xref
! 4395: linkend="feedback">.
! 4396: </para>
! 4397: </sect2>
! 4398:
! 4399: </sect1>
! 4400:
! 4401:
! 4402:
! 4403:
! 4404:
! 4405: ]]>
! 4406:
! 4407:
! 4408: </programlisting>
! 4409: </para>
! 4410: </sect1>
! 4411:
! 4412: <!-- ####### Document Templates | Templates 3: Application Help #######
! 4413:
! 4414: <sect1 id="template3">
! 4415: <title>Template 2: Application Help</title>
! 4416: <programlisting>
! 4417: <![CDATA[(Put sgml here.)]]> </programlisting>
! 4418: </sect1>
! 4419:
! 4420: ####### Document Templates | Templates 4: Application Context Sensitive Help #######
! 4421:
! 4422: <sect1 id="template4">
! 4423: <title>Template 3: Application Context Sensitive Help</title>
! 4424: <para>
! 4425: Context sensitive help is still in development.
! 4426: </para>
! 4427: </sect1>
! 4428:
! 4429: ####### Document Templates | Templates 5: Complete Application: gnome-hello #######
! 4430:
! 4431: <sect1 id="template5">
! 4432: <title>Template 4: Complete Application: gnome-hello</title>
! 4433: <programlisting>
! 4434: <![CDATA[(Put sgml here.)]]>
! 4435: </programlisting>
! 4436: </sect1>
! 4437:
! 4438: ####### Document Templates | Templates 6: Tutorial #######
! 4439:
! 4440: <sect1 id="template6">
! 4441: <title>Template 5: Tutorial</title>
! 4442: <programlisting>
! 4443: <![CDATA[(Put sgml here.)]]>
! 4444: </programlisting>
! 4445: </sect1>-->
! 4446: </appendix>
! 4447:
! 4448: </article>
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to docbook_0.xml CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / libxml2 / test / relaxng