The <read/> command

This command is used when you need to read external files that are not explicitly mentioned in the document content. for example, you may need to include a set of standard warnings or disclaimers at the beginning of a document. Alternatively, the name of the file to be included may have to be generated, rather than being declared explicitly.

To read the content of an external file into your document at the current location use the command:

<read file="NAME"/>

where NAME is the full pathname of the file to be read. You may use either forward or backslashes to delineate the path folders.

It is the user's responsibility to ensure that the included material is compatible with the current document. The content of an external file is assumed to be a well formed document.

Reading an external file that may or may not exist

By default, TopLeaf will report an error if the file referenced from a read directive does not exist. In some circumstances, you may want to include the content of an arbitrary external file, but not report an error if the file does not exist. If so, use the command:

<read file="NAME" if-exists="yes" />

where NAME is the full pathname of the file to be read. If the file exists, it will be included within your document at the current location. If the file does not exist, no further action will be taken by this command.

This option can also be used with the <read /> directive option once-only.

Avoiding multiple reads of the same file

By default, TopLeaf will always attempt to honor a <read /> request to include the content of an external file. In some style sheets, however, a number of mappings may independently specify a request to read the content of a file, but it is only necessary to read the file once. To read a file once, use the following command:

<read file="NAME" once-only="yes" />

This option can also be used with the <read /> directive option if-exists.

Reading part of a file

If the command has the form:

<read file="NAME" use-fragment="yes" />

the NAME will be tested to see if it ends with #ID. If it does, the value of ID will be used to locate an element in the document with a matching id attribute. If such an element is found, it is used as the result of the read command.

Generating a PDF page list

TopLeaf provides a simple method to generate an XML page list description for any PDF document. You can use the generated page list and standard tag mappings to create a placeholder page for each PDF page imported into the current document.

To read a PDF document and automatically generate an XML page list description into your document at the current location use the command:

<read file="PDF_FILENAME" />

where PDF_FILENAME is the full pathname of the PDF file to be read.