David Mason Red Hat, Inc.

dcm@redhat.com

Daniel Mueth

d-mueth@uchicago.edu

Alexander Kirillov

kirillov@math.sunysb.edu

This is a pre-release! 0.99 01.07.2000 2000 Red Hat, Inc., Daniel Mueth, and Alexander Kirillov 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. 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 GNOME Help Browser, 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 view of documentation on a machine by dynamically assembling the documentation of 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 APIs for the GNOME libraries, GNOME White Paper's, GNOME developer tutorials and FAQ's, GNOME Developer's Website, and GNOME Handbook's. User documentation include the GNOME User's Guide, the GNOME FAQ, and GNOME application documentation. Most GNOME applications have their own manual in addition to context sensitive help. 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 gnome-doc-list mailing list . Read , 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 GDP Website. 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 gnome-doc-list mailing list 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. This Handbook uses the following notation: /usr/bin Directory foo.sgml Filename command Command or text that would be typed. replaceable "Variable" text that can be replaced. Program or Doc Code Program or document code This Handbook is a guide for both writing documentation for GNOME components and applications and for properly binding and packaging documentation into GNOME applications. 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 Getting The GNOME Handbook of Writing Software Documentation . Alternately, one may download it anonymously from GNOME CVS under gnome-docu/gdp. The most frequently asked question new contributors have before starting to work on the GDP is "what should I start with?". Because most people involved are volunteers, we do not assign 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. It is also important to spend some time with GNOME to make sure you are familiar enough with it to be authoritative 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. 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 docs@gnome.org. The GDP Documentation Status Table (DocTable) (http://www.gnome.org/gdp/doctable/) 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. You should use the DocTable 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 DocTable also allows people to make announcements and suggestions and to discuss issues in the comments section. Note that the information in the DocTable 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. You may also want to see if there is any documentation in the GNOME User's Guide describing the application which you can extract into the application manual. All documentation for the GNOME project is written in SGML utilizing 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. 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 gnome-doc-list mailing list and a volunteer will mark it up for you. Seeing you document marked up will also be a great way for you to start learning how to use DocBook. Download and install the following DocBook Tools packages: jade,docbook, jadetex, sgml-common, stylesheets. You can find more information on DocBook Tools here. If you are an Emacs user you may want to grab the psgml package as well. This is a major mode for editing sgml files in Emacs. The GDP uses its own DocBook stylesheets. To use the GDP stylesheets, you should download the file gdp-both.dsl from the gnome-docu/gdp/dsssl module in CVS (or from GDP Custom DSSSL Stylesheet)and copy it into /usr/lib/sgml/stylesheets. You will need to point DocBook Tools to this stylesheet with the -d option: db2html -d /usr/lib/sgml/stylesheets/gdp-both.dsl foo.sgml. (Creating an alias to include this option and path is convenient.) Alternately, you could overwrite /usr/lib/sgml/stylesheets/cygnus-both.dsl with gdp-both.dsl. The current version of the DocBook Tools command db2ps does not have a -d option. In order to create PostScript output, you must overwrite /usr/lib/sgml/stylesheets/cygnus-both.dsl with gdp-both.dsl. 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 the documentation. You can read more about the issues involved with gifs at http://www.gnu.org/philosophy/gif.html. 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: Download the GDP DocBook DTD for PNG support and install it where you keep your DTD's. (On Red Hat use /usr/lib/sgml/.) Note that the 3.0 DTD is missing support for the <legalnotice> tag, so it is recommended that you use version 3.1 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: PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.0//EN" "png-support.dtd" If you are using the 3.1 DTD, use: PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.0//EN" "png-support-3.1.dtd" 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: Articles: ]]> Books: ]]> There are many editors available in 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. Probably the two most popular editors available are Emacs and vi. These, and other editors are used regularly by members of the GDP. Emacs does have 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 . The tools available in DocBook Tools allow you to convert your sgml to many different formats including html and postscript. The primary tool being used to make such transformations is an application called Jade. In most cases you will not have to work directly with Jade, you will use the scripts provided by DocBook Tools. To preview your DocBook document, it is easiest to convert it to html. If you have installed the DocBook tools described above, all you have to do is to run the command $db2html mydocument.sgml If there are no sgml syntax errors, this will create a subdirectory mydocument and place there the resulting html files. The title page of the document will be mydocument/index.html, and you can use any browser to view it. You can also convert your document to PostScript by running the command $db2ps mydocument.sgml, after which you can print out or view the resulting .ps file. 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 . 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. 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). To make sure you do not confuse the process you should never include the actual extension of the image file as DocBook Tools will handle that for you. For example: Sample GNOME Display ]]> You will notice in the example that the file myfile.png was referred to as simply myfile. Now when you run db2html to create an html file, it will automatically look for myfile.png in the directory. If you want to create PostScript 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 http://people.redhat.com/dcm/sgml.html (look for the img2eps section). There are many tools available to help you learn DocBook. The following resources on the web are useful for learning DocBook: http://www.docbook.org - Norman Walsh's DocBook: The Definitive Guide. Online O'Reilly book on using DocBook. Contains an excellent element reference. May be too formal for a beginner. A Practical Introduction to DocBook - The Open Source Writers Group's introduction to using DocBook. This is an excellent HOW-TO type article on getting started. Getting Going with DocBook: Notes for Hackers - 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. FreeBSD Documentation Project Primer for New Contributors - 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. Norman Walsh's book is also available in print. The following sections of this document are designed to help documentation authors write correct and consistent DocBook: - Descriptions of commonly used DocBook tags. 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. Examples of various types of GNOME documents are found in . There is also an example GNOME application with documentation called gnome-hello in GNOME cvs. Templates for various types of GNOME documents are found in . 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. To anonymously check out documents from CVS, you must first log in. From the bash shell, you should set your CVSROOT shell variable with export CVSROOT=':pserver:anonymous@anoncvs.gnome.org:/cvs/gnome' and then login with cvs login(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 cvs -z3 checkout gnome-docu/gdp. After you have this document checked out and you would like to download any updates on the CVS server, use cvs -z3 update -Pd. 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 username with a password, you must first set your CVSROOT shell variable with export CVSROOT=':pserver:username@cvs.gnome.org:/cvs/gnome'. Log in with cvs login 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 filename into the CVS server, type cvs -z3 commit filename. 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 EDITOR environment variable or with the -e option. To add a new file to the CVS server, use cvs -z3 add filename, followed by the commit command. 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 ChangeLog 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. At the core of the GNOME help system is the GNOME Help Browser. The Help Browser 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. The GNOME Help Browser 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. In GNOME 2.0, the GNOME Help Browser will be replaced by Nautilus. 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 GNOME Help Browser 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 jade 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 Nautilus, visit the #nautilus IRC channel on irc.gnome.org. 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. 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. 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 below. Applications should have a Help button on screens on which users may need help. These Help buttons should pull up the default help browser, determined by the ghelp URL Handler (configured using the Control Center), typically the GNOME Help Browser. 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 below. 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 below. The GNOME User Guide describes the GNOME desktop environment and core components of GNOME such as the panel and control center. 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. Aside from the GNOME User Guide, there are several other documents to help GNOME users learn GNOME, including the GNOME FAQ, GNOME Installation and Configuration Guide, and the GNOME Administrators Guide. There are many White Papers, Tutorials, HOWTO's and FAQ's to make programming GNOME and GNOME applications as easy as possible. 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 GNOME API Reference page. 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. 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 elements 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 <title>The Title</title>. 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. 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 DocBook Tools, a free package of utilities for working with DocBook which includes Jade, which does the SGML/DSSL parsing. You can read more about DocBook Tools in . The final appearance of the output (e.g. PostScript or HTML) is determined by a stylesheet. 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 . The advantage of specifying the structure of a document with SGML instead of specifying the appearance 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. 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. 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. As stated before, the GDP uses the DocBook DTD. For a list of introductory and reference resources on DocBook, see . The following sections also provide convenient instructions on which markup tags to use in various circumstances. Be sure to read for GDP documentation-specific guidelines. 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 strongly advised that the documentation writers conform to XML syntax rules. Here are most important differences: Minimization It is possible with some implementations of SGML to use minimizations to close elements in a document by using </>, for example: <title>The Title</>. This is not allowed in XML. You can use sgmlnorm command, included in DocBook Tools package, to expand minimized tags; if you are using Emacs with psgml mode, you can also use menu command Modify Normalize . Self-closing tags Also, in SGML some tags are allowed not to have closing tags. For example, it is legal for <xref> not to have a closing tag: <xref linkend="someid">. In XML, it is illegal; instead, you should use <xref linkend="someid"/> (note the slash!). Case sensitive tags In XML, unlike SGML, tags are case-senstive <title> and <TITLE> are different tags! Therefore, please always use lowercase tags (except for things like DOCTYPE, CDATA and ENTITY, which are not DocBook tags). Top-level element of a book body must be <chapter>; it may contain one or more <sect1>, each of them may contain <sect2> and so on up to <sect5>. Top-level element of an article body must be <sect1>. For usage example, see the template. Please try to avoid using deeply nested sections; for most situations, <sect1> and <sect2> should be sufficient. If not, you probably should split your <sect1> into several smaller ones. Use the tag <para> for paragraphs, even if there is only one paragraph in a section—see template for examples. 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 <note>, <tip>, <warning>, <important> respectively. For example: To speed up program compilation, use gcc compiler with Pentium optimization. ]]> produces To speed up program compilation, use gcc compiler with Pentium optimization. Note that this should not be inside a <para> but between paragraphs. To include screenshots and other figures, use the following tags: Screenshot of a program ]]> replacing example_screenshot with the actual file name (without extension). The result will look like this:

