diff --git a/twander.1 b/twander.1 index f007246..5dc0025 100644 --- a/twander.1 +++ b/twander.1 @@ -1158,6 +1158,7 @@ Wildcard Statements Variables And Command Definitions Conditional Processing Statements +The Include Directive .fi (See the ".twander" file provided with the program distribution @@ -1939,11 +1940,6 @@ .fi .IP \(bu 4 -A given Directory Shortcut can only be defined once. An attempt -to redefine it will cause a warning message to appear, and the -second instance of the definition to be ignored. - -.IP \(bu 4 All defined Directory Shortcut paths are also automatically inserted into the Directory Menu at program startup (or \*(CF reload) whether or not you've actually @@ -2230,8 +2226,9 @@ Command Keys are case-sensitive. If "m" is used as a Command Key, "M" will not invoke that command. Command Keys must be unique within a given \*(CF. If \*(TW finds multiple Command -Definitions assigned to the same Command Key, it will warn you and -ignore everything except the first definition. A Command Key can +Definitions assigned to the same Command Key, it will associate the +.B last +definition it finds with that Command Key. A Command Key can never be "#" which is always understood to be the beginning of a comment. @@ -2673,11 +2670,79 @@ .P See the example ".twander" file provided in the distribution for some -extended examples of using conditinals in your Configuration File. +extended examples of using conditionals in your Configuration File. Also see the .B GOTCHAS section below for further discussion. +.SS The Include Directive + +You may include other files in your \*(CF with the following +directive: + +.nf +\&.include path-to-file +.fi + +You may place as many of these statements in your \*(CF as you wish. +The only syntactic requirement is that there must be whitespace +between the directive and the file path. \*(TW makes no attempt +to validate that path, and you will see an warning message if the +file you specify cannot be opened. + +The most common reason to do this is to maintain a "standard" +configuration in a separate file which is controlled by the system +administrator. This is especially handy on larger systems with +multiple users. The system administrator provides a read-only copy of +the standard configuration in a place anyone can read it. Everyone is +free to use (but not modify) that standard configuration. You are +then free to add to, or even override the standard configuration +content with statements of your own following the ".include". Suppose +you have the following "standard" configuration file available on your +system: + +.nf +# Contents of /usr/local/etc/.twander.global + +SHELL = bash -c +XTERM = xterm -fn 9x15 -l +VSHELL = [XTERM] -e [SHELL] + +DIRSC1 = /usr/local +DIRSC2 = /usr/sbin + +t terminal [XTERM] +.fi + + +Now, you can create your own personal \*(CF which takes advantage +of this standard file, but augments it with additional configuration +information of your choosing: + +.nf +# Contents of $HOME/.twander + +\&.include /usr/local/etc/.twander.global + +DIRSC2 = /etc + +l ls [VSHELL] 'ls -al | [$PAGER]' +.fi + + +Keep in mind that \*(TW reads the contents of its \*(CF +.B in order. +In this case, it means that all of "/usr/local/etc/.twander.global" +is read and +.B then +the rest of "$HOME/.twander" is read. If something is defined more +than once, the +.B last definition +is what is used. In this case, DIRSC2 is overriden in the local +\*(CF and is ultimately assigned to "/etc". Similarly, you +can override previous definitions for User-Defined Variables +and even Command Definitions. + .SH ADVANCED WIN32 FEATURES @@ -3191,6 +3256,32 @@ \&.if [CondVar] .... \&.endif +.fi + +.IP \(bu 4 +You have to be careful when overriding variable or command +definitions. User-Defined Variables referenced in +a Command Definition are de-referenced +.B at the time the Command Definition is encountered in the \*(CF. +This means that if you change a User-Defined Variable after +it has already been used in a Command Definition, only +future references to that variable will reflect the change: + +.nf +FOO = bar + +x cmd1 command [FOO] + +FOO = baz + +y cmd2 command [FOO] +.fi + +In this example, the first command will be defined as "command bar", +but the second will be defined as "command baz". + +Watch for this, especially, when using the ".include" directive +and then overriding a variable defined in that file. .P Common mistakes include: