FlexDoc/XML - Generator

Output Formats

Because the Template Processor simultaneously acts as both the template interpreter and the output generator, its generic part is extended into several implementations targeted to one of the following currently supported output format:

HTML
RTF
TXT (plain text)

Which particular output format will be used is specified either:

Via the generator.config, which is edited using the generator GUI. In particular, the output format is specified in the «Output format» combo-box.
Using the -format option on the generator Java command line.

What are Output Format Options?

Output format options are those generator settings that are handled by the generator itself (its Java-hardcoded part) and relevant only to the selected output format. Most of them are not accessible in templates. However, in other respects format options are similar to template parameters.

All format options can be specified/edited in the generator GUI using the Format Option Inspector:

Finding the formatting option name in the Option Inspector

It is organized very similarly to the Template Parameter Inspector and invoked by «Options» button in the Generator Dialog. Then, the edited option values are stored the generator.config file.

Alternatively, any output format option can be specified directly on the command-line by its internal name with the -o option. The option internal name can be found in the Option Inspector. Just find that option in it and select. The internal name (also called simply Option Name) will be visible at the top of the bottom «Option Description» panel:

For example:

-o:html.output.css.namedRules.customRuleFile=C:\flexdoc-xml\XSDDoc\templates\css\azure-theme.css
or: -o:html.output.css.namedRules.customRuleFile "C:\flexdoc-xml\XSDDoc\templates\css\azure-theme.css"

HTML Output

HTML Options

When in the Generator Dialog you select HTML output format and click «Options» button, you will see the following HTML Option Inspector dialog (click on the screenshot to see the corresponding option description):

HTML Option Inspector

The descriptions of HTML options (the default option values are underlined):

Option Name / Type / Description

Output The options to control various properties of the generated HTML output as a whole.

Markup

html.output.markup : enum {"html401", "xhtml1"}

Specify the (X)HTML markup version of the generated output.

Possible Choices:

"HTML 4.01"

This is the default setting. The output files will be generally compatible with one of these Doctypes:

HTML 4.01 Transitional
HTML 4.01 Frameset

The incompatibility may come from the HTML markup found in the text coming from the data source (e.g. doc-comments). To fix the syntax errors (like missing closing tags) automatically, you can use the option: Text | Render Embedded HTML | Fix markup

"XHTML 1.0"

The output files will be generated according to one of the Doctypes:

XHTML 1.0 Transitional
XHTML 1.0 Frameset

This format also implies the mandatory/default settings for the following options:

Output | Add charset = true.
The charset must always be specified in XHTML.
Text | Render Embedded HTML | Fix markup = true (default).
If HTML markup embedded in input text is allowed to format the generated output, then, in the case of XHTML output it must be parsed and converted into XHTML too (e.g. simple tags must have proper XML endings "/>"). That means, any inconsistencies found in the embedded HTML (e.g. a missing closing tag) will be fixed on the way.

Charset

html.output.charset : string

Specifies the character set (encoding) of the generated HTML files. The name should be a preferred MIME name (canonical name) as given in the IANA Registry.

The default charset is UTF-8.

If the charset name is specified as empty (blank), the Java machine's default charset will be used.

Add charset

html.output.charset.add : boolean {true, false}

Specifies whether to insert the charset declaration in the generated HTML files. The charset name will be obtained from the option: Output | Charset

For example, when this option is selected (true) and the value of the "Charset" option is "ISO-8859-1", the following line will be inserted in the head of every generated HTML document:

<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">

Suppress timestamp

html.output.noTimeStamp : boolean {true, false}

Specifies whether to suppress the date/time information included in a special comment inserted automatically at the beginning of every generated HTML file, which looks as follows:

When this option is selected (true), such a comment is still inserted, however without the current date/time:

Besides affecting the automatic HTML comment, this option is also passed to templates via 'output.noTimeStamp' property available in FlexQuery expressions. So, if a template is programmed to display the generation's date/time on some page, it may suppress that as well, according to the setting of this option.

You may want to avoid getting the current date/time into the generated doc files, when you frequently upload them to some repository, which stores only changes of files against their previous versions. If your docs actually do not change, this will prevent the repository from storing unnecessary information.

HTML pattern file

html.output.documentPatternFile : file pathname

