<?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" [
]>

<!-- ################# Getting Started  ############### -->

<sect1 id="gettingstarted">
  <title>Getting Started Writing GNOME Documentation</title>

  <!--####### Getting Started | Selecting A Document ####### -->
  
  <sect2 id="selecting">
	<title>Selecting a Document</title>
    
	<sect3 id="know">
	  <title>Document Something You Know</title>
	  <para>
		The most frequently asked question of new contributors who
		join the GDP is <quote>which document should I start
          with?</quote>. Because most people involved are volunteers, we do
		not <emphasis>assign</emphasis> projects and applications to
		write documents for. The first step is all yours - you must
		decide what about GNOME interests you most and find out if
		it has complete documents or not.
	  </para>
	  <para>
		It is also important to spend some time with GNOME to make
		sure you are familiar enough with it to be
		<emphasis>authoritative</emphasis>  in your writing. The
		best way to do this is to just sit down and play with GNOME
		as much as possible before starting to write.
	  </para>
	  <para>
		The easiest way to get started is to improve existing
		documentation. If you notice some inaccuracies or omissions
		in the documentation, or you think that you can explain the
		material more clearly, just send your suggestions to the
		author of the original documentation or to the GNOME
		documentation project at <email>gnome-doc-list@gnome.org</email>.
	  </para>
	</sect3>
	
	<sect3 id="doctable">
	  <title>GNOME Documentation Status Table</title>
	  <para>
		The <citetitle>GDP Documentation Status Table</citetitle>
		(<citetitle>DocTable</citetitle>) (<ulink
		  url="http://developer.gnome.org/projects/gdp/doctable--.html"
		  type="http">http://developer.gnome.org/projects/gdp/doctable--.html
		</ulink>) is a web page which tracks the status of all the various
		documentation components of GNOME.  These components include
		application documentation, internal GNOME component
		documentation, user documentation, and developer
		documentation.  For each documentation item, it tracks the
		current status of the documentation, who is working on the
		particular document, where the documentation can be found,
		and provides a forum for the discussion of each item.
	  </para>
		<para>
		The GDP is currently looking at alternative ways to track our 
		documentation.  The DocTable fell into disuse and never completely 
		tracked all the documents in GNOME.  Alternatives we are looking 
		into is a new and better DocTable or a <ulink 
		  url="http://www.lampadas.org">Lampadas</ulink> like system to 
		track the documentation in GNOME.  If anyone has experience in 
		distributed project management email suggests or a willingness to 
		help to <email>gnome-doc-list@gnome.org</email>.
	  </para>
	  <para>
		You should use the <citetitle>DocTable</citetitle> to help
		you select a documentation item which needs work done.  Once
		you have selected an item to work on, please register
		yourself as an author so that other authors do not duplicate
		your work and may contact you to help or offer suggestions.
	  </para>
	  <note>
		<title>Note</title>
		<para>
          Note that the information in the
          <citetitle>DocTable</citetitle> may not always be up-to-date
          or accurate.  When you assign yourself to documenting an
          application, make sure you find out the latest status of
          documentation by contacting the application author.  
		</para>
	  </note>
	  <para>
		Also send an email to the GNOME documentation mailing list 
		(<email>gnome-doc-list@gnome.org</email>).  You should introduce 
		yourself and ask which programs need docs or ask if a 
		particular program you are interested in documenting already has 
		someone working on the docs.  People reading the list will know 
		which docs need working on and which docs need updating or writing.  
	  </para>
	</sect3>
  </sect2>
  
  <!-- ####### Getting Started | GDP Document Examples ####### -->
<!--
    <sect2 id="examples">
      <title>GDP Document Examples</title>
      <para>
        Examples of various types of GNOME documents are found in
        <xref linkend="examples" />.  There is also an example GNOME
        application with documentation called
        <application>gnome-hello</application> in GNOME cvs.
      </para>
    </sect2>
