<?xml version="1.0"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                  "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>

<!-- ################# The GNOME Documentation System###############
-->

<sect1 id="gnomedocsystem">
  <title>GNOME Documentation System</title>

  <para>
	The GNOME Documentation System consists of DocBook, Yelp (GNOME Help
	Browser), Scrollkeeper (document cataloging system), and the XML tools
	(called DocBook Tools) to transform and check the documentation.  Use of
	this system is necessary to write good documentation for GNOME.  This
	chapter gives a brief overview describing the tools in the GNOME
	Documentation System.
  </para>
  
  <!-- ####### The GNOME Documentation System | DocBook ####### -->
  
  <sect2 id="docbooksys">
	<title>DocBook</title>
	
	<para>
	  DocBook is a markup language, like HTML, for technical and computer 
	  documentation, papers, and books.  The GNOME Documentation Project 
	  uses DocBook to mark up GNOME documentation.  The GDP currently uses 
	  version 4.1.2 of DocBook.  DocBook SGML is used 
	  with <application>gtk-doc</application> for developer documentation 
	  while DocBook XML is used for end user documentation.
	</para>
	<para>
	  The main advantage of DocBook is its single-source multiple-output
	  nature.  Only one DocBook source file is needed to make many different
	  outputs.  From the same DocBook file the GDP lets the user view the
	  documentation as HTML with <application>Yelp</application> and can
	  provide a print copy, usually in PDF.
	</para>
	<para>
	  The GDP uses the XSL language to exploit DocBook's multi source nature.  
	  XSLT stylesheets convert DocBook into HTML, which 
	  <application>Yelp</application> displays.  XSLT stylesheets are 
	  also used to convert DocBook into FO, an XML print specification, 
	  which is in turn converted to PDF or PS files.  If any other format 
	  is needed the GDP could use an XSLT stylesheet to convert the 
	  DocBook files into another format such as man or info pages.
	</para>
	<para>
	  DocBook focuses on the document content, leaving presentation details
	  to XSLT. For example all the applications within DocBook use the
	  <sgmltag>&lt;application&gt;</sgmltag> tag.  The stylesheets determine
	  how the text inside the tag looks.  Authors need not concern
	  themselves, for example, with whether all applications will be in bold
	  text or italics or whether the applications should not have any
	  special formatting, focusing instead on what ideas the documentation
	  should convey to the readers.
	</para>
	
	<sect3 id="moredocbookinfo">
	  <title>Learning DocBook</title>
	  
	  <para>
		There are many resources available to help you learn DocBook, including 
		this manual.  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> &mdash; 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.ibiblio.org/oswg/oswg-nightly/oswg/en_US.ISO_8859-1/articles/DocBook-Intro/docbook-intro/"
			  type="http">A Practical Introduction to DocBook</ulink>
			&mdash; The Open Source Writers Group's introduction to using
			DocBook. This is an excellent HOW-TO 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> &mdash; 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 url="http://dpawson.co.uk/docbook/">Dave Pawson's DocBook FAQ</ulink>
			&mdash; Dave Pawson's FAQ on everything DocBook related.  He 
			discusses references, tools, catalogs, and stylesheets in a 
			concise FAQ format.  One of the best resources to find 
			answers to common questions and problems about DocBook.
		  </para>
		</listitem>
		<listitem>
		  <para>
			<ulink type="http" url="http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/index.html">
			  FreeBSD Documentation Project Primer for New
			  Contributors</ulink> &mdash; 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="docbook" /> - 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>
  
  <!-- ####### The GNOME Documentation System | The GNOME Help Browser
  ####### -->
  
  <sect2 id="gnomehelpbrowser">
	<title>GNOME Help Browser</title>
	
	<para>
	  At the core of the GNOME help system is 
	  <application>Yelp</application>.  <application>Yelp</application> 
	  provides a unified interface to several
	  distinct documentation systems on Linux/Unix systems: man
	  pages, info pages, Linux Documentation Project (LDP)
	  documents, GNOME application documentation, and other GNOME
	  documents.
	</para>
	<para>
	  <application>Yelp</application> works by getting a list of all 
	  documentation installed on your system from 
	  <application>Scrollkeeper</application>, documentation cataloging 
	  system used by GNOME, LDP, and other projects.  Thus, the documentation 
	  that appears in the <application>Yelp</application> is 
	  specific to each computer and will typically only represent
	  software that is installed on the computer.
	</para>
	<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.
	  <application>Yelp</application> describes only components which are 
	  currently installed on a users system.  Some of this documentation, 
	  such as the User's Guide, 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 application you
	  install that has documentation will show up in the index,
	  table of contents, and any search you do in the help browser.
	</para>
	<para>
	  <application>Yelp</application> also integrates the conversion from 
	  DocBook to HTML.  <application>Yelp</application> takes the DocBook 
	  document and runs a XSL processor, <application>xsltproc</application>, 
	  which uses a stylesheet to convert the DocBook file to a HTML 
	  file.  <application>Yelp</application> also uses the GDP's own 
	  stylesheets on top of Norman Walsh's stylesheets.  This allows 
	  the appearance of the all GNOME documentation to change with only 
	  altering one specific stylesheet.  Using a custom stylesheet gives 
	  GNOME a custom help environment.
	</para>
  </sect2>
  
  <!-- ####### GNOME Documentation System | Scrollkeeper #######-->
  
  <sect2 id="scrollkeeper">
	<title>Scrollkeeper</title>
	
	<para>
	  <ulink url="http://scrollkeeper.sourceforge.net">Scrollkeeper</ulink>
	  works with <application>Yelp</application> providing
	  <application>Yelp</application> with the location of the local
	  documentation, a TOC for that document, searching, and indexing
	  abilities based on metadata gathered about the document.
	  <application>Scrollkeeper</application> is a document cataloging
	  system using Open Source Metadata Framework (OMF) files to
	  provide metadata about each document installed in
	  <application>Scrollkeeper's</application> catalog.
	  <application>Scrollkeeper</application> is only meant to catalog
	  documentation available locally on the user's system.
	</para>
	<para>
	  <application>Scrollkeeper</application> uses metadata from OMF files 
	  provided with each piece of documentation to categorize the document 
	  in its catalog.  This catalog is then accessed by 
	  <application>Yelp</application> to build the links when 
	  <application>Yelp</application> starts up.  Currently the OMF files 
	  aren't used for anything else, but in future versions of Scrollkeeper 
	  it will be utilized.
	</para>
	<para>
	  <application>Scrollkeeper</application> uses DocBook 
	  <sgmltag>&lt;indexterm&gt;</sgmltag> tags in the documentation to 
	  build an index.  The index is a collection of words which refer to a 
	  specific document.  In <application>Yelp</application> you can search 
	  through these words and view the document they coorespond to.
	</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 | The GNOME Documentation
  Components  ####### -->
  
  <sect2 id="gnomehelpcomponents">
	<title>GNOME Documentation Components</title>
	
	<sect3 id="gdpstylesheets">
	  <title>GDP Stylesheets</title>
	  <para>
		The GDP uses its own DocBook stylesheets.  These stylesheets are 
		integrated into the Yelp help browser.  This means you do not need 
		to install any specific stylesheets.  All you need are the standard 
		DocBook stylesheets installed and a working XML Catalog.
	  </para>
	  
	  <para>
		If you do not wish to use <application>Yelp</application> to view 
		your completed documentation, the specific GDP stylesheets can 
		be obtained through Subversion.  The GDP stylesheets are in the 
		module <filename class="directory">gnome-doc-utils/trunk/xslt/</filename>
		of the GNOME Subversion.  <!-- The top level 
		stylesheet and the one you run through the XSL processor is 
		<filename>general-customizations.xsl</filename>. -->
	  </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>.
        </para>
        <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 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</title>
	  <para>
		Since DocBook 4.0 the DocBook DTD has included support for PNG 
		graphic files.  Therefore the GDP recommends documenters use the 
		standard DocBook DTD.
	  </para>
	  <para>
		The GDP used to use a customized DTD for DocBook SGML which added 
		support for PNG graphic files.  This is no longer needed.
	  </para>
