<?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" [
  <!ENTITY legal SYSTEM "legal.xml">
  <!ENTITY appversion "0.9.10">
  <!ENTITY manrevision "10.0">
  <!ENTITY date "January 2007">
  <!ENTITY app "<application>GnoCHM</application>">
  <!-- Information about the entities
       The legal.xml file contains legal information, there is no need to 
       edit the file. 
       Use the appversion entity to specify the version of the application.
       Use the manrevision entity to specify the revision number of this 
       manual.
       Use the date entity to specify the release date of this manual.
       Use the app entity to specify the name of the application. -->
]>
<!-- 
      (Do not remove this comment block.)
  Maintained by the GNOME Documentation Project
  http://developer.gnome.org/projects/gdp
  Template version: 2.0 beta
  Template last modified Apr 11, 2002
-->
<!-- =============Document Header ============================= -->
<article id="index" lang="en">
  <!-- please do not change the id; for translations, change lang to -->
  <!-- appropriate code -->
  <articleinfo> 
    <title>&app; Manual V&manrevision;</title>       

    <copyright> 
      <year>2003</year>
      <year>2004</year> 
      <year>2005</year> 
      <year>2006</year> 
      <year>2007</year> 
      <holder>Rubens Ramos</holder> 
    </copyright> 
    <!--     translators: uncomment this: -->
    
    <!--     <copyright> -->
    <!--     <year>2002</year> -->
    <!--   <holder>ME-THE-TRANSLATOR (Latin translation)</holder> -->
    <!--   </copyright> -->
    <!--     An address can be added to the publisher information.  If a role -->
    <!--     is not specified, the publisher/author is the same for all -->
    <!--     versions of the document. -->
<!--     <publisher>  -->
<!--       <publishername> Rubens Ramos </publishername>  -->
<!--     </publisher>  -->

    &legal;
    <!--     This file contains link to license for the documentation (GNU -->
    <!--     FDL), and other legal stuff such as "NO WARRANTY" -->
    <!--     statement. Please do not change any of this. -->

    <authorgroup> 
      <author> 
        <firstname>Rubens</firstname> 
        <surname>Ramos</surname> 
        <affiliation>
          <address>rubensr@users.sourceforge.net</address>
        </affiliation>
      </author>       
      <!--       This is appropriate place for other contributors: translators, -->
      <!--       maintainers,  etc. Commented out by default. -->
      <!--     <othercredit role="translator"> -->
      <!--     <firstname>Latin</firstname>  -->
      <!--     <surname>Translator 1</surname>  -->
      <!--     <affiliation>  -->
      <!--     <orgname>Latin Translation Team</orgname>  -->
      <!--     <address> <email>translator@gnome.org</email> </address>  -->
      <!--     </affiliation> -->
      <!--     <contrib>Latin translation</contrib> -->
      <!--     </othercredit> -->
    </authorgroup>


    <!-- According to GNU FDL, revision history is mandatory if you are -->
    <!-- modifying/reusing someone else's document.  If not, you can omit it. -->
    <!-- Remember to remove the &manrevision; entity from the revision entries -->
    <!-- other than the current revision.  The revision numbering system for -->
    <!-- GNOME manuals is as follows: * the revision number consists of two -->
    <!-- components * the first component of the revision number reflects the -->
    <!-- release version of the GNOME desktop.  * the second component of the -->
    <!-- revision number is a decimal unit that is incremented with each -->
    <!-- revision of the manual.  For example, if the GNOME desktop release is -->
    <!-- V2.x, the first version of the manual that is written in that desktop -->
    <!-- timeframe is V2.0, the second version of the manual is V2.1, etc. -->
    <!-- When the desktop release version changes to V3.x, the revision number -->
    <!-- of the manual changes to V3.0, and so on. -->
    <revhistory>
      <revision> 
        <revnumber>GnoCHM Manual V&manrevision;</revnumber> 
        <date>&date;</date> 
        <revdescription> 
          <para role="author">Rubens Ramos
            <email>rubensr@users.sourceforge.net</email>
          </para>
<!--           <para role="publisher">Rubens Ramos</para> -->
        </revdescription> 
      </revision> 
      <revision> 
        <revnumber>GnoCHM Manual V9.0;</revnumber> 
        <date>May 2006</date> 
        <revdescription> 
          <para role="author">Rubens Ramos
            <email>rubensr@users.sourceforge.net</email>
          </para>
<!--           <para role="publisher">Rubens Ramos</para> -->
        </revdescription> 
      </revision> 
      <revision> 
        <revnumber>GnoCHM Manual V8.0;</revnumber> 
        <date>October 2005</date> 
        <revdescription> 
          <para role="author">Rubens Ramos
            <email>rubensr@users.sourceforge.net</email>
          </para>
<!--           <para role="publisher">Rubens Ramos</para> -->
        </revdescription> 
      </revision> 
      <revision> 
        <revnumber>GnoCHM Manual V7.0;</revnumber> 
        <date>September 2005</date> 
        <revdescription> 
          <para role="author">Rubens Ramos
            <email>rubensr@users.sourceforge.net</email>
          </para>
<!--           <para role="publisher">Rubens Ramos</para> -->
        </revdescription> 
      </revision> 
      <revision> 
        <revnumber>GnoCHM Manual V6.0;</revnumber> 
        <date>March 2005</date> 
        <revdescription> 
          <para role="author">Rubens Ramos
            <email>rubensr@users.sourceforge.net</email>
          </para>