-->
  <!-- ####### Getting Started | Installing DocBook #######-->

  <sect2 id="installingdocbook">
	<title>Installing DocBook</title>
	<para>
	  All documentation for the GNOME project is written in XML
	  using the DocBook DTD. There are many advantages to using
	  this for documentation, not least of which is the single
	  source nature of XML. To contribute to the GDP you should
	  learn to use DocBook.
	</para>
	<note>
	  <title>Note</title>
	  <para>
		To get started writing for the GDP you do not need to rush
		out and learn DocBook - if you feel it is too much to handle
		for now, you can submit plain ASCII text to the <ulink
          url="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/">
          <citetitle>gnome-doc-list mailing list</citetitle>
		</ulink> and a volunteer will mark it up for you. Seeing your
		document marked up will also be a great way for you to start
		learning DocBook.
	  </para>
	</note>
	<para>
	  There isn't a standard set of packages to install DocBook XML and 
	  make it work locally.  Each distribution installs DocBook XML a 
	  bit differently with various degrees of support for needed features.
	</para>
	<sect3 id="RPMusers">
	  <title>RPM Users</title>
	  <para>
		Download and install the following RPM packages from 
		<ulink url="http://cyberelk.net/tim/docbook/">Tim Waugh's
		  DocBook page</ulink>:
		<itemizedlist>
		  <listitem><para>xml-common</para></listitem>
		  <listitem><para>docbook-dtds</para></listitem>
		  <listitem><para>docbook-style-xsl</para></listitem>
		  <listitem><para>libxml2</para></listitem>
		  <listitem><para>libxslt</para></listitem>
		</itemizedlist>
	  </para>
	  
	  <para>
		This will setup a basic build environment to convert DocBook
		XML documents into HTML.  If you wish to convert your DocBook
		document into multiple formats, you will need to download and
		install the following RPM packages from <ulink
		url="http://cyberelk.net/tim/docbook/">Tim Waugh's DocBook
		page</ulink>:
		<itemizedlist>
		  <listitem><para>xmltex</para></listitem>
		  <listitem><para>passivetex</para></listitem>
		  <listitem><para>xmlto</para></listitem>
		</itemizedlist>
	  </para>
	  
	  <note>
		<para>
		  The RPMs for docbook-dtds and docbook-style-xsl might not
		  install a correct entry in your XML Catalog.  To check if
		  there is a proper XML Catalog entry for the DTD run the
		  command <prompt>$</prompt> <command>xmlcatalog
		  <filename>/etc/xml/docbook</filename> &quot;-//OASIS//DTD
		  DocBook XML V4.1.2//EN&quot;</command>.  If this command
		  returns a URI which starts with
		  <computeroutput>file://</computeroutput> then the DTD is
		  correctly installed in the XML Catalog.  However, if the
		  command returns <computeroutput>No entry for
		  PUBLIC</computeroutput> then the DTD is not installed in the
		  XML Catalog.
		</para>
		
		<para>
		  To check if there is a proper XML Catalog entry for the
		  stylesheets run the command <prompt>$</prompt>
		  <command>xmlcatalog <filename>/etc/xml/docbook</filename>
		  &quot;http://docbook.sourceforge.net/release/xsl/1.49/&quot;</command>.
		  If this command returns a URI which starts with
		  <computeroutput>file://</computeroutput> then the stylesheet
		  is correctly installed in the XML Catalog.  However, if the
		  command returns <computeroutput>No entry for
		  SYSTEM</computeroutput> then the stylesheet is not installed
		  in the XML Catalog.
		</para>
	  </note>
	</sect3>
	<sect3 id="debianusers">
	  <title>Debian Users</title>
	  <para>
		To fetch all required packages, simply run:
		<informalexample>
		  <screen>
			<prompt>#</prompt> <command>apt-get install libxslt1</command> 
			<prompt>#</prompt> <command>apt-get install docbook-xsl</command>
		  </screen>
		</informalexample>
	  </para>
	  
	  <para>
		Debian packages do not install a XML Catalog currently.  Since
		a XML Catalog is essential to view DocBook documents quickly
		and easily, you will need to install a XML Catalog by hand.
		This is not too hard because there is a nice script
		<ulink url="http://xmlsoft.org/buildDocBookCatalog">
		  buildDocBookCatalog</ulink> which will install a XML
		Catalog.  If you want the XML Catalog to be installed in
		<filename class="directory">/etc/xml/</filename> you need to
		run the script as the root user.  However, if you want the XML
		Catalog to be install in your home directory you need to run
		the script as a regular user.
	  </para>
	  
	  <note>
		<para>
		  If the program <command>xmlcatalog</command> is not
		  installed in <filename class="directory">/usr/bin</filename>
		  you might need to alter the buildDocBookCatalog script.
		  Just edit the file in your favorite editor and replace
		  <quote>/usr/bin/xmlcatalog</quote> with
		  <quote>xmlcatalog</quote>.  Then as long as the program
		  <command>xmlcatalog</command> is in your path you should be
		  fine.
		</para>
	  </note>
	  
	</sect3>
	<sect3 id="sourceinstall">
	  <title>Installing from Source</title>
	  <para>
		To install the DocBook tools from source get the latest
		version of <ulink
		url="ftp://ftp.gnome.org/pub/GNOME/sources/libxml2/2.5/">
		libxml2</ulink> and
		<ulink url="ftp://ftp.gnome.org/pub/GNOME/sources/libxslt/1.0/">
		  libxslt</ulink> and compile it.  This will install
		the basic tools for working with XML files.  Next you
		will need to download the
		<ulink url="http://www.oasis-open.org/docbook/xml/4.1.2/index.shtml">
		  DocBook XML DTD</ulink> and
		<ulink url="http://sourceforge.net/project/showfiles.php?group_id=21935">
		  DocBook XSL Stylesheets (docbook-xsl)</ulink>.  These need
		to be unpacked and placed in the <filename class="directory">
		/usr/local/share/xml/docbook/xml-dtd-4.1.2</filename>
		directory and the <filename class="directory">
		/usr/local/share/xml/docbook/xsl-stylesheets-1.48</filename>
		directory respectively.  Now you need to install a XML Catalog
		so the DTD and stylesheets can be located locally.  This is
		not too hard because there is a nice script
		<ulink url="http://xmlsoft.org/buildDocBookCatalog">
		  buildDocBookCatalog</ulink> which will install a XML
		Catalog.  If you want the XML Catalog to be install in
		<filename class="directory">/etc/xml/</filename> you need to
		run the script as the root user.  However, if you want the XML
		Catalog to be installed in your home directory you need to run
		the script as a regular user.
	  </para>
	  
	  <note>
		<para>
		  If the program <command>xmlcatalog</command> is not
		  installed in <filename class="directory">/usr/bin</filename>
		  you might need to alter the buildDocBookCatalog script.
		  Just edit the file in your favorite editor and replace
		  <quote>/usr/bin/xmlcatalog</quote> with
		  <quote>xmlcatalog</quote>.  Then as long as the program
		  <command>xmlcatalog</command> is in your path you should be
		  fine.
		</para>
	  </note>
	</sect3>
	<sect3 id="editors">
	  <title>Editors</title>
	  <para>
		There are many editors on Linux and UNIX systems available
		to you. Which editor you use to work on the XML documents
		is completely up to you, as long as the editor is able to
		preserve XML and produce the source in a format that is
		readable by everyone.
	  </para>
	  <para>
		Probably the two most popular editors available are
		<application>Emacs</application> and
		<application>vi</application>. These and other editors are
		used regularly by members of the GDP. <application>Emacs</application> 
		has a major mode, psgml, for editing DocBook files which can save you 
		time and effort in adding and closing tags. You will find the
		psgml package in your distribution of Linux.  If your distribution 
		does not use binary packages, the source code for psgml is available 
		at <ulink url="http://psgml.sourceforge.net">
		  http://psgml.sourceforge.net</ulink>.
	  </para>
	</sect3>
  </sect2>
  
  <!-- ####### Getting Started | Using DocBook Tools ####### -->
  
  <sect2 id="usingdocbook">
	<title>Using DocBook Tools</title>
	
	<para>
	  There are three tools used with DocBook documents.
		<application> Xmllint</application> checks the documentation
		to make sure it is valid DocBook and follows all the rules of
		XML and the DTD.  <application>Xsltproc</application>
		transforms the document from DocBook to a variety of document
		formats, including HTML, using XSL stylesheets.
		<application>Xmlcatalog</application> generates, updates, and
		checks to make sure the XML catalog is working.  You may have
		used these tools <link linkend="installingdocbook"> installing
		DocBook</link>.  This isn't meant to be a complete guide to
		these tools, but an introduction to famaliarize you with the
		common DocBook tools.  If you want more information about any
		of them consult <ulink
		url="http://xmlsoft.org">http://xmlsoft.org</ulink> or view
		their respective man pages.
	</para>
	
	<sect3 id="xmllint">
	  <title>Using xmllint</title>
	  
	  <para>
		There are many different ways to use
		<application>xmllint</application>.
		<application>Xmllint</application> can check the document
		conforms to the XML specification.  It can check the document
		validates against the declared DTD or you can force
		<application>xmllint</application> to use another DTD.
		<application>Xmllint</application> resolves Xinlcudes and can
		then check the document validates against a DTD after the
		Xinclude resolution is complete.  There are many options to
		use with <application>xmllint</application>.
	  </para>

	  <para>
		The standard way to use xmllint to show just the errors is to
		type: <command>xmllint --noout --noent --valid
		<replaceable>filename.xml </replaceable></command>.  The
		option <parameter class="option"> --noout</parameter>
		suppresses the output of the XML document.
		<application>Xmllint</application> normally outputs the XML
		document to the screen and this option stops that behavior.
		The option <parameter class="option">--noent</parameter>
		resolves any entities which are declared in the document.
		This allows <application>xmllint </application> to check the
		validity of the document once the entities are replaced in the
		document.  The last option <parameter
		class="option">--valid</parameter> validates the document
		against the declared DTD.  By default <application>xmllint
		</application> just checks to see if the document is
		well-formed XML.  This option tells
		<application>xmllint</application> to check and make sure the
		document conforms to the DTD too.
	  </para>

	  <note>
		<para>
		  When <application>xmllint</application> does not display any 
		  errors and returns to the command prompt, the document is 
		  valid.
		</para>
	  </note>

	  <para>
		Occasionally you want to validate a document against another
		DTD.  The way to use <application>xmllint</application> to
		check for errors is to type: <command>xmllint --noout --noent
		--dtdvalid <replaceable>
		file:///path/to/dtd/filename.dtd</replaceable> <replaceable>
		filename.xml</replaceable></command>.  The option <parameter
		class="option">--dtdvalid</parameter> lets you validate the
		document against a different DTD than the one which was
		declared in the document.  The option has two parts.  The
		first part is the option itself and the second part is the URL
		to the DTD.  In the example above the URL is for a DTD on your
		local file system.  <application> Xmllint</application> can
		also retreive the DTD from the internet with a valid URL.
		This is useful to test if the document will conform to two
		different versions of the DTD.
	  </para>

	  <para>
		Sometimes you have a large document and use XIncludes so you
		have multiple XML files each with their own DTD.  The way to
		use <application>xmlllint</application> to check for errors is
		to type: <command>xmllint --noout --noent --xinclude
		--postvalid <replaceable>
		filename.xml</replaceable></command>.  There are two new
		options <parameter class="option">--xinclude</parameter> and
		<parameter class="option">--postvalid</parameter>.  The option
		<parameter class="option">--xinclude</parameter> processes the
		the document using the XInclude namespace.  After the
		processing is complete you want to check to make sure the
		entire document conforms to the DTD.  The option <parameter
		class="option">--postvalid </parameter> validates the document
		once all the processing is complete.  So, after the XInclude
		processing is done <application> xmllint</application> is told
		to validate the document.
	  </para>
	</sect3>
	
	<sect3 id="xsltproc">
	  <title>Using xsltproc</title>
	  
	  <para>
		The program to convert DocBook XML to a variety of output
		formats is <application>xsltproc</application>.  It is a very
		quick and powerful XSLT processor.  This means it can
		transform large documents from DocBook to HTML using XSLT
		stylesheets in seconds instead of minutes.
	  </para>

	  <para>
		To transform a XML file using a XSLT stylesheet type:
		  <command> xsltproc --noout -o
		  <replaceable>output</replaceable> <replaceable>
		  stylesheet.xsl</replaceable> <replaceable>filename.xml
		  </replaceable></command>.  This takes the file
		  <filename>filename.xml</filename> and applies the XSL
		  stylesheet <filename>stylesheet.xsl</filename>.  The output
		  of this transformation is saved in the file
		  <filename>output</filename>.  The option <parameter
		  class="option">--noout</parameter> surpresses the output of
		  the transformation to the screen.  Using the option
		  <parameter class="option">-o</parameter> the output of the
		  transformation is saved in the <filename>output</filename>
		  file.  If the stylesheet you are using saves the document in
		  multiple files, also called chunking, the option <parameter
		  class="option">-o </parameter> will save the files in the
		  specified directory.  This is an important distinction.
		  When the stylesheet saves the document to a single file,
		  <parameter class="option">-o</parameter> specifies the
		  output file. When the stylesheet saves the document in
		  multiple files, <parameter class="option">-o</parameter>
		  specifies the output directory.
	  </para>
	</sect3>

	<sect3 id="xmlcatalog">
	  <title>Using xmlcatalog</title>
	  
	  <para>
		The program <application>xmlcatalog</application> is a
		versatile application which creates, edits, and deletes
		entries in the XML catalog.  The XML catalog is similar to the
		SGML catalog in function, but very different in
		implementation.  XML catalogs are XML files which provide
		lookup and redirection for DTDs and URIs.  This allows the URL
		given in the DTD declaration of a XML file to be used in the
		lookup of the DTD locally in your system.  XML catalogs can
		also cascade so one XML catalog can be redirected to another.
	  </para>

	  <para>
		To create an XML Catalog type: <command>xmlcatalog --noout
		  --create <replaceable> /etc/xml/catalog</replaceable></command>.  An
		empty XML Catalog will be created in the directory <filename
		  class="directory">/etc/xml</filename> as the file
		<filename>catalog</filename>.  Make sure you have write permissions to
		the directory so the file can be created.  Now that you have an empty
		XML Catalog you need to populate the catalog.  To add a DTD to the
		catalog type: <command>xmlcatalog --noout --add "public" <replaceable>
			""-//OASIS//DTD DocBook XML V4.1.2//EN"</replaceable>
		  <replaceable>"file://usr/share/xml/docbook/docbookx.dtd"</replaceable>
		  <replaceable>/etc/xml/catalog</replaceable></command>.  This will
		redirect all queries for the DocBook V4.1.2 DTD to the location of the
		DocBook DTD, in this example
		<filename>file://usr/share/xml/docbook/docbookx.dtd</filename>.  The
		last option in the command is the location of the XML Catalog.  This
		should be the same place you created the XML Catalog.
	  </para>

	</sect3>
	
	<sect3 id="make-output">
	  <title>Creating Something Useful with your Docs</title>
	  <para>
		To view your DocBook documents you've made you need to run 
		<application>Yelp</application> from the 
		commandline.  This can be done by typing <command>yelp 
		  <filename>ghelp:/path/to/filename.xml</filename></command> to have 
		<application>Yelp</application> display the <acronym>XML</acronym> 
		file.
	  </para>
	  
	  <para>
		If you do not want to use <application>Yelp</application> to view 
		your documentation, you can use <application>xsltproc</application> 
		with the <acronym>GNOME</acronym> stylesheets.  The program 
		<application>xsltproc</application> takes the DocBook file and 
		using the GNOME stylesheets makes a new <acronym>HTML</acronym> 
		file.  The <acronym>HTML</acronym> file can be viewed from your 
		favorite web browser.  You will need to download the GNOME XSL 
		stylesheets in the module gnome-docu/gdp/xsl in GNOME SVN.  
		To run <application>xsltproc</application> 
		type <command>xsltproc <filename>general-customizations.xsl
		  </filename>     <filename>filename.xml</filename>
		</command> to produce the <acronym>HTML</acronym>.
	  </para>
	  
	  <note>
		<para>
		  Producing the HTML directly from the XML is not recommended.  The 
		  user documentation will be viewed in 
		  <application>Yelp</application>.  Therefore to see how the docs 
		  will look to the user the <acronym>GDP</acronym> recommends you 
		  use <application>Yelp</application> to view the documentation.  
		  An alternative way to view the documentation is given to those who 
		  may not have <application>Yelp</application> installed.
		</para>
	  </note>
