Viewing VHIST Files

To open a VHIST file, select "Open" from the "File" menu and navigate to the according file. Alternatively, just drag the file from you file manager (e.g. Explorer on Windows, the Finder on Mac OS X) onto the dialog. vhistzard will read the VHIST file and present you with an outline of its content as well as detailed information about the files and sections.

To navigate inside a VHIST file, you can either use the outline on the left-hand side of the dialog or scroll through the textual information on the right-hand side. To jump to one special section or file, double click on the entry in the outline.

To extract one or several files from a VHIST file, select the files in the outline, right click on one of them and select "extract" in the context menu. In the following dialog, you can select a directory to store the files in,

You can use vhistzard to view the summary of your VHIST file by means of various templates ("themes"). Different templates show information in different granularties and present them in different ways. To select a template, click on the drop down list above the text viewer.

To search for text in the summary, either click on the search icon above the text viewer or press Ctrl+F. Then enter the search term in the appearing text field. You can press Return or Shift+Return to jump to the next or previous search result, respectively.

A template is a XHTML2 [1] file which can be viewed by any HTML browser. It usually contains keywords (e.g. $COMMENT) which will then be replaced by the corresponding content from the current VHIST file. See below for a list of keywords which will be available when the template is being read by vhistzard. User-defined attributes (workflow step) are prepended with $USR:: and converted to upper case, so for a key pair ("MyKey", "MyValue") the placeholder $USR::MYKEY will yield the value "MyValue". We strongly suggest to use the dump-all.htm template to generate a list of all available keywords for a give VHIST file before modifying a template. Keywords may contain alphanumerical characters, "_" and ":" (but not as the last character).

The template can provide additional information on how information from the VHIST file should be rendered in HTML (or PDF) which can depend on the existence or values of certain entries. In addition, it is possible to define blocks of arbitrary HTML commands and use them as building blocks if certain conditions are met. In order to remain HTML compatible, we use HTML/XML comments and evaluate them in our own parser.

For each section/workflow step of the VHIST file, the template will be processed with a set of keywords for that particular workflow step, so e.g. $SECTION will contain the current section's name. There are named blocks with reserved names: __top__ and __bottom_ are only evaluated once and __files__ is evaluated for each file (of each section/workflow step).

In order to provide maximum flexibility, you can access the properties of all files of a section from the template. Keywords such as $FILEPATH[3] are available which in this case will refer to the path of the third file of that section. If you write $FILEPATH[*] inside the files block, the "*" will match the current file's index.

Similiarities to the C/C++ preprocessor syntax are intended in the following list of commands for HTML/PDF generation:

• #ifdef $KEYWORD - If $KEYWORD has a value (has been set in the VHIST file) the next HTML block will be used, otherwise it will be skipped.
• #ifndef $KEYWORD - If $KEYWORD has a value (has been set in the VHIST file) the next HTML block will be skipped, otherwise it will be used.
• #ifequal $KEYWORD value - If $KEYWORD is equal to value, the next HTML block will be used, otherwise it wll be skipped.
• #else - May only be used in conjunction with one of the #if statements.
• #begin(<name>) - Defines the start position of a named block.
• #end(<name>) - Defines the end position of a named block.
• #showblock(<name>) - Inserts a named block at this position.
• #evenodd begin - Starts processing for $EVENODD keywords.
• #evenodd end - Ends processing for $EVENODD keywords.

In the following example, the first and last line are HTML/XML comments which will be ignored by any HTML browser. When used in a template, the second line will only be used for rendering HTML/PDF output if the keyword $COMMENT has been set (which is the case if the current section/workflow step files contains a comment).

<!– #ifdef $COMMENT –>
Comment: $COMMENT<br/>
<!– #endif –>

The next example demonstrates how to set content differently for HTML and for PDF generation

<!– #ifndef $ISPDFGEN –>
 this will only appear in the HTML version
<!– #else –>
 this will only appear in the PDF file
<!– #endif –>

The following special keywords are available (in alphabetical order):

• $EVENODD - Processing of $EVENODD is activated between occurances of #evenodd start and #evenodd end. The keyword will be replaced by the strings "odd" and "even", resp. These terms will be used in an alternating fashion, starting with "odd". This feature is generally useful when defining tables with rows that should have an alternating background color and it is required when the table's rows depend on some conditions which are not fully known when designing the table's layout. Template black-and-white.htm makes use of this feature.
• $FILEHASUSRATTRIBUTES[*] - Will be set to "TRUE" if any User-defined attributes (files) have been defined for the workflow step, otherwise this keyword is undefined. User-defined attributes can be accessed with keywords of the form $USR::MYKEY[*].
• $ISPDFGEN - Will be set to "TRUE" if content is generated for a PDF file, otherwise this keyword is undefined.
• $ISFIRSTSECTION - Will be set to "TRUE" if the current section is the first section of the output (either HTML or PDF), otherwise this keyword is undefined.
• $PREVIEWID[*] - Contains the ID of the current file's preview image if one was defined, see Pre-defined flags (files), otherwise this keyword is undefined.
• $THUMBNAILID[*] - Contains the ID of the current file's thumbnail image if one was defined, see Pre-defined flags (files), otherwise this keyword is undefined.
• $VHISTFILE - The file name (without the full path) of the selected VHIST file.
• $VHISTFILESIZEINBYTES - The size of the selected VHIST file in Bytes.
• $VHISTFILESIZEINMB - The size of the selected VHIST file in MB.
• $VHISTFILELASTMODIFIED - The last-modified-date of the VHIST file.
• $WSHASUSRATTRIBUTES - Will be set to "TRUE" if any User-defined attributes (workflow step) have been defined for the workflow step, otherwise this keyword is undefined. User-defined attributes can be accessed with keywords of the form $USR::MYKEY.
• $WSPREVIEWID - Contains the ID of the section's preview image if one was defined, see Pre-defined flags (files), otherwise this keyword is undefined.