<!--           <para role="publisher">Rubens Ramos</para> -->
        </revdescription> 
      </revision> 
      <revision> 
        <revnumber>GnoCHM Manual V5.0;</revnumber> 
        <date>December 2004</date> 
        <revdescription> 
          <para role="author">Rubens Ramos
            <email>rubensr@users.sourceforge.net</email>
          </para>
<!--           <para role="publisher">Rubens Ramos</para> -->
        </revdescription> 
      </revision> 
      <revision> 
        <revnumber>GnoCHM Manual V4.0;</revnumber> 
        <date>August 2004</date> 
        <revdescription> 
          <para role="author">Rubens Ramos
            <email>rubensr@users.sourceforge.net</email>
          </para>
<!--           <para role="publisher">Rubens Ramos</para> -->
        </revdescription> 
      </revision> 
      <revision> 
        <revnumber>GnoCHM Manual V3.0</revnumber> 
        <date>February 2004</date> 
        <revdescription> 
          <para role="author">Rubens Ramos
            <email>rubensr@users.sourceforge.net</email>
          </para>
<!--           <para role="publisher">Rubens Ramos</para> -->
        </revdescription> 
      </revision> 
      <revision> 
        <revnumber>GnoCHM Manual V2.0</revnumber> 
        <date>January 2004</date> 
        <revdescription> 
          <para role="author">Rubens Ramos
            <email>rubensr@users.sourceforge.net</email>
          </para>
<!--           <para role="publisher">Rubens Ramos</para> -->
        </revdescription> 
      </revision> 
      <revision> 
        <revnumber>GnoCHM Manual V1.0</revnumber> 
        <date>December 2003</date> 
        <revdescription> 
          <para role="author">Rubens Ramos
            <email>rubensr@users.sourceforge.net</email>
          </para>
<!--           <para role="publisher">Rubens Ramos</para> -->
        </revdescription> 
      </revision> 
    </revhistory> 

    <releaseinfo>This manual describes version &appversion; of GnoCHM.
    </releaseinfo> 
    <legalnotice> 
      <title>Feedback</title> 
      <para>To report a bug or make a suggestion regarding the &app; 
       application or this manual, follow the directions in the 
       <ulink url="http://gnochm.sourceforge.net"
       type="http">GnoCHM Sourceforge page</ulink>. 
      </para>
      <!-- Translators may also add here feedback address for translations -->
    </legalnotice> 
  </articleinfo> 

  <indexterm zone="index"> 
    <primary>GnoCHM</primary> 
  </indexterm> 
  <indexterm zone="index"> 
    <primary>gnochm</primary> 
  </indexterm>

  <!-- ============= Document Body ============================= -->
  <!-- ============= Introduction ============================== -->
  <!-- Use the Introduction section to give a brief overview of what
  the application is and what it does. -->
  <sect1 id="myapp-introduction"> 
    <title>Introduction</title> 
    <para>&app; enables you to view files encoded in the MS ITSS
format. These files are most commonly known as Microsoft Html Help
files, and usually have a <filename>.chm</filename> extension.</para>
    <para>&app; has the following features:</para> 
    <itemizedlist> 
      <listitem> 
        <para>Full text search - it is possible to quickly search for
words in the CHM archive.</para>
      </listitem>
      <listitem>
        <para>Bookmarks - you can save your favorite pages in each
file and easily jump to them later.</para>
      </listitem>
      <listitem>
        <para>It supports external CHM links - some CHM files
contain hyperlinks to other CHM files. &app; is able to search a list
of directories in order to automatically find these targets.</para> 
      </listitem> 
      <listitem> 
        <para>Configurable support for HTTP links. Some of the
links in a CHM file are to web sites. &app; can be configured to open a
web browser when one of these links is clicked.</para> 
      </listitem> 
      <listitem>
        <para>Gnome2 integration. &app; supports internationalisation,
Drag-n-Drop, On-line help, applications registry, mime database and 
standard gnome command line parameters (where supported by PyGTK).</para>
      </listitem>
      <listitem>
        <para>You can view multiple files at the same time without having to start new instances of &app;.</para>
      </listitem>
      <listitem>
        <para>It is possible to display the HTML source of the current displayed page.</para>
      </listitem>
    </itemizedlist> 
  </sect1>

  <!-- =========== Getting Started ============================== -->
  <!-- Use the Getting Started section to describe the steps required
  to start the application and to describe the user interface components
  of the application. If there is other information that it is important
  for readers to know before they start using the application, you should
  also include this information here. 
  If the information about how to get started is very short, you can 
  include it in the Introduction and omit this section. -->

  <sect1 id="myapp-getting-started"> 
    <title>Getting Started</title> 

    <sect2 id="myapp-start">
      <title>To Start &app;</title>
      <para>You can start <application>&app;</application> in the following ways:</para> 
      <variablelist>
        <varlistentry>
          <term><guimenu>Applications</guimenu> menu</term>
          <listitem>
            <para>Choose 
        <menuchoice>
                <guisubmenu>Extras</guisubmenu>
                <guisubmenu>Accessories</guisubmenu>
                <guimenuitem>GnoCHM</guimenuitem>
              </menuchoice>. </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Command line</term>
          <listitem>
            <para>To start <application>&app;</application> from the
