nethack-gwaa-kiwi/nethack
1
0
Fork 0
Code Pull Requests Activity

doc/dlb.6: Revise description

Browse Source 
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.
This commit is contained in:
G. Branden Robinson
2024-12-28 11:44:02 -06:00
parent 0dc5d8c2f1
commit a6a32170ee
1 changed files with 69 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

120
doc/dlb.6
View File

@@ -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.