Embedding text files as examples

The usual way for an example is to write it as a block (parsed) or a verbatim paragraph (which is not parsed), like so

    Look at this example:
  
      This is a \I<parsed> example.
  
    <<EOE
  
      This example is not parsed.
  
    EOE

This way, examples are "inlined" - they are part of your PerlPoint file, which is sufficient in most cases.

Let's say you are a developer describing code. You can copy examples from your sources and paste them into (verbatim) blocks. This has the advantage that your examples do not change when the original code is evolved, which could cause it to differ from what you described in your document.

On the other hand, if you want to show up to date code, with inlined examples you need to update your PerlPoint source each time before producing your document, in order to include the latest source code version. But this can be automated: the \INCLUDE tag offers to import examples from a file.

To import a file as an example, set the type of \INCLUDE to example or parsedexample. Now when your source is processed, the file is loaded and its content is tranformed into a verbatim block with example, or into a standard block with parsedexample. As the option values indicate standard blocks are parsed as PerlPoint, e.g. to resolve tags, while verbatim blocks are taken as they are.

Here is, well, an example:

    \INCLUDE{type=example file="example.pl"}

This would integrate the contents of example.pl as a verbatim block. Likewise

    \INCLUDE{type=parsedexample file="example.pl"}

would include it as a standard block, so that embedded tags can be found. This might not sound useful, as your code is just code, and not PerlPoint, and is taken as it is - but it makes sense for things like automatic hightlightning with paragraph filters.

Please note that while example blocks are usually indented, neither the include directive nor the imported examples do need an indentation.

The content taken from an example file is usually included as it is, but it is possible to indent it by adding option indent. The value of this option should be a positive integer, configuring how many spaces should be added in front of each line.

    \INCLUDE{type=parsedexample indent=5 file="example.pl"}