command line, type the following command, then press
<keycap>Return</keycap>:</para>
            <para> 
      <command>gnochm</command> 
      <replaceable>filename.chm</replaceable>
        </para> 
            <para>where 
      <replaceable>filename.chm</replaceable> is the (optional) name
of the file you  want to open.</para> 
            <para>You can specify more than one file in the command line, and &app; will open each one of them in separate windows.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>File Manager</term>
          <listitem>
            <para>When using the File Manager, right-click on a CHM
file, and then select:
        <menuchoice>
                <guisubmenu>Open With</guisubmenu>
                <guimenuitem>gnochm</guimenuitem>
              </menuchoice>. </para>
          </listitem>
        </varlistentry>
      </variablelist>
    </sect2>

    <sect2 id="myapp-when-start">
      <title>When You Start &app;</title>

      <!-- ==== Figure ==== -->
<!--       <figure id="mainwindow-fig">  -->
<!--         <title>&app; Start Up Window</title>  -->
<!--         <screenshot>  -->
<!--           <mediaobject>  -->
<!--             <imageobject><imagedata -->
<!--                                     fileref="figures/myapp_start_window.png" format="PNG"/>  -->
<!--             </imageobject> -->
            <!-- EPS versions of the figures are not required at the moment. -->
            <!-- 
          <imageobject>
          <imagedata fileref="figures/image.eps" format="EPS"/>
          </imageobject>
            -->
<!--             <textobject>  -->
<!--               <phrase>Shows &app; main window. Contains titlebar, menubar, toolbar, display area, and -->
<!--         scrollbars. Menubar contains File, View, Settings, and Help menus. </phrase>  -->
<!--             </textobject>  -->
<!--           </mediaobject>  -->
<!--         </screenshot>  -->
<!--       </figure> -->
      <!-- ==== End of Figure ==== -->

      <!-- Include any descriptions of the GUI immediately after the screenshot of the main UI, -->
      <!-- for example, the items on the menubar and on the toolbar. This section is optional. -->

      <para>The &app; window contains the following elements:
    </para>
      <variablelist>
        <varlistentry>
          <term>Menubar. </term>
          <listitem>
            <para>The menus on the menubar contain all of the commands you need to work with files in 
  <application>&app;</application>.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Toolbar. </term>
          <listitem>
            <para> The toolbar contains a subset of the commands that you can access from the menubar.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Statusbar. </term>
          <listitem>
            <para>The statusbar displays information about current <application>&app;</application> 
  activity and contextual information about the menu items. </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Shortcuts</term>
          <listitem>
            <para>The shortcuts area is a tabbed window that can be
used to quickly navigate through a document.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>CHM Window</term>
          <listitem>
            <para>The CHM window is used to display pages of a CHM document.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </sect2>
    <sect2 id="myapp-command-line">
      <title>Command line parameters</title>
      <para>As indicated in <xref linkend="myapp-start"/>, &app; can
be run from the command-line. These are the currently accepted command
line parameters:</para>
      <variablelist>
        <varlistentry>
          <term>-h or --help</term>
          <listitem>
            <para>This will print a help message and exit.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>-v or --version</term>
          <listitem>
            <para>This prints the current &app; version and exits.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>-d or --debug</term>
          <listitem>
            <para>If this option is given, &app; runs in debug
mode. In debug mode, run-time information is written to a file named
<filename>~/.gnochm/gnochm.log</filename>. This mode is used to gather
information for bug reports. See <xref linkend="myapp-bug-report"/>
for more details.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </sect2>
  </sect1>
  <!-- ================ Usage ================================ -->
  <!-- Use this section to describe how to use the application to -->
  <!-- perform the tasks for which the application is designed. -->
  <sect1 id="myapp-usage"> 
    <para>The following items describe in detail how to use
&app;:</para>
    <itemizedlist> 
      <listitem> 
        <para><xref linkend="myapp-open-file"/> Opening Files</para> 
      </listitem> 
      <listitem> 
        <para><xref linkend="myapp-copying-text"/> Copying text 
from the HTML window</para> 
      </listitem> 
      <listitem> 
        <para><xref linkend="myapp-manipulate-view"/> Changing the 
zoom</para> 
      </listitem> 
      <listitem> 
        <para><xref linkend="myapp-contents-tree"/> Using the 
Contents Tree</para> 
      </listitem> 
      <listitem> 
        <para><xref linkend="myapp-index-tree"/> Using the 
Index Tree</para> 
      </listitem> 
      <listitem> 
        <para><xref linkend="myapp-search-tab"/> Searching 
for words</para> 
      </listitem> 
      <listitem> 
        <para><xref linkend="myapp-bookmarks"/> Using bookmarks</para> 
      </listitem> 
      <listitem>
        <para><xref linkend="myapp-navigation-buttons"/> Using the 
