diff --git a/tconfpy.3 b/tconfpy.3 index ba908aa..9409c7f 100644 --- a/tconfpy.3 +++ b/tconfpy.3 @@ -1639,6 +1639,67 @@ .SS The \'.include\' Directive +At any point in a configuration file, you can "include" another configuration file +like this: + +.nf + .include filename +.fi + +In fact, you can use all the variable substitution and string concatenation features we've +already discussed to do this symbolically: + +.nf + Base = MyConfig + Ver = 1.01 + + .include [Base]-[Ver].cfg +.fi + +The whitespace after the \'.include\' directive is mandatory to separate it from +the file name. You can have as many \'.include\' statements in your configuration file +as you wish, and they may appear anywhere. The only restriction is that they must +appear on a line by themselves (with an optional comment). + +Why bother? There are several reasons: + +.IP \(bu 4 +This makes it easy to break up large, complex configurations into simpler (smaller) +pieces. + +.IP \(bu 4 +This makes is easy to "factor" common configuration information into separate +files which can then be used by different programs as needed. + +.IP \(bu 4 +But the most common use for \'.include\' is to load a "standard" configuration for +your program. Recall that the last assignment of a variable's value "wins". +Suppose you want all the standard settings for a program, but you just want to +change one or two options. Instead of requiring each user to have the whole +set of standard settings in their own configuration file, the system administrator +can make them available as a common configuration. Each user \'.include\'s +that file and then overrides any options they like: + +.nf + # Get the standard options + .include /usr/local/etc/MyAppStandardConfig.cfg + + # Override the ones you like + ScreenColor = Blue + Currency = Euros +.fi + +This makes maintenance of complex configuration files +.B much +simpler. There is only one master copy of the configuration that needs to be +edited when system-wide changes are required. + +.P + +One last thing needs to be noted here. \*(TC does not detect so-called "circular" +inclusions. If file \'a\' \'.include\'s file \'b\' and file \'b\' \'.include\'s file \'a\', you will +have an infinite loop of inclusion, which, uh, is a Bad Thing... + .SS Conditional Directives .SS The \'.literal\. Directive