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