« Back to Documentation

RE: Documentation: View Modes in Documentation

Combination View Flat View Tree View
Threads [ Previous | Next ]
toggle
Documentation: View Modes in Documentation
community documentation transformation core transformation adoscript
Answer
27/03/14 12:26
It is unclear how it is possible to "tie in" models into documentation. Models have multiple view modes and ideally the tool should generate documentation including single or multiple optionally selected views on the same document. Now the graphics and the exported document is about the view mode which is currently open. It would be useful to know how to force exported document include all view modes or allow the user of the tool to select combination of view modes to be documented.

RE: Documentation: View Modes in Documentation
Answer
02/04/13 09:40 as a reply to Anonymous.
To support multiple views during export a script based solution has to be used to generate each image for each view and use this images then in the export transformation using DSSSL. The basic logic of the documentation generation using the “Configuration of documentation” attribute is shown in the image attached.

To include all views or selected ones the LIBRARY element, more specifically the “mode” configuration parameter can be used. By adding more than one SOURCE “Model2SGML” element in the EXPORT block with different settings in the LIBRARY block, this could be accomplished.

Alternatively, the AdoScript can be used to switch through the viewmodes and generate the images using an simple EXPORT block that only does image export (here the actual DSSSL adaptation could becomes tricky - but doable, since it needs to follow a common naming convention for models generated from different blocks.

Details on the documentation component below:
- Each EXPORT block can have one or more SOURCE elements also from the same type.
- SYNTAX and configuration parameters below.
- LIBRARY specific settings can be added for the SOURCE "Model2SGML" to have a custom behaviour per modeltype/library defined.
Attachment

Attachment

Attachments: DocumentationComponent_ElementHierarchy.jpg (17.6k), DocumentationComponent_Overview.jpg (20.1k)

EXPORT Block Definition
Answer
02/04/13 09:32 as a reply to Wilfrid Utz.
Configuration parameters
menuname STRING
The text for the menuentry in the "Documentation" menu. Must be unique to all other menu names in the documentation menu.
filename STRING
The target filename. Specifies the file to which the documentation should be written. This setting is set dynamically at run time by the export dialog to the filename the user has entered.
filedescription STRING
The description of the output file format. This is needed for the File-Choose Dialog (e.g. "HTML Files").
fileextension STRING
The file extension of the output file. This is needed for the File-Choose Dialog (e.g. "*.rtf" or "*.html").
[ temp1 ] STRING
For documentation generation temporary files are needed (e.g. the sgml file). With the temp setting (temp1, temp2, ...) filenames for temporary files can be created (e.g. "C:\temp\ado2"). After the documentation is exported these files are deleted automatically.
[ requirefile1 ] STRING
With these statements you can specify files (requirefile1:"db:\\sgm2html.dsl", requirefile2:"f:\myfolder\mypicture.bmp", etc) which are to be copied to the export destination folder. After the generation these file are removed again. If the files should not be removed afterwards, add as well a "copy" (see below) statement with the same filename.
If a file doesn't exist, an error message is displayed and the export is aborted. Use "%H" to specify the ADOxx installation directory. For example requirefile1:"%Hboclogo.gif" checks if the file boclogo.gif is contained in the ADOxx installation directory.
Use only "requirefile" for temporary required files like dsl files.
Use both "requirefile" and "copy" for files needed afterwards, too, like pictures for html files.
[ copy1 ] STRING
One or more copy settings can be set (copy1, copy2, ...). The files specified here are copied to the target directory and are not removed after generation. Files starting with "db:\" are copied out of the ADOxx database. Files specified by the "copy" statement must be specified as well with the "requirefile" statement.
Use only "requirefile" for temporary required files like dsl files.
Use both "requirefile" and "copy" for files needed afterwards, too, like pictures for html files.
[ visible ] INTEGER
Set visible to 1, if a menuentry should be added to the menu "Documentation" for this EXPORT block. Set visible to 0, if the corresponding menu entry for this EXPORT block should be hidden.
[ charmap ] STRING
This defines the character map used for documentation export. As string the filename (database file or absolute file) of the character map table file is expected. You can either define a static or dynamic value.
NOTE: For compatibility reasons a special value "DEFAULT" if defined which loads the character map table defined as resource in all versions of ADOxx. It contains the release language of ADOxx. If charmap is not defined, value "DEFAULT" is set.
smarticon: (html|rtf)
If smarticon is set to html, this menuentry is called when the user clicks on the smarticon. When it is set to rtf, the menu entry is called when the user clicks on the smarticon. Only one EXPORT block may be set to html and only one to rtf. This setting may not be set dynamically!

SOURCE "Model2SGML“ Definition
Answer
02/04/13 09:32 as a reply to Wilfrid Utz.
filename STRING
The name of the sgml file which should be generated. Usually the name of a temporary file.
basename STRING
The basename used for images and the log file.
multifilemode BOOL
If 1 (true), then for each model the related full <model> tag is written into a separate file. The main export file just contains a simple <model> tag for reference, which specifies the related file name.
[ sortmode ] ENUMERATION
There the following possibilities:
Breath-wise search (Default-mode)
Depth-wise search
Lexical ordering
The sort mode influences the order in which models and their submodels are exported. When exporting in depth-wise mode, submodels are exported directly after their supermodels. When exporting in breath-wise mode, first all models are exported, then all submodels of these models, then all sub-submodels etc. When exporting in lexical-order, submodels are sorted by the modelnames.
[ translation ] STRING
A list of attribute names and their translations. Every name and every translation has to be surrounded by '@'. E.g. @Name1@@Translation1@@Name2@@Translation2@
[ modeltypes ] ENUMERATIONLIST
If no modeltypes are set, all models are exported. If one or more modeltypes are listed (with their modeltype names), only models of these modeltypes can be exported. The modeltypenames have to be separated by the character ';'.
[ acfilter ] STRING
Here you can define Attribute/Class-Filters. The mode defines which classes are exported, the attribute-mode define which attributes are exported. With Attribute/Class-Filters, the user can suppress the export of several classes, relationclasses and attributes - even if they are included in the export- and attribute-modes.
[ copydocuments ] STRING
Here you can define an absolute or relative path. Documents referenced with the PROGRAMCALL attribute are then copied to this path when exporting the documentation
[ checkexternfilenames ] INTEGER
If this property is set to 1, the names of external files referenced with PROGRAMCALL attributes will be checked. Some systems (unix, ftp) have problems with filenames that are not alphanumeric and lowercase. If set to 1 attributes referencing such files will cause a warning when exported.
[ libraryspecific ] INTEGER
If this property is set to 0, the default LIBRARY properties are applied to all models. If it is set to 1, for every library specific LIBRARY properties have to be defined.
subprocesses INTEGER
This property specifies, if subprocesses shall also be exported by default. Value 1 means "yes", value 0 means "no".
LIBRARY
Every source element contains at least one library element, that defines further properties.

SOURCE "ModelGroups " Definition
Answer
02/04/13 09:32 as a reply to Wilfrid Utz.
Configuration parameters
filename STRING
The name of the sgml file where the model group and model reference information should be written.
[ exportall ] INTEGER
Can be either 0 or 1. If it is set to 1, all modelgroups and model references are exported. If if is set to 0, only the modelreferences (and their modelgroups) are exported that the user has selected in the export dialog.

EXAMPLE USAGE
1SOURCE "ModelGroups"
2   filename:attribute:"tempfilename"    
3   exportall:0


The file to which the modelgroups will be exported will usually be the same file as the file to which the model data is exported: The sgml-file which will later be parsed by jade. In the example only the model refernces which the user selects at export will be added to the documentation.

SOURCE "AdoScript “ Definition
Answer
02/04/13 09:34 as a reply to Wilfrid Utz.
Configuration parameters
name STRING
The name of the script.
[ var1 ] STRING
Variable declarations (var1, var2, var3, ...) for AdoScript variables.

EXAMPLE USAGE
1SOURCE "AdoScript"
2   name: "Jade Converter"
3    var1:attribute:"sgmlfilename"
4    var2:attribute:"filename"
5   var2:hugo:"123"
6    {
7      SYSTEM ( homedir + "\\jade.exe -f jade.log -t html -d \"" + homedir + "\\std2htm3.dsl\" -o " + filename + " " + sgmlfilename )
8   }

Three variables are defined in the example. The first two variables are called "sgmlfilename" / "filename" and are assigned the value of the settings "sgmlfilename" / "filename". The third variable is called "hugo" and is assigned the value "123".
The variable "homedir" is set automatically to the installation path of ADOxx.

SOURCE „UserVariables“ Definition
Answer
02/04/13 09:33 as a reply to Wilfrid Utz.
Configuration parameters
filename STRING
The name of the sgml file where the user variables should be written.
[ var1 ] STRING
Variable declarations (var1, var2, var3, ...) for user specific variables.

EXAMPLE USAGE
1SOURCE "UserVariable"
2   filename:attribute:"tempfilename"    
3   var1:attribute:"Title"
4   var2:attribute:"Headline"
5   var3:attribute:"ProjectLogo"


The file to which the uservariables will be exported will usually be the same file as the file to which the model data is exported: The sgml-file which will later be parsed by jade. Three variables are defined in the example. Each variable can be set by the user. The DSL-script will insert the values entered by the user in the document.

LIBRARY Definition
Answer
02/04/13 09:38 as a reply to Wilfrid Utz.
Configuration parameters
Library elements are used to specify library specific properties. At least one library element with default settings has to be defined. Additional library elements for library specific settings have to be added if specific settings will be used.

EXAMPLE USAGE
1 SOURCE "Model2SGML"
2   [...]    
3   LIBRARY
4       [...]
5    LIBRARY "Modeltype 1"
6       [...]
7    LIBRARY "Modeltype 2"
8       [...]


The following list describes the settings of one library element. Optional elements are listed in brackets.
graphics INTEGER
1 if graphics should be generated, 0 if no graphics should be exported
[ mode ] ENUMERATION
The mode in which the documentation should be exported. Depending on the mode different classes are visible and thus exported
[ notebookattr ] ENUMERATION
The attribute mode for the document export. The name of the attributemode (not the attributename / key) has to be specified
[ gfxformat ] ENUMERATION
The format of the graphic files (e.g. "bmp" for bitmaps, "jpg" for jpegs). gfxformat only has to be specified, if graphics is set to 1. Possible values are bmp, jpg, bmp1, bmp24, pcx8, pcx24, png, emf and svg.
[ gfxdpi ] DOUBLE
The dpi (size) for the graphics. This setting only has to be specified, if graphics is set to 1.
[ gfxmode ] ENUMERATION
The mode in which the graphics should be exported. Depending on the mode different classes are visible and thus exported Here you can specify which modelclasses are visible in the graphics. This mode can be different to the mode set in mode. This setting only has to be specified, if graphics is set to 1.
[ gfxorientation ] ENUMERATION
The orientation of the graphics: "don't change" ("unverändert"), "rotate left (counter clockwise)" ("um 90° nach links (im Gegenuhrzeigersinn) drehen"), "rotate right (clockwise)" ("um 90° nach rechts (im Uhrzeigersinn) drehen"), "rotate by 180°" ("um 180° drehen"). This setting only has to be specified, if graphics is set to 1.
REMARK: The gfxorientation can not be changed for graphics of type "emf".
[ gfxlayout ] ENUMERATION
The page layout for the graphics. This setting only has to be specified, if graphics is set to 1.
[ gfxscale ] INTEGER
The scale zoom factor applied on the page layout. Default is 100. This setting only has to be specified, if graphics is set to 1.
[ gfxdozoom ] INTEGER
If set to 0, only one image for each model will be generated. If set to 1, for every dpi-entry in gfxzoomlevels, an image will be generated.
[ gfxzoomlevels ] STRING
A list of dpi values. For each entry an image with this size will be generated. E.g. "10;40;80;120".
[ imagemaps ] INTEGER
If set to 1, imagemap information is exported. If set to 0, no imagemaps will be generated.