navigation buttons</para> 
      </listitem> 
      <listitem> 
        <para><xref linkend="myapp-newwindow"/> Viewing the HTML source</para> 
      </listitem> 
      <listitem> 
        <para><xref linkend="myapp-quit"/> Closing windows/Exiting the program</para> 
      </listitem> 
    </itemizedlist>    
    <title>Usage</title> 
    <!-- ================ Usage Subsection ================================ -->
    <sect2 id="myapp-open-file"> 
      <title>To Open a File</title>
      <para>Once &app; is running, it is possible to open files in the following ways:</para>
      <variablelist>
        <varlistentry>
          <term>Using the menu</term>
          <listitem>
            <para>To open a CHM file, choose:</para>
            <menuchoice> 
              <guimenu>File</guimenu> 
              <guimenuitem>Open...</guimenuitem> 
            </menuchoice>
            <para>The <guilabel>Select File</guilabel> dialog is
displayed. Select the file that you want to open, then click
<guibutton>OK</guibutton>. </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Using the Recents menu</term>
          <listitem>
            <para>The files you opened recently are also present in
the <menuchoice><guimenu>File</guimenu><guimenuitem>Recent
Files</guimenuitem> </menuchoice> menu. All you have to do is select
the archive you want to open 
(see <xref linkend="myapp-prefs-general"/> for 
details on how to change the number of entries in this menu)</para> 
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Using the toolbar</term>
          <listitem>
            The toolbar has an <guibutton>Open</guibutton> button that
            will also invoke the <guilabel>Select File</guilabel>
            dialog.
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Using the keyboard shortcut</term>
          <listitem>
            <para>To verify which keyboard shortcut to use, open the <guimenu>File</guimenu> menu and check the binding next to the <guimenuitem>Open...</guimenuitem> entry.</para>
            <para>To invoke the <guilabel>Select File</guilabel> dialog, just type in the shortcut.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Drag and Drop</term>
          <listitem>
            You can drag a CHM file from the File Manager window into
            the &app; Html window.
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Opening multiple windows</term>
          <listitem>
            <para>If you want to open more than one file at the same time, select:
             <menuchoice> 
              <guimenu>File</guimenu> 
              <guimenuitem>New</guimenuitem> 
            </menuchoice>
           . This will open a new &app; window.</para>
          </listitem>
        </varlistentry>
      </variablelist>
      <para>If you open a document in a window where another document is 
already being viewed, the current document is automatically closed.</para>
      <note>
        <para>If the file you are trying to open is not a CHM file, or
if a non-existing file name is given, a dialog indicating the error
will be shown.</para>
      </note>
    </sect2> 
    <!-- ================ Usage Subsection ================================ -->
    <sect2 id="myapp-copying-text">
      <title>Copying text from the HTML window</title>
      <para>There are two ways to select and copy text from the HTML window:
</para>
      <itemizedlist>
	<listitem>
	  <para>Select the text you want to copy, and using your mouse, paste
the selected text, which is usually achieved by pressing the middle mouse button
on the target window.</para>
	</listitem>
	<listitem>
	  <para>Select the text to be copied, and copy the text to the clipboard
by either using the <guimenu>Edit/Copy</guimenu> menu, right-clicking on the
HTML window and selecting the <guimenu>Copy</guimenu> option, or simply by
pressing the Copy shortcut (which is usually <keycombo><keycap>Ctrl</keycap>
<keysym>C</keysym></keycombo>).</para>
	</listitem>
      </itemizedlist>
    </sect2>
    <!-- ================ Usage Subsection ================================ -->
    <sect2 id="myapp-manipulate-view"> 
      <title>Changing the zoom</title> 
      <para>You can use the following methods to resize the view of an
image in the Html window:</para>
      <itemizedlist> 
        <listitem> 
          <para>To enlarge the HTML view, press the
<guibutton>Zoom In</guibutton> button.</para>
        </listitem> 
        <listitem> 
          <para>To shrink the HTML view, press the
<guibutton>Zoom Out</guibutton> button.</para>
        </listitem> 
        <listitem> 
          <para>To view the document at its actual size, press the
<guibutton>Reset Zoom</guibutton>.</para> 
        </listitem> 
      </itemizedlist> 
      <para>In addition to the toolbar buttons it is also possible to
resize the view using the <guimenu>View</guimenu> menu entries. These
commands also have shortcuts associated with them.</para>
    </sect2> 
    <!-- ================ Usage Subsection ================================ -->
    <sect2 id="myapp-contents-tree"> 
      <title>Using the Contents Tree</title> 
      <para>To quickly jump to a section of the document, you can
select it in the Contents Tab in the Shortcuts tab.</para> 
      <para>Sub sections can be collapsed or expanded in the tree. To
expand or collapse a branch, just click on the mark that is on the
left of each section header.</para>
      <para>It is possible to search through the contents tree -
the key bindings for this can be different for each system - but
usually bound to <keycombo><keycap>Ctrl</keycap><keysym>F</keysym>
</keycombo>.</para>
      <note>
        <para>In some CHM documents, certain nodes do not
contain any Html files, so even if you click on them,
nothing will be displayed on the Html window.</para>
      </note>
    </sect2>
    <!-- ================ Usage Subsection ================================ -->
    <sect2 id="myapp-index-tree"> 
      <title>Using the Index Tree</title> 
      <para>The index tree, just like the Contents tree (<xref linkend="myapp-contents-tree"/>), is used to
      quickly jump to specific sections of a document. To use it, just
      select the Index tab in the Shortcuts window, select the
      index item you want to jump to and press the
<guibutton>Display</guibutton> button.</para>
      <para>It is possible to search through the index -