<!--
        <para>
          The tools available in DocBook Tools allow you to convert
          your sgml document to many different formats including html
          and Postscript. The primary tool used to do the conversion
          is an application called <application>Jade</application>. In
          most cases you will not have to work directly with
          <application>Jade</application>; Instead,  you will use the
          scripts provided by DocBook Tools.
        </para>
        <para>
          To preview your DocBook document, it is easiest to convert
          it to <filename>html</filename>. If you have installed the
          DocBook tools described above, all you have to do is to run
          the command <prompt>$</prompt><command>db2html
          mydocument.sgml</command>. If there are no sgml syntax
          errors, this will create a directory <filename
          class="directory">mydocument</filename> and place the
          resulting html files in it. The title page of the document
          will typically be
          <filename>mydocument/index.html</filename>.  If you have
          screenshots in your document, you will have to copy these
          files into the <filename
          class="directory">mydocument</filename> directory by
          hand. You can use any web browser to view your document.
          Note that every time you run <command>db2html</command>, it
          creates the <filename
          class="directory">mydocument</filename> directory over, so
          you will have to copy the screenshots over each time.
        </para>
        <warning id="newTools">
          <title>Warning</title>
          <para>
             The <command>db2html</command> shipped with Red Hat 7.0
             doesn't work on documents using the GNOME DTD.  In order
             to get html, you'll need to use <command>jw -c <filename
	     class="directory">/etc/sgml/catalog</filename>
             <filename>filename.sgml</filename> -o <filename
             class="directory">filename/</filename></command>.
          </para>
        </warning>
        <para>
          You can also convert your document to PostScript by running
          the command <prompt>$</prompt><command>db2ps
          mydocument.sgml</command>, after which you can print out or
          view the resulting .ps file.  
        </para>
        <note>
          <title>Note</title>
          <para>
            The html files you get will not look quite the same as the
            documentation distributed with GNOME unless you have the
            custom stylesheets installed on your machine. DocBook
            Tools' default stylesheets will produce a different look
            to your docs. You can read more about the GDP stylesheets
            in <xref linkend="gdpstylesheets" />.
          </para>
        </note>
