RTF Format Specification

Introduction

The ETAS RTF converter add-on for the directory based EHANDBOOK Container-Build toolchain generates textual and graphical content for EHANDBOOK containers out of RTF files. Typically, per sub directory (which normally corresponds to a function component) you can place one single RTF document there, together with the model file. This content is then transformed into the EHB container in the text pane of the function component and describes verbally the functionality of the corresponding model.

This document provides a comprehensive information on the features within RTF that is supported by EHANDBOOK Container-Build tool.

Supported Versions and Format

RTF format is supported according to the Rich Text specification version 1.9.1, but as a rudimentary subset only. Supported functionalities are described below. As a generating tool for RTF, MS Word in Version 2013 is given. MS WordPad is not supported. Other tools or versions of MS Word may work also, but not guaranteed by ETAS.

The RTF file input is only supported by the directory based EHB-CB versions.

File size is limited to 120 MB, see chapter Other known Limitations.

Supported RTF Elements

The RTF specification provided by Microsoft gives the user the ability to create large variety of different data within the document file. For the scope of EHB, the support of plain text and standard graphics is provided only.

Currently, the features supported by EHB-CB tool are as follows:

Paragraphs
Chapters
Images
Model links from RTF
Tables

Paragraphs

Paragraphs within RTF includes different combinations of characters, words and other different text representation. The plain text is completely supported in the tool, which gets represented as a paragraph output HTML documentation. Other detailed support given within the plain text are as follows:

Text formatting
Unicode/Language support
Bullets & Lists

Numbering

As the EHB solution is using its own numbering system, the original numbering of chapters and figure legends and other numbered references will be ignored.

Text Formatting

Text formatting including color, font, style (bold, italic, underline) is not supported. Text alignment is also not supported, even in table cells. Paragraph alignments are not supported in paragraphs as following the intermediate DITA standards. Text has to be in single-column.

Unicode/Language Support

If the characters used in paragraph don’t belong to the standard ANSI characters, they are represented in RTF as Unicode’s. These Unicode’s help represent different language characters in code form. Different language support implementation is completely in place with the help of these Unicode identification and text conversion using standard libraries.

Input:

Output in EHB-NAV:

Bullets, Numbering & List

Many varieties of bullet characters are offered by the bullet library of Microsoft. Currently EHB support Numbering completely in the list and Bullets of different characters are converted to a generic symbol – “•” or “o”, depending on the input. List within table is also supported.

Following figure depicts the comparison of Input RTF in word on the left side and the final output inside EHANDBOOK NAVIGATOR on the right side.

Tables

Tables in RTF are basically structured data which are stored in rows and columns. There are different types of tables in RTF. The supported ones are:

Simple tables
Complex tables – as unstructured tables only

Simple tables contains data with uniform number of cells in each rows of the table. For example:

SL No.	Name	Last Name
1	Tom	Hanks
2	Ethan	Hunt

SL No.

Name

Last Name

Tom

Hanks

Ethan

Hunt

Complex tables contain irregular number of cells in each row. For Example:

15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
FC Name: FlexECU
Phys	-	Equation	Equation=PhysX2	Limit Equation	~65332

FC Name: FlexECU

Phys

Equation

Equation=PhysX2

Limit Equation

~65332

Limitations for table support in EHB:

Tables must contain more than one cell
Complex tables – as nested tables are currently not supported
Only plain text in cells is allowed, no other objects, like images
Tables are always rendered with thin frame lines in EHB-NAV, independent of the table styling in RTF.
Text alignment and line breaks may rendered in NAV differently than in the RTF source

Output example in EHB-NAV:

Chapter Identification

Different chapters in RTF are identified in Container using the different header styling given to the text. Firstly, the TOC table of the RTF document is processed for chapter bookmarks and prepared for chapter identification. This step is followed by identifying subchapter using both the header styles and field data identified in RTF. Detailed understanding of the process is as follows:

Bookmark from TOC table
Style sheet identifies the styles starting with “Heading” as chapter heading.

Bookmarks from TOC Table

Main chapters in RTF are identified using the main table of content fields in the documentation.

Example TOC table:

In case of unavailability of TOC table, style property of the heading text is considered for chapter identification.

Text Style for Chapter Identification

Chapters and subchapters in RTF documents are identified via the style associated to the heading. If the style is of type “Heading” i.e., if the style property starts with the prefix “Heading”. These headings are then converted to subchapters of their parent chapter.

Input Example in an RTF file:

Output in EHB-NAV:

Image Handling and Linkage

Static Images

RTF provides different image file formats to be embedded inside the document. The following image types are currently supported:

Joint Photographic Experts Group – (JPEG)
Portable Network Graphics - (PNG)

Windows Metafile (WMF) and Enhanced Metafile (EMF) are only supported, if they contain plain, un-scaled and un-tailored images only. Text, formulas and other elements may look scattered in EHB-NAV later.

EMF and WMF are converted to standard PNG format with standard SWT interfaces for EHB-NAV support.

Interactive Model linking from RTF

EHB offers a linking mechanism between model figures inside RTF documents and their respective model hierarchy within the functional component (FC) in both directions.

In EHB-NAV this will look as follows:

