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).
jmc
