From a6a32170ee2db092b5fbdb489902bbb8cf15e22c Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Sat, 28 Dec 2024 11:44:02 -0600 Subject: [PATCH] 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.