Source sections

The first type of conditionals manages complete document parts, including as many paragraphs as necessary. "Including paragraphs" means "complete paragraphs", it is not possible to make paragraph parts conditional this way. The reason for this is that this type uses special paragraphs to mark where the conditional part begins and ends. The prefix of these paragraphs is a question mark.

    bla bla bla
  
    ? 0
  
    Something that is never included.
  
    ? 1
  
    This part is included in any case.

The question mark is followed by a Perl expression. If the value of this expression is true, well, then PerlPoint continues to read the document. But if the expression returns a false value, all subsequent parts will be skipped until either a new condition paragraph appears or the file is read completely.

So in our example above, 0 of course evaluates to a false value, and so the next paragraph will never be processed. Then a second condition follows, and this time the condition evaluates to a true value. So, after this paragraph PerlPoint continues processing.

Condition paragraphs are only seen by PerlPoint itself. As they are just controlling translation, they do not appear in the results (HTML, XML or whatever).

Conditions of course can be more complex. They can be anything that is valid Perl code, but to get readable sources it is recommended to hide complexity in function calls, like here

     ? shouldWeIncludeTheFollowing()

The function can be declared in any other Active Contents part read before. A well working technique is to use \EMBED{lang=perl} for this. This tag starts a section of embedded Perl code which is evaulated only if Active Contents is enabled, and with the same rules. In our current context, one important rule is that all Active Contents code lives in the same namespace ( main:: from the codes point of view), so function definitions, package variables etc. can be shared.

Here is a definition of our "should-we-include-this" function:

     \EMBED{lang=perl}
  
     # declare a function for conditions
     sub shouldWeIncludeTheFollowing
      {
       1;
      }
  
     # supply an empty string as PerlPoint
     code to be processed
     '';
  
     \END_EMBED

I confess this is a rather simple function, but I think you get the point. Define whatever function you need, of your prefered complexity. An effective way to do this is to have a special file with all definitions etc. that should be used later on in conditions, and to include this file in all the documents that make use of it.

     // include code
     \INCLUDE{type=perl file="code.pp" smart=1}

Some functions of general use are provided without any definition. These are ...