diff --git a/doc/.gitattributes b/doc/.gitattributes index 41a7f6ff5..544cfa5c5 100644 --- a/doc/.gitattributes +++ b/doc/.gitattributes @@ -5,5 +5,6 @@ window.doc NHSUBST config.nh NHSUBST Guidebook.txt NH_header=no tmac.n NH_header=no +tmac.nh NUSUBST fixes* NH_header=no *.txt NH_header=no diff --git a/doc/Guidebook.mn b/doc/Guidebook.mn index e844724c6..ebe9a7628 100644 --- a/doc/Guidebook.mn +++ b/doc/Guidebook.mn @@ -1,4 +1,4 @@ -.\" $NHDT-Branch: NetHack-3.6.2-beta01 $:$NHDT-Revision: 1.284 $ $NHDT-Date: 1539898655 2018/10/18 21:37:35 $ +.\" $NHDT-Branch: NetHack-3.6.2-beta01 $:$NHDT-Revision: 1.286 $ $NHDT-Date: 1540625949 2018/10/27 07:39:09 $ .\" .\" This is an excerpt from the 'roff' man page from the 'groff' package. .\" NetHack's Guidebook.mn currently does *not* adhere to these guidelines. @@ -15,6 +15,9 @@ .\"| ter each sentence. .\"||| .\" +. +.so tmac.nh \" extra macros which aren't in tmac.n +. .ds h0 "NetHack Guidebook .ds h1 .ds h2 % @@ -23,67 +26,6 @@ .ds f1 .ds f2 "October 16, 2018 . -.\" labeled paragraph start (should be part of tmac.n, but I don't want to -.\" make changes to that file) -.\" .PS word -.\" set the width for the label column -.\" .PL word -.\" label for the entry -.\" .PE -.\" clean up -.de PS -.nr PY \\w'\\$1\ -\ 'u \" width of label plus " - " -.nr PX \\w'\ -\ 'u \" width of " - " -.sn \\n(pdu \" tmac.n: inter-paragraph space -.in +\\n(PYu \" additional indent past label (etc) -.si \" tmac.n: start indented section -.. -.\" labeled paragraph label (and first line) -.de PL -.br -\\h'|-\\n(PYu'\\$1\\h'|-\\n(PXu'\ -\ \\c \" back up, output the label, then -. \" skip to width-of(" - ") before the -. \" normal indentation, output the " - " -. \" then attach the next line (the -. \" text) without stopping (\c: nroff -. \" section 4.2) -.. -.\"labeled paragraph end -.de PE -.ei \" tmac.n: end indented section -.in -\\n(PYu \" undo indent past label (etc) -.sn \\n(pdu \" tmac.n: inter-paragraph space -.. -.\" end of labeled paragraph -.\" -.\" aligned single character key with SHORT definition (if it overflows one -.\" line, all bets are off) -.\" Usage: -.\" .CC k "definition here" -.nr CZ \w'\fBW' \" width of the key character column -.nr CW \n(CZ/2 \" half the width of the key character column -.de CC -.nr CX \\w'\\fB\\$1'u/2 \" half the width of the key character -.nr CY \\n(CWu-\\n(CXu \" difference between the two half widths -.\" output: move right CR units, print the key letter, move right to -.\" the full width of the column, print " - " and the definition -\\h'|\\n(CYu'\\fB\\$1\\fP\\h'|\\n(CZu'\ -\ \\$2 -.. -.\" '.UX' is verbatim copy of tmac.n's '.ux' with the exception that -.\" the trademark owner for "UNIX" has been updated. (tmac.n contains -.\" a comment asking that modified versions not be distributed, so we -.\" are using this substitute instead of modifying that file.) -.de UX \" print "UNIX" -.ie \\n(ux \\&\\$2\\s-1UNIX\\s0\\$1 -.el \{\ -. nr ux +1 \" mark footnote as dropped -\\&\\$2\\s-1UNIX\\s0\\*(rg\\$1 -. fn \" put out the footnote -\\&\\*(rgUNIX is a registered trademark of The Open Group. -. ef \" short and sweet ... -.\} -.. -. .\" A note on some special characters: .\" \(lq = left double quote .\" \(rq = right double quote \(dq = double quote character @@ -285,8 +227,7 @@ replaces the \(lqYou see ...\(rq descriptions of text adventure games. Figure 1 is a sample of what a NetHack screen might look like. The way the screen looks for you depends on your platform. . -.br \" break - advance to next line -\ \" space to force non-empty line before table +.BR 2 .ft CR \" set font to constant-width Roman .TS S center box tab(~); @@ -2479,7 +2420,8 @@ Very large humanoids (giants and their ilk) have been known to use boulders as weapons. .pg For some configurations of the program, statues are no longer shown as -\(oq\`\(cq but by the letter representing the monster they depict instead. +\(oq\f(CR\`\fP\(cq but by the letter representing the monster they depict +instead. .hn 2 Gold (\(oq$\(cq) .pg @@ -2816,6 +2758,7 @@ OPTIONS=lit_corridor OPTIONS=!splash_screen .ft \" revert to previous font .ed +.BR 2 .hn 2 Using the NETHACKOPTIONS environment variable .pg @@ -2823,32 +2766,46 @@ The NETHACKOPTIONS variable is a comma-separated list of initial values for the various options. Some can only be turned on or off. You turn one of these on by adding the name of the option to the list, -and turn it off by typing a \(oq!\(cq or \(lqno\(rq before the name. +and turn it off by typing a \(oq\f(CR!\fP\(cq or \(lq\f(CRno\fP\(rq +before the name. Others take a character string as a value. You can set string options by typing the option name, a colon or equals sign, and then the value of the string. The value is terminated by the next comma or the end of string. .pg -For example, to set up an environment variable so that \(lqcolor\(rq -is on, \(lqautopickup\(rq is off, the name is set to \(lqBlue Meanie\(rq, -and the fruit is set to \(lqpapaya\(rq, you would enter the command -.sd -% \f(CRsetenv NETHACKOPTIONS "color,\e!autopickup,name:Blue Meanie,fruit:papaya"\fP -.ed +For example, to set up an environment variable so that +\fIcolor\fP is \f(CRon\fP, +\fIlegacy\fP is \f(CRoff\fP, +character \fIname\fP is set to \(lq\f(CRBlue Meanie\fP\(rq, +and named \fIfruit\fP is set to \(lq\f(CRlime\fP\(rq, +you would enter the command +.\" Guidebook.ps looks better with the normal indentation for .sd (.SD i) +.\" but the 'setenv' example is too wide for Guidebook.txt unless the +.\" indentation is suppressed (.SD n). Even though the second example +.\" can be indented, it should match the first or they'll both look odd. +.\" groff has a built-in register allowing recognition of '-T', but we +.\" can't rely on that. Assume Guidebook.ps uses a proportional font +.\" and Guidebook.txt a fixed-width one and test which sort we're using. +.ds sD i \" assume proportional, indentation acceptable and preferred +.\" Check for fixed-width font; 'f' will be same width as 'F'. +.if (\w'f'p)=(\w'F'p) .ds sD n \" if same width, suppress indentation +.SD \*(sD +\f(CR% setenv NETHACKOPTIONS "color,\\!leg,name:Blue Meanie,fruit:lime"\fP +.ED in \fIcsh\fP (note the need to escape the \(oq!\(cq since it's special -to the shell), or -.sd -$ \f(CRNETHACKOPTIONS="color,!autopickup,name:Blue Meanie,fruit:papaya"\fP -$ \f(CRexport NETHACKOPTIONS\fP -.ed +to that shell), or the pair of commands +.SD \*(sD +\f(CR$ NETHACKOPTIONS="color,!leg,name:Blue Meanie,fruit:lime"\fP +\f(CR$ export NETHACKOPTIONS\fP +.ED in \fIsh\fP, \fIksh\fP, or \fIbash\fP. .pg Instead of a comma-separated list of options, NETHACKOPTIONS can be set to the full name of a configuration file you want to use. -If that full name doesn't start with a slash, precede it with \(oq@\(cq +If that full name doesn't start with a slash, precede it with \(oq\f(CR@\fP\(cq (at-sign) to let NetHack know that the rest is intended as a file name. -If it does start with \(oq/\(cq, the at-sign is optional. +If it does start with \(oq\f(CR/\fP\(cq, the at-sign is optional. .hn 2 Customization options .pg diff --git a/doc/Guidebook.tex b/doc/Guidebook.tex index 3b434806e..e184d7192 100644 --- a/doc/Guidebook.tex +++ b/doc/Guidebook.tex @@ -283,6 +283,7 @@ understand what {\it NetHack\/} is doing with the screen. The {\it NetHack\/} screen replaces the ``You see \ldots'' descriptions of text adventure games. Figure 1 is a sample of what a {\it NetHack\/} screen might look like. The way the screen looks for you depends on your platform. +%.BR 2 \vbox{ \begin{verbatim} @@ -297,8 +298,8 @@ The way the screen looks for you depends on your platform. - Player the Rambler St:12 Dx:7 Co:18 In:11 Wi:9 Ch:15 Neutral - Dlvl:1 $:0 HP:9(12) Pw:3(3) AC:10 Exp:1/19 T:257 Weak + Player the Rambler St:12 Dx:7 Co:18 In:11 Wi:9 Ch:15 Neutral + Dlvl:1 $:0 HP:9(12) Pw:3(3) AC:10 Exp:1/19 T:257 Weak \end{verbatim} \begin{center} Figure 1 @@ -1620,7 +1621,7 @@ bit), you can invoke many extended commands by meta-ing the first letter of the command. In {\it NT, OS/2, PC\/ {\rm and} ST NetHack}, the `Alt' key can be used in this fashion; -on the {\it Amiga\/}, set the {\it altmeta\/} option to get this behavior. +on the {\it Amiga}, set the {\it altmeta\/} option to get this behavior. On other systems, if typing `Alt' plus another key transmits a two character sequence consisting of an {\tt Escape} followed by the other key, you may set the {\it altmeta\/} @@ -2040,7 +2041,7 @@ location ordinarily wouldn't be seen any more. %.pg When you find something in the dungeon, it is common to want to pick -it up. In {\it NetHack\/}, this is accomplished automatically by walking over +it up. In {\it NetHack}, this is accomplished automatically by walking over the object (unless you turn off the {\it autopickup\/} option (see below), or move with the `{\tt m}' prefix (see above)), or manually by using the `{\tt ,}' command. @@ -2791,7 +2792,7 @@ fire, and kick weapons; use a wand, spell, or other type of item; or fight with your hands and feet. %.pg -In {\it NetHack\/}, a pacifist refuses to cause the death of any other monster +In {\it NetHack}, a pacifist refuses to cause the death of any other monster (i.e. if you would get experience for the death). This is a particularly difficult challenge, although it is still possible to gain experience by other means. @@ -3032,6 +3033,7 @@ Here is a short example of config file contents: OPTIONS=!splash_screen \end{verbatim} %.ed +%.BR 2 %.hn 2 \subsection*{Using the NETHACKOPTIONS environment variable} @@ -3047,25 +3049,29 @@ the option name, a colon or equals sign, and then the value of the string. The value is terminated by the next comma or the end of string. %.pg -For example, to set up an environment variable so that {\it color\/} -is on, {\it autopickup\/} is off, the {\it name\/} is set to ``Blue Meanie'', -and the {\it fruit\/} is set to ``papaya'', you would enter the command -%.sd +For example, to set up an environment variable so that +{\it color\/} is {\tt on}, +{\it legacy\/} is {\tt off}, +character {\it name\/} is set to ``{\tt Blue Meanie}'', +and named {\it fruit\/} is set to ``{\tt lime}'', +you would enter the command +%.SD i \begin{verbatim} - setenv NETHACKOPTIONS "color,\!autopickup,name:Blue Meanie,fruit:papaya" + setenv NETHACKOPTIONS "color,\!leg,name:Blue Meanie,fruit:lime" \end{verbatim} -%.ed +%.ED \nd in {\it csh} -(note the need to escape the `!' since it's special to the shell), or -%.sd +(note the need to escape the `!' since it's special +to that shell), or the pair of commands +%.SD i \begin{verbatim} - NETHACKOPTIONS="color,!autopickup,name:Blue Meanie,fruit:papaya" + NETHACKOPTIONS="color,!leg,name:Blue Meanie,fruit:lime" export NETHACKOPTIONS \end{verbatim} -%.ed +%.ED -\nd in {\it sh\/}, {\it ksh}, or {\it bash}. +\nd in {\it sh}, {\it ksh}, or {\it bash}. %.pg Instead of a comma-separated list of options, diff --git a/doc/Guidebook.txt b/doc/Guidebook.txt index 2b44d9beb..4f96aae71 100644 --- a/doc/Guidebook.txt +++ b/doc/Guidebook.txt @@ -3154,11 +3154,11 @@ equals sign, and then the value of the string. The value is ter- minated by the next comma or the end of string. - For example, to set up an environment variable so that "col- - or" is on, "autopickup" is off, the name is set to "Blue Meanie", - and the fruit is set to "papaya", you would enter the command + For example, to set up an environment variable so that color + is on, legacy is off, character name is set to "Blue Meanie", and + named fruit is set to "lime", you would enter the command - % setenv NETHACKOPTIONS "color,\!autopickup,name:Blue Meanie,fruit:papaya" + % setenv NETHACKOPTIONS "color,\!leg,name:Blue Meanie,fruit:lime" @@ -3172,11 +3172,11 @@ - in csh (note the need to escape the `!' since it's special to the - shell), or + in csh (note the need to escape the `!' since it's special to + that shell), or the pair of commands - $ NETHACKOPTIONS="color,!autopickup,name:Blue Meanie,fruit:papaya" - $ export NETHACKOPTIONS + $ NETHACKOPTIONS="color,!leg,name:Blue Meanie,fruit:lime" + $ export NETHACKOPTIONS in sh, ksh, or bash. diff --git a/doc/tmac.nh b/doc/tmac.nh new file mode 100644 index 000000000..6914d018a --- /dev/null +++ b/doc/tmac.nh @@ -0,0 +1,127 @@ +.\" NetHack 3.6 tmac.nh $NHDT-Date: $ $NHDT-Branch: $:$NHDT-Revision: $ +. +.\" Miscellaneous tmac.n-style macros specifically for nethack's Guidebook. +.\" +.\" Most are modelled after, or variations of, macros in tmac.n whose author +.\" has specified that that file remain unmodified if it gets distributed. +.\" These used to be inline within Guidebook.mn but it was becoming too +.\" cluttered as their number increased. It now uses the '.so' directive +.\" to include this file. (tmac.n is passed to 'roff on the command line.) +. +.\" labeled paragraph start +.\" .PS word +.\" set the width for the label column +.\" .PL word +.\" label for the entry +.\" .PE +.\" clean up +.de PS +.nr PY \\w'\\$1\ -\ 'u \" width of label plus " - " +.nr PX \\w'\ -\ 'u \" width of " - " +.sn \\n(pdu \" tmac.n: inter-paragraph space +.in +\\n(PYu \" additional indent past label (etc) +.si \" tmac.n: start indented section +.. +.\" labeled paragraph label (and first line) +.de PL +.br +\\h'|-\\n(PYu'\\$1\\h'|-\\n(PXu'\ -\ \\c \" back up, output the label, then +. \" skip to width-of(" - ") before the +. \" normal indentation, output the " - " +. \" then attach the next line (the +. \" text) without stopping (\c: nroff +. \" section 4.2) +.. +.\" labeled paragraph end +.de PE +.ei \" tmac.n: end indented section +.in -\\n(PYu \" undo indent past label (etc) +.sn \\n(pdu \" tmac.n: inter-paragraph space +.. +.\" end of labeled paragraph +. +.\" +.\" aligned single character key with SHORT definition (if it overflows one +.\" line, all bets are off) +.\" Usage: +.\" .CC k "definition here" +.nr CZ \w'\fBW' \" width of the key character column +.nr CW \n(CZ/2 \" half the width of the key character column +.de CC +.nr CX \\w'\\fB\\$1'u/2 \" half the width of the key character +.nr CY \\n(CWu-\\n(CXu \" difference between the two half widths +.\" output: move right CR units, print the key letter, move right to +.\" the full width of the column, print " - " and the definition +\\h'|\\n(CYu'\\fB\\$1\\fP\\h'|\\n(CZu'\ -\ \\$2 +.. +. +.\" .SD = .sd with extra choices for argument; pair with .ED +.\" c - centered (original choice; as of this writing, not used by nethack) +.\" i - indented (default if choice is omitted) +.\" n - not indented +.\" SF - set (1=>indent, 0=>no-indent) by .SD, used by .ED unless centering +.de SD \" start display +. \" look for nested displays -- ILLEGAL +.ie \\n(id>0 .er "display within display" +.el \{\ +. nr sf 0 \" don't center by default +. nr SF 1 \" assume indent +. ie '\\$1'c' .nr sf 1 \" center the sucker +. el .if '\\$1'n' .nr SF 0 \" don't indent if 'n' +.\} +.sn \\n(pdu \" a little bit of space +.ev 2 \" switch to display environment +.nf \" what you type is what you get +.if \\n(id=0 .di dd \" start saving text +.rs \" don't eat leading space +.nr id +1 \" increment level of display +.. +.\" .ED = .ed with support for \n(SF (indent vs no-indent); pair with .SD +.de ED \" end display +.br \" flush line +.ie \\n(id<=0 .er "end display has no corresponding begin display" +.el \{\ +. nr id -1 \" decrement level of display +. if \\n(id=0 \{\ +. di \" end diversion +. fi \" resume filling +. in -\\n(piu \" dedent +. ev \" pop environment +. ne \\n(dnu \" be sure you have room +. nf \" don't reprocess display +. rs \" don't eat leading space +. zi \" save indents +. ie \\n(sf .in (\\n(llu-\\n(dlu)/2u \" center +. el .if \\n(SF .in +\\n(piu \" indent +. dd \" drop display +. yi \" restore indents +. \} +.\} +.fi \" resume filling +.sn \\n(pdu \" a little bit of space +.. +. +.\" '.UX' is verbatim copy of tmac.n's '.ux' with the exception that +.\" the trademark owner for "UNIX" has been updated. +.de UX \" print "UNIX" +.ie \\n(ux \\&\\$2\\s-1UNIX\\s0\\$1 +.el \{\ +. nr ux +1 \" mark footnote as dropped +\\&\\$2\\s-1UNIX\\s0\\*(rg\\$1 +. fn \" put out the footnote +\\&\\*(rgUNIX is a registered trademark of The Open Group. +. ef \" short and sweet ... +.\} +.. +. +.\" .BR - hard line break with vertical padding inserted +.\" $1 - repeat count for amount of padding (optional; default is 1) +.de BR +.nr bR (\\$1-0) +.if \\n(bR<1 .nr bR 1 +.nr bR \\n(bR*\\n(pd +.sn \\n(bRu +.br +.. +. +.\"tmac.nh/" diff --git a/sys/unix/Makefile.doc b/sys/unix/Makefile.doc index dd3703b01..1d2f53532 100644 --- a/sys/unix/Makefile.doc +++ b/sys/unix/Makefile.doc @@ -1,5 +1,5 @@ # NetHack Documentation Makefile. -# NetHack 3.6 Makefile.doc $NHDT-Date: 1524689449 2018/04/25 20:50:49 $ $NHDT-Branch: NetHack-3.6.0 $:$NHDT-Revision: 1.16 $ +# NetHack 3.6 Makefile.doc $NHDT-Date: 1540625947 2018/10/27 07:39:07 $ $NHDT-Branch: NetHack-3.6.2-beta01 $:$NHDT-Revision: 1.17 $ # Copyright (c) 2015 by Kenneth Lorber, Kensington, Maryland # NetHack may be freely redistributed. See license for details. @@ -45,11 +45,11 @@ NHGREP = $(MAKEDEFS) --grep --input - --output - GUIDE_PREFORMAT = cat Guidebook.mn | $(NHGREP) | tbl tmac.n - # the basic guidebook -Guidebook: Guidebook.mn +Guidebook: Guidebook.mn tmac.n tmac.nh $(GUIDECMD) > Guidebook # Fancier output for those with ditroff, psdit and a PostScript printer. -Guidebook.ps: Guidebook.mn +Guidebook.ps: Guidebook.mn tmac.n tmac.nh $(GUIDE_PREFORMAT) | $(PSCMD) > Guidebook.ps # Guidebook.tex is the same as Guidebook.mn but formatted with LaTeX. @@ -95,7 +95,7 @@ DISTRIB = Guidebook.txt nethack.txt lev_comp.txt dgn_comp.txt recover.txt \ distrib: $(DISTRIB) @echo "Plain text documentation is up to date." -Guidebook.txt : Guidebook.mn tmac.n +Guidebook.txt : Guidebook.mn tmac.n tmac.nh $(GUIDECMD) > Guidebook.txt MAN2TXT = $(NHGREP) | nroff -man - | $(COLCMD) nethack.txt : nethack.6