-->
	</sect3>
  </sect2>
  
  
  <!-- ####### Getting Started | GDP Document Templates ####### -->
  
  <sect2 id="gdptemplates">
	<title>GDP Document Templates</title>
	<para>
	  Templates for various types of GNOME documents are found at the 
	  <ulink url="http://developer.gnome.org/projects/gdp/templates.html">
		GDP Document Templates</ulink> website.  
	  They are kept in SVN at <filename class="directory">gnome-doc-utils/trunk/data/templates</filename>.
	  These templates are 
	  meant to guide you through the process of making documentation.  They 
	  contain the structure of the <sgmltag>articleinfo</sgmltag> section.  
	  The basic structure of a document is outlined.  Many different 
	  elements are marked up in DocBook such as itemized lists, variable 
	  lists, and figures.  It is okay to change the templates to fit the 
	  application you are writing documentation for.  Changing the format of 
	  the <sgmltag>articleinfo</sgmltag> section is not recommended as the 
	  output will not look nice.
	</para>
  </sect2>
  
  <!-- ####### Getting Started | Converting GNOME 1.x Documentation to GNOME 2 
  ####### -->
  
  <sect2 id="converting">
	<title>Converting GNOME 1.x Documentation to GNOME 2</title>
	<para>
      GNOME 2 documentation is written in DocBook <acronym>XML</acronym>,
      version 4.1.2.
    </para>
    <para>
      We use DocBook because it provides structured semantic markup, allowing
      publication in a variety of media. We use <acronym>XML</acronym> because
      of the more flexible tool kit available to use with it.
    </para>
	<sect3 id="conversion">
	  <title>Conversion</title>
	  <para>
		Converting documents from SGML to XML requires a few changes.
    </para>

	  <variablelist>
		<varlistentry id="convertdtd">
		  <term>The DTD</term>
		  <listitem>
			<para>
			  A new DTD is needed at the start of the document:
			  <programlisting>
	  <![CDATA[
<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
]>
	  ]]>
			  </programlisting>
			  Note that the system identifier is required.
			</para>
		  </listitem>
		</varlistentry>
		<varlistentry id="convertgraphic">
		  <term>Graphic</term>
		  <listitem>
			<para>
			  The <sgmltag>graphic</sgmltag> tag is deprecated in DocBook 
			  version 4, and while it will still work, we plan to change to
			  <sgmltag>figure</sgmltag> and <sgmltag>mediaobject</sgmltag> of 
			  several flavors, depending on whether the image is a large 
			  figure, a small figure, or a screenshot. This will utilize the 
			  greater flexibility of DocBook 4.1.2 and specify the content of 
			  the images more accurately.
			</para>

			<para>
			  A large figure is a large image which isn't a screenshot. This 
			  can be a variety of images. The markup for a large figure:
			  <programlisting>
  <![CDATA[
	<figure id="id">
	  <title>Figure Description</title>
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref="path/to/image.png" format="PNG"/>
            </imageobject>
	    <imageobject>
	       <imagedata fileref="path/to/image.eps" format="EPS"/>
            </imageobject>
	    <textobject>
	       <phrase>Acessibility description</phrase>
	    </textobject>
      </mediaobject>
    </figure>
 ]]>
			  </programlisting>
			</para>

			<para>
			  A small figure is a small image which isn't a screenshot.  This 
			  can be a variety of things.  The markup for a small figure:
			  <programlisting>
  <![CDATA[
  <mediaobject id="id">
	<imageobject>
	  <imagedata fileref="path/to/image.png" format="PNG"/>
	</imageobject>
	<imageobject>
	  <imagedata fileref="path/to/image.eps" format="EPS"/>
	</imageobject>
	<textobject>
	  <phrase>Acessibility description</phrase>
	</textobject>
  </mediaobject>
]]>
			  </programlisting>
			</para>

			<para>
			  A screenshot is an image which is taken of the desktop or of an 
			  application or a dialog box.  The markup for a screenshot:
			  <programlisting>
	 <![CDATA[
  <figure id="id">
    <title>Figure Description</title>
	<screenshot>
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref="path/to/image.png" format="PNG"/>
            </imageobject>
	    <imageobject>
	       <imagedata fileref="path/to/image.eps" format="EPS"/>
            </imageobject>
	    <textobject>
	        <phrase>Acessibility description</phrase>
	    </textobject>
      </mediaobject>
    </screenshot>
  </figure>
]]>
			  </programlisting>
			</para>
		  </listitem>
		</varlistentry>
		<varlistentry id="convertxref">
		  <term>xref</term>
		  <listitem>
			<para>
			  The <sgmltag>xref</sgmltag> tag also must be closed:
			  <programlisting>
	   <![CDATA[
<xref linkend="mainwindow-fig" />
	  ]]>
			  </programlisting>
			</para>
		  </listitem>
		</varlistentry>
