[src/trunk]: src/share/man/man4 Try to document this in a little more verbose...

[jruoho <jruoho%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/356cb8529823
branches:  trunk
changeset: 753138:356cb8529823
user:      jruoho <jruoho%NetBSD.org@localhost>
date:      Wed Mar 17 17:16:43 2010 +0000

description:
Try to document this in a little more verbose manner.

diffstat:

 share/man/man4/acpibat.4 |  72 ++++++++++++++++++++++++++++++++++++++++--------
 1 files changed, 60 insertions(+), 12 deletions(-)

diffs (110 lines):

diff -r 46ae78dae3f3 -r 356cb8529823 share/man/man4/acpibat.4
--- a/share/man/man4/acpibat.4  Wed Mar 17 11:07:59 2010 +0000
+++ b/share/man/man4/acpibat.4  Wed Mar 17 17:16:43 2010 +0000
@@ -1,6 +1,6 @@
-.\" $NetBSD: acpibat.4,v 1.7 2009/05/04 19:17:49 wiz Exp $
+.\" $NetBSD: acpibat.4,v 1.8 2010/03/17 17:16:43 jruoho Exp $
 .\"
-.\" Copyright (c) 2002, 2004 The NetBSD Foundation, Inc.
+.\" Copyright (c) 2002, 2004, 2010 The NetBSD Foundation, Inc.
 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -24,30 +24,66 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd September 4, 2007
+.Dd March 17, 2010
 .Dt ACPIBAT 4
 .Os
 .Sh NAME
 .Nm acpibat
-.Nd ACPI Control Method Battery
+.Nd ACPI Battery
 .Sh SYNOPSIS
 .Cd "acpibat* at acpi?"
 .Sh DESCRIPTION
 The
 .Nm
-driver supports ACPI Control Method Battery.
+driver supports
+.Tn ACPI
+batteries.
 .Pp
-The status can be monitored by
+The battery status is made available through the
 .Xr envsys 4
-API or
+.Tn API .
+The battery information can be displayed also with the
 .Xr envstat 8
-command.
+command:
+.Bd -literal -offset 2n
+$ envstat -d acpibat0
+                Current  CritMax  WarnMax  WarnMin  CritMin Unit
+       present:      ON
+design voltage:  14.400                                        V
+       voltage:  16.267                                        V
+    design cap:  74.880                                       Wh
+ last full cap:  48.260                                       Wh
+        charge:  47.910                      5.000%   0.414%  Wh (99.27%)
+   charge rate:     N/A
+discharge rate:  16.641                                        W
+      charging:     OFF
+  charge state:  NORMAL
+.Ed
+.Pp
+Depending on the battery, the unit of measurement is either watt-hour
+.Tn Pq Wh
+or ampere hour
+.Tn Pq Ah
+for the capacity related information.
+From these the
+.Dq charge
+is usually the most interesting value,
+but it is possible to derive useful information also from the other values.
+For example, when
+.Xr acpiacad 4
+is disconnected, the
+.Dq discharge rate
+gives a coarse approximation of the current power consumption.
+The ratio between design capacity and last full capacity on the other hand
+reveals the overall
+.Dq health
+of deteriorating lithium-ion batteries.
 .Sh EVENTS
 The
 .Nm
 driver is able to send events to
 .Xr powerd 8
-when capacity state has been changed.
+daemon when a capacity state has been changed.
 The new state will be reported as the
 .Em fourth
 argument to the
@@ -68,8 +104,20 @@
 .Sh HISTORY
 The
 .Nm
-driver
-appeared in
+driver appeared in
 .Nx 1.6 .
 .Sh BUGS
-Smart Battery Specification-based batteries are not supported.
+The
+.Tn ACPI
+specifications make a distinction between
+.Dq control method batteries
+and
+.Dq smart batteries .
+The
+.Nm
+driver only supports control method batteries.
+Furthermore,
+.Nm
+does not yet support some additional battery information introduced in the
+.Tn ACPI 4.0
+standard.