Return to docbook_0.xml CVS log | Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / libxml2 / test / relaxng |
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>