On Mon, Oct 16, 2017 at 03:57:22PM +0100, Jason McIntyre wrote:
> On Mon, Oct 16, 2017 at 04:06:59PM +0200, Anton Lindqvist wrote:
> > Hi,
> > A proposal on improving the `-t` option documentation. Most importantly,
> > remove the recursive reference to the option being documented.
> >
> > Comments? OK?
> >
> > Index: apmd.8
> > ===================================================================
> > RCS file: /cvs/src/usr.sbin/apmd/apmd.8,v
> > retrieving revision 1.49
> > diff -u -p -r1.49 apmd.8
> > --- apmd.8 29 Aug 2017 06:13:20 -0000 1.49
> > +++ apmd.8 16 Oct 2017 14:05:02 -0000
> > @@ -107,14 +107,12 @@ and
> > .Nm
> > exits without monitoring the APM status.
> > .It Fl t Ar seconds
> > -.Nm
> > -periodically polls the APM driver for the current power state.
> > -If the battery charge level changes substantially or the external power
> > -status changes, the new status is logged.
> > -The polling rate defaults to
> > -once per 10 minutes, but may be specified using the
> > -.Fl t
> > -command-line flag.
> > +Set the APM driver poll interval to
> > +.Ar seconds .
> > +Defaults to 10 minutes.
> > +After polling,
> > +the battery status is logged if the charge level changed substantially or
> > the
> > +external power status changed.
> > .It Fl Z Ar percent
> > Automatically hibernate the system if no AC is connected and the
> > estimated battery life is equal or below
> >
>
> hi.
>
> i also dislike when options are documented this way, so i'm happy to see
> this change.
>
> having said that, have you seen this paragraph near page top:
>
> When the power status changes (battery is connected or
> disconnected) apmd fetches the current status and reports it
> via syslog(3) with logging facility LOG_DAEMON.
>
> it looks a bit like we are describing logging in two places instead
> of one (and on top of that, the descriptions of when logging happens
> differ). i wonder whether it would make sense to more fully describe
> when logging happens (and that it happens after polling) in the
> paragraph i quoted, and that would allow for a very brief description
> of -t.
>
> oh, i also dislike that the argument to -t is in seconds, but the
> default is given in minutes. minutes makes sense, but having the default
> in both might make it easier to both read and calculate a change.
> something like:
>
> The default is 600 (10 minutes).
Good call. Without knowing too much about the apmd internals, here's a
first stab. As I read the code, the period polling is also used by
auto{suspend,hibernate}. Is this worth mentioning? Since a more frequent
interval will increase the accuracy of the chosen action to perform?
Index: apmd.8
===================================================================
RCS file: /cvs/src/usr.sbin/apmd/apmd.8,v
retrieving revision 1.49
diff -u -p -r1.49 apmd.8
--- apmd.8 29 Aug 2017 06:13:20 -0000 1.49
+++ apmd.8 16 Oct 2017 16:29:20 -0000
@@ -57,13 +57,17 @@ When resuming after suspend or standby,
.Nm
runs the appropriate configuration program (if one exists).
.Pp
-When the power status changes
-(battery is connected or disconnected)
+Upon receiving an event from
+.Xr apm 4 ,
.Nm
fetches the current status and reports it via
.Xr syslog 3
with logging facility
.Dv LOG_DAEMON .
+In addition,
+.Nm
+periodically polls the power status and reports significant changes to the
+battery charge level.
.Pp
The options are as follows:
.Bl -tag -width Ds
@@ -107,14 +111,9 @@ and
.Nm
exits without monitoring the APM status.
.It Fl t Ar seconds
-.Nm
-periodically polls the APM driver for the current power state.
-If the battery charge level changes substantially or the external power
-status changes, the new status is logged.
-The polling rate defaults to
-once per 10 minutes, but may be specified using the
-.Fl t
-command-line flag.
+Set the APM driver poll interval to
+.Ar seconds .
+Defaults to 600 (10 minutes).
.It Fl Z Ar percent
Automatically hibernate the system if no AC is connected and the
estimated battery life is equal or below
