Generating Documentation

While in design mode, generate documentation for projects, controllers or devices, POUs, variables, and library elements. The output format of the documentation is
Microsoft®
Word®
2010 (*.docx). Use
Generate Documentation
 to view the project information for a specific time, and search and edit the generated documentation.
Install
Microsoft
Word
 2010 (or more recent) or another *.docx application to properly view, search, and edit the generated documentation.
TIP:
Microsoft
Word
 2013 has a file size limitation that affects generated documents. Documents generated from projects with large POUs or many variables are unusable or incomplete. For more information on the
Microsoft
Word
 2013 file size limitation, see Operating parameter limitations and specifications in Word.
The
Generate Documentation
 dialog box is separated into three panes:
Document Options
,
Sections
, and
TOC Preview
. Selections in a pane affect what displays in the next pane (from left to right). Changes in the
Document Options
 pane affect what displays in the
Sections
pane and changes in the
Sections
pane affect the
TOC Preview
 pane.
dgn_dg
Options for the
Document Options
 pane are:
Option
Description
Possible Values
Sections Template
Template in XML format defining the Sections to be generated in the documentation and their hierarchy. The selected Sections Template affects the items that display in the Sections and TOC Preview panes.
The templates are located in the following directory: %PUBLIC%\Public Documents\SIS Workstation <
version
>\Templates\DocumentGenerator
DefaultTemplate, NoISaview Template, or a user-defined *.xml template. The default value is DefaultTemplate.
Orientation
Orientation of the page
Portrait or Landscape. The default value is Landscape.
Page size
Size of the page
Letter, Legal, Statement, Executive, A3, A4, A5, B4 (JIS), B5 (JIS), 11x17, Envelope #10, Envelope DL, Envelope C5, Envelope B5, Envelope Monarch, Japanese Postcard, A6, Double Japan Postcard Rotated, Executive (JIS), Oficio 8.5x13, 12x18, 8k 273x394 mm, 16k 197x273 mm, or Custom. The default value is Legal.
Margins
Left, right, top, and bottom margins for the page
Narrow, Normal, Moderate, or Custom. The custom margins range from 0 inches to the maximum size of the page. The default value is Normal.
Microsoft
Word
 Template
Microsoft
Word
 template in *.dotx format used to define the layout for the title page, table of contents, and tables.
The templates are located in the following directory: %PUBLIC%\Public Documents\SIS Workstation <
version
>\Templates\DocumentGenerator
IsagrafFooter.dotx, Isagraf_NoHeader.dotx, or a user-defined *.dotx template. The default template is IsagrafFooter.dotx.
Diagram Scaling
Scaling for all diagrams that display in the generated documentation.
25%, 50%, 75%, 100%, 125%, 150%, 175%, 200%, 300%, 400%, 500%, Fit to Page, or Custom. When selecting the Custom scaling, a spin box appears enabling the user to select the scaling value. The default value is 100%.
Link Type
Type of links in the documentation.
None, Only Bookmarked, Cross Reference, or Hyperlink. The default value is None.
Comment Style
How comments display in the documentation. This option does not affect how comments are displayed in graphical POU diagrams.
// comment, /* comment */, or (* comment *). The default value is (* comment *).
Selecting a Sections Template in the
Document Options
 pane modifies the items listed in the
Sections
pane. The Title Page and Table of contents items are always available for selection in the
Sections
pane. The dgn_var button displays the
Variable Settings
 dialog box and is used to specify how to sort the variables in the generated documentation.
  • For AADvance projects, sort variables by Name, Comment, Alias, Data Type, Wiring, Attribute, Dimension, Initial Value, Direction, or String Size in ascending or descending order.
  • For
    Trusted®
    projects, sort variables by Name, Comment, Data Type, Wiring, Initial Value, Attribute, Direction, String Size, Modbus Address, Message True, Message False, Retained, or Unit in ascending or descending order.
The items selected in the
Sections
pane modify the items that display in the tree view of the
TOC Preview
pane. Select or clear items in the
TOC Preview
 pane. The final selection in the
TOC Preview
 pane displays what is generated in the documentation.
The items that display in the
Sections
and
TOC Preview
 panes also depend on the element selected in the
Application View
 when using the
Generate Documentation
 command.
  • Example: if a POU is selected in a
    Trusted
     application, only associated sections (diary, local variables, and the POU diagram) display in the
    Generate Documentation
     dialog box.
When the project is selected in the
Application View
, all sections (project, global variables, defined words, structures, arrays, targets, etc.) display in the dialog box. Where a project, resource, device, POU, or library element is not selected, the documentation generator tries to find the associated element.
  • Example: if Local Variables of a POU are selected, the POU is considered the associated element and therefore displays in the
    Sections
    and
    TOC Preview
     panes. If the document generator is unable to find an associated element, the
    Generate Documentation
    command does not appear in the
    File
    menu.
The document generator retains the selections made in the three panes for each element across project sessions. Reset the pane selections by clicking
Default Settings
.
Users can create their own custom templates for the Sections Templates (*.xml) and
Microsoft
Word
 templates (*.dotx). When creating a custom XML template, the following syntax must be used:
Section
Description
TitlePageSection
The title page
TOCPageSection
The table of contents
SolutionSection
The title of the solution name
ProjectSection
The title of the project name
ArraysSection
The table displaying arrays
StructuresSection
The table displaying structures
DefinedWordsSection
The table displaying defined words
ConfigurationSection
The title of the controller or device name and the table displaying network links
ProgramSection
The title of the program name
POUContentSection
The POU diagrams
VariableSection
The tables for local and global variables. Also displays the extended attributes for global variables.
IOWiringSection
The I\O wiring table
TargetSection
The table displaying the targets
BindingSection
The table displaying the bindings
When creating a custom
Microsoft
Word
 template (*.dotx), how sections display may be modified, but the following styles and table styles defined by
Microsoft
Word
 or
AADvance-Trusted SIS Workstation software®
 must be maintained:
Style
Description
Heading 1
How Header 1 displays in the documentation.
Heading 2
How Header 2 displays in the documentation.
Heading 3
How Header 3 displays in the documentation.
Heading 4
How Header 4 displays in the documentation.
Heading 5
How Header 5 displays in the documentation.
Heading 6
How Header 6 displays in the documentation.
Heading 7
How Header 7 displays in the documentation.
Heading 8
How Header 8 displays in the documentation.
Heading 9
How Header 9 displays in the documentation.
Alias
How the Alias section displays in the documentation.
Comment
How comments displays in the documentation.
Table Style
Description
IOWiring
The tables displaying information for I/O wiring and targets.
NormalStyle
The tables displaying information for bindings.
VariableTableStyle
The tables displaying information for variables, arrays, structures, and defined words.
To generate documentation
  1. In the
    Application View
    , select the element (project, controller or device, POU, library element, etc.) for which to generate documentation.
  2. From the
    File
    menu, click
    Generate Documentation
    .
  3. Specify the required options, and then click
    Generate
    .
  4. In the
    Save As
     dialog box, specify the file name and save location, and then click
    Save
    .
    A progress bar appears over the
    Generate Documentation
     dialog box displaying the generation progress. Click
    Cancel
    to stop the document generation process. Any files created during the generation process are deleted.
    Once generation is complete, the *.docx application displays the documentation.
Provide Feedback
Have questions or feedback about this documentation? Please submit your feedback here.
Normal