inc

This function inc generates an ITP statement that post includes a document in the result document. The post-included text will appear as-is in the result document; it is included post the ITP process.

Note

This function must be called in the text mode of the model document, for this reason it must be used inside an @ ( ) construction.

@( inc ( post_include_document; path_to_the_post_include_document ) )

The result of this function is of type TEXT: the post-include statement itself. The construction @( ) places this text in the result document so it can be processed.

This function has two parameters.

1. post_include_document, type TEXT. The name of the document to be post-included. The extension of the document must be added as well. It's also possible to set the document with its complete path in this parameter in which case the second parameter can be left empty.
2. path_to_the_post_include_document, type TEXT. The path to the document to be post-included. This is either an UNC path or a path relative to the path set with the ITP/Workstation or ITP/Server Administrator. The path setting can be left empty if the path where the document can be found is exactly this configured path.

Including a part of a document

1. It's also possible to include a part of a document. To do so, the text that is to be included should be marked with a bookmark. The name of this bookmark has to be added to the document name (first parameter) when calling the function.
2. This functionality can only be used in Microsoft Wordand OpenOffice.org documents.

Lazy post-includes

Handling post-includes requires that the result document is processed in two steps. During the first step the document is scanned for include documents and during the second step these documents are inserted and the final result document is produced. The lazy post-include process scans the result document for includes generated with the @(inc(...)) construction. If these are not found during the first step, the final result document will be produced immediately, and the second step will be skipped. This will improve performance for documents that do not include external documents.

The lazy post-include process does not detect __INC(...) statements when it considers whether or not to perform the second step. Either replace these with the inc(...) function or disable the lazy post-include feature if your result documents do contain __INC(...) statements. If the result document contains includes inserted both by the @(inc(...)) construction and __INC(...) statements both these includes are processed. Lazy post-include is a runtime configuration setting of ITP/Workstation or ITP/Server. For more information on configuring this kind of settings, refer to the Help of one of these products.

Setting alternate documents or parts of documents

It's also possible to set one or more alternate documents (or parts of documents) that ITP will try to include if it fails including a document (or part of a document). In order to do so, the different documents/parts of documents have to be divided with a "|". ITP will try to include the first document (or part of a document). If this fails, ITP will try to include the next document (or part of a document) This process stops a soon as ITP succeeds in including a document (or a part of a document). The include process fails if none of the documents (of part of document) can be included.

This functionality can only be used in Microsoft Word documents and OpenOffice.org documents.

Example

@( inc( "document"; "folder" ) ) 
@( inc( "document<bookmark>"; "folder" ) ) 
@( inc("document1|document2"; "folder"))

Result:

__INC(folder\document) in the result document. This statement will be processed if post-including is enabled in the ITP configuration or when LAZYPOSTINC is set to Y, like it is in ITP/Server.

For WordPerfect this function usually generates native WordPerfect subdocument instructions. If however the postinclude mechanism is enabled in the configuration file, the inc( ) function will generate __INC statements in the WordPerfect result documents instead.

Post-include statements in result documents are also resolved by the put_in_document( ), put_in_text_file( ) and add_to_output( ) functions, when the fifth parameter of these functions is set to Y, regardless of the post-include configuration setting of ITP.