summaryrefslogtreecommitdiff
path: root/battstat/docs/C/index.docbook
diff options
context:
space:
mode:
authorStefano Karapetsas <[email protected]>2013-08-06 14:35:10 -0700
committerStefano Karapetsas <[email protected]>2013-08-06 14:35:10 -0700
commited0921aa6001db711ef137ba5b97941c7c2a6d80 (patch)
tree09022320f0381761340f6ef24866f9b276837cfc /battstat/docs/C/index.docbook
parent32a2bc051959798d978e6967bd34ff8882aada39 (diff)
parent556640ffc27a3496ceda03c7f5d75e4d8813586d (diff)
downloadmate-applets-ed0921aa6001db711ef137ba5b97941c7c2a6d80.tar.bz2
mate-applets-ed0921aa6001db711ef137ba5b97941c7c2a6d80.tar.xz
Merge pull request #51 from infirit/yelptools
Use yelp-tools instead of mate-doc-utils
Diffstat (limited to 'battstat/docs/C/index.docbook')
-rw-r--r--battstat/docs/C/index.docbook511
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>