From 0dc5d8c2f1389e6df1742da15337216a1f530671 Mon Sep 17 00:00:00 2001
From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Date: Sat, 28 Dec 2024 11:07:59 -0600
Subject: [PATCH] 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.
---
 doc/dlb.6 | 39 ++++++++++++++++++++++++++++-----------
 1 file changed, 28 insertions(+), 11 deletions(-)

diff --git a/doc/dlb.6 b/doc/dlb.6
index 5505bc3f8..75b77637e 100644
--- a/doc/dlb.6
+++ b/doc/dlb.6
@@ -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