Teamwork

As Wikis and Web 2 tools like Writely show often its not exactly one person working on a document - often it's a team. In PerlPoint, teamwork means you can compose a document out of parts that are documents by their own. The typical model is that every author in the team works on his parts and processes them with PerlPoint. Then in a second step, the several parts are included by a "master" document. The master document is a usual PerlPoint source with an \INCLUDE statement.

Here is a document that might be edited by a team member. It can be processed for itself. It does not need to be written a special way to be includable later on:

    =Wikis
  
    In the last few years wikis ... bla bla bla

This article is stored in wikis.pp

Now, this excellent article shall be integrated into a greater context. Another team member writes about recent trends in the Internet world, with a subchapter about collaboration.

    ===Collaborative Writing Techniqes
  
    Wikis, Web 2, bla bla bla ...

After this intro there is the place for the wiki article written by his co-author. To include it the following directive is sufficient:

    \INCLUDE{src="wikis.pp" type=pp headlinebase=CURRENT_LEVEL}

\INCLUDE takes another document and substitutes itself by its contents. The way this substitution is done depends on the type option. pp stands for " Perl Point" and means the file included should be treated as a PerlPoint source. As a result, the contents of this file is parsed and included as if it was written in the original source, instead of the \INCLUDE tag.

The src option specifies the file to include, the headlinebase option adds an offset to the headline levels of the document included. With CURRENT_LEVEL, the headline level of the chapter containing the \INCLUDE directive is used as an offset. In our example, this is level 3, so any level 1 headline in wikis.pp is moved to level 4 (1 plus offset 3), which makes them appear as subchapters of the including chapter.

    // this is how the document would look like
    // if it was written without \INCLUDE
  
    ===Collaborative Writing Techniqes
  
    Wikis, Web 2, bla bla bla ...
  
    ====Wikis
  
    In the last few years wikis ... bla bla bla

Likewise, BASE_CHAPTER adds the parent level of the including chapter, which makes included documents appear on the same level as the including chapter.

    // this is an illustration for inclusion
    // of the same document, but with BASE_LEVEL
  
    ===Collaborative Writing Techniqes
  
    Wikis, Web 2, bla bla bla ...
  
    ===Wikis
  
    In the last few years wikis ... bla bla bla

It is possible to set an absolute offset as in headlinebase=10, but this is not flexible and tends to fail when the document structure changes, so it is recommended to use CURRENT_LEVEL or BASE_LEVEL which adapt themselves.

As it is possible to use \INCLUDE in included files the level of source nesting is not limited. As a consequence a document can be split up in as many parts as required - for teamwork or modularization.