the key bindings for this can be different for each system - but
usually bound to <keycombo><keycap>Ctrl</keycap><keysym>F</keysym>
</keycombo>.</para>
      <note>
        <para>Not all CHM documents contain an Index. For these
documents, &app; will not display the Index tab.</para>
      </note>
    </sect2>
    <!-- ================ Usage Subsection ================================ -->
    <sect2 id="myapp-search-tab">
      <title>Searching for words</title>
      <para>It is possible to quickly search for one or more words in
the CHM document - using the Search tab in the shortcuts
window. You can also reach the Search tab using the <menuchoice><guisubmenu>Edit</guisubmenu><guisubmenu>Search in archive</guisubmenu></menuchoice> menu entry, or use the shortcut shown beside this entry.</para>
      <para>To search for a word, just type it in the combo box at the
top of the window and press the <guibutton>Search</guibutton>
button.</para>
      <para>The searches can be customized using the checkboxes in the
search window. Following is a description of their usage:
<variablelist>
          <varlistentry>
            <term>Whole words only</term>
            <listitem>
              If this option is set, &app; will only search for words
              that completely match the selection.
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>Titles only</term>
            <listitem>
              If this box is checked, only page titles are searched,
              not page contents.
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>Search previous results</term>
            <listitem>
              If this entry is selected, the search will look for the
              words in the results of the previous search. Every time
              a new document is opened, the previous result is
              cleared. This option has no effect while the previous
              search value is cleared.
            </listitem>
          </varlistentry>
        </variablelist></para>
      <para>It is possible to search through the match results -
the key bindings for this can be different for each system - but
usually bound to <keycombo><keycap>Ctrl</keycap><keysym>F</keysym>
</keycombo>.</para>
      <note>
        <para>CHM files store words for search as lowercase strings
without accents, so the search is
<emphasis>case-insensitive</emphasis>.</para>
        <para>You should not enter accented characters in your search
words, because the words are stored in ASCII format in the CHM words
database.</para>
      </note>
      <sect3>
        <title>Executing complex searches</title>
        <para>If more than one word is entered in the search combo
box, &app; will match pages that have <emphasis>ALL</emphasis> of the
words.</para>
        <para>In order to formulate more complex queries, the keywords
<emphasis>AND</emphasis> and <emphasis>OR</emphasis> (note they are
capitalized) can be used. <emphasis>AND</emphasis> has the same effect
as separating words with spaces, and <emphasis>OR</emphasis> searches
for pages that contain one word or another.</para>
        <para>Note that <emphasis>OR'ed</emphasis> terms are handled
after <emphasis>AND'ed</emphasis> terms. So, in the sentence 
<quote>word1 OR word2 AND word3 word4</quote>, &app; will search for
pages that contain the word <emphasis>word1</emphasis> or all of the
words <emphasis>word2, word3</emphasis> and
<emphasis>word4</emphasis>.</para>
      </sect3>
    </sect2>
    <!-- ================ Usage Subsection ================================ -->
    <sect2 id="myapp-bookmarks">
      <title>Using bookmarks</title>
      <para>Bookmarks are used to save links to frequently used pages
in your CHM files. In order to store a bookmark, just choose a page
that you want to link to, jump to it (so it is displayed on the HTML
window) and then enter a name for it in the entry box at the bottom of
the Bookmarks tab in the shortcuts window. Once this is done, you just
need to press <guibutton>Add</guibutton>.</para>
      <para>&app; will warn you if a bookmark with the same title has
already been saved, and prompt you to confirm if you want to overwrite
it. It will <emphasis>not</emphasis> prevent links with different
names that point to the same page from being saved.</para>
      <para>In order to remove a bookmark, select it in the list box,
and press the <guibutton>Remove</guibutton> button.</para>
      <para>Bookmarks for a certain file will be automatically saved
and reloaded every time you open a certain file. In order to use the
bookmarks you saved, just double-click on it in the list window, or
select it and press the <guibutton>Display</guibutton> button.</para>
      <para>Note that in order to load bookmarks for a certain file,
&app; compares its <emphasis>full</emphasis> pathname with the stored
bookmark file name. So if identical files have the same name but live
in different folders, &app; will handle them as different files as far
as bookmarks are concerned.</para>
    </sect2>
    <!-- ================ Usage Subsection ================================ -->
    <sect2 id="myapp-navigation-buttons"> 
      <title>Using the navigation buttons</title> 
      <para>There are three navigation buttons on the toolbar:
<guibutton>forward</guibutton>, <guibutton>back</guibutton> and
<guibutton>home</guibutton>:</para>
      <variablelist>
        <varlistentry>
          <term>Back</term>
          <listitem>
            <para>This button is used to visit pages that were previously
            seen.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Forward</term>
          <listitem>
            <para>If you were using the <guibutton>Back</guibutton>
button, this one will allow you to go forwards.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Home</term>
          <listitem>
            <para>The <guibutton>Home</guibutton> button jumps back to