This option allows you to frame the output generated by FlexDoc into your own HTML file. This may be useful when you need to insert into the generated HTML some extra lines with special settings.

To do this, you will need to prepare a special HTML pattern file with the content as follows:


<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">

<html>

<head>

  <!-- a custom style sheet -->

  <link href="${flexdoc-doc-root}/mystyle.css" rel="stylesheet" type="text/css">

  ...

  <!-- flexdoc-html-head -->

</head>

<body>

  <!-- flexdoc-html-body -->

</body>

</html>

The lines:


<!-- flexdoc-html-head -->

<!-- flexdoc-html-body -->

are obligatory because they are replaced with the actual HTML head and body blocks generated by FlexDoc.

Anything else is up to you to fill in. Just make sure your markup is valid HTML or XHTML (if you selected one; see the option: Output | Markup).

You may also use a few macros expanded to the values provided by FlexDoc:

Macro Description

${flexdoc-doc-root}

Expanded to the relative pathname leading from the given HTML file to the documentation root directory.

This macro will allow you, for instance, to specify your custom CSS file, which you can place in the documentation root and use it to format the HTML markup embedded in your descriptions/annotations.

A different possibility to add your custom styles is via the CSS pattern file. See the option: Output | CSS | Generate style sheet file | CSS pattern file.

${flexdoc-encoding}

Expanded to the name of the character set used in the generated HTML document (e.g. UTF-8). It is the same as specified with the option: Output | Charset. This macro may be useful particularly in case of XHTML to specify the XML declaration in your HTML pattern file, e.g.:

<?xml version="1.0" encoding="${flexdoc-encoding}"?>

Once your HTML pattern file is ready, you should specify it with this option. Then, it will be used to generate all HTML document files. Note that the generation of the frameset HTML file (normally 'index.html') is not affected by this setting.

CSS The group of options related to formatting of HTML output, which is done through Cascading Style Sheets (CSS).
For details, see: FlexDoc.XYZ | Documentation | Usage of CSS in generated HTML | HTML Generator Options for CSS

Generate style sheet file

html.output.css.file : boolean {true, false}

Specify whether to generate the external CSS file (global style sheet).

When this option is selected (true), an external CSS file will be generated, which is placed in the output destination directory typically under the name 'stylesheet.css'. Most of the HTML formatting settings used in the generated documentation will be held in this file referenced from each HTML document via a <link> tag, e.g.:

<link rel="stylesheet" type="text/css" href="../../stylesheet.css">

When this option is unselected (false), no external style sheet file will be generated. In that case, all CSS rules used in the generated HTML will be defined locally within those HTML files themselves, inside <style> element.

CSS pattern file

html.output.css.file.pattern : file pathname

Specify a CSS pattern file to frame the generated global style sheet into your own CSS file.

Include anonymous rules

html.output.css.file.anonymRules : boolean {true, false}

Specify whether all generated anonymous CSS rules must be stored in the external CSS file (global style sheet).

Anonymous CSS rules are CSS rules generated from the formatting settings specified on template components. They are called “anonymous” because these are basically sets of inline CSS properties initially generated for particular HTML tags and, then, moved to a style sheet to eliminate their repeating across the HTML file(s). Now, only class selectors assigned to those CSS rules are specified in the HTML tags (instead of the original CSS properties). But the class selectors are generated automatically, which depends on how early a particular CSS property set was registered in the style sheet. That makes them completely unpredictable and dependent on the data being documented, which prohibits substituting the anonymous rules with any custom ones.

When this option is selected (true), all anonymous rules generated across all generated HTML files will be collected in the global style sheet (which is printed further as the external CSS file). That produces the most compact documentation files, since many anonymous rules repeat themselves across different HTML document. So, it is the default setting.

When this option is unselected (false), the anonymous rules will be generated and stored locally by each HTML document where they are used. The global style sheet won't include anonymous rules. You may want this in the following situations:

Since anonymous CSS rules (i.e. their class selectors) are generated completely unpredictably, even a little change in the input data, which would affect just a single HTML file, may cause a great disturbance in the naming of all anonymous rules stored in the style sheet used by that HTML file. When it is the global style sheet, all HTML files, where any anonymous rules are used, will change too.
This won't be good, for instance, when you store your generated documentation in a repository system that updates only changes of files relative to the previous version. Then, a massive disturbance in the generated HTML (caused by just a few changes in the input data) will lead to a massive update of your repository (particularly in the case of very large documentation). So, keeping all anonymous rules locally would help!
If you substitute all generated default and named CSS rules with your custom CSS rules and exclude all anonymous rules from the global style sheet, its content effectively becomes static. Then, you can simply use a CSS pattern file as a complete your CSS file.

