The Document Factory

This section illustrates the features of the Document Factory component. The component is a separate BSCW extension package which may not be activated on your BSCW system.

1 Introduction
2 Basic Concepts
3 Document Set
4 Entities
5 Templates
6 Functions
7 Using the Document Factory

1 Introduction

The Document Factory facilitates a comfortable management of document sets which need to be continually revised and periodically published. Based on hierarchically structured templates, documents within such document sets can be automatically created by an evaluation process using the templates. The Document Factory can thereby help to reduce redundancies and to achieve a consistent structure or layout of the documents. The Document Factory provides also an "Export" function which may be invoked to transfer documents within such a document set to an FTP server. The Document Factory is particularly useful for - but not restricted to - Web Site management.

2 Basic Concepts

The Document Factory is based on the following concepts:

BSCW Document Set: The BSCW Document Set (or Document Set for short) is a special folder which provides the specific action "Evaluate" and has specific attributes, the BSCW entities (see below). In general, it also contains special documents, the BSCW Templates. If a BSCW Document Set folder contains folders, these folders inherit the "Evaluate" action and also the feature to specify BSCW entities.
BSCW Template: A BSCW Template (or Template for short) is a template for the creation of a document in a Document Set. A template usually consists of text in which references to BSCW Entities or references to other BSCW Templates are imbedded. There are two classes of BSCW Templates: templates of the first class create directly a document during the evaluation process (see below); templates of the second class contribute indirectly to the creation of a document because they are referenced from other templates.
BSCW Entity: A BSCW Entity (or Entity for short) is a variable which can be used within the templates of a document set. Such a variable can be a short term like a name, a directory path or version number. It may be also be a text section to be used as a headline, a paragraph or even the complete text of a web page. BSCW Entities are defined within templates or as attributes of a Documents Set or of folders contained in a Document Set.
Functions: Templates or entity definitions may also contain calls of a few functions where the result of the function call is a text string. For example, the size of a document can be automatically inserted in a document during the evaluation process by a calling the function which returns the file size as a text string.
Evaluation Process: An evaluation process can be applied to the objects contained in a Document Set. In general, one or more documents are created by the evaluation process by taking one or more templates and replacing references to entities or other templates and function calls by their respective values, possibly recursively until all references and function calls are resolved.

3 Document Set

A BSCW Document set is created by selecting the menu entry [ File - New - Document Set ]. A Document Set is represented by the icon. Since a Document Set is similar to a folder, folders (and recursively sub-folders within these folders) may be created within a Document Set. A Document Set also contains BSCW Templates which a user puts into the Document Set or into folders within the Document Set.

During the evaluation process, new documents - as specified by the evaluation parameters "document" (see below) - are created which are automatically inserted into the Document Set or into folders within the Document Set.

4 Entities

Entities are variables within a Document Set. They always have a name and a value. The name consists of a string of alphanumeric characters (a ... z, A ... Z, 0 ... 9). The value is any character string which may also contain references to other entities.

Entities can be defined at a Document Set, at folders within a Document Set, or in templates within the Document Set.

4.1 Entity definition for a Document Set or folder

For a Document Set or a folder entities are defined by selecting the menu entry [ - Entities] and then filling a form with the name and value of the entity.

4.2 Entity definition in Templates

Within templates, entities are defined with the notation

<entity name="name of entity">
value of entity
</entity>

4.3 Entity references

Entities are references with the notation

&(name of entity);

References can be made within templates or within entity definitions for a Document Set or a folder.

4.4 Scope of entity definitions

Entities defined at the Document Set can be referenced anywhere from folders or in templates within the Document Set and its folders. Entities defined at a specific folder of the Document Set can be referenced anywhere from folders or in templates subordinate to this folders, i.e., the scope of entities definitions follows the folder hierarchy. Existing entity definitions can be replaced (overridden) by new definitions at subordinate folders or within templates.

5 Templates

A template is a document of type Document Template (text/x-bscw-template). Such a document should be created with a normal ASCII text editor (e.g.., with MS Windows Notepad), not with a document processing system such as MS Word. When uploading a template document into a Document Set, the Mime Type text/x-bscw-template has to be specified. Otherwise the evaluation process does not recognize the document as a template.

It is recommended to use an extension such as '.dtm' for documents of type BSCW Template so they can easily be identified within folder listings by their names. A template is represented by the icon .

There are two classes of BSCW Templates: templates of the first class create directly a document during the evaluation process. A template belongs to this class if the evaluation parameter "document" is specified for the template.

Templates of the second class contribute indirectly to the creation of a document because they are referenced from other templates. A template belongs to this class if the evaluation parameter "document" is missing.

Besides the evaluation parameter "document" there exists also the evaluation parameter "template". Both evaluation parameters specify file names within the Document Set.

The following rules apply during the evaluation process:

5.1 Evaluation parameter "document" specified for a template X

In this case the evaluation process will evaluate template X and create a document with the name specified by the parameter "document". In this case, the template consists, in general, out of text and entity references which are resolved from the evaluation process before the document is inserted into the Document Set.