<!--
    <sect4 id="others">
      <title>Others</title>
      <para>
	FIXME: other common changes required, both DocBook 3 to 4 and SGML to
	XML.
      </para>
    </sect4>
-->
		<varlistentry id="convertartheader">
		  <term>Artheader</term>
		  <listitem>
			<para>
			  <sgmltag>artheader</sgmltag> must be replaced with
			  <sgmltag>articleinfo</sgmltag>.  The contents of the
			  meta data for documentation has changed considerably.
			  Refer to the <ulink
			  url="http://developer.gnome.org/projects/gdp/templates.html">
			  GNOME 2.x templates</ulink> for more information on how
			  to write the <sgmltag>articleinfo</sgmltag> section.
			</para>
		  </listitem>
		</varlistentry>
	  </variablelist>
	</sect3>

<!--	
	<sect3 id="translation">
	  <title>Translation</title>
	  <para>
		To help translate documentation, there's a new translation tool for use
		with GNOME 2.  Called <application>doc-i18n-tool</application>, it
		extracts strings from a document and puts them in a pot file for
		translators. It can then reconstruct the translated document. 
	  </para>

	  <para>
		FIXME: Where to get it and how to use it.
	  </para>

	</sect3>
-->	
  </sect2>
  
  <!-- ####### Getting Started | GDP Style Guide ####### -->

  <sect2 id="gdpstyleguide">
	<title>GDP Style Guide</title>
	
	<para>
	  The GDP Style Guide should be read in conjunction with this document.  
	  The Style Guide tells how to write documentation, ways to structure 
	  the documentation, and technical writing techniques.  The GDP Style 
	  Guide is located at <ulink 
		url="http://library.gnome.org/devel/gdp-style-guide/stable/">
		http://library.gnome.org/devel/gdp-style-guide/stable/</ulink>.  
	</para>
	
  </sect2>

  <!-- ####### Getting Started | Screenshots ####### -->
  
  <sect2 id="screenshots">
	<title>Screenshots</title>
	<para>
	  Most GNOME documents will have screenshots of the particular
	  applet, application, GNOME component, or widget being
	  discussed.  As discussed previously all images for GNOME documentation 
	  should be in the PNG format.  Alternatively if you wish the 
	  documentation to be printed you should also include the same images 
	  in EPS format.  For the basic DocBook structure used to 
	  insert images in a document, see <xref linkend="docbookimages" /> below.
	</para>
	<sect3 id="docbookimages">
	  <title>Screenshots in DocBook</title>
	  <para>
		If your document uses images you will need to take note of a
		few things that should take place in order for you to make
		use of those images in your output.
	  </para>
	  <para>
		The DocBook tools and applications are smart enough
		to know that when you are creating html you will be using
		PNG files and when you are creating Postscript you will be
		using EPS files (you must use EPS with Postscript).
	  </para>
	  <!--
	    <para>
	      Thus, you should never explicitly
	      include the extension of the image file, since DocBook
          Tools will automatically insert it for you. For example:
        </para>
