Merge pull request #51 from infirit/yelptools

Use yelp-tools instead of mate-doc-utils

1 files changed, 511 insertions, 0 deletions

diff --git a/battstat/docs/C/index.docbook b/battstat/docs/C/index.docbook
new file mode 100644
index 00000000..09d358cb
--- /dev/null
+++ b/battstat/docs/C/index.docbook
@@ -0,0 +1,511 @@
+<?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 appletversion "2.12.0">
+  <!ENTITY applet "Battery Charge Monitor">
+]>
+
+<!-- 
+      (Do not remove this comment block.)
+  Maintained by the MATE Documentation Project
+  http://developer.mate.org/projects/gdp
+  Template version: 2.0 beta
+  Template last modified Feb 12, 2002
+-->
+
+<!-- =============Document Header ============================= -->
+<article id="index" lang="en">
+<!-- please do not change the id; for translations, change lang to -->
+<!-- appropriate code -->
+  <articleinfo> 
+    <title>&applet; Manual</title> 
+    <abstract role="description">
+      <para>&applet; shows the current charge of the 
+        battery and provides notifications if charge drops below a certain
+        threshold.</para>
+    </abstract>
+    <copyright>
+      <year>2005</year>
+      <holder>Davyd Madeley</holder>
+    </copyright>
+    <copyright>
+      <year>2004</year>
+      <holder>Angela Boyle</holder>
+    </copyright>
+    <copyright>
+      <year>2004</year>
+      <holder>Sun Microsystems</holder>
+    </copyright>
+    <copyright>
+      <year>2002</year>
+      <holder>Trevor Curtis</holder>
+    </copyright>
+    <copyright> 
+      <year>1999</year> 
+      <year>2000</year> 
+      <holder>Jorgen Pehrson</holder> 
+    </copyright>
+<!-- translators: uncomment this:
+
+    <copyright>
+     <year>2002</year>
+     <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
+    </copyright>
+
+   -->
+
+    <publisher role="maintainer"> 
+      <publishername> MATE Documentation Project </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>Sun</firstname>
+        <surname>MATE Documentation Team</surname>
+        <affiliation><orgname>Sun Microsystems</orgname></affiliation>
+      </author>
+      <author>
+        <firstname>Trevor</firstname>
+        <surname>Curtis</surname>
+        <affiliation>
+          <orgname>MATE Documentation Project</orgname>
+          <address> <email>[email protected]</email> </address>
+        </affiliation>
+      </author>
+      <author> 
+        <firstname>Jorgen </firstname> 
+        <surname> Pehrson</surname> 
+        <affiliation> 
+          <orgname>MATE Documentation Project</orgname> 
+          <address> <email>[email protected]</email> </address> 
+        </affiliation> 
+      </author> 
+      <author>
+	<firstname>Angela</firstname>
+	<surname>Boyle</surname>
+	<affiliation>
+	  <orgname>MATE Documentation Project</orgname>
+	</affiliation>
+      </author>
+      <author>
+        <firstname>Davyd</firstname>
+	<surname>Madeley</surname>
+	<affiliation>
+	  <orgname>MATE Project</orgname>
+	</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>[email protected]</email> </address> 
+	       </affiliation>
+	       <contrib>Latin translation</contrib>
+             </othercredit>
+-->
+
+    </authorgroup>
+	
+	<releaseinfo revision="2.26" role="review"/>
+
+    <revhistory>
+      <revision>
+        <revnumber>Version 2.12</revnumber>
+	<date>September 2005</date>
+	<revdescription>
+	  <para role="author">Davyd Madeley</para>
+	</revdescription>
+      </revision>
+      <revision>
+        <revnumber>Version 2.10</revnumber>
+	<date>March 2005</date>
+	<revdescription>
+	 <para role="author">Davyd Madeley</para>
+	</revdescription>
+      </revision>
+      <revision>
+	<revnumber>Version 2.8</revnumber>
+	<date>September 2004</date>
+	<revdescription>
+	  <para role="author">Angela Boyle</para>
+	  <para role="publisher">MATE Documentation Project</para>
+	</revdescription>
+      </revision>
+      <revision>
+        <revnumber>Battery Charge Monitor Applet Manual V2.2</revnumber>
+        <date>August 2004</date>
+        <revdescription>
+          <para role="author">Sun MATE Documentation Team</para>
+          <para role="publisher">MATE Documentation Project</para>
+        </revdescription>
+      </revision>
+      <revision>
+        <revnumber>Battery Charge Monitor Applet Manual V2.0</revnumber>
+        <date>May 2002</date>
+        <revdescription>
+          <para role="author">Trevor Curtis
+            <email>[email protected]</email>
+          </para>
+          <para role="author">Jorgen Pehrson
+            <email>[email protected]</email>
+          </para>
+          <para role="publisher">MATE Documentation Project</para>
+        </revdescription>
+      </revision>
+    </revhistory>
+                                                                                                  
+    <releaseinfo>This manual describes version &appletversion; of &applet;.
+    </releaseinfo>
+                                                                                                  
+    <legalnotice>
+      <title>Feedback</title>
+      <para>
+        To report a bug or make a suggestion regarding the &applet; applet or
+        this manual, follow the directions in the <ulink url="help:mate-feedback"
+        type="help">MATE Feedback Page</ulink>.
+      </para>
+    </legalnotice> 
+  </articleinfo> 
+
+  <indexterm zone="index"> 
+	 <primary>Battery Charge Monitor Applet</primary> 
+  </indexterm> 
+
+  <indexterm zone="index"> 
+	 <primary>Battstat Applet</primary> 
+  </indexterm> 
+
+<!-- ============= Document Body ============================= -->
+<!-- ============= Introduction ============================== -->
+  <sect1 id="battstat-introduction"> 
+    <title>Introduction</title> 
+
+    <figure id="battstat-applet-fig"> 
+      <title>&applet; Applet</title> 
+      <screenshot> 
+        <mediaobject> 
+          <imageobject><imagedata
+            fileref="figures/battstat-applet.png" format="PNG"/> 
+          </imageobject>
+          <textobject> 
+            <phrase>The &applet; applet.</phrase>
+          </textobject> 
+        </mediaobject> 
+      </screenshot> 
+    </figure>
+
+    <para>
+      The <application>&applet;</application> shows the
+      status of any batteries in your laptop computer. The monitor can tell you
+      the capacity remaining both visually and as a percentage, as well as offer
+      you an estimate of the time remaining based off the current usage rate.
+    </para>
+
+    <sect2 id="battstat-introduction-add">
+      <title>To Add &applet; to a Panel</title>
+      <para>To add <application>&applet;</application> to a panel,
+      right-click on the panel, then choose <guimenuitem>Add to
+      Panel</guimenuitem>.  Select <application>&applet;</application>
+      in the <application>Add to the panel</application> dialog, then
+      click <guibutton>OK</guibutton>.</para>
+      <para>
+        The layout of the <application>&applet;</application> applet varies depending on the size and type of panel in which the applet resides.
+      </para>
+    </sect2>
+
+    <sect2 id="battstat-power-backends">
+     <title>Power Management Backends</title>
+
+     <para>
+       The battery monitor supports a number of power management backends.
+       If it is available, the monitor will attempt to use the freedesktop.org
+       <ulink url="http://upower.freedesktop.org/">upower</ulink> interface.
+       If it is unavailable or unsupported on your platform, it will fall back
+       to the freedesktop.org
+       <ulink url="http://freedesktop.org/Software/hal">HAL (Hardware
+       Abstraction Layer)</ulink>. If that is also not availble, the
+       battery monitor will attempt direct access to the power management system
+     </para>
+     <para>
+      Not all power management backends are available from all vendors, and some
+      vendors add their own additional backends for specific platforms and
+      hardware. If the battery monitor is misreporting information from your
+      battery see <xref linkend="battstat-troubleshooting" />.
+     </para>
+    </sect2>
+
+    <sect2 id="battstat-getting-help">
+      <title>Getting Help</title>
+      <para>
+        If the battery monitor doesn't work for you,
+	see these additional resources:
+      </para>
+      <itemizedlist>
+       <listitem><para>
+        <xref linkend="battstat-troubleshooting"/>;
+       </para></listitem>
+       <listitem><para>
+        <ulink url="http://mail.mate.org/archives/">MATE mailing
+	lists</ulink>
+       </para></listitem>
+      </itemizedlist>
+    </sect2>
+
+</sect1>
+
+<!-- ================ Customizing the Appearance ========================= -->
+
+  <sect1 id="battstat-appearance">
+    <title>Preferences</title>
+          <para>To bring up the preferences for the monitor, right-click on
+	  the monitor in the panel and then choose
+	  <guimenuitem>Preferences</guimenuitem></para>
+    <figure id="battstat-applet-prefs-menu"> 
+      <title>&applet; context (right-click) menu</title> 
+      <screenshot> 
+        <mediaobject> 
+          <imageobject><imagedata
+            fileref="figures/context-menu.png" format="PNG"/> 
+          </imageobject>
+          <textobject> 
+            <phrase>&applet; context menu</phrase>
+          </textobject> 
+        </mediaobject> 
+      </screenshot> 
+    </figure>
+    <figure id="battstat-applet-prefs"> 
+      <title>Preferences Dialog</title> 
+      <screenshot> 
+        <mediaobject> 
+          <imageobject><imagedata
+            fileref="figures/battstat-preferences.png" format="PNG"/> 
+          </imageobject>
+          <textobject> 
+            <phrase>Preferences Dialog</phrase>
+          </textobject> 
+        </mediaobject> 
+      </screenshot> 
+    </figure>
+      <variablelist>
+        <varlistentry>
+          <term><guilabel>Appearance</guilabel></term>
+	  <listitem>
+	  <variablelist>
+	    <varlistentry>
+	      <term><guilabel>Compact view</guilabel></term>
+	      <listitem><para>
+	       This view shows only a single graphic in the panel, either an
+	       upright battery to indicate remaining capacity or a plug to
+	       indicate your laptop is connected to an external power source.
+    <figure id="battstat-applet-compact"> 
+      <title>Compact view</title> 
+      <screenshot> 
+        <mediaobject> 
+          <imageobject><imagedata
+            fileref="figures/battstat-applet.png" format="PNG"/> 
+          </imageobject>
+          <textobject> 
+            <phrase>Compact View</phrase>
+          </textobject> 
+        </mediaobject> 
+      </screenshot> 
+    </figure>
+              </para>
+	      <para>
+	       The compact view is the default view for the monitor as of MATE
+	       2.12.
+	      </para></listitem>
+	    </varlistentry>
+	    <varlistentry>
+	      <term><guilabel>Expanded view</guilabel></term>
+	      <listitem><para>
+	       The expanded view is old look from previous versions of MATE. It
+	       has the larger graphic for the battery as well as a separate
+	       graphic to indicate what state the battery is in.
+    <figure id="battstat-applet-expanded"> 
+      <title>Expanded view</title> 
+      <screenshot> 
+        <mediaobject> 
+          <imageobject><imagedata
+            fileref="figures/battstat-applet-expanded.png" format="PNG"/> 
+          </imageobject>
+          <textobject> 
+            <phrase>Expanded View</phrase>
+          </textobject> 
+        </mediaobject> 
+      </screenshot> 
+    </figure>
+	      </para></listitem>
+	    </varlistentry>
+	    <varlistentry>
+	      <term><guilabel>Show time/percentage</guilabel></term>
+	      <listitem><para>Selecting this option will display one of two
+	      pieces of information. <guilabel>Show time remaining</guilabel>
+	      will tell you how many hours and minutes until the battery is
+	      fully discharged or recharged. <guilabel>Show percentage
+	      remaining</guilabel> will tell you the percentage charge remaining
+	      in the battery.</para></listitem>
+	    </varlistentry>
+	  </variablelist>
+	  </listitem>
+        </varlistentry>
+	<varlistentry>
+	 <term><guilabel>Notifications</guilabel></term>
+	  <listitem>
+	  <itemizedlist>
+	   <listitem><para><guilabel>
+	    Warn when battery charge drops to
+	   </guilabel></para>
+	   <para>
+	    Selecting this option will cause a warning dialog to be displayed 
+	    whenever your laptop
+	    battery reaches specified value, either as a percentage remaining or
+	    a number of minutes remaining. This indicates that the amount of
+	    charge remaining in your battery is critically low.
+	    charge. You can dismiss this warning dialog yourself, otherwise it
+	    will vanish automatically when you plug your laptop into mains
+	    power.
+	   </para>
+	   </listitem>
+	   <listitem>
+	    <para><guilabel>
+	     Notify when the battery is fully recharged
+	    </guilabel></para>
+	    <para>
+	     Selecting this option notifies when your battery is fully
+	     recharged. If you have compiled the &applet; with libnotify
+	     support a non-intrusive notification will popup from the monitor on
+	     the panel.
+	    </para>
+	   </listitem>
+	  </itemizedlist>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+   </sect1>
+
+   <sect1 id="battstat-troubleshooting">
+    <title>Troubleshooting</title>
+    
+    <para>
+      Due to the complexities of power management and the vast differences
+      between each of the different power management systems available,
+      debugging errors in the battery monitor can be difficult. You will need to
+      determine if the error exists in the battery monitor or is a bug in the
+      information provided by your machine.
+    </para>
+    <para>
+     The following information may be useful for troubleshooting what is wrong
+     with your battery monitor. It is by no means exhaustive. If you find a bug
+     with the &applet; (that is not caused by bad information being reported
+     by ACPI), please <ulink url="http://bugzilla.mate.org/">report it</ulink>.
+    </para>
+
+    <sect2 id="battstat-troubleshooting-backends">
+     <title>Determining the backend</title>
+     <para>
+       If you are using the upower interface, or the the Hardware
+       Abstraction Layer (see <xref linkend="battstat-power-backends"/>) then
+       that will be indicated in the about dialog by placing a star next to the
+       author of the HAL backend.
+    <figure id="battstat-credits-hal"> 
+      <title>Check you're using the HAL backend</title> 
+      <screenshot> 
+        <mediaobject> 
+          <imageobject><imagedata
+            fileref="figures/battstat-credits-hal.png" format="PNG"/> 
+          </imageobject>
+          <textobject> 
+            <phrase>Expanded View</phrase>
+          </textobject> 
+        </mediaobject> 
+      </screenshot> 
+    </figure>
+     </para>
+
+     <para>
+      Other backends do not currently give indication they are being used, so
+      you will have to guess based on your hardware. Most modern PC laptops are
+      using ACPI as the backend. This is also the backend with the largest
+      number of inconsistencies.
+     </para>
+    </sect2>
+
+    <sect2 id="battstat-troubleshooting-acpi">
+      <title>Checking the ACPI information</title>
+      <para>
+        If you are using the ACPI backend for the &applet;, it is important to
+	check that ACPI is giving you the right information. If it isn't, then
+	you will need to look into upgrading your DSDT or something else related
+	to ACPI.
+      </para>
+      <example><title>Example ACPI output</title>
+       <screen>
+[rupert@laptop ~]$ cat /proc/acpi/battery/BAT1/info
+present:                 yes
+design capacity:         41040 mWh
+last full capacity:      37044 mWh
+battery technology:      rechargeable
+design voltage:          10800 mV
+design capacity warning: 745 mWh
+design capacity low:     0 mWh
+capacity granularity 1:  10 mWh
+capacity granularity 2:  10 mWh
+model number:            G71C00056110
+serial number:           0000000008
+battery type:            Li-ION
+OEM info:
+[rupert@laptop ~]$ cat /proc/acpi/battery/BAT1/state
+present:                 yes
+capacity state:          ok
+charging state:          discharging
+present rate:            11232 mW
+remaining capacity:      27140 mWh
+present voltage:         11400 mV
+[rupert@laptop ~]$</screen>
+      </example>
+      <para>
+       You can quickly calculate the percentage remaining using <guilabel>remaining
+       capacity</guilabel> divided by <guilabel>last full capacity</guilabel>, you can
+       calculate the time remaining by taking <guilabel>remaining capacity</guilabel>
+       divided by <guilabel>present rate</guilabel>.
+      </para>
+    </sect2>
+
+    <sect2 id="battstat-troubleshooting-nohal">
+      <title>Hardware Abstraction Layer</title>
+      <para>
+        You can check that your battery is detected by HAL using the command
+	<command>hal-device-manager</command>. If your battery is not detected
+	by HAL or the wrong information is being reported, you can attempt to
+	disable the HAL backend by setting a GSettings key.
+      </para>
+      <para>
+       Select <guimenuitem>Configuration Editor</guimenuitem> from the
+       <guimenu>Applications</guimenu> menu, under
+       <guisubmenu>System Tools</guisubmenu>. Search for the key value
+       <prompt>OAFIID:MATE_BattstatApplet</prompt> which should be located in
+       the path <filename>/apps/panel/applets</filename>.
+      </para>
+      <para>
+       Assuming the path is <filename>/apps/panel/applets/applet_1</filename>.
+       In <filename>/apps/panel/applets/applet_1/prefs</filename> add a
+       <guimenuitem>New Key...</guimenuitem> called <guilabel>no_hal</guilabel>
+       and set it to the boolean value of true. This will disable the usage of
+       HAL (see <xref linkend="battstat-troubleshooting-backends"/> to learn how
+       to check this).
+      </para>
+    </sect2>
+    
+   </sect1>
+
+</article>