Improve the Guidebook config file section

2016-06-04 12:43:09 +03:00
parent ad9e3dcef9
commit c36bc0043c
2 changed files with 236 additions and 87 deletions
@@ -1969,12 +1969,111 @@ Setting the options
 .pg
 Options may be set in a number of ways.  Within the game, the `O'
 command allows you to view all options and change most of them.
-You can also set options automatically by placing them in the
+You can also set options automatically by placing them in a configuration
-NETHACKOPTIONS environment variable or in a configuration file.
+file, or in the NETHACKOPTIONS environment variable.
 Some versions of NetHack also have front-end programs that allow
 you to set options before starting the game or a global configuration
 for system administrators.
 .hn 2
 Using a configuration file
 .pg
 The default name of the configuration file varies on different
 operating systems. On DOS and Windows, it is ``defaults.nh''
 in the same folder as nethack.exe or nethackW.exe. On Unix, Linux
 and Mac OS X it is ``.nethackrc'' in the user's home directory.
 The file may not exist, but it is a normal ASCII text file and
 can be created with any text editor.
 .pg
 Any line in the configuration file starting with `#' is treated as a comment.
 Empty lines are ignored.
 .pg
 You can use different configuration statements in the file, some
 of which can be used multiple times. In general, the statements are
 written in capital letters, followed by an equals sign, followed by
 settings particular to that statement. Here is a list of allowed statements:
 .lp OPTIONS
 There are two types of options, boolean and compound options.
 Boolean options toggle a setting on or off, while compound options
 take more diverse values.
 Prefix a boolean option with `no' or `!' to turn it off.
 For compound options, the option name and value are separated by a colon.
 Some options are persistent, and apply only to new games.
 You can specify multiple OPTIONS statements, and multiple options
 in a single OPTIONS statement.
 .pg
 Example:
 .sd
 \fBOPTIONS=dogname:Fido\fP
 \fBOPTIONS=!legacy,autopickup,pickup_types:$"=/!?+\fP
 .ed
 .lp HACKDIR
 Default location of files NetHack needs. On Windows HACKDIR
 defaults to the location of the NetHack.exe or NetHackw.exe file
 so setting HACKDIR to override that is not usually necessary or recommended.
 .lp LEVELDIR
 The location that in-progress level files are stored. Defaults to HACKDIR,
 must be writeable.
 .lp SAVEDIR
 The location where saved games are kept. Defaults to HACKDIR, must be
 writeable.
 .lp BONESDIR
 The location that bones files are kept. Defaults to HACKDIR, must be
 writeable.
 .lp LOCKDIR
 The location that file synchronization locks are stored. Defaults to
 HACKDIR, must be writeable.
 .lp TROUBLEDIR
 The location that a record of game aborts and self-diagnosed game problems
 is kept. Defaults to HACKDIR, must be writeable.
 .lp AUTOPICKUP_EXCEPTION
 Set exceptions to the
 .op pickup_types
 option. See the ``Configuring Autopickup Exceptions'' section.
 .lp MSGTYPE
 Change the way messages are shown in the top status line.
 See the ``Configuring Message Types`` section.
 .lp MENUCOLOR
 Highlight menu lines with different colors.
 See the ``Configuring Menu Colors`` section.
 .lp SYMBOLS
 Override one or more symbols in the symbols files.
 See the ``Modifying NetHack Symbols'' section.
 .pg
 Example:
 .sd
 \fBSYMBOLS=S_boulder:0\fP
 .ed
 .lp WIZKIT
 Wizard-mode extra items, in a text file containing item names,
 one per line, up to a maximum of 128 lines. Each line is processed
 by the function that handles wishing.
 .pg
 Example:
 .sd
 \fBWIZKIT=~/wizkit.txt\fP
 .ed
 .lp SOUNDDIR
 Define the directory that contains the sound files.
 See the ``Configuring User Sounds'' section.
 .lp SOUND
 Define a sound mapping. See the ``Configuring User Sounds'' section.
 .pg
 Here is a short example of config file contents:
 .sd
 \fB# Set your character's role, race, gender, and alignment.\fP
 \fBOPTIONS=role:Valkyrie, race:Human, gender:female, align:lawful\fP
 \fB# Turn on autopickup, and set automatically picked up object types\fP
 \fBOPTIONS=autopickup,pickup_types:$"=/!?+\fP
 \fB# Show colored text if possible\fP
 \fBOPTIONS=color\fP
 \fB# Show lit corridors differently\fP
 \fBOPTIONS=lit_corridor\fP
 \fB# No startup splash screen. Windows GUI only.\fP
 \fBOPTIONS=!splash_screen\fP
 .ed
 .hn 2
 Using the NETHACKOPTIONS environment variable
 .pg
 The NETHACKOPTIONS variable is a comma-separated list of initial