5.2 Evaluation parameters "document" and "template" specified for template X

In this case the evaluation process will evaluate the template specified by the parameter "template" and create a document with the name specified by the parameter "document". During the evaluation process, the entity definitions of template X are used. In this case, the template consists, in general, out of entity definitions, which are inserted into the template specified by the parameter "template" from the evaluation process before the document is inserted into the Document Set.

5.3 No evaluation parameter specified for a template X

In this case the evaluation process will evaluate template X. The name of the document to be created is specified within another template via the parameter "document" and template X is referenced by another template via the parameter "template" (see preceding case 5.2).

5.4 Evaluation parameter "template" specified for a template X

In this case the evaluation process will evaluate the template specified by the parameter "template" (see case 2. above). Template X is referenced by another template via the evaluation parameter "template" (see preceding case 5.2), i.e., at least three templates are involved in the evaluation process. The name of the document to be created is specified within another template via the parameter "document".

5.5 Nested Templates

Templates can have references to other templates, i.e., a template can be used by several other templates. A reference to a template is denoted by the following notation :

#(name of template)#

During the evaluation process the reference to a template will be replaced by the actual text of the template. The reference to a template may also contain path information to locate the template in the folder hierarchy of the document set. Path names are considered relative to the location of the including template. Templates defining entities can also be included in another template. In this case the result of the evaluation process will be inserted (see case 5.4)

With

#(name of template, name of combined template)#

one can define the combined template at the point of inclusion. In this way templates defining entities can be included in various contexts by other templates.

Template names may contain the wildcards '*' and '?'. In this case all templates that match the pattern will be included consecutively.

For example:

#(&(content_dir);/faq/questions*.dtm, &(template_dir);/faq.dtm)#

In this case, all templates which are found in the directory &(content_dir);/faq and whose name matches the pattern question*.dtm will be included and combined with the template &(template_dir);/faq.dtm.

6 Functions

To insert some environment values during the evaluation process, the document factory provides several functions that can be used in entities or templates:

&base(file name); removes path information and the extension from the file name, e.g.:

&base(/home/bscw/www/faq.bht); -> faq

&rel(path);

generates a relative pathname out of an absolute one in dependency of the document that should be generated, e.g.:

If one uses &rel(/Images); in a template, that generates the document /faq/index.htm, it is evaluated to ../Images. If one use it in a template, that generates the document /faq/question/install.htm, it is evaluated to ../../Images.

&size(file name, [B|K|M|G]);

'file name'

&size(/Download/bscw34.exe, M); -> 8.43

&date(format);

insert the local time. The following directives can be embedded in the format string. They are shown without the optional field width and precision specification:

Directive	Meaning
`%a`	Locale's abbreviated weekday name.
`%A`	Locale's full weekday name.
`%b`	Locale's abbreviated month name.
`%B`	Locale's full month name.
`%c`	Locale's appropriate date and time representation.
`%d`	Day of the month as a decimal number [01,31].
`%H`	Hour (24-hour clock) as a decimal number [00,23].
`%I`	Hour (12-hour clock) as a decimal number [01,12].
`%j`	Day of the year as a decimal number [001,366].
`%m`	Month as a decimal number [01,12].
`%M`	Minute as a decimal number [00,59].
`%p`	Locale's equivalent of either AM or PM.
`%S`	Second as a decimal number [00,61].
`%U`	Week number of the year (Sunday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Sunday are considered to be in week 0.
`%w`	Weekday as a decimal number [0(Sunday),6].
`%W`	Week number of the year (Monday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Sunday are considered to be in week 0.
`%x`	Locale's appropriate date representation.
`%X`	Locale's appropriate time representation.
`%y`	Year without century as a decimal number [00,99].
`%Y`	Year with century as a decimal number.
`%Z`	Time zone name (or by no characters if no time zone exists).
`%%`	A literal "`%`" character.

E.g.:

&date(%M %Y); -> September 2001

7 Using the Document Factory

To start with the document factory you have to add a new Document Set with the menu item [ File - New - Document Set ]. There you have to give a name for the new document set and optionally a description.

To set entities in the folder hierarchy of a document set use the menu item [ - Entities ]. You can specify the name and the value for a new entity or change an old one. If name field remains empty, the entities will be removed.

At templates, i.e. documents of type Document Template (text/x-bscw-template), you set the evaluation parameter with the menu item [ - Eval Parameter ]. This lets you define a template name, with which this template is combined and a document name, if the template should result in a document. Internally the evaluation parameter are entities with the name @template@ respectively @document@.

To show all entities at a folder or a template use [ - Show Entities ]. If a name is in italic it is inherit through the directory structure.

The operation | evaluate | resp. [ - Evaluate ] starts the evaluation process on the selected objects.

For a backup of a document set you can save all entities with [ - Export Entities ]. This generates a file with the following syntax and save it to your local machine:

<object path>' = {
<entity name>' : '<entity value>',
...
}
...

With the menu item [ - Import Entities ] you can import such backups of the entities.