doc/dlb.6: Revise description
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:
118
doc/dlb.6
118
doc/dlb.6
@@ -51,12 +51,22 @@ dlb \- NetHack data librarian
|
|||||||
\&.\|.\|.
|
\&.\|.\|.
|
||||||
.SH DESCRIPTION
|
.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
|
||||||
NetHack version 3.1 and higher. It is used to maintain the
|
.IR tar (1)
|
||||||
archive files from which NetHack reads special level files and other
|
for
|
||||||
read-only information. Note that like tar the command and option
|
.IR nethack (6)
|
||||||
specifiers are specified as a continuous string and are followed
|
version 3.1 and higher.
|
||||||
by any arguments required in the same order as the option specifiers.
|
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
|
.ig
|
||||||
.PP
|
.PP
|
||||||
^?ALLDOCS
|
^?ALLDOCS
|
||||||
@@ -72,65 +82,73 @@ configuration.
|
|||||||
^.
|
^.
|
||||||
^.
|
^.
|
||||||
..
|
..
|
||||||
.SH COMMANDS
|
.SS Operations
|
||||||
The
|
|
||||||
.B x
|
|
||||||
command causes
|
|
||||||
.I dlb
|
|
||||||
to extract the contents of the archive into the current directory.
|
|
||||||
.PP
|
|
||||||
The
|
|
||||||
.B c
|
.B c
|
||||||
command causes
|
causes
|
||||||
.I dlb
|
.I dlb
|
||||||
to create a new archive from files in the current directory.
|
to create a new archive from files in the current directory.
|
||||||
.PP
|
.PP
|
||||||
The
|
|
||||||
.B t
|
.B t
|
||||||
command lists the files in the archive.
|
lists the files in the archive.
|
||||||
.SH OPTIONS AND ARGUMENTS
|
.PP
|
||||||
.TP 12m
|
.B x
|
||||||
\fBv
|
causes
|
||||||
verbose output
|
.I dlb
|
||||||
.br
|
to extract the contents of the archive into the current directory.
|
||||||
.sp 1
|
.SH OPTIONS
|
||||||
|
.TP 13n \" "I list-file" + 2n
|
||||||
|
.BI "C " dir
|
||||||
|
Change directory to
|
||||||
|
.I dir
|
||||||
|
before trying to
|
||||||
|
read any files.
|
||||||
.TP
|
.TP
|
||||||
\fBf\fI\ archive
|
.BI "f " archive
|
||||||
specify the archive. Default if f not specified is
|
Read from or write to
|
||||||
LIBFILE (usually the nhdat file in the playground).
|
.I archive
|
||||||
.br
|
instead of LIBFILE
|
||||||
.sp 1
|
(usually the
|
||||||
|
.I nhdat
|
||||||
|
file in the playground).
|
||||||
.TP
|
.TP
|
||||||
\fBI\fI\ lfile
|
.BI "I " list-file
|
||||||
specify the file containing the list of files to
|
Read from
|
||||||
put in to or extract from the archive if no files are listed
|
.I list-file
|
||||||
on the command line. Default for archive creation if no files
|
the names of files to emplace within or extract from the archive.
|
||||||
are listed is LIBLISTFILE.
|
The default for archive creation is LIBLISTFILE.
|
||||||
.br
|
|
||||||
.sp 1
|
|
||||||
.TP
|
.TP
|
||||||
\fBC\fI\ dir
|
.B v
|
||||||
change directory. Changes directory before trying to
|
Operate verbosely.
|
||||||
read any files (including the archive and the lfile).
|
|
||||||
.br
|
|
||||||
.SH EXAMPLES
|
.SH EXAMPLES
|
||||||
Create the default archive from the default file list:
|
Create the default archive from the default file list:
|
||||||
.br
|
.RS
|
||||||
dlb c
|
.EX
|
||||||
.sp 1
|
dlb c
|
||||||
List the contents of the archive 'foo':
|
.EE
|
||||||
.br
|
.RE
|
||||||
dlb tf foo
|
|
||||||
.SH AUTHOR
|
|
||||||
.PP
|
.PP
|
||||||
|
List the contents of the archive
|
||||||
|
.IR foo :
|
||||||
|
.RS
|
||||||
|
.EX
|
||||||
|
dlb tf foo
|
||||||
|
.EE
|
||||||
|
.RE
|
||||||
|
.SH AUTHOR
|
||||||
Kenneth Lorber
|
Kenneth Lorber
|
||||||
.SH "SEE ALSO"
|
.SH "SEE ALSO"
|
||||||
.PP
|
.IR nethack (6),
|
||||||
nethack(6), tar(1)
|
.IR tar (1)
|
||||||
.SH BUGS
|
.SH BUGS
|
||||||
.PP
|
.IP \(bu 2n
|
||||||
Not a good tar emulation; - does not mean stdin or stdout.
|
Not a good
|
||||||
|
.I tar
|
||||||
|
emulation;
|
||||||
|
.B -
|
||||||
|
does not mean stdin or stdout.
|
||||||
|
.IP \(bu
|
||||||
Should include an optional compression facility.
|
Should include an optional compression facility.
|
||||||
|
.IP \(bu
|
||||||
Not all read-only files for NetHack can be read out of an archive;
|
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
|
.SH COPYRIGHT
|
||||||
|
|||||||
Reference in New Issue
Block a user