diff --git a/tconfpy.3 b/tconfpy.3 index 081638c..499930c 100644 --- a/tconfpy.3 +++ b/tconfpy.3 @@ -2452,6 +2452,14 @@ .fi .ft \" revert +As a practical matter, unless you actually need to do comparisons involving +\fC"True"\fP and \fC"False"\fP strings, it is best to use the Existential Conditionals +to test the +.B state +of a boolean variable. See the section entitled, +.B Existential Conditionals And Booleans +below, for the details. + .SS The \fC.include\fP Directive @@ -2769,6 +2777,112 @@ defined appropriate for the currently defined terminal, for instance. +.SS Existential Conditionals And Booleans + +As we've just seen, \fC.ifall/any/none\fP check to see if the +variables named on the Right Hand Side "exist". This is true +for all kinds of variables, regardless of their type. For instance: + +.ft C \" Courier +.nf + .ifall Boolean1 Boolean2 + ... + .endif + + Foo = Boolean3 + + .ifall [Foo] + ... + .endif +.fi +.ft \" revert + +The first conditional will be \fCTrue\fP only if both variables, +\fCBoolean1\fP and \fCBoolean2\fP exist. Similarly, the second +conditional will be \fCTrue\fP only if \fCBoolean3\fP exists. + +However, when using indirection on a boolean variable (i.e. A variable +that has been pre-defined to be a boolean type by the calling program), +.B the state of the boolean is returned. +For example: + +.ft C \" Courier +.nf + .ifall [Boolean1] [Boolean2] + ... + .endif +.fi +.ft \" revert + +In this case, the \fC[Boolean..]\fP indirection is understood to mean, +"Return the logical state of the boolean variable in question". This +allows the existential conditionals to act like +.B logical +operators when their targets are boolean. In the example above, +the test will only be True if both booleans are logically True. + +You can even mix and match: + +.ft C \" Courier +.nf + .ifall Boolean1 [Boolean2] + ... + .endif +.fi +.ft \" revert + + +This conditional will be \fCTrue\fP only if \fCBoolean1\fP +.B exists +and \fCBoolean2\fP is \fCTrue\fP. + +It's worth mentioning just +.B why +the semantics of indirect boolean references are different than for +other variable types. If booleans were treated the same as other +variables, then \fC[Boolean]\fP would return a string representation +of the boolean variable's state - i.e., It would return \fC"True"\fP +or \fC"False"\fP. In effect, we would be doing this: + +.ft C \" Courier +.nf + .ifall/any/none True False True True False ... +.fi +.ft \" revert + +This more-or-less makes no sense, since we're checking to see if +variables named "True" and "False" exist. What +.B does +make a lot of sense is to use the state of a boolean variable to drive +the conditional logic. + +There is one other reason this feature is provided. Earlier versions +of \fCtconfpy\fP did not have this feature - booleans were treated +like any other variable. This meant that doing logical tests on the state +of the boolean required a kind of tortuous construct using the Comparsion +Conditionals (described in the next section): + +.ft C \" Courier +.nf + # Example of AND logic using Comparison Conditional + + .if [Bool1][Bool2][Bool3] == TrueTrueTrue + ... + .endif +.fi +.ft \" revert + +This is ugly, hard to read, and hard to maintain. By contrast, the +method just described allows booleans to be used in their intended +manner - to make logical choices. \fC.ifall\fP becomes a logical +"AND" function. \fC.ifany\fP becomes a logical "OR" function, and +\fC.ifnone\fP becomes a logical "NOR" function when these tests are +applied to indirect boolean references. + +Both methods of testing boolean state remain supported, so you can use +the style most appropriate for your application. + + .SS Comparison Conditional Directives There are two Comparison Conditionals: @@ -3373,4 +3487,4 @@ .ft \" revert .SH DOCUMENT REVISION INFORMATION -$Id: tconfpy.3,v 1.158 2005/01/20 08:42:34 tundra Exp $ +$Id: tconfpy.3,v 1.159 2005/01/20 09:32:57 tundra Exp $