the main page of the CHM file. Note that it is not necessarily the
page at the top of the Contents Tree.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </sect2>
    <!-- ================ Usage Subsection ================================ -->
    <sect2 id="myapp-newwindow"> 
      <title>Viewing the HTML source</title> 
      <para>To view the HTML source for the currently displayed page, select
      <menuchoice>
          <guimenu>View</guimenu>
          <guimenuitem>View Source</guimenuitem>
        </menuchoice></para>
      <para>The source will be displayed on a separate window or will replace the page currently being viewed in the CHM Window, depending on the preference settings (<xref linkend="myapp-prefs-general"/>).</para>
      <para>When showing the source in the CHM Window, the same menu option can be used to switch between the source/HTML representations.</para>
    </sect2>
    <!-- ================ Usage Subsection ================================ -->
    <sect2 id="myapp-quit"> 
      <title>Closing windows/Exiting the program</title> 
      <para>To exit &app;, choose
      <menuchoice>
          <guimenu>File</guimenu>
          <guimenuitem>Quit</guimenuitem>
        </menuchoice></para>
      <para>If you have more than one file opened, and want to close its window, you can select:
            <menuchoice> 
              <guimenu>File</guimenu> 
              <guimenuitem>Close</guimenuitem> 
            </menuchoice>
       </para>
      <para>If you have just one window opened, choosing this option will exit &app;.</para>
    </sect2>
  </sect1>
  <!-- ============= Customization ============================= -->
  <!-- Use this section to describe how to customize the application. -->
  <sect1 id="myapp-prefs"> 
    <title>Preferences</title> 
    <para>To configure &app;, choose 
      <menuchoice> 
        <guimenu>Edit</guimenu> 
        <guimenuitem>Preferences</guimenuitem> 
      </menuchoice>. The 
      <guilabel>Preferences</guilabel> dialog contains the following tabbed
      sections:</para> 
    <itemizedlist> 
      <listitem> 
        <para><xref linkend="myapp-prefs-general"/> General</para> 
      </listitem> 
      <listitem> 
        <para><xref linkend="myapp-prefs-chm"/> CHM</para> 
      </listitem> 
      <listitem> 
        <para><xref linkend="myapp-prefs-http"/> HTTP</para> 
      </listitem> 
    </itemizedlist>
    <!-- =============== Customization Subsection ================ -->
    <!-- Use a new section to describe different tabbed sections on the Settings or Preferences
    dialog. -->
    <sect2 id="myapp-prefs-general"> 
      <title>General</title> 
      <variablelist> 
        <varlistentry> 
          <term><guilabel>HTML window background</guilabel></term> 
          <listitem> 
            <para>Use this color selection button to define a default
color to use in the Html window. Note that some pages will override
this value anyway.</para>
            <para>Default: <guilabel>White</guilabel>.</para> 
          </listitem> 
        </varlistentry> 
        <varlistentry> 
          <term><guilabel>Contents Tree initial state</guilabel> </term> 
          <listitem> 
            <para>Use this drop-down list box to specify the initial
state of the Contents Tree when a new file is opened. Select one of
the following options:</para>
          </listitem> 
        </varlistentry> 
        <varlistentry> 
          <term> <guilabel>Index Tree initial state</guilabel> </term> 
          <listitem> 
            <para>Same as for the Contents Tree.</para> 
          </listitem> 
        </varlistentry> 
        <varlistentry>
          <term><guilabel>Number of entries in the recents menu</guilabel></term>
          <listitem>
            <para>This is a number that define the maximum number of
            entries in the recents menu. Its value can range from 1 to
            20.</para> 
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><guilabel>View source in a new window</guilabel></term>
          <listitem>
            <para>If this option is enabled, the source for the currently shown page will be displayed in a new window. Otherwise the source will replace the page in the main window.</para>
            <para>Note that when using the CHM window, the page source is not added to the page history, so moving to a different page and then pressing the <guibutton>Back</guibutton> button will not redisplay the source.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><guilabel>Synchronise page and contents tree</guilabel></term>
          <listitem>
            <para>If this option is enabled, when a new page is displayed in the HTML window, the selection on the contents tree is updated to reflect that.</para>
          </listitem>
        </varlistentry>
        <varlistentry> 
          <term><guilabel>Toolbar enabled</guilabel> </term> 
          <listitem> 
            <para>If this box is not selected, the toolbar is not shown.</para>
          </listitem> 
        </varlistentry> 
        <varlistentry> 
          <term><guilabel>Toolbar tooltips enabled</guilabel> </term> 
          <listitem> 
            <para>If this box is not selected, the toolbar tooltips are not shown. This option is available only when the toolbar check box is selected.</para>
          </listitem> 
        </varlistentry> 
      </variablelist> 
    </sect2>
    <!-- ============= Customization Subsection ===================== -->
    <!-- Another tabbed section on the Preferences dialog. -->
    <sect2 id="myapp-prefs-chm"> 
      <title>CHM</title> 
      <para>This section is used to configure details specific to CHM
files behaviour.</para>
      <variablelist> 
        <varlistentry> 
          <term> <guilabel>CHM search path</guilabel> </term> 
          <listitem> 
            <para>Some CHM files contain internal links that reuse
components or files from other CHM files. This is a list of
directories that &app; will automatically use to search for these
external files. It is a <emphasis>:</emphasis> (colon) separated
list.</para>
            <para>You can also use the <guibutton>Browse...</guibutton> button to select directories that will then be added to the list.</para>
            <para>Note that in addition to this, &app; will also use
