doc/dlb.6: Revise synopsis

Follow Unix idioms and the guidelines presented in groff_man_style(7).[1]

* Present multiple synopses since the command has multiple operation
  modes accessed via mutually inexpressible command letters.  See the
  POSIX standard for copious precedent.
* Stop implying that file name arguments are accepted alongside the `I`
  option; see line 236 of util/dlb_main.c.
* Stop spacing around synopsis punctuation where unnecessary.
* Set metasyntactic variables (parameters) in italics, not roman or
  bold.
* Spell ellipsis idiomatically for pleasant typesetting.
* Use `\c` escape sequence to force adjacency of tar-like option letters
  to the mandatory operation letter.
* Use singular, not plural, for repeatable argument.  The ellipsis does
  the grammatical work of pluralization for us.

[1] Full disclosure: I wrote much of (the current form of) that man page.
This commit is contained in:
G. Branden Robinson
2024-12-28 11:07:59 -06:00
parent dc14fb131f
commit 0dc5d8c2f1

View File

@@ -21,18 +21,35 @@
dlb \- NetHack data librarian
.SH SYNOPSIS
.B dlb
{
.B xct
}
[
.B vfIC
]
arguments...
[
.B files...
]
.SH DESCRIPTION
.\" We'd use `RB` with 7 arguments, but Unix troff man(7) has a limit of
.\" 6 arguments to its macros.
{\c
.BR c | t | x\c
}\c
.RB [ v ]\c
.RB [ C
.IR directory ]
.RI [ file ]
\&.\|.\|.
.PP
.B dlb
{\c
.BR c | t | x\c
}\c
.RB [ v ]\c
.B I
.IR list-file
.PP
.B dlb
{\c
.BR c | t | x\c
}\c
.RB [ v ]\c
.RB [ f
.IR archive-file-name ]
.RI [ file ]
\&.\|.\|.
.SH DESCRIPTION
.I Dlb
is a file archiving tool in the spirit (and tradition) of tar for
NetHack version 3.1 and higher. It is used to maintain the