-->
	  <programlisting>
<![CDATA[
<figure id="id">
  <title>My Picture</title>
  <screenshot>
    <mediaobject>
      <imageobject>
        <imagedata fileref="myfile.png" format="PNG"/>
      </imageobject>
      <textobject>
        <phrase>Acessibility description</phrase>
      </textobject>
    </mediaobject>
  </screenshot>
</figure>
]]>   </programlisting>
<!--
        <para>
          You will notice in this example that the file
          <filename>myfile.png</filename> was referred to as simply
          <filename>myfile</filename>. Now when you run
          <application>Yelp</application> to create a <acronym>HTML</acronym> 
		  file, it will automatically look for <filename>myfile.png</filename> 
		  in the directory.
        </para>
-->
	  <para>
		If you want to create PostScript ouput, you will need to create an
		EPS version of your image file to be displayed in the
		PostScript file. There is a simple script available which
		allows you to change a PNG image into an EPS file
		easily. You can download this file - png2eps - from <ulink
          url="http://dmason.net/download/png2eps"
          type="html">http://dmason.net/download/png2eps</ulink>.
	  </para>
	</sect3>
	<sect3 id="screenshotappearance">
	  <title>Screenshot Appearance</title>
	  <para>
	  Screenshots of windows should show GNOME's default theme, Clearlooks.
	  (Your distribution may be using a different default.)</para>
	  <para>This is to minimize possible
		confusion to the reader, improve the appearance of GNOME
		documents, and guarantee the screenshot is readable when
		printed.</para>
		<para>If you are unable to provide
		screenshots in this form, you should create screenshots as
		you wish them to appear and send an email to the
		<ulink url="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/">
          <citetitle>gnome-doc-list mailing list</citetitle> </ulink>
		requesting a GDP member reproduce these screenshots in the
		correct format and email them to you.  Please do not send the actual 
		images in the email but wait until you contact someone to do the 
		screenshots for you and mail them the images.
	  </para>
	</sect3>