the contents of the environment variable <envar>CHMPATH</envar> to
search for files. It is also a colon-separated list of directories.</para>
          </listitem>
        </varlistentry> 
        <varlistentry>
          <term>Use Locale (LCID) from archive</term>
          <listitem>
            <para>Most archives define their character encoding in an internal file called #SYSTEM. This information is used to render the topics and index lists for example. When the archive does not have that information, &app; can try to deduce this by looking at the LCID (Locale ID - when it exists) that is also included in the CHM file. If you are experiencing situations where the characters in the topics or index lists are not being rendered properly, you can try to disable this.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Save last used path</term>
          <listitem>
            <para>By enabling this option, &app; will reuse the last pathname used to load an archive the next time &app; is run.</para>
          </listitem>
        </varlistentry>
      </variablelist> 
    </sect2> 
    <!-- ============= Customization Subsection ===================== -->
    <!-- Another tabbed section on the Preferences dialog. -->
    <sect2 id="myapp-prefs-http"> 
      <title>HTTP</title> 
      <para>This section is used to configure the &app; behaviour when
HTTP links are selected in the Html window.</para>
      <variablelist> 
        <varlistentry> 
          <term> <guilabel>Web browser</guilabel> </term> 
          <listitem> 
            <para>Some CHM files contain links to HTTP (internet)
pages. It is possible to access these pages via an external web
browser or to ignore them completely.</para>
          </listitem>
        </varlistentry> 
        <varlistentry> 
          <term> <guilabel>New browser window</guilabel> </term> 
          <listitem> 
            <para>If allowed by the window manager, &app; can open a
new web browser window every time a HTTP link is clicked on the Html window.</para>
          </listitem>
        </varlistentry> 
        <varlistentry> 
          <term> <guilabel>Auto raise browser window</guilabel> </term> 
          <listitem> 
            <para>If allowed by the window manager, &app; will raise
the browser window when a new HTTP link is clicked on the Html window.</para>
          </listitem>
        </varlistentry> 
      </variablelist> 
    </sect2> 
  </sect1>
  <!-- ============= Bugs ================================== -->
  <!-- This section is optional and is commented out by default. 
  You can use it to describe known bugs and limitations of the 
  program if there are any - please be frank and list all
  problems you know of. -->
  
  <sect1 id="myapp-bugs">
    <title>Known Bugs and Limitations</title>
    <para> This section lists bugs and limitations of this
program.</para>
    <sect2 id="myapp-bugs-limitations">
      <title>Limitations</title>
      <variablelist>
        <varlistentry>
          <term>No support for printing</term>
          <listitem>
            <para>As far as I know, there is no support for printing
in GtkHTML2. Since I needed CSS support, it seems to me that I would
not be able to use GtkHTML1 for &app;. Some people suggested that I
should use GtkHTML3, but I have to say I am reluctant to do this,
since I could not find strong evidence that it is either being
developed or even being packaged/supported too much.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>No "find" command inside pages</term>
          <listitem>
            <para>It is not possible to search for strings inside the
GtkHTML2 widget (as far as I know). Even if it was, I don't think this
feature is in the PyGTK bindings, so all I can do is wait.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>No support for <emphasis>merge</emphasis> tag in CHM files</term>
          <listitem>
            <para>In some files, the contents are created by merging
contents from external CHM files. When &app; is building the contents
tree, it will just skip these nodes silently. Support for this feature
is still in my plans but I have not got the time to do it yet.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Why don't you use GtkHTML2 to open HTTP links?</term>
          <listitem>
            <para>Well, I actually planned to do that, but I had to
start making too many changes to &app;, so this is now a low priority activity.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Can you use the hourglass cursor or a progress bar when
opening a large document?</term>
          <listitem>
            <para>I actually tried that - but did not quite work well,
because I could not find a way to ask GtkHTML2 to notify my
application when it finishes parsing its file and rendering its
contents...</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </sect2>
    <sect2 id="myapp-bugs-known">
      <title>Known Bugs</title>
      <variablelist>
        <varlistentry>
          <term>&app; crashes every time I follow a HTML link!</term>
          <listitem>
            <para>Please use gtkhtml2 version 2.6.1 or higher.</para>
            <para>Gtkhtml2 sources are available at the <ulink url="http://ftp.gnome.org/pub/GNOME/sources/libgtkhtml">Gnome ftp site</ulink>.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>I am clicking on an anchor, but &app; does not jump to it!</term>
          <listitem>
            <para>This seems to be a bug (and it is on buzilla) on the GtkHTML2 widget, when anchors without #PCDATA are used.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Funny characters show up in the Html window</term>
          <listitem>
            <para>Yes, it happens with some files - my guess is that
this is related to the file encoding, but I have no idea why.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Menu and Toolbar detach option cannot be configured via the system configuration tool!</term>
          <listitem>
            <para>Yes - and that is because libglade is not registering the dock items to listen to the desktop gconf values - I wrote most of the code in python, but the bindings I am using lack one of the APIs from bonobodockitem (it is private) to change the dock item behaviour.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </sect2>
    <sect2 id="myapp-bug-report">
      <title>Bug reports</title>
      <para>If you believe you found a new bug, you can submit a bug
report to the maintainers, so that the problem can be fixed in the
next &app; release. </para>
      <para>In order to provide adequate information in your bug
report, make sure you include the following:</para>
      <itemizedlist>
        <listitem>
          <para>The version of &app; you are running;</para>
        </listitem>
        <listitem>
          <para>The system you are using (e.g. Fedora Core 3, RedHat 8.0, Mandrake 9.2, etc.);</para>
        </listitem>
        <listitem>
          <para>The type of &app; distribution you used - RPM, source,
