efiwake(8): add man page

[jo_bruelltuete.com]

Summary

add man page

Test Plan

Renders as:

EFIWAKE(8)              FreeBSD System Manager's Manual             EFIWAKE(8)

NAME
     efiwake – manipulate the EFI wake timer

SYNOPSIS
     efiwake
     efiwake -d
     efiwake -e yyyy-mm-ddThh:mm:ss

DESCRIPTION
     efiwake reports the current value of, disables or enables the EFI wake
     timer that can wake your machine from S3 sleep at a given time.

     If invoked without arguments, the current EFI time and the current value
     of the wake timer will be printed, followed by an enabled status and a
     pending status.  EFI time is supposed to be in UTC.  Note that it can be
     out of sync with kernel time.  The pending status tells whether the wake
     timer fired recently; it is cleared upon reading.

     If invoked with the -d option, the wake timer is reset and disabled.

     If invoked with the -e option, the wake timer is set to the given time
     and date.  If the date or time is invalid, an error is returned.

     The current EFI time is always printed.

EXAMPLES
     Without arguments:

           # efiwake
           Current EFI time: 2023-05-04T15:30:45
           EFI wake time: 2023-05-04T10:00:00; enabled=0, pending=1

     Disabling and resetting the wake timer:

           # efiwake -d
           Current EFI time: 2023-05-04T15:32:16
           EFI wake time: 2023-05-04T15:32:16; enabled=0, pending=0

     Enabling the wake timer with a valid date:

           # efiwake -e 2023-05-04T15:35:00
           Current EFI time: 2023-05-04T15:34:05
           EFI wake time: 2023-05-04T15:35:00; enabled=1, pending=0

     Trying to enable with an invalid date (there is no 31st of April):

           # efiwake -e 2023-04-31T15:35:00
           Current EFI time: 2023-05-04T15:35:25
           efiwake: cannot enable EFI wake time: Invalid argument

AUTHORS
     The tool and manual page were written by Johannes Totz
     <[e-mail]>.

BUGS
     The quality of EFI implementations differs widely.  Corruption of the
     wake-up date has been observed on real hardware.

FreeBSD 13.2-STABLE               May 9, 2023              FreeBSD 13.2-STABLE

[jo_bruelltuete.com]

cc @kib

[kib]

Did you run mandoc -T lint on the man page?

usr.sbin/efiwake/efiwake.8

38

This should be like
.Op Fl d
.Op Fl e Ar ...

49

New sentence should start with a new line.

50

No need to scream, please end the sentence with dot.

66

Use

.Bd -literal
# efiwake
Current time ...
.Ed

for literal displays.

[christos]

usr.sbin/efiwake/efiwake.8

59

New sentence, new line.

87

.Pp is not needed here.

93

New sentence, new line.

[jo_bruelltuete.com]

thanks for looking at this patch

usr.sbin/efiwake/efiwake.8

38

The current .Op Fl d | e Ar yyyy-mm-ddThh:mm:ss renders as efiwake [-d | -e yyyy-mm-ddThh:mm:ss] which means either of these options could be present but not both.

Having separate Fl d and Fl e will render as efiwake [-d] [-e yyyy-mm-ddThh:mm:ss] which means both could be specified at the same time.

[jo_bruelltuete.com]

address comments

[jo_bruelltuete.com]

linter is happy

[christos]

usr.sbin/efiwake/efiwake.8

67

Use .Bd -literal -offset indent instead. Same for the other occurrences of .Bd.

[jo_bruelltuete.com]

review comments

[christos]

You also need to add:

MAN=	efiwake.8

to usr.sbin/efiwake/Makefile, otherwise the man page won't be installed.

[christos]

Rename the title to efiwake(8): add man page

[jo_bruelltuete.com]

In D39961#909771, @christos wrote:

You also need to add:

MAN=	efiwake.8

to usr.sbin/efiwake/Makefile, otherwise the man page won't be installed.

ah looks like that got lost in one of the updates... git-sausage-fingers.

[jo_bruelltuete.com]

making sure to pick up the makefile as well

[christos]

LGTM.

[grahamperrin]

usr.sbin/efiwake/efiwake.8

42

44

52–53

57

61

62

64

If something is explicitly always, then in any case is superfluous.

99

[christos]

usr.sbin/efiwake/efiwake.8

96

It'd be good to add your email as well.

[jo_bruelltuete.com]

review

[kib]

usr.sbin/efiwake/efiwake.8

38

Then it perhaps should be

.Nm
.Op Fl d
.Nm
.Op Fl e Ar ...

The point is that d/e are different uses, instead of being options for the single use.

[jo_bruelltuete.com]

d and e option on separate lines

[grahamperrin]

I don't yet have a build of the OS that includes efiwake, but the parts of the (non-rendered) manual page that I can read look OK to me. Thanks.

[kib]

Please fix the issue I pointed out and mail me the patch with all metadata and tag lines.

usr.sbin/efiwake/efiwake.8

36

Should there be a synopsis line for querying the current settings?

[jo_bruelltuete.com]

synopsis for no options. make the other two non-optional.

[jo_bruelltuete.com]

usr.sbin/efiwake/efiwake.8

36

looks weird if the args are optional, so i made them non-optional.