Generate named rules

html.output.css.namedRules : enum {"none", "all", "selected"}

Specify whether to generate named CSS rules.

Named CSS rules are CSS rules generated from the formatting styles defined in templates. When such a style is assigned to a template component, the HTML tags generated by that component can be assigned with the CSS rule generated from that style. The class selector assigned to that CSS rule is specified in the template style itself (or derived from its name). Therefore, it has a constant (predictable) relationship with both the particular CSS property set produced from that style and the particular output structures where that CSS rule is applied. This opens a possibility to substitute the generated named CSS rules with the custom ones.

Please note that named CSS rules are not required for proper HTML output and will only increase its size. You need named rules only when you want to style the generated HTML documentation with your own CSS properties/rules.

Possible Values:

"none"

Disable the generation of named CSS rules.

"all"

Generate all named CSS rules possible.

When this setting is selected, almost all template formatting styles involved in the generation of the particular HTML output will be rendered into named CSS rules. See also: Which template styles can produce named rules?

"selected"

Generate only those named CSS rules, which come from the template formatting styles with the selected property: CSS | Allow named rule

Custom Style Sheet

Since the version 1.9.0 it is possible to substitute some of the generated CSS rules with your custom ones. This allows you to adjust (to some extent) how the generated documentation looks without changing the templates.

For further details, please see: FlexDoc.XYZ | Documentation | Usage of CSS in generated HTML

RTF Output

RTF Options

When in the Generator Dialog you select RTF output format and click «Options» button, you will see the following RTF Option Inspector dialog (click on the screenshot to see the corresponding option description):

RTF Option Inspector

The descriptions of RTF options (the default option values are underlined):

Option Name / Type / Description

Styles The group of options related to RTF styles

Include paragraph styles
Include character styles

rtf.styles.include.parStyles : boolean {true, false}
rtf.styles.include.charStyles : boolean {true, false}

These two options specify whether paragraph/character styles should be included in the generated RTF.

When the option is true (checked), for each paragraph/character style defined in templates a corresponding RTF style will be generated and references to it will be inserted in each location where that style is used.

When the option is false (unchecked), no specific character style information will get into the RTF. However, any formatting specified in the template styles will be used anyway.

You may need to disable the inclusion of style information in some situations, when the generated RTF is intended primarily for using in non MS Word applications. Certain RTF importers, although appear to understand most of the RTF settings quite well, nevertheless, may produce such a mess with the styles imported from an RTF that the result document may look considerably distorted.

Attached Template

rtf.styles.attachedTemplate : file pathname

This option allows you to attach your MS Word document template (.dot file) to the generated RTF document. This template may override the formatting styles originally specified in FlexDoc templates.

MS Word uses the styles contained in dot-files to dynamically replace the formatting of equally named styles contained in RTF documents. The styles are connected by their full names.

For example, let's assume that in your dot-file you have a paragraph style named "My Cool Style" that you want to use in your docs.

Then, you will need to define a paragraph style in the template exactly with that very name "My Cool Style". To define a style in the Template Designer, you should go to the File | Styles menu item which invokes the Formatting Styles dialog.

Once the "My Cool Style" paragraph style is defined in your template, you may or may not specify in that style some formatting properties as you like, which actually doesn't matter as you wish to override them with the dot-file.

Then, you should assign that style to the specific template components whose output you want to format using the dot-file.

In particular, you should specify the 'Style' setting in the component's Properties Dialog -> Formatting -> Paragraph (or Text) tabs. Note, that other formatting settings in those tabs should be specified as 'default'. In accordance with RTF rules, the local formatting settings different from those defined in the template styles will have the higher priority over the styles and, therefore, will not be overridden by dot-files.

This setting will work only when the corresponding options are selected:

Styles | Include paragraph styles
Styles | Include character styles

Text The group of options to control the processing of source texts (character data)

Render embedded HTML

rtf.text.renderEmbeddedHTML : boolean {true, false}

Specifies whether to render (interpret) embedded HTML markup.