<!--
      <sect3 id="screenshotfiles">
        <title>Screenshot Files</title>
        <para>
          Screenshots should be kept in a directory called "figures" for 
		  application and other documentation.  After you use 
		  <application>Yelp</application> to view your XML file in HTML (see <xref
          linkend="make-output" />), you will need to copy your
          screenshots (either the individual PNG files for applet
          documentation, or the whole "figs" directory for other
          documentation) into the directory your DocBook file resides.
        </para>
      </sect3>
-->
  </sect2>


  <!-- ####### Getting Started | Application Bugs ####### -->
  
  <sect2 id="applicationbugs">
	<title>Application Bugs</title>
	<para>
	  Documentation authors tend to investigate and test applets and
	  applications more thoroughly than most 
	  users.  Often documentation authors will discover one or
	  more bugs in the software.  These bugs vary from small ones,
	  such as mis-spelled words or missing
	  <interface>About</interface> dialogs in the menu, to large
	  ones which cause the applet to crash.  As all users, you
	  should be sure to report these bugs so that application
	  developers know of them and can fix them.  The easiest way to
	  submit a bug report is by using <application>Bug
        Buddy</application> located in 
	  <menuchoice>
		<guimenu>Applications</guimenu>
		<guisubmenu>Programming</guisubmenu>
		<guimenuitem>Bug Report Tool</guimenuitem>
	  </menuchoice>.
	</para>
  </sect2>
</sect1>
