diff --git a/tconfpy.3 b/tconfpy.3 index 9409c7f..98b03ec 100644 --- a/tconfpy.3 +++ b/tconfpy.3 @@ -1696,12 +1696,93 @@ .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... +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 +One of the most powerful features of \*(TC is its "conditional +processing" capabilities. The general idea is to test some +condition and +.B include or exclude configuration information based on the outcome of the test. + +What's the point? You can build large, complex configurations that test things +like environment variables, one of the Predefined Variables, or even a variable +you've set previously in the configuration file. The resulting configuration is then +produced in a way that is appropriate for +.B that particular system, on that particular day, for that particular user, ... + +By using conditional directives, you can create a single configuration file that +works for every user regardless of operating system, location, and so on. + +There are two kinds of conditional directives. "Existential Conditionals" test to +see if a configuration or environment variable +.B exists. +Existential Conditionals pay no attention to the +.B value +of the variables in question, merely whether or not those variables have been defined. + +"Comparison Conditionals" actually +.B compare +two strings. Typically, one or more variable references appear in the compared strings. +In this case, the +.B value of the variable +is important. + +The general structure of any conditional looks like this: + +.nf + ConditionalDirective Argument(s) + + This is included if the conditional was True + + .else # Optional + + This is included if the conditional was False + + .endif # Required +.fi + +Except for the whitespace after the conditional directive itself, whitespace is not +significant. You may indent as you wish. + +Conditionals may also be "nested". You can have a conditional within another conditional +or \'.else\' block: + +.nf + + ConditionalDirective Argument(s) + stuff + + ConditionalDirective Argument(s) + more stuff + .endif + + .else + ConditionalDirective Argument(s) + other stuff + .endif + .endif +.fi + +There are no explicit limits to how deeply you can nest a configuration. However, +you must have an \'.endif\' that terminates each conditional test. Bear in mind that +\*(TC pays no attention to your indentation. It associates an \'.endif\' +.B with the last conditional it encountered. +That's why it's a really good idea to use some consistent indentation style so +.B you +can understand the logical structure of the conditions. It's also a +good idea to put comments throughout such conditional blocks so it's +clear what is going on. + +.SS Existential Conditionals + + +.SS Comparison Conditionals + + .SS The \'.literal\. Directive .SH ADVANCED TOPICS