The model figure is shown with a button “Open interactive model” in the text pane. By click on it, the corresponding model hierarchy is opened in the model explorer. Here the pop-up menu “Show in Documentation” navigates you back to the model figure in the text pane.

Model linking with embedded Images

In this case, the model figure is directly embedded in the RTF document. To invoke the linkage, the following syntax in the RTF has to be used:

Model image identifier keyword [Model]
Followed by the model snapshot image
Model hierarchy path below the image whose text style is of type “Caption”

(exact hierarchy path of the model from which the image snapshot is taken)

This works for ASCET and Simulink models.

Total length of sub hierarchy path and model name is limited to one text line only. If necessary, reduce the font size to achieve this.

The model hierarchy path is not verified by EHB-CB Tool. In case the model link path specified is invalid, no link will be created.

RTF input sample for the EHB-NAV view shown above:

Model linking with Images generated by EHB-CB

In this case, the model figure is generated by EHB-CB out of the interactive model and placed into the EHB-NAV text pane from the RTF content.

Major advantages:

No manual model screenshot generation required
No update of model figures required, if changes in model were made
ClickPic possible (Model navigation in text pane of EHB-NAV)
File size of the RTF document keeps small

To invoke the image generation and model linkage, the following syntax in the RTF has to be used:

For ASCET or Simulink models:

Model image identifier keyword [ehbmodelref]
Model hierarchy path directly below in text style of type “Caption”
(exact hierarchy path of the model from which the image snapshot is taken)

Constraints for the model path:

If a SL model refers to another model file, e.g. a library, the model path has to start from the beginning of this library file

For C-Code:

Model image identifier keyword [ehbmodelref]
C-filename.c/SubFunctionName directly below in text style of type “Caption”

Constraints for c-code:

Only the very most top sub functions of the c-file can be defined and selected for the graphic
All elements of the model are shown in unexpanded view
The c-file or model is in the same location as the RTF file
Depending on the code size, the image of the interactive model may be too big to be shown fully in the text pane or be in reduced downsized view to fit in.
Only the very most top sub functions of the c-file can be defined and selected for the graphic
All elements of the model are shown in unexpanded view
The c-file is in the same location as the RTF file
Depending on the code size, the image of the interactive model may be too big to be shown fully in the text pane or be in reduced downsized view to fit in.

Total length of sub hierarchy path and model name is limited to one text line only. If necessary, reduce the font size to achieve this.

The model hierarchy path or sub function name is not verified by EHB-CB Tool. In case the model link path specified is invalid, no image and no link will be created. |

Function Overview Images

The RTF converter allows to show a Function Overview Diagram within the textual content in the container. This diagram is generated by EHB and shows all inputs and outputs of a module. It has also a link to its interactive model. For this, a location in the text should be defined with below format. The image content will be inserted in the existing text flow where the format is provided.

Definition in RTF document:

[ehbfunctionoverview-begin]
    List of function names separated by comma (“,”)
[ehbfunctionoverview-end]

The function names provided here are the function component folder name which will have the metadata excel file.

Example:

[ehbfunctionoverview-begin]
    Actuators,Amf,Afr
[ehbfunctionoverview-end]

To provide all the functions in documentation, below format can be provided.

Definition in RTF document:

[ehbfunctionoverview-all]

Text In-lining

The RTF converter allows to integrate additional textual content, e.g. c-code source files into the container. For this, the location in the text is defined by the header keyword [ehbinline] and the name of the file. The file content will be inserted in the existing text flow. In principle, any kind of text file can be integrated.

Definition in RTF document:

[ehbinline] filename

Example:

[ehbinline] codename.c

Constraints:

The file content is displayed as pure text only
The source file is in the same location as the RTF-file

Unsupported Content

EHB-CB tool currently does not support the following data:

OLE – Object Linking and Embedding
- These are basically objects that are embedded to rtf document from another source like – excel, PowerPoint, Equations etc. At present, the tool throws a warning information when such objects are encountered.
Diagram Objects (DO)
- These are special complex images, which are variety of shapes and texts embedded into it. We are currently not supporting this data.
Header & Footers
- These data are currently trimmed from RTF conversion, as exclusive styling feature is incorporated in EHB-NAV for custom header and footers in documentation.
Watermarks
- No support of watermarks (background image on every page). Images should be removed in advance of the build process. We are able to provide an adapted CCS in EHB-CB to integrate this functionality if required.
Documents within Review State / Revisions
- MS Word allows to mark, check and follow-up of text changes. This functionality is not supported
Hyperlinks/Bookmarks

Apart from the points above mentioned, many different data can be included in RTF as defined in Microsoft RTF specification. If those data are not mentioned in this document, it by default means that they are not yet a part of the conversion into EHB.

Other known Limitations

Figure Title

For every graphics embedded in the RTF document, an additional title with a figure number is generated and later displayed centralized in NAV. If smaller graphics are in the text inline, the result may look hard to read.

File Size Limit

Due to heap space memory constrains in EHB-CB, the file size of an RTF document is limited to 120 MB. If the file is bigger, it is excluded from the container generation and an error message is written into the log file.

To overcome this limitation and for general performance reasons and easier version handling ETAS recommend, not embedding model images at all, but use model linking. See chapter Interactive Model linking from RTF.