Screenshot of a program

Notice in this example that the screenshot file name does not include the file type extension — to find out why, please read . To show a file fragment—for example, program listing—use <programlisting> tag: [Desktop Entry] Name=Gnumeric spreadsheet Exec=gnumeric Icon=gnome-gnumeric.png Terminal=0 Type=Application ]]> which produces [Desktop Entry] Name=Gnumeric spreadsheet Exec=gnumeric Icon=gnome-gnumeric.png Terminal=0 Type=Application As a matter of fact, all examples in this document were produced using <programlisting>. To show a record of terminal session—i.e., sequence of commands entered at the command line—use <screen> tag: bash$make love make: *** No rule to make target `love'. Stop. ]]> which produces bash$make love make: *** No rule to make target `love'. Stop. Note the use of tags <prompt> and <userinput> for marking system prompt and commands entered by user. Note that both <programlisting> and <screen> preserve linebreaks, but interpret SGML tags (unlike LaTeX verbatim environment). Take a look at the source of this document to see how you can have SGML tags literally shown but not interpreted, The most common list types in DocBook are <itemizedlist>, <orderedlist>, and <variablelist>. <itemizedlist> This is the simplest unnumbered list, parallel to <ul> in HTML. Here is an example: Show backup files — This will show any backup file that might be on your system. Show hidden files — This will show all "dot files" or files that begin with a dot. This files typically include configuration files and directories. Mix files and directories — This option will display files and directories in the order you sort them instead of always having directories shown above files. ]]> and output: Show backup files — This will show any backup file that might be on your system. Show hidden files — This will show all "dot files" or files that begin with a dot. This files typically include configuration files and directories. Mix files and directories — This option will display files and directories in the order you sort them instead of always having directories shown above files. Note the use of &mdash; for long dash (see ). Also, please note that the result looks much nicer because the terms being explained (Show backup files, etc.) are set in a different font. In this case, it was achieved by using <guilabel> tag. In other cases, use appropriate tags such as <guimenuitem>, <command>, or — if none of this applies — use <emphasis>. <orderedlist> This list is completely analogous to <itemizedlist> 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 numeration, for example <orderedlist numeration="lowerroman">. Possible values of these attribute are arabic, upperalpha, loweralpha, upperroman, lowerroman. <variablelist> 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. For example, the lines you are reading now were produced by <variablelist>. The source looked liked this: <itemizedlist> This is the simplest unnumbered list, parallel to <ul> in HTML. Here is an example:... <orderedlist> This list is completely analogous to <itemizedlist> <variablelist> This list is used when each entry is rather long,... ]]> Lists can be nested; in this case, the stylesheets are smart enough to change the numeration (for <orderedlist>) or marks of each entry (in <itemizedlist>) for sub-lists <guibutton> — used for buttons, including checkbuttons and radio buttons <guimenu>, <guisubmenu> —used for top-level menus and submenus respectively, for example Utilities submenu of the Main Menu]]> <guimenuitem>—an entry in a menu <guiicon>—an icon <guilabel>—for items which have labels, like tabs, or bounding boxes. <interface>— for most everything else... a window, a dialog box, the Panel, etc. If you need to refer to a sequence of menu choices, such as Main Menu Utilities GNOME terminal there is a special construction for this, too: Main Menu Utilities GNOME terminal ]]> To refer to another place in the same document, you can use tags <xref> and <link>. 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: tip was given in . ]]> which produces: An example of a tip was given in . Here notes and extip are the id attributes of and of the example of a tip in it. To produce a link to an external source, such as a Web page or a local file, use <ulink> tag, for example: GNOME Web page ]]> which produces: To find more about GNOME, please visit The GNOME Web Site You can use any of the standard URL types, such as http, ftp, file, telnet, mailto (in most cases, however, use of mailto is unnecessary—see discussion of <email> tag). Here are some tags used to describe operating system-related things: <filename> — used for filenames, e.g.<filename> foo.sgml </filename> produces: foo.sgml. <filename class="directory"> — used for directories, e.g.<filename class="directory">/usr/bin </filename> produces: /usr/bin. <application> — used for application names, e.g. <application>Gnumeric </application> produces: Gnumeric. <command> — used for commands entered on command line, e.g. <command>make install </command> produces: make install. <replaceable> — used for replaceable text, e.g. <command>db2html<replaceable> foo.sgml </replaceable></command> produces: db2html foo.sgml. To mark up text input by the user, use <userinput>. To mark keystrokes such as shortcuts and other commands, use <keysym> and <keycap>. The difference — as far as I understand — is that <keycap> is used for physical keys on the keyboard (<keycap>A</keycap>, <keycap>Ctrl</keycap>), while <keysym> is used for "logical" symbols, for example <keysym>Ctrl-q</keysym>. In most cases, you should use <keysym>. To mark up a sequence of keystrokes, use the <keycombo> wrapper: Ctrl-x Ctrl-f ]]> Finally, if you want to show a shortcut for some menu command, here are the appropriate tags (rather long): Ctrl-q Quit ]]> which produces simply Ctrl-q Quit To mark up e-mail address, use <email>: me@mydomain.com)]]> which produces: The easiest way to get in touch with me is by e-mail (me@mydomain.com) Note that <email> automatically produces a link in html version. 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 entities, which is SGML analogue of macros, or commands, of LaTeX. They generally have the form &entityname;. Note that the semicolon is required. here is partial list of most commonly used enitites: &amp; — ampersend (&) &lt; — left angle bracket (<) &copy; — copyright sign (©) &mdash; — long dash (—) &hellip; — ellipsis (…) 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 (&mdash;) 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. All GNOME documentation should conform to XML syntax requirements, which are stricter than SGML ones — see for more informaion. 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. Application documentation should identify the version of the application for which the documentation is written: blah-blah-blah This document describes version 1.0.53 of gfoo. ]]> Application documentation should contain a copyright notice, stating the licensing terms. It is suggested that you use the same licensing terms as used by this Handbook (these are the terms that used by Free Software Foundation for its own documentation). 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). Every GNOME application(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 application(applet) does and how to use it. Manuals will typically describe each window or panel of the application(applet), using screenshots(PNG format only) when appropriate. They should also describe each feature and preference option available. Applications(applets) should not rely on documentation which is only available on the internet. All manuals and other documentation should be packaged with the application(applet) and be made available to the user through the standard GNOME help system methods described below. Application manuals should be based on the template in . Applet manuals should be based on the template in . Manuals for very large applications, such as GNOME Workshop components should be a <book> (and thus use <chapter> for each primary section) , instead of <article> which most applications use(with each primary section being a <sect1>). 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 <sect1>. Applet manuals will typically have several sections, each of which is <sect2>. Application manuals should be made available by having a "Manual" entry in the Help pull-down menu at the top of the application, as described in . Applets should make their manuals available by right-clicking on the applet. This section is for developers. Documentation authors generally do not need to know this material. Typically the application manual and possibly additional help documents will be made available to the user under the Help menu at the top right of the application. To do this, you must first write a topic.dat file. The format for this file is: 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. For example, Gnumeric's topic.dat file is: gnumeric.html Gnumeric manual function-reference.html Gnumeric function reference When the application is installed, the topic.dat file should be placed in the $prefix/share/gnome/help/appname/C/ directory where appname is replaced by the application's name. The application documentation (converted from SGML into HTML with db2html) should be placed in this directory too. If the help files are not present in the correct directory, the menu items will NOT appear when the program is run. The topic.dat file is used by the GNOME menu building code to generate the Help menu. When you define your menu: 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("appname"), GNOMEUIINFO_END }; the line specifying GNOMEUIINFO_HELP causes GNOME to create a menu entry which is tied to the documentation in the directory mentioned above. Also, all the topics in the topic.dat file will get menu entries in the Help menu. When the user selects any of these topics from the Help menu, a help browser will be started with the associated HTML documentation. This section is for developers. Documentation authors generally do not need to know this material. Most GNOME applications will have Help buttons. These are most often seen in Preference windows. (All Preference windows should have Help buttons.) Most Help buttons will connect to the application manual, although some may connect to special documents. Because the Help 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 Help buttons are pressed. To make the Help buttons call the correct document in the GNOME Help Browser the developer should add code based on the following example: gchar *tmp; tmp = gnome_help_file_find_file ("module", "page.html"); if (tmp) { gnome_help_goto(0, tmp); g_free(tmp); } The example above is in the C language, please refer to other documentation or forums for other GNOME language bindings. In GNOME 2.0 each applet will have its own documentation packaged and installed separately, and the GNOME 2.0 help browser (Nautilus) will dynamically merge the applet documents into a single virtual document. During the transitionary stage between GNOME 1.0 and GNOME 2.0, each applet has its own manual(stored with the applet in CVS), but they are merged together manually into a single document before distribution. Telsa hobbit@aloss.ukuu.org.uk 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 to bind to the applet documentation if necessary. This section is for developers. Documentation authors generally do not need to know this material. Applets should have About and Manual 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. To add an applet's manual to its applet menu, use: /* add an item to the applet menu */ applet_widget_register_callback(APPLET_WIDGET(applet), "manual", _("Manual"), &open_manual, NULL); 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. You will need to write a simple callback function to open the help browser to the appropriate document. This is done using the gnome_help_file_find_file function, as described in . You will also want to add an About menu item to the applet's menu. This is a stock menu item and is done: applet_widget_register_stock_callback (APPLET_WIDGET(applet), "about", GNOME_STOCK_MENU_ABOUT, _("About"), &my_applet_cb_about, NULL); More information can be found at Writing GNOME panel applets using the GTK+/GTK-- widget set. 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. 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. 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. 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. 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. 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. 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 GDP Documentation Status Table (http://www.gnome.org/gdp/doctable/) 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 gnome-doc-list mailing list. 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 gnome-doc-list mailing list. 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. 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. 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. The final step is to email the GNOME Translation Team at gnome-i18n@nuclecu.unam.mx to notify them that there is a new document for them to translate. The GNOME Documentation Project Web page lists current GDP projects and members. The GDP Documentation Status Table tracks the status of all the various documentation components of GNOME. Norman Walsh's DocBook: The Definitive Guide in an excellent book on DocBook, available both online and in print. Docbook: The Definitive Guide is available in both printed form and on the web at: Docbook: The Definitive Guide The gnome-docs-list 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 GNOME Mailing Lists. This is a rather low-volume list, so you will not be flooded with messages. 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. The following template should be used for all application manuals. You can always get the latest copy of this template from GDP Documentation Templates. &APP-TEMPLATE The following template should be used for all applet manuals. You can always get the latest copy of this template from GDP Documentation Templates. &APPLET-TEMPLATE