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-31 06:52:27 -06:00
parent dc14fb131f
commit 0dc5d8c2f1
+28 -11
View File
@@ -21,18 +21,35 @@
dlb \- NetHack data librarian dlb \- NetHack data librarian
.SH SYNOPSIS .SH SYNOPSIS
.B dlb .B dlb
{ .\" We'd use `RB` with 7 arguments, but Unix troff man(7) has a limit of
.B xct .\" 6 arguments to its macros.
} {\c
[ .BR c | t | x\c
.B vfIC }\c
] .RB [ v ]\c
arguments... .RB [ C
[ .IR directory ]
.B files... .RI [ file ]
] \&.\|.\|.
.SH DESCRIPTION
.PP .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 .I Dlb
is a file archiving tool in the spirit (and tradition) of tar for 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 NetHack version 3.1 and higher. It is used to maintain the