<!--
        <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>&lt;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="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
		<guilabel>File Types and Programs</guilabel> dialog, typically 
		<application>Yelp</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-3.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>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>nautilus</application>. In GNOME 1.x this
		was the main source of documentation while sometimes duplicating 
		existing documentation of various components. In GNOME 2.0
		this is 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.  The User Guide 
		is the main source of documentation for basic components of the 
		GNOME desktop such as the panel, Nautilus, and customizations.
	  </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 new users learn
		GNOME, including the <citetitle>Introduction to GNOME</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.</para>
	  <para>You can find general developer documentation on the <ulink
          url="http://library.gnome.org/devel/" type="http">Developer 
          section of the GNOME Documentation Library</ulink>.
	  </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>
  <!-- ####### GNOME Documentation System | Using Subversion  ####### -->
  
  <sect2 id="svn">
	<title>Using Subversion</title>
	<para>
		Subversion (SVN) 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 the Subversion
		repository. The GNOME Subversion server allows users to
		anonymously check out files. Most GDP members will access the
		repository without a login 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 privileges so they
		may commit modified files directly to the Subversion
		repositories. Below is a simple tutorial which will take you
		through the basics of using Subversion. A more complete guide
		is <ulink url="http://svnbook.red-bean.com/"><citetitle>
		Version Control with Subversion</citetitle></ulink>.
	</para>
	
	<sect3 id="initialcheckout">
	  <title>Initial Checkout</title>
	  <para>
		You can download files anonymously from the server to create
		a local working copy. As an example, we will check out the
		files for this handbook. To check out for the first time,
		type <command>
		svn checkout http://svn.gnome.org/svn/gnome-devel-docs/trunk/gdp-handbook/
		</command>. After you have this document checked out and you
		would like to download any updates from the Subversion
		repository, use <command>svn update</command>.
	  </para>
	</sect3>
	
	<sect3 id="committingchanges">
	  <title>Committing Changes</title>  
	  <para>  
		If you are a registered GNOME developer, you may use your SSH
		key to authenticate yourself so you can commit changes back
		to the Subversion repositories. Be sure to read the following
		section on Subversion etiquette before making any commits. To
		authenticate to the Subversion server as user <command>
		<replaceable>username</replaceable></command>, you will use a
		slightly different URL. To commit <command><replaceable>
		filename</replaceable></command> to the Subversion server,
		type <command> svn commit
		svn+ssh://<replaceable>username@</replaceable>svn.gnome.org/svn/gnome-devel-docs/trunk/gdp-handbook/<replaceable>filename</replaceable>
		</command>. You will be given an editor window to type in a
		brief log entry, summarizing your changes. Note the default
		editor can be changed using the <varname>EDITOR</varname>
		environment variable or with the
		<command><option>--editor-cmd</option></command> option.
	  </para>
	</sect3>
	
	<sect3 id="svnetiquette">
	  <title>SVN Etiquette</title>
	  <para>
		Because files in Subversion are typically used and modified
		by multiple developers and documentation authors, users should
		exercise a few simple practices out of courtesy towards the
		other Subversion users and the project leader. First, you
		should not commit changes back to the Subversion repositories
		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 Subversion user commits a file, they should
		make an entry in the Subversion 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>
