diff options
Diffstat (limited to 'battstat/docs/C/index.docbook')
| -rw-r--r-- | battstat/docs/C/index.docbook | 511 |
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> |