When this option is true (checked), all custom HTML tags will be parsed and rendered with the appropriate features of RTF. That's pretty much complicated processing and only limited set of HTML tags is supported in this way. Any other tags will be ignored. See: FlexDoc/XML | Features | Formatting | Rendering of embedded HTML

This setting affects only the output of those template components whose 'Render embedded HTML' option is checked. That option is located at the component's Properties Dialog | Formatting | Text Flow tab. When such an option is not specified, any markup contained in the component's output will be treated as an ordinary text.

Render line breaks

rtf.text.renderLineBreaks : boolean {true, false}

Specifies whether the newlines ('\n' codes) found in the text must be interpreted with separate lines in the generated output.

You may use newlines in your annotation text just to make it more readable during the editing, with no intent to see it broken into the same line in the generated documentation. However, you may use the original newlines also as a simple way of formatting your text.

When this option is true (checked), all '\n' codes will be rendered with the new line in RTF (i.e. \line controls).

When this option is false (unchecked), all '\n' codes will be passed to the output as is.

Hypertext The group of options controlling the generation of hyperlinks and bookmarks

Generate hyperlinks

rtf.hypertext.hlinks : boolean {true, false}

Specify whether to add hyperlinks in the RTF output.

Hyperlinks will be highlighted with a special style specified for hyperlinks in templates (typically, blue text with underlining).

To allow cross-reference hyperlinks (those pointing within the same document) being generated, the "Generate bookmarks" option must be selected as well. Without it, only external (URL) hyperlinks will be possible.

Generate bookmarks

rtf.hypertext.bookmarks : boolean {true, false}

Specify whether to add bookmarks in the RTF output.

Bookmarks are needed to generate both cross-reference hyperlinks and page number references.

Bookmark name prefix

rtf.hypertext.bookmarks.prefix : string

Specify prefix for automatically generated bookmark names.

When the name of a bookmark is generated automatically, it is made of some prefix (the same for the whole RTF document) and an internal bookmark number (about which it is certain only that it is unique within that document). For example, if the prefix is "abc", the automatic bookmark name may look like:

abc125

where '125' is the bookmark number.

The default bookmark name prefix is "b". With this option, you can specify a different prefix to be used in the RTF document you will generate.

When you need to merge several RTF files produced with FlexDoc into a single document, you should generate those files with different bookmark prefixes. This will ensure that the bookmarks from different RTFs never overlap and all hyperlinks and page number references in the result document are correct.

The generation of the bookmarks is specified in templates in the "Hypertext" properties of particular template components. In those properties, it is also possible to assign a formula expression that will generate specific bookmark names. The bookmark names produced by such formulas will never be changed (no additional prefix will be added to them). The prefix is used only when a bookmark name is produced completely automatically by the generator (without any programming about it in the template).

Tables The group of options controlling the generation of tables in RTF

Allow auto resize table cells

rtf.tables.allowAutoFit : boolean {true, false}

Allows table cells to be automatically resized to fit their contents.

When this option is true (checked), the table autofit setting is added to the definitions of tables in RTF.

This will affect only those tables generated by the template components with the specified setting: Formatting | Table | Auto resize to fit contents

In Microsoft Word, that RTF setting will activate the "Automatically resize to fit contents" option for the given table.

You may want to disable the table autofit for some reasons. For instance, some RTF readers do not interpret it (e.g. LibreOffice) or even in MS Word there is a problem with wrapping of long non-breaking strings within tables with autofit.

Break long nonbreaking strings

rtf.tables.breakLongStrings : boolean {true, false}

Specify whether to break automatically the long non-breaking strings placed within the tables with the table autofit setting (see the option: Tables | Allow auto resize table cells).

This option addresses a problem with wrapping of very long non-breaking strings within table cells. Some of your data may be represented in the generated documentation by long strings without spaces. For instance, this may be very long qualified names of Java classes, some character patterns and so on. MS Word interprets such strings as single non-breaking words. (This happens also when all spaces in a string are non-breaking.)

The problem arises when non-breaking strings are placed in table cells. Many FlexDoc templates use tables as layouts, so lots of text data is put in table cells. To have a table-based layout to be arranged correctly, the table autofit RTF setting is specified with those tables. MS Word normally arranges such tables correctly and wraps the text as needed. But this works well only when the text consists of not too long words separated with spaces. When there are long sequences of characters without spaces, MS Word does not wrap them. Instead, it produces a table so wide that it is "displayed" beyond the page, making some data invisible in the result document.

