From 01b2ea12f7109be0927c262f874fd8856558c425 Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Sat, 28 Dec 2024 10:55:11 -0600 Subject: [PATCH 1/4] doc/dlb.6: Use correct scaling unit for ems In *roff numeric expressions, ems are spelled "m", not "em". https://www.gnu.org/software/groff/manual/groff.html.node/Measurements.html --- doc/dlb.6 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/dlb.6 b/doc/dlb.6 index 80ca26861..e16edaed1 100644 --- a/doc/dlb.6 +++ b/doc/dlb.6 @@ -70,7 +70,7 @@ The .B t command lists the files in the archive. .SH OPTIONS AND ARGUMENTS -.TP 12em +.TP 12m \fBv verbose output .br From dc14fb131feb51ad4496dfa6649a43100c0c5ab4 Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Sat, 28 Dec 2024 11:05:04 -0600 Subject: [PATCH 2/4] doc/{dlb,recover}.6: Disable dead dynamic code Portions of these man pages seem at one time to have been dynamically selected, but the mechanism for doing so appears to be commented out in the source tree: see "NHGREP" in sys/{unix,vms}/Makefile.doc. Wrap them in *roff "ignore blocks" to keep their noise from cluttering the man page actually seen by the users. --- doc/dlb.6 | 2 ++ doc/recover.6 | 2 ++ 2 files changed, 4 insertions(+) diff --git a/doc/dlb.6 b/doc/dlb.6 index e16edaed1..5505bc3f8 100644 --- a/doc/dlb.6 +++ b/doc/dlb.6 @@ -40,6 +40,7 @@ archive files from which NetHack reads special level files and other read-only information. Note that like tar the command and option specifiers are specified as a continuous string and are followed by any arguments required in the same order as the option specifiers. +.ig .PP ^?ALLDOCS This facility is optional and may be excluded during NetHack @@ -53,6 +54,7 @@ This facility is optional and was excluded from this NetHack configuration. ^. ^. +.. .SH COMMANDS The .B x diff --git a/doc/recover.6 b/doc/recover.6 index f291917f9..3829760e9 100644 --- a/doc/recover.6 +++ b/doc/recover.6 @@ -48,6 +48,7 @@ supplies a directory which is the NetHack playground. It overrides the value from NETHACKDIR, HACKDIR, or the directory specified by the game administrator during compilation (usually /usr/games/lib/nethackdir). +.ig .PP ^?ALLDOCS For recovery to be possible, @@ -69,6 +70,7 @@ This configuration of was created without support for recovery. ^. ^. +.. NetHack normally writes out files for levels as the player leaves them, so they will be ready for return visits. When checkpointing, NetHack also writes out the level entered and From 0dc5d8c2f1389e6df1742da15337216a1f530671 Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Sat, 28 Dec 2024 11:07:59 -0600 Subject: [PATCH 3/4] 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 From a6a32170ee2db092b5fbdb489902bbb8cf15e22c Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Sat, 28 Dec 2024 11:44:02 -0600 Subject: [PATCH 4/4] doc/dlb.6: Revise description MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Content: * Document that the command has a default file list. * Demote "COMMANDS" section to "Operations" subsection. The former term is (1) too easily confused with Unix commands and (2) not a widely used section heading in man pages. Style: * Italicize command names. * Italicize file names. * Use idiomatic man page cross references. * Present operation and option letters in alphabetical order. * Render option descriptions as full sentences. * Set bug list as a bulleted list. Markup: * Break input lines at sentence boundaries. * Favor use of man(7) font selection and alternation macros over roff(7) font selection escape sequences. * Drop numerous extraneous paragraphing macro calls. See subsection "Horizontal and vertical spacing" of groff_man(7). * Replace use of *roff requests to break lines and vertically space with calls of paragraphing macros, which is what they're for. Two things the page author didn't know: `.sp 1` already implies a break, so the preceding `.br` was redundant. `.sp 1` without an argument already means to vertically space by 1 vee; that is, the "1" argument was superfluous. It was a bad idea anyway because the default inter-paragraph spacing in man(7) is not one vee, but 0.4v--this matters when typesetting. It has also been the case since 1979. * Use `RS` and `RE` macros instead of a literal tab to achieve a relative inset. Use of the macros is more idiomatic. * Use `EX` and `EE` to attempt to set the examples in a monospaced font family. These are extensions and are silently ignored by formatters that don't support them. groff_man(7): .EX .EE Begin and end example. After .EX, filling is disabled and a constant‐width (monospaced) font is selected. Calling .EE enables filling and restores the previous font. .EX and .EE are extensions introduced in Ninth Edition Unix. Documenter’s Workbench, Heirloom Doctools, and Plan 9 troffs, and mandoc (since 1.12.2) also support them. Solaris troff does not. See subsection “Use of extensions” in groff_man_style(7). * Kill off useless trailing space on input line. --- doc/dlb.6 | 120 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 69 insertions(+), 51 deletions(-) diff --git a/doc/dlb.6 b/doc/dlb.6 index 75b77637e..b58b12164 100644 --- a/doc/dlb.6 +++ b/doc/dlb.6 @@ -51,12 +51,22 @@ dlb \- NetHack data librarian \&.\|.\|. .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 -archive files from which NetHack reads special level files and other -read-only information. Note that like tar the command and option -specifiers are specified as a continuous string and are followed -by any arguments required in the same order as the option specifiers. +is a file archiving tool in the spirit (and tradition) of +.IR tar (1) +for +.IR nethack (6) +version 3.1 and higher. +It is used to maintain the +archive files from which the game reads special level files and other +read-only information. +Note that like +.IR tar , +the letters specifying the operation and options +are expressed as a continuous string. +Unlike +.IR tar , +.I dlb +is configured with a default set of file names to process. .ig .PP ^?ALLDOCS @@ -72,67 +82,75 @@ configuration. ^. ^. .. -.SH COMMANDS -The -.B x -command causes -.I dlb -to extract the contents of the archive into the current directory. -.PP -The +.SS Operations .B c -command causes +causes .I dlb to create a new archive from files in the current directory. .PP -The .B t -command lists the files in the archive. -.SH OPTIONS AND ARGUMENTS -.TP 12m -\fBv -verbose output -.br -.sp 1 +lists the files in the archive. +.PP +.B x +causes +.I dlb +to extract the contents of the archive into the current directory. +.SH OPTIONS +.TP 13n \" "I list-file" + 2n +.BI "C " dir +Change directory to +.I dir +before trying to +read any files. .TP -\fBf\fI\ archive -specify the archive. Default if f not specified is -LIBFILE (usually the nhdat file in the playground). -.br -.sp 1 +.BI "f " archive +Read from or write to +.I archive +instead of LIBFILE +(usually the +.I nhdat +file in the playground). .TP -\fBI\fI\ lfile -specify the file containing the list of files to -put in to or extract from the archive if no files are listed -on the command line. Default for archive creation if no files -are listed is LIBLISTFILE. -.br -.sp 1 +.BI "I " list-file +Read from +.I list-file +the names of files to emplace within or extract from the archive. +The default for archive creation is LIBLISTFILE. .TP -\fBC\fI\ dir -change directory. Changes directory before trying to -read any files (including the archive and the lfile). -.br +.B v +Operate verbosely. .SH EXAMPLES Create the default archive from the default file list: -.br - dlb c -.sp 1 -List the contents of the archive 'foo': -.br - dlb tf foo -.SH AUTHOR +.RS +.EX +dlb c +.EE +.RE .PP +List the contents of the archive +.IR foo : +.RS +.EX +dlb tf foo +.EE +.RE +.SH AUTHOR Kenneth Lorber .SH "SEE ALSO" -.PP -nethack(6), tar(1) +.IR nethack (6), +.IR tar (1) .SH BUGS -.PP -Not a good tar emulation; - does not mean stdin or stdout. +.IP \(bu 2n +Not a good +.I tar +emulation; +.B - +does not mean stdin or stdout. +.IP \(bu Should include an optional compression facility. +.IP \(bu Not all read-only files for NetHack can be read out of an archive; -examining the source is the only way to know which files can be. +examining the source is the only way to know which files can be. .SH COPYRIGHT This file is Copyright (C) \*(Na, \*(Nd for version \*(Nb:\*(Nr. NetHack may be freely redistributed. See license for details.