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 (a] 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 (a] 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 (a] 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 (a] 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 (a] 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 (a] mydomain.com</email>)]]> 1834 </programlisting> 1835 which produces: The easiest way to get in touch with me is 1836 by e-mail (<email>me (a] 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 (a] 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 (a] 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 (a] 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 (a] 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 (a] 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 (a] 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 (a] 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> 4449
