ZptBuilder.exe manual

 

NAME

ZptBuilder.exe - parse and render Zope Page Templates documents  

SYNOPSIS

ZptBuilder.exe [options] [inputs]  

DESCRIPTION

The ZptBuilder application is used to parse and render documents formatted as Zope Page Templates source files, into either HTML or XML output documents. The inputs may be one or more file or directory paths, indicating the files and/or directories to be parsed and rendered.

Alternatively, if the only input is - (a single minus-dash) then the application will expect a single ZPT document to be passed via STDIN. Input passed via standard input is treated and rendered as HTML, unless the --xml option is used.

Where directory paths are specified amongst the input, then that directory (and all child directories) will be searched for matching documents to be rendered. This search is controlled by the mode (HTML or XML) and the options --input-filename-pattern and --ignore.

By default, rendered output is emitted to standard output; this behaviour may be overridden, writing the output to file(s) using the --output option. When directory paths are specified as inputs and the --output option is used, each output file is saved to a path relative to the output path, based on its relative path from the input directory.  

OPTIONS

--help,-h

Prints a usage statement and exits.

--version

Prints version information and exits.

--html,-t

Sets the application to work in HTML mode; all inputs will be treated and rendered as HTML files. The default behaviour is to use the input file's extension to determine the file type: .pt for HTML files or .xml for XML files.

--xml,-x

Sets the application to work in XML mode; all inputs will be treated and rendered as XML files. The default behaviour is to use the input file's extension to determine the file type: .pt for HTML files or .xml for XML files.

--annotate

Enables source annotation; causes comments to be generated and added to the rendered output annotating information about the source files used. A comment is generated each time the rendered output switches context to use a different piece of the source file, such as when METAL macros or slots are used.

--no-xml-declaration

Omits the <?xml?> declaration from the output when rendering XML inputs. Has no effect for inputs treated as HTML.

--input-filename-pattern=PATTERN,-p

Sets a glob pattern for matching input files when directory path(s) are provided amongst the input, by default this is set to "*.pt". Note that this default value will mean that the only input files matched will be treated as HTML files.

--output=PATH,-o

Sets the application to emit output to the filesystem, instead of using standard output. If the path indicates a single file then all output is redirected to that file. In this case, the file will be created if it does not already exist, as long as its parent directory exists.

If the path to a directory is specified then each rendered document will be rendered to a separate file within the output directory. In this case, the output directory path must exist or else an error will be raised. Where a directory path is used, the names of the created files are based upon the name of the input files; the option --output-filename-extension controls their extension. Additionally, if a directory path is used for the input, then the output files are created using a directory structure mimicking the relative path from the input directory. Consider the following:

ZptBuilder.exe --output=my-out-dir/ my-input-dir

A file at the path my-input-dir/foo/bar/baz.pt would be rendered and output to the path my-out-dir/foo/bar/baz.html. Thus, the relative directory structure within an input directory of files to render is preserved in the output.

--output-filename-extension=EXT,-e

Controls the file extension of the file outputs, when the --output option is used with a directory path. By default this is either .html or .xml based upon how the input file is treated. Has no effect when the output is sent to a single file or if the output is rendered to standard output.

--ignore=PATH,-i

When a directory path is amongst the inputs, causes the named path (or paths, separated by semicolons) to be ignored from the search. Ignored paths (which may be file or directory paths) will not be rendered. Has no effect when the input does not contain any directory paths.

--keyword-options=KEY_VALUE_PAIRS

Provides keyword options for the rendering application. This is a semicolon-separated list of key/value pairs to be provided to the root TALES context as keyword options. This should be provided in the format "keyone=valueone;keytwo=valuetwo" and so on.

--rendering-context-factory=CLASS

Where provided, overrides the default implementation of CSF.Zpt.Rendering.IRenderingContextFactory to use when rendering pages. This must be a full, assembly-qualified type name where provided.

--output-encoding=ENCODING,-n

Sets the text encoding to use for the output(s). By default the UTF-8 encoding is used. Any encoding 'web name' may be specified here.

--context-visitors=CLASSES

Where provided, overrides the default implementations of CSF.Zpt.Rendering.IContextVisitor to use when rendering pages. This is an ordered list of type names, separated by semicolons. These names must be full, assembly-qualified type names where provided.

--quiet,-q

Disables all application output (to standard error) except for fatal unexpected errors (application crashes). Usually, the count of documents rendered by the application is sent to the console, along with a list of documents which failed to render. This has no effect upon documents rendered to standard output, when specified by --output. This flag takes precedence should --verbose also be specified.

--verbose,-v

Sends a list of the documents which were successfully rendered to standard error, in addition to the default application output. This flag is only useful when --quiet is not specified.

 

FILES

ZptBuilder.exe.config

This is the configuration file used by the ZptBuilder.exe application. It is used for configuring the plugin assemblies loaded, and also for configuring diagnostic logging/tracing.

There are comments in the configuration file illustrating sample configuration. This sample configuration demonstrates both how to enable the default plugins and also how to enable logging of rendering operations.

Plugins (various files)

ZPT-Sharp, and with it the ZptBuilder.exe application, makes use of a plugin architecture. The plugin architecture is used for parsing and rendering of document types (such as HTML or XML) and also for the evaluation of TALES expressions.

The ZptBuilder.exe application will not be very useful if no plugins are installed. Consequently, a few plugins - which provide the standard ZPT functionality - are installed by default. Plugins are distributed as separate DLL assembly files. To install them, place them into a directory of your choosing and add relevant configuration to the configuration file. This will include, at a minimum, the path to each plugin assembly. If you wish to set/change the default document providers or to change the default TALES expression evaluator then this may also be achieved in the configuration file.

 

SEE ALSO

ZptBuilder.exe.config (5)

Information about the configuration syntax