diff --git a/doc/dlb.6 b/doc/dlb.6 index b58b12164..e314989d2 100644 --- a/doc/dlb.6 +++ b/doc/dlb.6 @@ -11,6 +11,8 @@ .. .NB $NHDT-Branch: keni-gitset $ .NR $NHDT-Revision: 1.13 $ +.ie \n(.g .ds ^ \(ha +.el .ds ^ ^ .\" groff and AT&T-descended troffs use different hyphenation patterns. .\" Don't hyphenate the last word on a page or column, or .\" before/after last/first 2 characters of a word. @@ -38,7 +40,7 @@ dlb \- NetHack data librarian }\c .RB [ v ]\c .B I -.IR list-file +.I list-file .PP .B dlb {\c @@ -69,18 +71,18 @@ Unlike is configured with a default set of file names to process. .ig .PP -^?ALLDOCS +\*^?ALLDOCS This facility is optional and may be excluded during NetHack configuration. -^: -^?DLB +\*^: +\*^?DLB This facility is optional but is included in this NetHack configuration. -^: +\*^: This facility is optional and was excluded from this NetHack configuration. -^. -^. +\*^. +\*^. .. .SS Operations .B c @@ -144,7 +146,7 @@ Kenneth Lorber Not a good .I tar emulation; -.B - +.B \- does not mean stdin or stdout. .IP \(bu Should include an optional compression facility. @@ -152,5 +154,12 @@ Should include an optional compression facility. 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. .SH COPYRIGHT -This file is Copyright (C) \*(Na, \*(Nd for version \*(Nb:\*(Nr. -NetHack may be freely redistributed. See license for details. +.\" All troffs and nroffs support `\(co` except Plan 9 nroff, but Plan 9 +.\" offers no test for special character availability, and its feature +.\" set too closely resembles DWB 3.3 to test for it. Use a string with +.\" any nroff-mode formatter not claiming groff compatiblity. +.ds co \(co +.if !\n(.g .if n .ds co (C)\" in principle, should be just "c" +This file is Copyright \*(co \*(Na, \*(Nd for version \*(Nb:\*(Nr. +NetHack may be freely redistributed. +See license for details. diff --git a/doc/makedefs.6 b/doc/makedefs.6 index f33dc42e1..af3919c39 100644 --- a/doc/makedefs.6 +++ b/doc/makedefs.6 @@ -10,6 +10,8 @@ .. .NB $NHDT-Branch: NetHack-5 $ .NR $NHDT-Revision: 1.22 $ +.ie \n(.g .ds ^ \(ha +.el .ds ^ ^ .\" groff and AT&T-descended troffs use different hyphenation patterns. .\" Don't hyphenate the last word on a page or column, or .\" before/after last/first 2 characters of a word. @@ -20,80 +22,73 @@ makedefs \- NetHack miscellaneous build-time functions .SH SYNOPSIS .B makedefs -{ -.B -o -| -.B -d -| -.B -e -| -.B -m -| -.B -v -| -.B -p -| -.B -q -| -.B -r -| -.B -h +{\c +.BR \-o |\c +.BR \-d |\c +.BR \-e |\c +.BR \-m |\c +.BR \-v |\c +.BR \-p |\c +.BR \-q |\c +.BR \-r |\c +.B \-h\c } .P -.B makedefs --input +.B makedefs \-\-input .I file -.B --output +.B \-\-output .I file -.BI -- command +.BI \-\- command .SH DESCRIPTION -.PP .B Makedefs is a build-time tool used for a variety of -.BR NetHack (6) -source file creation and modification tasks. For historical reasons, +.IR nethack (6) +source file creation and modification tasks. +For historical reasons, .B makedefs -takes two types of command lines. When invoked with a short option, the -files operated on are determined when +takes two types of command lines. +When invoked with a short option, +the files operated on are determined when .B makedefs -is compiled. When invoked with a long option, the -.B --input -and -.B --output +is compiled. +When invoked with a long option, +the +.B \-\-input +and +.B \-\-output options are used to specify the files for the -.BI -- command. +.BI \-\- command. Each command is only available in one of the two formats. .SH SHORT COMMANDS Upper and lower case are both accepted for the short commands. .TP -.B -o +.B \-o Generate -.I onames.h. -.br +.IR onames.h . .TP -.B -d +.B \-d Generate -.I data.base. -.br +.IR data.base . .TP -.B -e +.B \-e Generate -.I dungeon.pdf. +.IR dungeon.pdf . The input file .I dungeon.def is passed through the same logic as that used by the -.B --grep +.B \-\-grep command; see the .B MDGREP FUNCTIONS section below for details. -.br .TP -.B -m +.B \-m Generate .I date.h and .I options -file. It will read +file. +It will read .IR dat/gitinfo.txt , only if it is present, to obtain .B githash= @@ -102,175 +97,184 @@ and info and include related preprocessor #defines in .I date.h file. -.br .TP -.B -p +.B \-p Generate -.I pm.h -.br +.IR pm.h . .TP -.B -q +.B \-q Generate the .I rumors file. -.br .TP -.B -s +.B \-s Generate the -.IR bogusmon ", " engrave ", and " epitaph " files." -.br +.IR bogusmon , +.IR engrave , +and +.I epitaph +files. .TP -.B -1 +.B \-1 Generate the -.IR epitaph +.I epitaph file. -.br .TP -.B -2 +.B \-2 Generate the -.IR engrave +.I engrave file. -.br .TP -.B -3 +.B \-3 Generate the -.IR bogusmon +.I bogusmon file. -.br .TP -.B -h +.B \-h Generate the -.B oracles +.I oracles file. -.br .SH LONG COMMANDS .TP -.B --debug +.B \-\-debug Show debugging output. -.br .TP -.B --make \fR[\fIcommand\fR] -Execute a short command. Command is given without preceding dash. -.br +.B \-\-make \fR[\fIcommand\fR] +Execute a short command. +.I Command +is given without preceding dash. .TP -.BI --input " file" +.BI \-\-input " file" Specify the input .I file -for the command (if needed). If the file is - standard -input is read. -.br +for the command (if needed). +If +.I file +is \*(lq\-\*(rq, +.B makedefs +reads the standard input stream. .TP -.BI --output " file" +.BI \-\-output " file" Specify the output .I file -for the command (if needed). If the file is - standard -output is written. -.br +for the command (if needed). +If +.I file +is \*(lq\-\*(rq, +.B makedefs +writes to the standard input stream. .TP -.B --svs \fR[\fIdelimiter\fR] +.B \-\-svs \fR[\fIdelimiter\fR] Generate a version string to standard output without a trailing newline. If specified, the delimiter is used between each part of the version string. -.br .TP -.B --grep +.B \-\-grep Filter the input .I file to the output .IR file . See the .B MDGREP FUNCTIONS section below for information on controlling the filtering operation. -.br .TP -.B --grep-showvars +.B \-\-grep\-showvars Show the name and value for each variable known to the grep option. -.br .TP -.B --grep-trace +.B \-\-grep\-trace Turn on debug tracing for the grep function ( -.B --grep +.B \-\-grep must be specified as well). -.br .TP -.BI --grep-defined " symbol" +.BI \-\-grep\-defined " symbol" Exit shell true (0) if .I symbol is known and defined, otherwise exit shell false (1). .TP -.BI --grep-define " symbol" +.BI \-\-grep\-define " symbol" Force the value of .I symbol -to be "defined." +to be \*(lqdefined.\*(rq .I Symbol must already be known to .BR makedefs . -.br .TP -.BI --grep-undef " symbol" +.BI \-\-grep\-undef " symbol" Force the definition of .I symbol -to be "undefined." +to be \*(lqundefined.\*(rq .I Symbol must already be known to .BR makedefs . .SH MDGREP FUNCTIONS The -.B --grep +.B \-\-grep command (and certain other commands) filter their input, on a line-by-line basis, according to control lines embedded in the input and on information gleaned from the -.BR NetHack (6) -configuration. This allows certain changes such as embedding platform-specific +.I nethack +configuration. +This allows certain changes such as embedding platform-specific documentation into the master documentation files. .P Rules: -.RS -.IP - 4 +.IP \(bu The default conditional state is printing enabled. -.IP - 4 +.IP \(bu Any line .I NOT -starting with a caret (^) is either suppressed or passed through unchanged +starting with a caret (\*^) is either suppressed or passed through unchanged depending on the current conditional state. -.IP - 4 +.IP \(bu Any line starting with a caret is a control line; as in C, zero or more spaces may be embedded in the line almost anywhere (except immediately after the caret); however the caret must be in column 1. -.IP - 4 +.IP \(bu Conditionals may be nested. -.IP - 4 +.IP \(bu .I Makedefs will exit with an error code if any errors are detected; processing will continue (if it can) to allow as many errors as possible to be detected. -.IP - 4 -Unknown identifiers are treated as both TRUE and as an error. Note that -.BR --undef " or " #undef +.IP \(bu +Unknown identifiers are treated as both TRUE and as an error. +Note that +.BR \-\-undef " or " #undef in the -.BR NetHack (6) +.I nethack configuration are different from unknown. -.RE .P Control lines: -.RS -.IP ^^ 4 +.TP +.B +\*^\*^ a line starting with a (single) literal caret -.IP ^# +.TP +.B \*^# a comment -.IP ^?\fIID +.TP +.B \*^?\fIID if the .I ID is defined set the conditional state to TRUE -.IP ^!\fIID +.TP +.B \*^!\fIID if the .I ID is not defined set the conditional state to TRUE -.IP ^: +.TP +.B \*^: else; invert the conditional state -.IP ^. +.TP +.B \*^. end the most recent conditional -.RE .\".SH EXAMPLES .SH AUTHOR The NetHack Development Team .SH COPYRIGHT -This file is Copyright (C) \*(Na, \*(Nd for version \*(Nb:\*(Nr. -NetHack may be freely redistributed. See license for details. +.\" All troffs and nroffs support `\(co` except Plan 9 nroff, but Plan 9 +.\" offers no test for special character availability, and its feature +.\" set too closely resembles DWB 3.3 to test for it. Use a string with +.\" any nroff-mode formatter not claiming groff compatiblity. +.ds co \(co +.if !\n(.g .if n .ds co (C)\" in principle, should be just "c" +This file is Copyright \*(co \*(Na, \*(Nd for version \*(Nb:\*(Nr. +NetHack may be freely redistributed. +See license for details. diff --git a/doc/mnh.7 b/doc/mnh.7 index df7fe5856..802c806ec 100644 --- a/doc/mnh.7 +++ b/doc/mnh.7 @@ -1,5 +1,16 @@ +.\"DO NOT REMOVE NH_DATESUB .TH MAKEDEFS 6 "Date(%-d %B %Y)" Project(uc) .\" $NHDT-Branch: NetHack-3.6.2 $:$NHDT-Revision: 1.0 $ $NHDT-Date: 1541298620 2018/11/04 02:30:20 $ -.TH MNH 7 NETHACK +.TH MNH 7 "4 November 2018" NETHACK +.\"DO NOT REMOVE NH_DATESUB .ds Nd Date(%Y) +.ds Nd 2018 +.de NB +.ds Nb \\$2 +.. +.de NR +.ds Nr \\$2 +.. +.NB $NHDT-Branch: NetHack-3.6.2 $ +.NR $NHDT-Revision: 1.0 $ .SH NAME mnh \- additional text formatting macros for the NetHack Guidebook .SH SYNOPSIS @@ -9,14 +20,14 @@ mnh \- additional text formatting macros for the NetHack Guidebook .\".B "troff \-mn" .\"[ options ] file ... .SH DESCRIPTION -.PP This package of .IR nroff (1) and .IR troff (1) macro definitions extends .IR tmac.n (7) -for the NetHack Guidebook. This document should be +for the NetHack Guidebook. +This document should be read as an addendum to the documentation for .IR tmac.n . .PP @@ -27,11 +38,10 @@ and number registers are defined below. .SH FILES doc/tmac.nh .SH "SEE ALSO" -mn(7) +.IR mn (7) .SH AUTHOR Pat Rankin .SH REQUESTS -.PP In the .I Note column, diff --git a/doc/nethack.6 b/doc/nethack.6 index 85b99c389..7decd3bf5 100644 --- a/doc/nethack.6 +++ b/doc/nethack.6 @@ -16,134 +16,124 @@ .ie \n(.g .hy 12 .el .hy 14 .ds Na Robert Patrick Rankin +.\" DWB, Solaris 10, and Plan 9 troffs don't support `\(ti`, `\(oq`, or +.\" `\(cq`. Assume the best, then detect these older troffs and fall +.\" back as needed. +.\" +.\" Put NO SPACE between special character and comment escape sequences. +.ds ~ \(ti\" The name "ti" is taken by *roff's `ti` request. +.ds oq \(oq +.ds cq \(cq +.if !\n(.g \{\ +. ds ~ ~ +. ds oq ` +. ds cq ' +.\} +.\" Define string to exercise groff's hyphenless break point feature. +.ie \n(.g .ds : \: +.el .ds : \" empty +.\" Define string to exercise groff's adjustable, unbreakable space. +.ie \n(.g .ds _ \~ +.el .ds _ \ \" backslash, space +.\" Define local versions of groff's "an-ext.tmac" macros if needed. +.ds %% \" empty +.if \n(.g .ig %% +.\" Add supplementary paragraph tag on its own line after TP. +.de TQ +. br +. ns +. \" Do not quote the argument to `TP`; the user might specify +. \" their own quotes for multi-word tags or to exercise AT&T troff +. \" quoting rules. +. TP \\$1\" +.. +.%% .SH NAME nethack \- Exploring The Mazes of Menace .SH SYNOPSIS +.HP +.nr sA \n(.j \" Save the adjustment mode. .na -.hy 0 -.\" Some options ordering is explicit (-d first, -u before -D), others -.\" have been arranged to fit within an 80-column page with nearly full -.\" lines while avoiding splitting "[" and "-opt ]" or "[ -opt" and "]" -.\" across line boundaries. It would be better to do that with 'roff magic. .B nethack -[ -.BR \-d | \-\-directory -.I directory -] -.\" '.B token newline .I token' will include a space between the two tokens; -.\" '.BI token token' will not. Likewise for .BR, .RB, &c. -[ -.BR \-w | \-\-windowtype -.I interface -] -.br 1 -[ -.BI \-\-nethackrc: RC-file -| -.B \-\-no\-nethackrc -] -[ -.B \-n -] -[ -.BR \-dec " | " \-ibm -] -.br 1 -[ -.B \-u -.I playername -] -[ -.BR \-X " | " \-D -] -[ -.B \-p -.I profession -] -[ -.B \-r -.I race -] -[ -.B \-\@ +.RI [ role-option ] +.RB [ \-d | \-\-directory\*_\c +.IR directory ] +.RB [ \-w | \-\-windowtype\*_\c +.IR interface ] +\%[\c +.BI \-\-nethackrc: rc-file\c +|\c +.B \-\-no\-nethackrc\c ] +.RB [ \-n ] +.RB [ \-dec | \-ibm ] +.RB [ \-u\*_\c +.IR player-name ] +.RB [ \-X | \-D ] +.RB [ \-p\*_\c +.IR profession ] +.RB [ \-r\*_\c +.IR race ] +.RB [ \-@ ] .PP -Also -[ +.I role-option +can be any of the following. +.PP +.RS +.nf .BR \-A | \-Arc -| .BR \-B | \-Bar -| .BR \-C | \-Cav -| .BR \-H | \-Hea -| .BR \-K | \-Kni -| .BR \-M | \-Mon -| .BR \-P | \-Pri -| .BR \-R | \-Rog -| -.BR \-Ran -| +.B \-Ran .BR \-S | \-Sam -| .BR \-T | \-Tou -| .BR \-V | \-Val -| .BR \-W | \-Wiz -] +.fi +.RE +.HP +.B nethack +.RB { \-s | \-\-scores } +.RB [ \-d | \-\-directory\*_\c +.IR directory ] +.RB [ \-v ] +.RB [ \-p\*_\c +.IR profession ] +.RB [ \-r\*_\c +.IR race ] +.RI [ player-name\*_\c +\&.\|.\|.] .PP .B nethack -[ -.BR \-d | \-\-directory -.I directory -] -.BR \-s | \-\-scores -[ -.B \-v -] -.br 1 -[ -.B \-p -.I profession -] -[ -.B \-r -.I race -] -[ -.I playernames -] +.RB { \-\-usage | \-\-help } .PP .B nethack -[ -.B \-\-usage -| -.B \-\-help -] -[ -.BR \-\-showpaths -] -.\" force line wrap now rather than have that happen after the opening brace -.br -[ -.BR \-\-version [ :copy | :dump | :show ] -] -.ad -.hy 14 +.B \-\-showpaths +.PP +.B nethack +.BR \-\-version [ :copy | :dump\c +.RB | :show ] +.ad \n(sA \" Restore the adjustment mode. .\" Make sure path is not hyphenated below .hw nethackdir .SH DESCRIPTION -.PP .I NetHack -is a display oriented Dungeons & Dragons(tm) - like game. -The standard tty display and command structure resemble rogue. +is a fantasy-themed game of surival, +exploration, +and combat +set in the Mazes of Menace, +an elaborate underground complex. .PP -Other, more graphical display options exist for most platforms. +Traditionally, +the game's interface uses a Unix terminal connection, +depicting the interface on a grid of character cells +and responding to keyboard-entered commands. +Other interface options exist for most platforms. .PP To get started you really only need to know two commands. The command @@ -201,17 +191,17 @@ below). On other systems, the default may be different, possibly NetHack.cnf. On MS-DOS, the name is defaults.nh in NetHack's directory (folder), while -.\" on the Macintosh or BeOS, it is \(lqNetHack Defaults\(rq, and +.\" on the Macintosh or BeOS, it is \*(lqNetHack Defaults\*(rq, and on VMS|OpenVMS it is nethack.ini in your home directory. The default configuration file may be overridden via the -.BI \-\-nethackrc: "rc-file" +.BI \-\-nethackrc: rc-file command line option or by setting NETHACKOPTIONS in your environment to a string consisting of an @ character followed by the path and filename. .PP The .B \-u -.I playername -option supplies the answer to the question "Who are you?". +.I player-name +option supplies the answer to the question \*(lqWho are you?\*(rq. It overrides any name from the options or configuration file, USER, LOGNAME, or getlogin(), which will otherwise be tried in order. If none of these provides a useful name, the player will be asked for one. @@ -220,31 +210,34 @@ so you can have several saved games under different names. Conversely, you must use the appropriate player name to restore a saved game. .PP A -.I playername +.I player-name suffix can be used to specify the profession, race, alignment and/or gender -of the character. The full syntax of the playername that includes a -suffix is "name-ppp-rrr-aaa-ggg". "ppp" are at least the first three letters +of the character. +The full syntax of a +.I player-name +including a suffix is \*(lqname\-ppp\-rrr\-aaa\-ggg\*(rq. +\*(lqppp\*(rq are at least the first three letters of the profession (this can also be specified using a separate .B \-p .I profession -option). "rrr" are at least the first three letters of the character's +option). +\*(lqrrr\*(rq are at least the first three letters of the character's race (this can also be specified using a separate .B \-r .I race -option). "aaa" are at least the first three letters of the character's -alignment, and "ggg" are at least the first three letters of the -character's gender. Any of the parts of the suffix may be left out. +option). +\*(lqaaa\*(rq are at least the first three letters of the character's +alignment, and \*(lqggg\*(rq are at least the first three letters of the +character's gender. +Any of the parts of the suffix may be left out. .PP .B \-p .I profession can be used to determine the character profession, also known as the role. You can specify either the male or female name for the character role, or the first three characters of the role as an abbreviation. -.\" .B "\-p \@" +.\" .B "\-p @" .\" has been retained to explicitly request that a random role be chosen. -.\" It may need to be quoted with a backslash (\\@) if @ -.\" is the "kill" character (see "stty") for the terminal, in order -.\" to prevent the current input line from being cleared. .PP Likewise, .B \-r @@ -270,7 +263,7 @@ The | .BR \-R | \-Rog | -.BR \-Ran +.B \-Ran | .BR \-S | \-Sam | @@ -289,8 +282,8 @@ is already used for the .I Rogue role. .PP -.B \-\@ -tells nethack to choose any omitted characteristics (profession/role, race, +.B \-@ +tells NetHack to choose any omitted characteristics (profession/role, race, gender, alignment) randomly without prompting. Otherwise, leaving out any of these characteristics will result in you being prompted during game startup for the information. @@ -305,11 +298,22 @@ option will start the game in a special non-scoring discovery mode (also known as explore mode). .B \-D will start the game in debug mode (also known as wizard mode) after -changing the character name to \(lqwizard\(rq, if the player is allowed. +changing the character name to \*(lqwizard\*(rq, +if the player is allowed. Otherwise it will switch to .BR \-X . Control of who is allowed to use debug mode is done via the -.RI "\(lq" WIZARDS= "\(rq line in nethack's " sysconf " file." +.\" The `lq` and `rq` strings are not reliable in macro calls, because +.\" some nroffs interpolate `"` for them, messing up macro argument +.\" delimitation. Use an (initially) uglier method than `RI`. +.\".RI "\*(lq" WIZARDS= "\*(rq line in NetHack's " sysconf " file." +\*(lq\c +.I WIZARDS=\c +\*(rq +line in +NetHack's +.I sysconf +file. .PP The .BR \-d " or " \-\-directory @@ -317,7 +321,8 @@ option, which must be the first argument if it appears, supplies a directory which is to serve as the playground. It overrides the value from NETHACKDIR, HACKDIR, or the directory specified by the game administrator during compilation -(usually /usr/games/lib/nethackdir). +(usually +.IR /usr/\*:games/\*:lib/\*:nethackdir ). This option is usually only useful to the game administrator. The playground must contain several auxiliary files such as help files, the list of top scorers, and a subdirectory @@ -335,18 +340,15 @@ specified in the run-time configuration file. NetHack's #version command shows available interfaces. .PP The -.BI \-\-nethackrc: RC-file +.BI \-\-nethackrc: rc-file option will use -.I RC-file +.I rc-file instead of the default run-time configuration file -.RI "(typically " \(ti/.nethackrc ")" +.RI "(typically " \*~/.nethackrc ) and the .B \-\-no\-nethackrc option can be used to skip any run-time configuration file. .PP -.\" extra blank line -.br 1 -.PP Some options provide feedback and then exit rather than play the game: .PP The @@ -355,7 +357,7 @@ option alone will print out the list of your scores on the current version. An immediately following .B \-v reports on all versions present in the score file. -.RB \(oq \-s | \-s\~\-v \(cq +.RB \*(oq \-s | \-s\*_\-v \*(cq may also be followed by arguments .B \-p .I profession @@ -367,7 +369,7 @@ Either can be specified multiple times to include more than one role or more than one race. When both are specified, score entries which match either the role or the race (or both) are printed rather than just entries which match both. -.RB \(oq \-s | \-s\~\-v \(cq +.RB \*(oq \-s | \-s\*_\-v \*(cq may be followed by one or more player names to print the scores of the players mentioned, by 'all' to print out all scores, or by a number to print that many top scores. @@ -406,10 +408,9 @@ customize aspects of how the game operates. .BR \-\-usage " or " \-\-help will display information similar to this manual page, then exit. Use -.RB \(oq "nethack \-\-usage | more" \(cq +.RB \*(oq "nethack \-\-usage | more" \*(cq to read it a page at a time. .SH AUTHORS -.PP Jay Fenlason (+ Kenny Woodland, Mike Thome and Jon Payne) wrote the original hack, very much like rogue (but full of bugs). .PP @@ -427,160 +428,240 @@ development by the Usenet. Andries Brouwer has made this request for the distinction, as he may eventually release a new version of his own. .SH FILES -.PP Run-time configuration options were discussed above and use a platform specific name for a file in a platform specific location. For Unix, the -name is '.nethackrc' in the user's home directory. - -.br +name is +.I .nethackrc +in the user's home directory. +.PP All other files are in the playground directory, -normally /usr/games/lib/nethackdir. -If DLB was defined during the compile, the data files and special levels -will be inside a larger file, normally nhdat, instead of being separate -files. - -.br -.DT -.\" continuation lines begin with -.ta \w'cmdhelp, opthelp, wizhelp\ \ \ 'u -nethack The program itself. -.br -Guidebook\ |\ Guidebook.txt NetHack's user manual. -.br -data, oracles, rumors Data files used by NetHack. -.br -bogusmon Another data file. -.br -engrave, epitaph, tribute Still more data files. -.br -symbols Data file holding sets of specifications -.br -\ for how to display monsters, objects, and -.br -\ map features. -.br -options Data file containing a description of the -.br -\ build-time option settings. -.br -help,\ hh,\ cmdhelp Help data files. -('cmdhelp' is obsolete.) -.br -opthelp,\ optmenu,\ wizhelp More help data files. -.br -keyhelp,\ usagehlp Even more help data files. -.br -*.lua Predefined special levels, dungeon control -.br -\ for special levels, quest texts. -.br -history A short history of NetHack. -.br -license Rules governing redistribution. -.br -record The list of top scorers. -.br -logfile An extended list of games played -.br -\ (optional). -.br -xlogfile A more detailed version of 'logfile' -.br -\ (also optional). -.br -paniclog Record of exceptional conditions -.br -\ discovered during program execution. -.br -xlock.nn Description of dungeon level 'nn' of -.br -\ active game 'x' if there's a limit on the -.br -\ number of simultaneously active games. -.br -UUcccccc.nn Alternate form for dungeon level 'nn' -.br -\ of active game by user 'UU' playing -.br -\ character named 'cccccc' when there's no -.br -\ limit on number of active games. -.br -perm Lock file for xlock.0 or UUcccccc.0. -.br -bonD0.nn Descriptions of the ghost and belongings -.br -\ of a deceased adventurer who met his or -.br -\ her demise on level 'nn'. +normally +.IR /usr/\*:games/\*:lib/\*:nethackdir . +If DLB was defined during the compile, +the data files and special levels will be inside a larger file, +normally +.IR nhdat , +instead of being separate files. +.TP +.I nethack +The program itself. +.TP +.I Guidebook +.TQ +.I Guidebook.txt +NetHack's user manual. +.TP +.I data +.TQ +.I oracles +.TQ +.I rumors +Data files used by NetHack. +.TP +.I bogusmon +Another data file. +.TP +.I engrave +.TQ +.I epitaph +.TQ +.I tribute +Still more data files. +.TP +.I symbols +Data file holding sets of specifications +for how to display monsters, objects, and +map features. +.TP +.I options +Data file containing a description of the +build-time option settings. +.TP +.I help +.TQ +.I hh +.TQ +.I cmdhelp +Help data files. +.RI ( cmdhelp +is obsolete.) +.TP +.I opthelp +.TQ +.I optmenu +.TQ +.I wizhelp +More help data files. +.TP +.I keyhelp +.TQ +.I usagehlp +Even more help data files. +.TP +.RI * .lua +Predefined special levels, dungeon control +for special levels, quest texts. +.TP +.I history +A short history of NetHack. +.TP +.I license +Rules governing redistribution. +.TP +.I record +The list of top scorers. +.TP +.I logfile +An extended list of games played +(optional). +.TP +.I xlogfile +A more detailed version of +.I logfile +(also optional). +.TP +.I paniclog +Record of exceptional conditions +discovered during program execution. +.TP +.RI x lock. nn +Description of dungeon level +.I nn +of active game +.I x +if there's a limit on the +number of simultaneously active games. +.TP +.RI UUcccccc . nn +Alternate form for dungeon level +.I nn +of active game by user +.I UU +playing character named +.I cccccc +when there's no +limit on number of active games. +.TP +.I perm +Lock file for +.RI x lock.0 +or +.RI UUcccccc .0 . +.TP +.IR bonD0. nn +Descriptions of the ghost and belongings +of a deceased adventurer who met his or +her demise on level +.IR nn . A subsequent -.br -\ character might encounter this old level. -.br -.\"following line should contain -\ -.br -save/ A subdirectory containing saved games. -.br -.\"following line should contain -\ -.br -sysconf System-wide options. Required if -.br -\ program is built with 'SYSCF' option -.br -\ enabled, ignored if not. -.br - -The location of 'sysconf' is specified at build time and can't be changed -except by updating source file "config.h" and rebuilding the program. -.br - +character might encounter this old level. +.TP +.I save/ +Subdirectory containing saved games. +.TP +.I sysconf +System-wide options. +Required if +program is built with 'SYSCF' option +enabled, ignored if not. +.PP +The location of +.I sysconf +is specified at build time and can't be changed +except by updating source file +.\" We do the following in an ugly and non-idiomatic way to work around +.\" a DWB 3.3 nroff bug. +.\" troff: if-else overflow.; doc/nethack.6:623 +.\" stack: }S }S }S }S }S }S }S }S }S }S }S }S }S }S }S }S RI +.\" Even at that, DWB insists on setting the period in roman. +"\c +.I config.h\c +" +and rebuilding the program. +.PP NetHack's Guidebook might not be present if whoever packaged or installed the program distribution neglected to include it. -.br - -In a perfect world, 'paniclog' would remain empty. +.PP +In a perfect world, +.I paniclog +would remain empty. .SH ENVIRONMENT -.DT -.ta \w'NETHACKDIR or HACKDIR\ \ \ 'u -USER or LOGNAME Your login name. -.br -HOME Your home directory. -.br -SHELL Your shell. -.br -TERM The type of your terminal. -.br -HACKPAGER or PAGER Replacement for default pager. -.br -MAIL Mailbox file. -.br -MAILREADER Replacement for default reader -.br -\ (probably /bin/mail or /usr/ucb/mail). -.br -NETHACKDIR or HACKDIR Playground. -.br -NETHACKOPTIONS String predefining several NetHack options. -.br - -If the same option is specified in both NETHACKOPTIONS and .nethackrc, -the value assigned in NETHACKOPTIONS takes precedence. -.br - -SHOPTYPE and SPLEVTYPE can be used in debugging (wizard) mode. -.br -DEBUGFILES can be used if the program was built with 'DEBUG' enabled. +In some cases, +.I NetHack +attempts to access multiple environment variables in sequence +(via +.IR getenv (3) +or similar) +to determine information. +.TP 16n \" "NETHACKOPTIONS" + 2n +.I USER +.TQ +.I +LOGNAME +Your login name. +.TP +.I HOME +Your home directory. +.TP +.I SHELL +Your login shell +(not necessarily the one running when you started +.IR NetHack ). +.TP +.I TERM +Your terminal type. +.TP +.I HACKPAGER +.TQ +.I PAGER +Replacement for default pager. +.TP +.I MAIL +Mailbox file. +.TP +.I MAILREADER +Replacement for default reader +(probably +.I /bin/\*:mail +or +.IR /usr/\*:ucb/\*:mail ). +.TP +.I NETHACKDIR +.TQ +.I HACKDIR +Playground. +.TP +.I NETHACKOPTIONS +Predefined +.I NetHack +options. +.PP +If the same option is specified in both +.I \%NETHACKOPTIONS +and +.IR \%.nethackrc , +the value assigned in +.I \%NETHACKOPTIONS +takes precedence. +.PP +.I SHOPTYPE +and +.I \%SPLEVTYPE +can be used in debugging (wizard) mode. +.I \%DEBUGFILES +can be used if the program was built with 'DEBUG' enabled. .SH "SEE ALSO" -.PP -recover(6) +.IR recover (6) .SH BUGS -.PP Probably infinite. .SH COPYRIGHT -This file is Copyright (C) \*(Na, \*(Nd for version \*(Nb:\*(Nr. -NetHack may be freely redistributed. See license for details. -.PP -Dungeons & Dragons is a Trademark of Wizards of the Coast, Inc. +.\" All troffs and nroffs support `\(co` except Plan 9 nroff, but Plan 9 +.\" offers no test for special character availability, and its feature +.\" set too closely resembles DWB 3.3 to test for it. Use a string with +.\" any nroff-mode formatter not claiming groff compatiblity. +.ds co \(co +.if !\n(.g .if n .ds co (C)\" in principle, should be just "c" +This file is Copyright \*(co \*(Na, \*(Nd for version \*(Nb:\*(Nr. +NetHack may be freely redistributed. +See license for details. diff --git a/doc/recover.6 b/doc/recover.6 index 90d56c8c9..a1c8ad68b 100644 --- a/doc/recover.6 +++ b/doc/recover.6 @@ -10,7 +10,9 @@ .. .NB $NHDT-Branch: NetHack-5 $ .NR $NHDT-Revision: 1.12 $ -.\" groff and AT&T-descended troffs use different hyphenation patterns. +.ie \n(.g .ds ^ \(ha +.el .ds ^ ^ +.\" groff and AT&T-descended troffs use different hyphenation patterns. .\" Don't hyphenate the last word on a page or column, or .\" before/after last/first 2 characters of a word. .ie \n(.g .hy 12 @@ -20,77 +22,89 @@ recover \- recover a NetHack game interrupted by disaster .SH SYNOPSIS .B recover -[ -.B \-d -.I directory -] -.I "base1 base2" ... +.RB [ \-d +.IR playground-directory ] +.I base +\&.\|.\|. .SH DESCRIPTION -.PP -Occasionally, a NetHack game will be interrupted by disaster -when the game or the system crashes. -Prior to NetHack v3.1, these games were lost because various information +Occasionally, a NetHack game is interrupted by disaster +when the program or the system crashes. +Prior to NetHack v3.1, these games were lost because information like the player's inventory was kept only in memory. Now, all pertinent information can be written out to disk, so such games can be recovered at the point of the last level change. .PP -The -.I base -options tell +.I Base +operands tell .I recover which files to process. -Each base option specifies recovery of a separate game. +Each +.I base +specifies recovery of a separate game. .PP The .B \-d option, which must be the first argument if it appears, -supplies a directory which is the NetHack playground. -It overrides the value from NETHACKDIR, HACKDIR, or the directory +supplies the directory housing the NetHack playground. +It overrides the value of the environment variables +.I NETHACKDIR +and +.IR HACKDIR , +and the directory specified by the game administrator during compilation -(usually /usr/games/lib/nethackdir). +(usually +.IR /usr/games/lib/nethackdir ). .ig .PP -^?ALLDOCS +\*^?ALLDOCS For recovery to be possible, -.I nethack +.IR nethack (6) must have been compiled with the INSURANCE option, and the run-time option .I checkpoint must also have been on. -^: -^?INSURANCE +\*^: +\*^?INSURANCE For recovery to be possible, .I nethack must have been compiled with the INSURANCE option (this configuration was), and the run-time option .I checkpoint must also have been on. -^: +\*^: This configuration of .I nethack was created without support for recovery. -^. -^. +\*^. +\*^. .. -NetHack normally writes out files for levels as the player leaves them, +.IR nethack (6) +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 +When checkpointing, it also writes out the level entered and the current game state on every level change. -This naturally slows level changes down somewhat. +This procedure slows level changes. .PP -The level file names are of the form base.nn, where nn is an internal -bookkeeping number for the level. -The file base.0 is used for game identity, locking, and, when checkpointing, +The level file names are of the form +.IR base. nn, where +.I nn +is an internal bookkeeping number for the level. +The file +.I base.0 +is used for game identity, locking, and, when checkpointing, for the game state. Various OSes use different strategies for constructing the base name. -Microcomputers use the character name, possibly truncated and modified +Single-user systems use the character name, +possibly truncated and modified to be a legal filename on that system. Multi-user systems use the (modified) character name prefixed by a user number to avoid conflicts, -or "xlock" if the number of concurrent players is being limited. +or +.I xlock +if the number of concurrent players is being limited. It may be necessary to look in the playground to find the correct base name of the interrupted game. .I recover -will transform these level files into a save file of the same name as +transforms these level files into a save file of the same name that .I nethack would have used. .PP @@ -105,13 +119,16 @@ through setuid or setgid is tantamount to leaving the playground world-writable, with respect to both cheating and messing up other players. For a single-user system, this of course does not change anything, -so some of the microcomputer ports install +so some of these ports install .I recover by default. .PP For a multi-user system, -the game administrator may want to arrange for all .0 files in the -playground to be fed to recover when the host machine boots, +the game administrator may want to arrange for all +.I .0 +files in the playground to be fed to +.I recover +when the host machine boots, and handle game crashes individually. If the user population is sufficiently trustworthy, .I recover @@ -122,12 +139,11 @@ In either case, .I recover is easily compiled from the distribution utility directory. .SH NOTES -.PP Like .I nethack itself, .I recover -will overwrite existing savefiles of the same name. +will overwrite existing save files of the same name. Savefiles created by .I recover are uncompressed; @@ -136,17 +152,24 @@ but even a compression-using .I nethack will find them in the uncompressed form. .SH "SEE ALSO" -nethack(6) +.IR nethack (6) .SH BUGS -.PP .I recover makes no attempt to find out if a base name specifies a game in progress. If multiple machines share a playground, this would be impossible to determine. .PP .I recover -should be taught to use the nethack playground locking mechanism to -avoid conflicts. +should be taught to use the +.I nethack +playground locking mechanism to avoid conflicts. .SH COPYRIGHT -This file is Copyright (C) \*(Na, \*(Nd for version \*(Nb:\*(Nr. -NetHack may be freely redistributed. See license for details. +.\" All troffs and nroffs support `\(co` except Plan 9 nroff, but Plan 9 +.\" offers no test for special character availability, and its feature +.\" set too closely resembles DWB 3.3 to test for it. Use a string with +.\" any nroff-mode formatter not claiming groff compatiblity. +.ds co \(co +.if !\n(.g .if n .ds co (C)\" in principle, should be just "c" +This file is Copyright \*(co \*(Na, \*(Nd for version \*(Nb:\*(Nr. +NetHack may be freely redistributed. +See license for details.