@@ -1997,48 +2096,9 @@ $ \fBNETHACKOPTIONS="autoquiver,!autopickup,name:Blue Meanie,fruit:papaya"\fP
 $ \fBexport NETHACKOPTIONS\fP
 .ed
 in \fIsh\fP or \fIksh\fP.
 .hn 2
 Using a configuration file
 .pg
-Any line in the configuration file starting with `#' is treated as a comment.
+NETHACKOPTIONS can also be set to the full name of a configuration file you
 Any line in the configuration file starting with ``OPTIONS='' may be
 filled out with options in the same syntax as in NETHACKOPTIONS.
 Any line starting with ``SYMBOLS=''
 is taken as defining the corresponding symbol
 in a different syntax, a sequence of decimal numbers giving
 the character position in the current font to be used in displaying
 each entry. Such a sequence can be continued to multiple lines by
 putting a `\e'
 at the end of each line to be continued.
 .pg
 Any line starting with ``AUTOPICKUP_EXCEPTION='' is taken
 as defining an exception to the
 .op pickup_types
 option.
 There is a section of this Guidebook that discusses that.
 .pg
 The default name of the configuration file varies on different
 operating systems. On DOS and Windows, it is ``defaults.nh''
 in the same folder as nethack.exe or nethackW.exe. On Unix, Linux
 and Mac OS X it is ``.nethackrc'' in the user's home directory.
 NETHACKOPTIONS can also be set to the full name of a file you
 want to use (possibly preceded by an `@').
 .pg
 Here is a short example of config file contents:
 .sd
 \fB# Set your character's role, race, gender, and alignment.\fP
 \fBOPTIONS=role:Valkyrie, race:Human, gender:female, align:lawful\fP
 \fB# Turn on autopickup, and set automatically picked up object types\fP
 \fBOPTIONS=autopickup,pickup_types:$"=/!?+\fP
 \fB# Show colored text if possible\fP
 \fBOPTIONS=color\fP
 \fB# Show lit corridors differently\fP
 \fBOPTIONS=lit_corridor\fP
 \fB# No startup splash screen. Windows GUI only.\fP
 \fBOPTIONS=!splash_screen\fP
 .ed
 .hn 2
 Customization options
 .pg
@@ -2360,12 +2360,143 @@ behaves.
 %.pg
 Options may be set in a number of ways.  Within the game, the `{\tt O}'
 command allows you to view all options and change most of them.
-You can also set options automatically by placing them in the
+You can also set options automatically by placing them in a configuration
-``NETHACKOPTIONS'' environment variable or in a configuration file.
+file, or in the ``NETHACKOPTIONS'' environment variable.
 Some versions of {\it NetHack\/} also have front-end programs that allow
 you to set options before starting the game or a global configuration 
 for system administrators.
 %.hn 2
 \subsection*{Using a configuration file}
 %.pg
 The default name of the configuration file varies on different
 operating systems. On DOS and Windows, it is ``defaults.nh''
 in the same folder as nethack.exe or nethackW.exe. On Unix, Linux
 and Mac OS X it is ``.nethackrc'' in the user's home directory.
 The file may not exist, but it is a normal ASCII text file and
 can be created with any text editor.
 %.pg
 Any line in the configuration file starting with `{\tt \#}' is treated as a comment.
 Empty lines are ignore.
 %.pg
 You can use different configuration statements in the file, some
 of which can be used multiple times. In general, the statements are
 written in capital letters, followed by an equals sign, followed by
 settings particular to that statement. Here is a list of allowed statements:
 %.lp
 \blist{}
 \item[\bb{OPTIONS}]
 There are two types of options, boolean and compound options.
 Boolean options toggle a setting on or off, while compound options
 take more diverse values.
 Prefix a boolean option with `no' or `!' to turn it off.
 For compound options, the option name and value are separated by a colon.
 Some options are persistent, and apply only to new games.
 You can specify multiple OPTIONS statements, and multiple options
 in a single OPTIONS statement.
 %.pg
 Example:
 %.sd
 \begin{verbatim}
    OPTIONS=dogname:Fido
    OPTIONS=!legacy,autopickup,pickup_types:$"=/!?+
 \end{verbatim}
 %.ed
 %.lp
 \item[\bb{HACKDIR}]
 Default location of files NetHack needs. On Windows HACKDIR
 defaults to the location of the NetHack.exe or NetHackw.exe file
 so setting HACKDIR to override that is not usually necessary or recommended.
 %.lp
 \item[\bb{LEVELDIR}]
 The location that in-progress level files are stored. Defaults to HACKDIR,
 must be writeable.
 %.lp
 \item[\bb{SAVEDIR}]
 The location where saved games are kept. Defaults to HACKDIR, must be
 writeable.
 %.lp
 \item[\bb{BONESDIR}]
 The location that bones files are kept. Defaults to HACKDIR, must be
 writeable.
 %.lp
 \item[\bb{LOCKDIR}]
 The location that file synchronization locks are stored. Defaults to
 HACKDIR, must be writeable.
 %.lp
 \item[\bb{TROUBLEDIR}]
 The location that a record of game aborts and self-diagnosed game problems
 is kept. Defaults to HACKDIR, must be writeable.
 %.lp
 \item[\bb{AUTOPICKUP\_EXCEPTION}]
 Set exceptions to the {{\it pickup\_types\/}}
 option. See the ``Configuring Autopickup Exceptions'' section.
 %.lp
 \item[\bb{MSGTYPE}]
 Change the way messages are shown in the top status line.
 See the ``Configuring Message Types`` section.
 %.lp
 \item[\bb{MENUCOLOR}]
 Highlight menu lines with different colors.
 See the ``Configuring Menu Colors`` section.
 %.lp
 \item[\bb{SYMBOLS}]
 Override one or more symbols in the symbols files.
 See the ``Modifying NetHack Symbols'' section.
 %.pg
 Example:
 %.sd
 \begin{verbatim}
    SYMBOLS=S_boulder:0
 \end{verbatim}
 %.ed
 %.lp
 \item[\bb{WIZKIT}]
 Wizard-mode extra items, in a text file containing item names,
 one per line, up to a maximum of 128 lines. Each line is processed
 by the function that handles wishing.
 %.pg
 Example:
 %.sd
 \begin{verbatim}
    WIZKIT=~/wizkit.txt
 \end{verbatim}
 %.ed
 %.lp
 \item[\bb{SOUNDDIR}]
 Define the directory that contains the sound files.
 See the ``Configuring User Sounds'' section.
 %.lp
 \item[\bb{SOUND}]
 Define a sound mapping. See the ``Configuring User Sounds'' section.
 \elist
 %.pg
 Here is a short example of config file contents:
 %.sd
 \begin{verbatim}
    # Set your character's role, race, gender, and alignment.
    OPTIONS=role:Valkyrie, race:Human, gender:female, align:lawful
    # Turn on autopickup, and set automatically picked up object types
    OPTIONS=autopickup,pickup_types:$"=/!?+
    # Show colored text if possible
    OPTIONS=color
    # Show lit corridors differently
    OPTIONS=lit_corridor
    # No startup splash screen. Windows GUI only.
    OPTIONS=!splash_screen
 \end{verbatim}
 %.ed
 %.hn 2
 \subsection*{Using the NETHACKOPTIONS environment variable}
@@ -2400,52 +2531,10 @@ and the {\it fruit\/} is set to ``papaya'', you would enter the command
 \nd in {\it sh\/} or {\it ksh}.
 %.hn 2
 \subsection*{Using a configuration file}
 %.pg
-Any line in the configuration file starting with `{\tt \#}' is treated as a comment.
+NETHACKOPTIONS can also be set to the full name of a configuration file you
 Any line in the configuration file starting with ``{\tt OPTIONS=}'' may be
 filled out with options in the same syntax as in NETHACKOPTIONS.
 Any line starting with ``{\tt SYMBOLS=}''
 is taken as defining the corresponding {\it symbol}
 in a different syntax, a sequence of decimal numbers giving 
 the character position in the current font to be used in displaying 
 each entry. Such a sequence can be continued to multiple lines by putting a
 `{\tt \verb+\+}' at the end of each line to be continued.
 %.pg
 Any line starting with ``{\tt AUTOPICKUP\verb+_+EXCEPTION=}'' 
 is taken as defining an exception to the ``{\tt pickup\verb+_+types}'' option.
 There is a section of this Guidebook that discusses that.
 %.pg
 The default name of the configuration file varies on different
 operating systems. On DOS and Windows, it is ``{\tt defaults.nh}''
 in the same folder as nethack.exe or nethackW.exe. On Unix, Linux
 and Mac OS X it is ``{\tt.nethackrc}'' in the user's home directory.
 NETHACKOPTIONS can also be set to the full name of a file you
 want to use (possibly preceded by an `{\tt @}').
 %.pg
 Here is a short example of config file contents:
 %.sd
 \begin{verbatim}
    # Set your character's role, race, gender, and alignment.
    OPTIONS=role:Valkyrie, race:Human, gender:female, align:lawful
    # Turn on autopickup, and set automatically picked up object types
    OPTIONS=autopickup,pickup_types:$"=/!?+
    # Show colored text if possible
    OPTIONS=color
    # Show lit corridors differently
    OPTIONS=lit_corridor
    # No startup splash screen. Windows GUI only.
    OPTIONS=!splash_screen
 \end{verbatim}
 %.ed
 %.hn 2
 \subsection*{Customization options}