other?;</para>
        </listitem>
        <listitem>
          <para>Versions of the following programs/libraries:</para>
          <itemizedlist>
            <listitem>PyCHM</listitem>
            <listitem>Python</listitem>
            <listitem>pygtk2</listitem>
            <listitem>pygtk2-libglade</listitem>
            <listitem>gnome-python2</listitem>
            <listitem>gnome-python-gtkhtml2</listitem>
          </itemizedlist>
        </listitem>
        <listitem>
          <para>A good description of how to re-create the problem. If
the bug only shows up when you open a particular file, provide a
pointer to where the file can be obtained, so we can verify our fix;</para>
        </listitem>
        <listitem>
          <para>A log file. Check <xref linkend="myapp-command-line"/>
to see how to run &app; in <emphasis>debug</emphasis> mode.</para>
        </listitem>
      </itemizedlist>
      <para>To submit a bug report or a feature request, go to the 
<ulink url="http://sourceforge.net/projects/gnochm/" type="http">&app;
project</ulink> webpage and follow the links in the page.</para> 
    </sect2>
  </sect1>

  <!-- ============= About ================================== -->
  <!-- This section contains info about the program (not docs), such as
  author's name(s), web page, license, feedback address. This
  section is optional: primary place for this info is "About.." box of
  the program. However, if you do wish to include this info in the
  manual, this is the place to put it. Alternatively, you can put this information in the title page.-->
  <sect1 id="myapp-about"> 
    <title>About &app;</title> 
    <para> &app; was written by Rubens Ramos
      (<email>rubensr@users.sourceforge.net</email>).</para>
    <para>To find more information about &app;, please visit the 
      <ulink url="http://gnochm.sourceforge.net" type="http">GnoCHM Web
  page</ulink>. </para>
    <para>
      To report a bug or make a suggestion regarding this application or
      this manual, follow the directions in this 
      <ulink url="http://gnochm.sourceforge.net" type="http">web site</ulink>.
    </para>

    <para> This program is distributed under the terms of the GNU
      General Public license as published by the Free Software
      Foundation; either version 2 of the License, or (at your option)
      any later version. A copy of this license can be found at this
      <ulink url="ghelp:gpl" type="help">link</ulink>, or in the file
      COPYING included with the source code of this program. </para>

    <sect2 id="myapp-about-ack">
      <title>Acknowledgements</title>

      <para>Icons/Logo by Kostia</para>

      <para>Translations:</para>

      <itemizedlist>
	<listitem>Chinese translation by Carlos Liu</listitem>
	<listitem>Czech translation by Zbynek Mrkvicka</listitem>
	<listitem>French translation by David Mascle</listitem>
	<listitem>German translation by Daniel Schindler.</listitem>
	<listitem>Greek translation by Antonis Papaderos</listitem>
	<listitem>Hungarian translation by Garami Gábor</listitem>
	<listitem>Italian translation and patches by Alessandro Gatti</listitem>
	<listitem>Japanese translation by Tadashi Jokagi</listitem>
	<listitem>Polish translation by Michał Kastelik</listitem>
	<listitem>Portuguese (BR) updates by Alan Kelon</listitem>
	<listitem>Russian translation by Alexandre Prokoudine, Vitaly Lipatov, Basil Shubin</listitem>
	<listitem>Spanish translation by Antonio Garcia Marin</listitem>
	<listitem>Swedish translation by Daniel Nylander</listitem>
	<listitem>Traditional Chinese Taiwan by Chao, Wei-Lun</listitem>
	<listitem>Turkish translation by Sertac O. YILDIZ</listitem>
	<listitem>Vietnamese translation by Huttic</listitem>
	<listitem>Mime patch by Dag Wieers and Mariusz Smykula</listitem>
      </itemizedlist>

      <para>Thanks to:</para>

      <itemizedlist>
	<listitem>
	  James Henstrige  - for writing the python bindings
	</listitem>
	<listitem>
	  Christian Reis   - for maintaining the PyGTK FAQ/Web site
	</listitem>
	<listitem>
	  Jed Wing         - for developing CHMLIB
	</listitem>
	<listitem>
	  Pabs             - for the excellent CHM documentation
	</listitem>
	<listitem>
	  People at #pygtk - Thanks for the help, guys!
	</listitem>
	<listitem>
	  Padraig O'briain - for helping with the gtkhtml2 problem
	</listitem>
      </itemizedlist>

      <para>Patches, bug reports and help testing:</para>

      <para>Paolo Borelli, David Breakey, Ed Catmur, Joseph Churchill, Ahmed El-Mahmoudy, Zoltan Filyo, Alessandro Gatti, Ow Mun Heng, Raphael Higino, Jan Horacek, Ismael Juma, Alan Kelon, Carlos Liu, Eugenia Loli-Queru, Darius Mazeika, Jiri Pejchal, Renato Ramonda, Jody Ricker, Pablo Rodriguez, Fabio Silva, JD Smith, Alex Tarkovsky, Scott Tsai, Cheuksan Edward Wang, Glenn Washburn, Ralgh Young, Nan Zou</para>
    </sect2>
  </sect1> 
</article>