Unfortunately, we have found no reliable natural way to force MS Word to wrap long non-breaking strings and arrange the table containing them correctly. (That's probably because MS Word is focused mainly to process hand-written documents rather than to layout correctly something generated automatically.)

To work around that problem, the RTF output generator breaks long non-breaking strings automatically by itself according to certain estimations. Because that breaking is not always perfect, a group of options was introduced in order to control it (see nested options).

Maximal unbroken length

rtf.tables.breakLongStrings.maxNbrLength : integer

Specify the maximum character length for a non-breaking string (i.e. non-wrapping text) allowed to be left unbroken.

This option allows you to define what a long non-breaking string actually is, thereby preventing from breaking some fairly long words and names. Those strings that do not exceed the specified length will not be affected by the automatic breaking.

Maximal unbroken width

rtf.tables.breakLongStrings.maxNbrWidth : percent

Specify the maximal width for a long non-breaking string (i.e. non-wrapping text) allowed to be left unbroken.

The purpose of automatic breaking of strings is to help MS Word to wrap those strings within table cells. When it is possible to estimate that for a given table configuration a string will fit into it without breaking, no breaking is actually needed (as it always distorts the original text).

Using the font face and size specified in the template, the RTF generator is able to estimate the width occupied by a string. It is also possible to determine the approximate maximum width available for a table.

This option specifies the percent of the table width in which any non-breaking string should be wrapped.

For example, when the option value is 50, each long non-breaking string placed in a table will be broken so to wrap within approximately half of the estimated table width. The 75 percent will wrap the strings into 3/4 of the estimated table width.

When the table is nested within other table(s), the topmost table is used as a base for the wrapping estimation.

The zero (default) value assigned to this option has a special meaning.

In that case, the percentage of the table width available for wrapping will be obtained from the "Formatting | Table Cell | Options | Max width allowed for long non-breaking strings" setting specified in the template control that generates the given table cell (in which the string is placed). In most cases, this actually allows for much better adjustment of the string wrapping.

However, even this is not waterproof – the reason why this option is exposed here.

At last, if the percentage value found in the template is 0, the default 50% is used.

Use optional breaks

rtf.tables.breakLongStrings.useOptionalBreaks : boolean {true, false}

Specify whether to use 'Non-width Optional Breaks' when breaking long strings for wrapping.

The 'Non-width Optional Break' is a pseudo-symbol provided by MS Word (the RTF equivalent is '\zwbo') exactly for such situations: to specify where the text should be broken when it is wrapped. It has no effect when no wrapping is needed.

However, the problem with 'Non-width Optional Break' is that some RTF readers do not interpret it. That's why this option was introduced.

If wrapping of long nonbreaking strings does not work, try to unselect (false) this option. Then, the normal line breaks will be used.

Never keep rows together

rtf.tables.neverKeepRowsTogether : boolean {true, false}

If you encounter a problem with the disappearance of a piece of your text in the generated RTF, this option may help you. Please read the explanation.

If this option is checked (true), each row of a table contained in the generated RTF will always be allowed to break across pages in spite of any settings specified in templates.

Some templates may be designed so that tables generated by them will be specified to keep together on a single page. When such a table does not fit on the rest of the current page, instead of breaking it across pages, the RTF renderer should start this table from the next page.

That works fine as long as the content of each cell in the table is not too large. However, in MS Word, there may be a problem with that. When a text contained in a table cell is so large that it does not fit on a single page, MS Word will not break such a table row automatically regardless of its settings. If the row containing this cell is set to keep on a single page, you simply won't find a piece of your text in the document at all. MS Word will "display" it beyond the page boundaries!

If you have such a problem, try to check this option and generate your document again. Most likely, you will find the whole text in the right place after that.

Images The image related options

Store graphics in RTF

rtf.images.storeGraphicsInRTF : boolean {true, false}

If true (checked), all graphics will get into the generated RTF so the result will be a single file.

If false (unchecked), the graphic files will be saved separately in a xxx_files subdirectory near the document. Only references will be placed in the generated RTF output. This may reduce the result file size, especially when some images are repeating.

Show failed image paths

rtf.images.showFailedPaths : boolean {true, false}

When an image specified by a pathname (or URL) is not found or cannot be loaded, it is replaced with a placeholder (i.e. a special icon indicating the image failure).

If this option is true (checked), in addition to the placeholders, the failed image's pathnames (or URLs) will be shown in the generated RTF, so you could see where the generator tried to find those images.

Since the file pathnames tend to be long non-breaking strings, showing them in the generated document may considerably distort its formatting layout. That's why this option was introduced.

Allow image rotation

rtf.images.allowRotation : boolean {true, false}

Allows the automatic rotation of large images to better fit tem in the specified paper size so as to minimize the image scaling. Currently, this is supported only for the element images (diagrams) generated in PNG format and only when all graphics is stored in RTF files.

The rotation should also be enabled in the template Image Controls generating those images.

Page Settings

This group of options allows you to configure the page layout used in the generated RTF.

These are the same settings as specified in

Formatting | Page Settings

properties of the main template you will run.

Here, you can override some of them to better fit your needs.

Most of these options work so that when an option is set as default, the corresponding value from the main template will be used.

Orientation

rtf.page.orientation : enum {"Portrait", "Landscape"}

Specify the page orientation used in the generated RTF document.

This option overrides the corresponding property of the main template:

Formatting | Page Settings | Paper | Orientation

When this option is set as default, the value specified in the main template will be used.

Some template sets may support the dynamic switching of page orientation selectively for specific sections of the generated output. That behavior cannot be overridden with this option and is controlled rather through template parameters.

See also the FlexQuery GOM property: Template Designer | Help | Generator Object Model | output | pageOrientation

Size

rtf.page.size : enum {"A4", "Letter", "Legal", "A3", "Custom"}

Specify the page size used in the generated RTF document.

This option overrides the corresponding property of the main template:

Formatting | Page Settings | Paper | Size

When this option is set as default, the value specified in the main template will be used.

Width
Height


rtf.page.size.width : number

rtf.page.size.height : number

Specify the page width/height.

The values of these options are implied from the page size and can be changed only for Custom page size.

Margins

The group of options to specify the page margins used in the generated RTF document.

These options override the corresponding property group of the main template:

Formatting | Page Settings | Page Margins

If you need to set very narrow margins, you can use the following settings:

Top

15 mm

Bottom

15 mm

Left

10 mm

Right

10 mm

Header

5 mm

Footer

5 mm

Top

rtf.page.margin.top : number

Specify the page top margin.

It is the distance between the top edge of the page and the top edge of any regular page content (e.g. text). That means, the top margin must also reserve the spacing for the page header (if any required) and be calculated as follows:

header margin +
header height +
spacing between the page header and page content

This option overrides the corresponding property of the main template:

Formatting | Page Settings | Page Margins | Top

When this option is set as default, the value specified in the main template will be used.

Bottom

rtf.page.margin.bottom : number

Specify the page bottom margin.

It is the distance between the top edge of the page and the bottom edge of any regular page content (e.g. text). That means, the bottom margin must also reserve the spacing for the page footer (if any required) and be calculated as follows:

spacing between the page content and page footer +
footer height +
footer margin

This option overrides the corresponding property of the main template:

Formatting | Page Settings | Page Margins | Bottom

When this option is set as default, the value specified in the main template will be used.

Left

rtf.page.margin.left : number

Specify the page left margin.

It is the distance between the left edge of the page and the left edge of any regular page content (e.g. text).

This option overrides the corresponding property of the main template:

Formatting | Page Settings | Page Margins | Left

When this option is set as default, the value specified in the main template will be used.

Right

rtf.page.margin.right : number

Specify the page right margin.

It is the distance between the right edge of the page and the right edge of any regular page content (e.g. text).

This option overrides the corresponding property of the main template:

Formatting | Page Settings | Page Margins | Right

When this option is set as default, the value specified in the main template will be used.

Header

rtf.page.margin.header : number

Specify the page header margin.

It is the distance between the top edge of the page and the top edge of any content that serves as the page header (e.g. a line of text).

This option overrides the corresponding property of the main template:

Formatting | Page Settings | Page Margins | Header

When this option is set as default, the value specified in the main template will be used.

Footer

rtf.page.margin.footer : number

Specify the page footer margin.

It is the distance between the bottom edge of the page and the bottom edge of any content that serves as the page footer (e.g. a line of text).

This option overrides the corresponding property of the main template:

Formatting | Page Settings | Page Margins | Footer

When this option is set as default, the value specified in the main template will be used.

Mirror

rtf.page.margin.mirror : boolean {true, false}

Specify whether the margin definitions should be automatically switched on left and right pages.

That will allow you to print on both sides of each paper sheet so that the wider margin will be always on the same place that will help you to bind everything as a single booklet.

Measurement Units

rtf.page.units : enum {"mm", "in"}

Specify the measurment units used in page settings.

Other Options Miscellaneous options

Tune output for

rtf.misc.tuneFor : enum {"ms_word", "docx", "libre_office"}

This option allows you to instruct the generator to adjust the RTF formatting settings specifically for some of the most common applications of RTF.

RTF is a rich text format that although allows you to express almost any document formatting concept, the exact interpretation of all that is rather loose and may substantially vary by different applications (RTF readers). Especially, it concerns more complex features (like the relationship between borders, paddings and margins; adjustment of table column widths and other things). So, to achieve that the generated RTF output looks properly in a particular application, those things need to be determined experimentally and the corresponding RTF settings corrected accordingly.

Possible Settings:

"MS Word"

Tunes everything to display the generated RTF (as is) in MS Word, from where it can be printed or converted to PDF.

"DOCX conversion"

Select this setting, when the generated RTF file will be open in MS Word and further converted to DOCX format.

DOCX is a newer format, with which MS Word works much faster than with RTF. You may want to convert the generated documentation into DOCX when you need to edit it extensively or merge with something else.

"LibreOffice"

Select this setting, when the generated RTF file will be open in LibreOffice.

Suppress timestamp

rtf.misc.noTimeStamp : boolean {true, false}

Specifies whether to suppress the date/time information included in a special comment inserted automatically at the beginning of every generated RTF file, which looks as the following:

{\comment Generated by FlexDoc/XML 1.14 on Mon Sep 16 10:53:29 CEST 2024}

When this option is selected (true), such a comment is still inserted, however without the current date/time:

{\comment Generated by FlexDoc/XML 1.14}

Besides affecting the automatic RTF comment, this option is also passed to templates via 'output.noTimeStamp' property available in FlexQuery expressions. So, if a template is programmed to display the generation's date/time in the document, it may suppress that as well, according to the setting of this option.

Updating RTF fields in MS Word

The RTF documentation generated by the provided templates heavily uses document fields (for such things like page number references, number of pages and so on).

When you load the generated RTF in MS Word, to have the fields display the correct values, you will need to update them. To do this, please type: Ctrl+A, then F9.

Including generated RTF in larger Word document

Your task is the following. You have prepared a certain static Word document and need to include into it the output generated with FlexDoc so as each time your XML documentation is regenerated, the larger Word document is updated as well.

Here is how you can do that.

You should insert into your Word document an INCLUDETEXT field. Using the MS Word menu, it may be done like this:

Insert | Field... | Categories: Links and References | Field names: Include Text

In the Word document (when “Toggle Field Codes” switched on), the field will look like the following:

{ INCLUDETEXT "C:\\blah\\blah\\XMLDoc.rtf" \* MERGEFORMAT }

Here, the RTF document generated with FlexDoc should be found by the path:

C:\blah\blah\XMLDoc.rtf

Make sure you use double slashes in the field's pathname (as a single slash is used to start a command or an option)!

After that, you can generate with FlexDoc the XMLDoc RTF. To prepare the result big document, open it with MS Word. Then, press Ctrl+A (select all) and F9 (to update fields).

Including static Word document into generated RTF

Now, the task is the opposite. You have prepared some static Word document and need to include it somewhere in the RTF document generated by FlexDoc.

That is possible too. However, you will need to specify this in some template (because only templates eventually generate any output). Therefore, you will need to use the Template Designer.

In some template location, which is determined by where you need to insert your Word document, you should specify a Data Control as shown on the screenshot (the rectangle with "Include Text ..."):

In the property dialog of that Data Control, you should specify: Data Source = 'Document Field'; Field = 'Include Text', as shown on the next screenshot:

In the “Expression for Filename or URL” field, specify a FlexQuery expression that will evaluate to the pathname or URL of the Word document file you want to include. That expression may be as simple as just a string constant (as shown in the screenshot).

When you generate an RTF file with that template and open it in MS Word, you will see in it a field like this:

After updating that field, your Word document will be included there.

Generating RTF for non-Word applications

The RTF generated by FlexDoc/XML may be successfully imported into OpenOffice.org Writer, Adobe FrameMaker and probably many other (non MS Word) software.

To make the RTF look better in other applications, before generating it, you may change the option:

Other Options | Tune output for

e.g. in RTF Options Inspector or on the Java command line with the -o option like:

-o:rtf.misc.tuneFor=libre_office

When that option is set (default):

Other Options | Tune output for = "ms_word"

the generator will adjust some RTF formatting settings specifically for MS Word.

Although Microsoft is the originator of RTF format, the MS Word itself appears to have some oddities of rendering certain RTF settings, even though those settings may well follow the RTF specification. For instance, when displaying the paragraph or table borders, their horizontal positions may be shifted (e.g. when MS Word interprets horizontal margins of a paragraph, it draws the paragraph borders and paddings within the specified margin space but not within the paragraph content as it might be natural).

To overcome this, in such cases, we adjust the initial dimensions in the opposite way so as the result formatting would look properly in MS Word (e.g. to make the actual paragraph margin look as intended the margin width specified in RTF is increased by the paragraph border and padding widths).

However, when you generate RTF to display it primarily not in MS Word but rather in different viewers or editors (e.g. LibreOffice.org under Linux), which interpret the original RTF specification more literally, those specific adjustments may cause a visible distortion of the intended formatting of the document. In such cases, we recommend to try with different values of this option.

If something is wrong with the imported RTF, try also to uncheck the options:

Styles | Include paragraph styles
Styles | Include character style

Some tools have problems with the formatting styles embedded in RTF.

Plain-Text (TXT) Output

TXT Options

When in the Generator Dialog you select TXT output format and click «Options» button, you will see the following TXT Option Inspector dialog (click on the screenshot to see the corresponding option description):

TXT Option Inspector

The descriptions of TXT options (the default option values are underlined):

Option Name / Type / Description

Option	Name / Type / Description
Charset	`txt.charset : string` Specifies the character set (encoding) of the generated plain text files. The name should be a preferred MIME name (canonical name) as given in the IANA Registry. The default charset is UTF-8. If the charset name is specified as empty (blank), the Java machine's default charset will be used.
Render embedded HTML	`txt.renderEmbeddedHTML : boolean {true, false}` When this option is `true` (checked), all embedded HTML markup will be filtered out and not appear in the generated output. If `false` (unchecked), everything gets into output as it is. This setting affects only output of those template components whose 'Render embedded HTML' option is specified. This option is located at the component's Properties Dialog \| Formatting \| Text Flow tab. When such an option is not specified, any markup contained in the component's output will be treated as an ordinary text.

Charset

txt.charset : string

Specifies the character set (encoding) of the generated plain text files. The name should be a preferred MIME name (canonical name) as given in the IANA Registry.

The default charset is UTF-8.

If the charset name is specified as empty (blank), the Java machine's default charset will be used.

Render embedded HTML

txt.renderEmbeddedHTML : boolean {true, false}

When this option is true (checked), all embedded HTML markup will be filtered out and not appear in the generated output. If false (unchecked), everything gets into output as it is.

This setting affects only output of those template components whose 'Render embedded HTML' option is specified. This option is located at the component's Properties Dialog | Formatting | Text Flow tab. When such an option is not specified, any markup contained in the component's output will be treated as an ordinary text.

Using plain-text output to generate auxiliary files

The most important use of plain-text output is the generation of various auxiliary files (like JavaScripts) that complement the generated documentation with extended functionality.

The settings for such auxiliary plain-text output are specified the same as for the main format. See TXT Options.

For instance, the framed HTML XML Schema documentation generated by XSDDoc includes the dynamic search functionality, which is implemented using JavaScript. The search indexes, which are equally JavaScript files with index arrays, are generated by special templates that must produce the plain-text JavaScript files even though the main output format is HTML.

The following screenshot shows the search.tpl template open in the Template Designer. That template itself generates the Search Page, which is an HTML. However, on the way, it calls from itself also several other templates (e.g. search-indexes.tpl) that generate JavaScripts required for the dynamic search to function.