<?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 CVS.  The GDP stylesheets are in the 
		module gnome-docu/gdp/xsl of the GNOME CVS.  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. 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>
  <!-- ####### GNOME Documentation System | 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.
	  Below is a simple tutorial which will take you through the
	  basics of using CVS.  A more complete guide is <ulink
	  url="http://cvsbook.red-bean.com/"> <citetitle>Open Source
	  Development with CVS</citetitle></ulink>.  The free chapters are
	  a good guide to using CVS and can be found at <ulink
	  url="http://cvsbook.red-bean.com/cvsbook.html">http://cvsbook.red-bean.com/cvsbook.html</ulink>.
	</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.  Note 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>

