TIA Portal Add-In

Code2Docu for
generating
documentation
Siemens
TIA Portal Industry
Online
https://support.industry.siemens.com/cs/ww/en/view/109809007 Support
 Legal information

Legal information
Use of application examples
Application examples illustrate the solution of automation tasks through an interaction of several components in
the form of text, graphics and/or software modules. The application examples are a free service by Siemens AG
and/or a subsidiary of Siemens AG ("Siemens"). They are non-binding and make no claim to completeness or
functionality regarding configuration and equipment. The application examples merely offer help with typical
tasks; they do not constitute customer-specific solutions. You yourself are responsible for the proper and safe
operation of the products in accordance with applicable regulations and must also check the function of the
respective application example and customize it for your system.
Siemens grants you the non-exclusive, non-sublicensable and non-transferable right to have the application
examples used by technically trained personnel. Any change to the application examples is your responsibility.
Sharing the application examples with third parties or copying the application examples or excerpts thereof is
permitted only in combination with your own products. The application examples are not required to undergo the
customary tests and quality inspections of a chargeable product; they may have functional and performance
defects as well as errors. It is your responsibility to use them in such a manner that any malfunctions that may
occur do not result in property damage or injury to persons.

Disclaimer of liability
Siemens shall not assume any liability, for any legal reason whatsoever, including, without limitation, liability for
the usability, availability, completeness and freedom from defects of the application examples as well as for
related information, configuration and performance data and any damage caused thereby. This shall not apply in
cases of mandatory liability, for example under the German Product Liability Act, or in cases of intent, gross
negligence, or culpable loss of life, bodily injury or damage to health, non-compliance with a guarantee,
fraudulent non-disclosure of a defect, or culpable breach of material contractual obligations. Claims for damages
arising from a breach of material contractual obligations shall however be limited to the foreseeable damage
typical of the type of agreement, unless liability arises from intent or gross negligence or is based on loss of life,
bodily injury or damage to health. The foregoing provisions do not imply any change in the burden of proof to
© Siemens AG 2023 All rights reserved

your detriment. You shall indemnify Siemens against existing or future claims of third parties in this connection
except where Siemens is mandatorily liable.
By using the application examples you acknowledge that Siemens cannot be held liable for any damage beyond
the liability provisions described.

Other information
Siemens reserves the right to make changes to the application examples at any time without notice. In case of
discrepancies between the suggestions in the application examples and other Siemens publications such as
catalogs, the content of the other documentation shall have precedence.
The Siemens terms of use (https://support.industry.siemens.com) shall also apply.

Security information
Siemens provides products and solutions with industrial security functions that support the secure operation of
plants, systems, machines and networks.
In order to protect plants, systems, machines and networks against cyber threats, it is necessary to implement –
and continuously maintain – a holistic, state-of-the-art industrial security concept. Siemens’ products and
solutions constitute one element of such a concept.
Customers are responsible for preventing unauthorized access to their plants, systems, machines and networks.
Such systems, machines and components should only be connected to an enterprise network or the internet if
and to the extent such a connection is necessary and only when appropriate security measures (e.g. firewalls
and/or network segmentation) are in place.
For additional information on industrial security measures that may be implemented, please visit
https://www.siemens.com/industrialsecurity.
Siemens’ products and solutions undergo continuous development to make them more secure. Siemens strongly
recommends that product updates are applied as soon as they are available and that the latest product versions
are used. Use of product versions that are no longer supported, and failure to apply the latest updates may
increase customer’s exposure to cyber threats.
To stay informed about product updates, subscribe to the Siemens Industrial Security RSS Feed under
https://www.siemens.com/cert.

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 2
 Table of contents

Table of contents
Legal information .............................................................................................................................. 2
1 Introduction ............................................................................................................................. 5
1.1 What is Code2Docu ................................................................................................... 5
1.1.1 Benefits of Code2Docu .............................................................................................. 5
1.2 Functionality and delimitation .................................................................................... 6
1.3 Structure of the documentation / outline .................................................................... 7
1.4 MarkDown as markup language ................................................................................ 8
2 Installation of “Code2Docu” .................................................................................................. 9
2.1 Dependencies / Requirements .................................................................................. 9
2.1.1 Supported TIA Portal version(s) ................................................................................ 9
2.1.2 Components as part of the application ...................................................................... 9
2.1.3 Components as reference in the application ............................................................. 9
2.1.4 Components to run the application .......................................................................... 10
2.2 Installation................................................................................................................ 11
2.2.1 Add user to Windows user group “Siemens TIA Openness” ................................... 11
2.2.2 Install dependent programs and copy add-in file..................................................... 11
2.3 Activate “Code2Docu” add-in .................................................................................. 13
3 Markdown syntax (Cheat Sheet) ......................................................................................... 15
3.1 Chapter / headings / titles ........................................................................................ 15
3.2 Paragraphs / Line Breaks ........................................................................................ 15
© Siemens AG 2023 All rights reserved

3.3 Horizontal line and Page break ............................................................................... 15

3.4 Text formatting ......................................................................................................... 16
3.5 Lists / Enumerations ................................................................................................ 16
3.6 Indented text / Block Quote / Quotations ................................................................. 17
3.7 Inline code ............................................................................................................... 17
3.8 Code block ............................................................................................................... 17
3.9 Math formulas .......................................................................................................... 17
3.10 Hyperlink .................................................................................................................. 18
3.11 Graphics / Images ( Figures ) .................................................................................. 19
3.12 Tables ...................................................................................................................... 21
3.12.1 Simple table (Pipe Table) ........................................................................................ 21
3.12.2 Complex table (Grid Table) ..................................................................................... 22
3.13 Note boxes............................................................................................................... 24
4 Document TIA Portal project according to “Code2Docu” ................................................ 26
4.1 Data storage in the TIA Portal project folder ........................................................... 26
4.1.1 Log file ..................................................................................................................... 27
4.2 Structure of the TIA Portal project ........................................................................... 27
4.3 Multilingualism in TIA Portal project ........................................................................ 29
4.3.1 Activate project languages ...................................................................................... 29
4.3.2 Edit multilingual texts / comments ........................................................................... 30
4.4 General and generic project and document information ......................................... 32
4.5 Folder information / descriptions (optional). ............................................................ 35
4.6 PLC blocks............................................................................................................... 37
4.6.1 Title, header and short description .......................................................................... 38
4.6.2 Interface description ................................................................................................ 38
4.6.3 Functional description .............................................................................................. 45
4.6.4 ProDiag Supervisions .............................................................................................. 47
4.6.5 Change history ........................................................................................................ 48
4.7 PLC data types ........................................................................................................ 51
4.7.1 PLC data type with elementary data type variables ................................................ 52
4.7.2 PLC data types with subordinate structures ............................................................ 53
4.8 Global constants ......................................................................................................54
4.8.1 Status and error codes ............................................................................................54
4.8.2 General constants....................................................................................................56
TIA Portal Add-In Code2Docu for generating documentation
Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 3
 Table of contents

4.9 Global change history ..............................................................................................57

4.9.1 General ....................................................................................................................57
4.9.2 Separate change history .......................................................................................... 58
5 Operation of the “Code2Docu” add-in ................................................................................ 59
5.1 Calling the add-in ..................................................................................................... 59
5.2 Functions in the main menu .................................................................................... 60
5.3 Settings menu .......................................................................................................... 61
5.3.1 Dialog box settings / Export options ........................................................................ 62
5.3.2 Dialog box Settings / Code2Docu options ............................................................... 64
5.3.3 Dialog box Settings / Rendering options ................................................................. 66
6 Location of documentation .................................................................................................. 69
6.1 User-defined documentation for global TIA Portal libraries ..................................... 69
7 Further information about multiuser projects and libraries ............................................. 71
7.1 Documentation of multiuser projects in project server environment ....................... 71
8 Tips and Tricks / FAQ (Frequently Asked Questions) ...................................................... 72
8.1 MS Office Word 365 - Document generation fails ................................................... 72
8.2 Help for documentation with MarkDown .................................................................. 72
9 Appendix ................................................................................................................................ 73
9.1 Service and support ................................................................................................. 73
9.2 Industry Mall ............................................................................................................ 74
© Siemens AG 2023 All rights reserved

9.3 Links and Literature ................................................................................................. 74

9.4 Changelog / History ................................................................................................. 75

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 4
 1 Introduction

1 Introduction
1.1 What is Code2Docu
With the help of “Code2Docu”, documentation is generated from functions (FCs), function
blocks (FBs) and PLC data types ( in the following named as “objects”) of a TIA Portal project.
In defined properties and areas objects can be documented using MarkDown (MD) as defined
markup language. With “Code2Docu” this information and text elements are extracted from the
objects, prepared for the documentation to be generated and stored accordingly.
Figure: Code2Docu process flow
© Siemens AG 2023 All rights reserved

1.1.1 Benefits of Code2Docu

• Reduction of engineering and coordination efforts

• Time savings and thus cost reduction
• Increase of engineering efficiency
• Same “look and feel” for all objects and all documentations, because of template based
generation
• Integration in CI/CD workflows (“Continuous Integration” / “Continuous Delivery”)
• Updateability of the documentation
– Document style
– Change history
• “Single point of source”, generation of the entire documentation and the user-defined
documentation (user help) from one source
• All documented languages are also stored in the objects as language (multilingual)
• Documentation cannot be “lost” as it is stored together with the project
• Developers can document their code directly –> acceptance criterion for code
documentation

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 5
 1 Introduction

1.2 Functionality and delimitation

“Code2Docu” is primarily developed for the documentation of library objects.
“Code2Docu” supports the following objects:
• PLC blocks (FC, FB, Safety FC, Safety FB) in the programming languages SCL, STL, FBD,
LAD.
• PLC data types (UDT, Safety UDT / subordinate structures)
• PLC constants ( Global constants)

Note “Code2Docu” can export the standard program or a software unit.

A mixed configuration of standard program and software unit or multiple software units is not
supported.

Note Safety Software Unit's (Safety Unit) have been introduced in TIA Portal V18, and therefore
not supported, as the Development of “Code2Docu” stays on the TIA Portal V17 API.

“Code2Docu” extracts the texts from the block interface, the title and block comments of the
objects and generates documentation from them. It works as follows:
© Siemens AG 2023 All rights reserved

• The texts of the objects are exported from TIA Portal using the TIA Portal add-in
“Code2Docu” and saved as a SimaticML / XML file.
• The exported data is then parsed and the following information is extracted:
– Variable names, data types and comments from the inputs, outputs and inputs/outputs
of the function block interface.
– Defined comments, header information, texts from description part created with
MarkDown (MD).
• The result is saved as HTML, DocX and PDF based on a template.
Additionally, areas for introduction, appendix and generic document information are provided.
More about this later.

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 6
 1 Introduction

1.3 Structure of the documentation / outline

When generating the documentation, a separate chapter is created for each object. The
following figure shows you how the description of an object and the entire documentation are
structured.
Figure: Code2Docu generated documentation
© Siemens AG 2023 All rights reserved

The documentation is structured as follows:

• Introduction / Preamble / General information
• PLC blocks
The description of the individual blocks includes:
– Short description
– Block interface
– Description of the input, output and InOutput parameters of the interface
– Function description
– Change history of the block
• PLC data types
Description of the data type and parameters.
• PLC Global Constants
• Appendix
• Change log for all blocks (“Delta” to the last state)
The PLC objects are structured according to the folder structure in TIA Portal. The levels of the
representation are structured as follows:
1st level: PLC blocks / PLC data types / Global constants 2nd level: Folder structure, composed
with "/". 3rd level: Objects

Note The fixed level structuring is due to the fact that only a finite number of hierarchy and outline
levels are available in the documents.
This property is circumvented by the fixed structuring.

How the content for this must be stored in the TIA Portal project is described in the following
chapters.

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 7
 1 Introduction

1.4 MarkDown as markup language

Since TIA Portal does not support text styles and formatting like Microsoft Word, for example,
another method of formatting the texts is required.
“Code2Docu” is based on MarkDown (MD), because this language uses few characters to mark
up text elements. MarkDown is easy to learn, easy to read, and has little overhead.
For example, headings are created with a # preceding the line. The number of # determines the
order of the heading.

# First order heading

## Second order heading
### Third-order heading
#### Fourth-order heading (Title block)
##### Fifth-order heading (Title block including table of contents)

Note A detailed list of the markups possible in “Code2Docu” can be found in the chapter
"Supported MarkDown Syntax (Cheat Sheet)".
© Siemens AG 2023 All rights reserved

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 8
 2 Installation of “Code2Docu”

2 Installation of “Code2Docu”
This chapter describes how to install the TIA Portal add-in and integrate it into the TIA Portal
environment.

2.1 Dependencies / Requirements

2.1.1 Supported TIA Portal version(s)

“Code2Docu” is supported by the following TIA Portal versions:

• TIA Portal V16 (no Features from TIA Portal >V16)
• TIA Portal V17
• TIA Portal V18 (using V17 API - no TIA Portal V18 Features)
• TIA Portal V19 (using V17 API - no TIA Portal V19 Features)

2.1.2 Components as part of the application

Component Version Reference

Serilog 2.12.0 https://github.com/serilog/serilog/
releases/tag/v2.12.0
Markdig 0.32.0 https://github.com/xoofx/markdig
/releases/tag/0.32.0
© Siemens AG 2023 All rights reserved

QRCoder 1.4.3 https://github.com/codebude/QR

Coder/
DocumentFormat.OpenXml 2.15.0 https://github.com/OfficeDev/Op
en-XML-SDK
SVG 3.4.4 https://github.com/svg-net/SVG
Fizzler 1.2.1 https://github.com/atifaziz/Fizzler
ExCSS 4.1.4 https://github.com/TylerBrinks/Ex
CSS
System.Buffers 4.5.1 https://github.com/dotnet/core/
System.Memory 4.5.4 https://github.com/dotnet/core/
System.Drawing.Common 4.7.0 https://github.com/dotnet/corefx
System.Numerics.Vectors 4.5.0 https://github.com/dotnet/corefx
System.Runtime.CompilerServic 4.7.1 https://github.com/dotnet/corefx
es.Unsafe

2.1.3 Components as reference in the application

Component Version Reference

Highlight.js 10.5.0 https://highlightjs.org/
katex.js 0.12.0 https://katex.org/
JAVA 1.8.0_281 https://www.java.com/
Microsoft.Office.Interop.Word 15.0.0.0 MS Office API
Siemens.Engineering.Hmi V17 TIA Portal Api
Siemens.Engineering.AddIn V17 TIA Portal Api
Siemens.Engineering.AddIn.Per V17 TIA Portal Api
missions
Siemens.Engineering.AddIn.Utilit V17 TIA Portal Api
ies

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 9
 2 Installation of “Code2Docu”

2.1.4 Components to run the application

Component Version Reference

Microsoft Office 2019 https://www.microsoft.com/en-us/microsoft-365/
PanDoc 2.10.1 https://pandoc.org/
https://github.com/jgm/pandoc/releases/tag/2.10.1

Note Copyright © Siemens AG 2023, and licensors. All rights reserved. Portions include Open
Source Software. See ReadMe_OSS for details.
© Siemens AG 2023 All rights reserved

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 10
 2 Installation of “Code2Docu”

2.2 Installation
Each add-in is represented by its own file with the extension “.addin”. The installation of the add-
in requires administrator rights for the following steps:
• Add user to “Siemens TIA Openness” Windows user group.
• Install dependent programs and copy add-in file to add-in folder
• Activate add-in in TIA Portal

2.2.1 Add user to Windows user group “Siemens TIA Openness”

Each Windows user working on the Windows system with TIA Portal must be added to the
Windows user group “Siemens TIA Openness”. The user must then be logged off and logged on
again for the modified policy to become active.
Further information about setting up the user can be found in the TIA Portal Openness manual
(chapter “General”):
https://support.industry.siemens.com/cs/ww/en/view/109773802/101778035467

2.2.2 Install dependent programs and copy add-in file

For installation and update of the add-in “Code2Docu” two batch files are provided, which take
over the installation or update of the add-in for the user.
• Code2Docu_Installation.cmd
© Siemens AG 2023 All rights reserved

– Installation of “Code2Docu”
– Installation of “PanDoc”
Document renderer: Document renderer: for Math formulas and syntax highlighting
Checking the installation, if Pandoc is not installed the download web page for manual
installation appears.
– Adjustment of default “Time-out” for TIA Portal add-in in the installation folder of TIA
Portal:
Bin\Siemens.Automation.Opns.AddIn.Impl.dll.config
– Copy the add-in files to the default add-in installation path:
C:\Program Files\Siemens\Automation\Portal V17\AddIns\
• Code2Docu_Update.cmd
– Update of the “Code2Docu” add-in

Note The respective batch script must be started with administrator rights, since the target
directory is located in C:\. To do this, right-click on the batch file and select Run as
administrator.

Note The installation or update cannot be started via the respective batch file if the files are stored
in a network drive or “shared folder”.
You can copy the folder Code2Docu from the delivered installation directory with all files
manually into the Or the installation directory of TIA Portal, or copy the data to your local
computer.

Note TIA Portal add-ins can be installed while TIA Portal is running. It is not necessary to close
TIA Portal during installation or to restart it after installation.
The add-in must be reactivated each time after installation or an update.

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 11
 2 Installation of “Code2Docu”

Note For further information on TIA Portal add-ins and their integration into the TIA Portal
environment, please refer to the TIA Portal online help or the “SIMATIC STEP 7
Basic/Professional V17 and SIMATIC WinCC V17” manual in the chapter “Extending TIA
Portal functions with add-ins”.
https://support.industry.siemens.com/cs/ww/en/view/109798671/135143324427
© Siemens AG 2023 All rights reserved

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 12
 2 Installation of “Code2Docu”

2.3 Activate “Code2Docu” add-in

In order to use the add-in after installation or update, it must be activated in TIA Portal. The add-
ins can be found in TIA Portal on the right side in the task card Add-Ins. The folder Code2Docu
with the add-in is listed in the palette Add-Ins.
To activate the add-in, proceed as follows:
1. Select the “Code2Docu” add-in.
2. Select the command “Activate” in the context menu or in the column “Status” or in “Details”
under “Status”.
You can recognize the activated add-in by the green check mark in the “Status” column.
Figure: Activation of the add-in
© Siemens AG 2023 All rights reserved

Note TIA Portal add-ins can be integrated at various points in the TIA Portal environment. They
are displayed for certain elements in the TIA Portal user interface in the context menu of the
respective element.
During the execution of an add-in, the TIA Portal user interface is blocked. Thus, it is not
possible to perform actions in TIA Portal during execution.
If the add-in contains its own user interface, TIA Portal is also blocked as long as the add-in
window is displayed.

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 13
 2 Installation of “Code2Docu”

Data loss
The use of an add-in can lead to data loss and a possible resulting production stop.
CAUTION For example, Snapshots, start values (except constants), setpoints, texts of
Program_Alarm or ProDiag settings will be lost.
Comments written in a language that is not enabled at the time of conversion will also be
lost.
An add-in has access to project data as well as access to disks and Internet connections. Be
aware to install only add-ins from trusted sources and refer to the documentation of the
respective add-in.
The user must regularly create data backups and check the correctness of the program after
using the add-in.
© Siemens AG 2023 All rights reserved

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 14
 3 Markdown syntax (Cheat Sheet)

3 Markdown syntax (Cheat Sheet)

This chapter lists the examples of the supported MarkDown language commands and gives a
brief overview of the supported syntax.

3.1 Chapter / headings / titles

Headings are supported up to the 5th order and prefixed with #.
The first three headings are numbered. The fourth and fifth order headings correspond to the
block title in Word, whereby the fifth order heading is included in the table of contents.

# First order heading

## Second order heading
### Third-order heading
#### Fourth-order heading ( Block Title)
##### Fifth-order heading ( Block Title incl. table of contents)

3.2 Paragraphs / Line Breaks

To create a paragraph with Markdown, simply write text of any length. The line before and the
line after must be empty.
Simple line breaks are created at the end of the line with two spaces before the line break itself.
Without these spaces, the line break is not recognized as such, so it can be used in the
MarkDown source for simple structuring.
© Siemens AG 2023 All rights reserved

3.3 Horizontal line and Page break

Horizontal lines are created with three hyphens ---.
Appearance

Page breaks are created with six hyphens ------.

Note Before or after figures, lists, tables, note boxes, math blocks or code blocks, three hyphens -
-- create a blank line.

Example:

Text before

---

Figure, List, Table, Note box, Math block or Code block

---

Text afterwards

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 15
 3 Markdown syntax (Cheat Sheet)

3.4 Text formatting

With Markdown you can use the following text formatting:
Formatting Appearance
*This text is italic* "This text is italic "
_This text is italic_ “This text is italic”
**This text is BOLD ** “This text is BOLD”
__This text is BOLD __ “This text is BOLD”
***This text is BOLD and Italic** "This text is BOLD and Italic "
_**This text is BOLD and Italic**_ "This text is BOLD and Italic "
~~This test is strikethrough~ ~"This text is strikethrough "**
~subscript~ Example (subscript) “subscript”
^superscript^ example (superscript) “superscript”
==yellow highlighted/marked== Example (marked) “yellow highlighted/marked”

3.5 Lists / Enumerations

Markdown supports sorted and unsorted lists (enumerations).

Unsortierte Listen
© Siemens AG 2023 All rights reserved

Unsortierte Listen erstellen Sie mit einem Sternchen gefolgt von einem Leerzeichen. Die
Einrückung einer untergeordneten Liste erreichen Sie mit drei Leerzeichen.

* Unsorted list with nesting

1. simple subordinated sorted list
2. further list entry
* second unsorted list entry

Appearance
• Unsorted list with nesting
a. simple subordinated sorted list
b. further list entry
• second unsorted list entry

Sorted lists
You create sorted lists with a number followed by a dot and a space.

1. Simple sorted list with nesting

* unsorted child list
* second list entry
2. further list entry

Appearance
1. Simple sorted list with nesting
– unsorted child list
– second list entry
2. further list entry

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 16
 3 Markdown syntax (Cheat Sheet)

3.6 Indented text / Block Quote / Quotations

You can get an indented text for e.g. quotes with > followed by a space.

> Block Quote

second line in quote

Appearance
block quote
second line in quote

3.7 Inline code

Create inline-code with surrounding back-ticks `code`.

3.8 Code block

Insert a code block with three preceding and ending back-ticks or tildes, together with the
abbreviation of the programming language, e.g. SCL:

```scl
stringVariable := 'code with syntax highlighting';
© Siemens AG 2023 All rights reserved

FunctionCall(stringVariable);
```

Appearance

stringVariable := 'code with syntax highlighting';

FunctionCall(stringVariable);

3.9 Math formulas

Mathematical formulas can be generated with the notation from LaTeX / TexMath.
This is an inline 𝑚𝑎𝑡ℎ𝑏𝑙𝑜𝑐𝑘 surrounded by $ - $math block$.
$\int_0^\infty \frac{x^3}{e^x-1}\,dx = \frac{\pi^4}{15}$
Appearance
∞
𝑥3 𝜋4
∫ 𝑑𝑥 =
0 𝑒𝑥 − 1 15

$$
\int_0^\infty \frac{x^3}{e^x-1}\,dx = \frac{\pi^4}{15}
$$

Appearance
∞
𝑥3 𝜋4
∫ 𝑑𝑥 =
0 𝑒𝑥 − 1 15

Note It is also possible to include mathematical formulas in the form of images instead of working
with LaTeX scripts.

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 17
 3 Markdown syntax (Cheat Sheet)

3.10 Hyperlink
You can create hyperlinks without and with link text in square brackets.
Direct hyperlink:
https://support.industry.siemens.com
Appearance
https://support.industry.siemens.com
Hyperlink with link text:
[go to SIEMENS Industry Support](https://support.industry.siemens.com)
Appearance
go to SIEMENS Industry Support
Spaces in filename or path
Relative Hyperlinks including spaces can be created by enclosing them between the < and >
characters :
[LCode2Docu_DemoType_FC.htm](<../../../../../code2doc_demo/UserFiles/UserDocumentatio
n/en-US/Library Types/LCode2Docu_DemoType_FC.htm>)

Note Relative paths can only be displayed as Hyperlinks in HTML but not in Word or PDF
documents.
© Siemens AG 2023 All rights reserved

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 18
 3 Markdown syntax (Cheat Sheet)

3.11 Graphics / Images ( Figures )

Graphics and images to be used in the documentation are stored within the TIA Portal project
structure in the folder \UserFiles\Code2Docu\images\.
Images can also be stored outside of the project folder structure and will be copied
automatically into the images folder. You can configure such an external image path in the
Settings. For further information please see chapter Dialog box Settings / Code2Docu
options.
You can also store PowerPoint presentations in the images folder directly as well as in the
configured external image folder. The slides of each presentation are exported as png image
files and saved in the same folder as their corresponding presentation. The names of the
exported image files follow the pattern PresentationName_SlideNumber.png. If a presentation
contains only a single slide then the underscore and slide number are omitted from the resulting
image file name.
To include images in the documentation, use the following syntax:
![ALT text] (path/image.PNG "optional title").
In the square brackets, specify the alt attribute. In the round brackets, specify the relative path
using the slash / to the image. This way it is also possible to group images in subdirectories.
Optionally you can specify a title in quotes.

Note The following file formats for graphics and images are supported:
© Siemens AG 2023 All rights reserved

png, jpg, bmp, svg.

Space in Name or Path of Image file should be avoided.

Examples
Image indented with text (text width):
Appearance

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 19
 3 Markdown syntax (Cheat Sheet)

Image over full page width with attribute {.pageWidth} in the line before the image:

{.pageWidth}

Appearance
© Siemens AG 2023 All rights reserved

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 20
 3 Markdown syntax (Cheat Sheet)

3.12 Tables
You can use tables for a clear arrangement of data and texts.

3.12.1 Simple table (Pipe Table)

Pipe tables are created from vertical bars | and hyphens - as well as the texts. You can use
colons : in the separator between the header and the rest of the lines to specify the alignment
of the text.
Table indented with the text:

| tables | are | great |

| ----------- |:-------------:| -----:|
| column 1 is | left aligned | 456 |
| column 2 is | centered | 123 |
| column 3 is | right aligned | 0815 |

Appearance
tables are great
column 1 is left aligned 456
column 2 is centered 123
© Siemens AG 2023 All rights reserved

column 3 is right aligned 0815

Table over full page width without indentation with prefixed attribute [pageWidth]:

{.pageWidth}
| tables | are | great |
| ----------- |:-------------:| -----:|
| column 1 is | left aligned | 456 |
| column 2 is | centered | 123 |
| column 3 is | right aligned | 0815 |

Appearance
tables are great
column 1 is left aligned 456
column 2 is centered 123
column 3 is right aligned 0815

Note Tables are always to be considered as independent paragraphs, i.e. there must always be a
blank line before and after a table.

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 21
 3 Markdown syntax (Cheat Sheet)

3.12.2 Complex table (Grid Table)

Grid tables additionally use the plus sign + and equal sign =. The plus sign defines the nodes of
the grid lines and the equal sign defines the separation between the header row and the rest of
the rows. Grid tables allow multiple rows per cell as well as connecting a cell across multiple
columns.
The following figure shows you a simple grid table:

+---------+---------+
| Header | Header |
| Column1 | Column2 |
+=========+=========+
| 1 ab | the second column
| 2 cde |
| 3 f |
+---------+---------+
| Second row spanning
| on two columns
+---------+---------+
| Back | |
| to | |
| one | |
| column | |
© Siemens AG 2023 All rights reserved

Appearance
Header Header
Column1 Column2
1 ab the second column
2 cde
3f
Second row spanning
on two columns
Back
to
one
column

Rules
• A table must be preceded by a blank line, and the table must then start with the column
separator +.
• Each column separator starts with an optional space…
– followed by an optional : to specify left alignment, followed by optional spaces
(alignment can be specified on the first line)
– followed by a sequence of at least one - character, followed by optional spaces
– followed by an optional : to specify the right alignment (or the middle alignment if the
left alignment is also defined)
– followed by optional spaces
• A table header is separated with +========+ instead of +---------+.
• The first line separator must be followed by a regular line.
• A regular line must start with the | character, which starts at the same position as the +
column separator of the first line separator.

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 22
 3 Markdown syntax (Cheat Sheet)

• A regular line can continue a previous regular line if the column separators | are in the
same position as the previous line. If they are in the same position, the column can span
several columns.
• The last column separator | can be omitted.
• A table must not have irregularly shaped cells.
• The respective width of the columns is calculated from the ratio of the total size of the first
table row without considering the +:
+----+--------+----+ would be divided into 4/16 = 25%, 8/16 = 50%, 4/16 = 25%.

A grid table can have cells that span columns as well as rows.

+---+---+---+
| AAAAA | B |
+---+---+ B +
| D | E | B |
+ D +---+---+
| D | CCCCC |
+---+---+---+

Appearance
AAAAA B
B
D E
© Siemens AG 2023 All rights reserved

D B
D CCCCC
A cell can be connected by columns as well as by rows.

+---+---+---+
| AAAAA | B |
+ AAAAA +---+
| AAAAA | C |
+---+---+---+
| D | E | F |
+---+---+---+

Appearance
AAAAA B
AAAAA C
AAAAA
D E F

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 23
 3 Markdown syntax (Cheat Sheet)

3.13 Note boxes

You create note boxes as follows:
The first line contains the keyword. The second line starts with a colon : and FOUR spaces.
This is followed by the text over several lines. The final line is an empty line followed by a
horizontal line --- which is not visible in the document. A blank line before the hint box can also
be generated with --- and a blank line in front of the note box.
The keywords are (English / German):
• NOTE / Hinweis
• NOTICE / Achtung
• CAUTION / Vorsicht
• WARNING / Warnung
• DANGER / Gefahr
• ReadMe / LiesMich

NOTE
: indicates a possible advantage. Has tip character.
: New line in the box.

---
© Siemens AG 2023 All rights reserved

Appearance

Note Indicates a possible advantage, has the character of a Tipp.

NOTICE What is the danger?

What threatens if the danger is disregarded?
How can the danger be avoided?

What is the danger?

What threatens if the danger is disregarded?
CAUTION How can the danger be avoided?

What is the danger?

What threatens if the danger is disregarded?
WARNING How can the danger be avoided?

What is the danger?

What threatens if the danger is disregarded?
DANGER How can the danger be avoided?

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 24
 3 Markdown syntax (Cheat Sheet)

Reference to literature
What to read?
Why?
Read me
© Siemens AG 2023 All rights reserved

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 25
 4 Document TIA Portal project according to “Code2Docu”

4 Document TIA Portal project according to

“Code2Docu”
This chapter describes the necessary steps how to document your TIA Portal project so that you
can create a complete documentation with “Code2Docu”.

4.1 Data storage in the TIA Portal project folder

In the TIA Portal project folder, the information that cannot be integrated in the TIA Portal project
is stored in the directory UserFiles/Code2Docu.
The following files and information are stored in the directory:
Figure: Project folder structure
© Siemens AG 2023 All rights reserved

Relevant for the user:

• images: All images that are used in the documentation are stored here.
This is the initial folder for referencing the images and graphics that “Code2Docu” accesses.
Images can also be stored outside of the project folder structure and will be copied
automatically into the images folder. You can configure such an external image path in the
Settings. For further information please see chapter Dialog box Settings / Code2Docu
options.
You can also store PowerPoint presentations here. The slides of each presentation are
exported as png image files and saved in the same folder as their corresponding
presentation. For further information please see chapter Markdown syntax / Graphics /
Images.
– The background image for the first page in the documentation can also be stored here.
The file must contain the keyword TitlePageBackground in the name and can
additionally contain a prefix, for example LCode2Docu_TitlePageBackground.png.
• GenericTextsCustomized.csv: Generic texts that are not stored in TIA Portal. The user can
customize the texts.
The generic text list is generated from the file.
• styleCustomized.css: Stylesheet for the design of user-defined documentation (user help),
customizable by the user.
• startCode2Docu.bat: Batch file to restart generation without previous export from TIA Portal.

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 26
 4 Document TIA Portal project according to “Code2Docu”

Not relevant for the user:

– highlightJS: JavaScript library for user-defined documentation.
– katex: JavaScript library for user-defined documentation.
– Code2DocuSettings.xml: The settings of “Code2Docu” are saved in the file that the user
specifies with the “Code2Docu” add-in.
– GenericTexts.csv: Generic texts that are not stored in TIA Portal.
– xxx_ChangeLog.xml: Current status of the change history.
– xxx_ChangeLog_Previous.xml: Previous status at the release time of the change history.
– style.css: Stylesheet for the design of user-defined documentation.

Note In the folder AddIn\Code2Docu you will find the previously exported TIA Portal objects as XML
files. The XML files correspond to the regular Openness XML export.

4.1.1 Log file

A log file is written in the Logs folder directly under the TIA Portal project folder and is named
like {TIA_ProjectFileName}_C2D.log.
Every step of generating the documentation is logged.
© Siemens AG 2023 All rights reserved

Note The log file is overwritten at each start of Code2Docu.

4.2 Structure of the TIA Portal project

As mentioned in the introduction, “Code2Docu” was developed to document predefined block
collections (libraries).
For this purpose, you have to group and structure the information according to their affiliation in
the TIA Portal project. You achieve this by storing all related objects in a separate folder with a
suitable name.
The following graphic shows you an exemplary structuring based on the demo project for
“Code2Docu”. All objects and subordinate folders are grouped in the folder Code2Docu. During
generation, the names of the subordinate folders are used for the designation of the chapters.

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 27
 4 Document TIA Portal project according to “Code2Docu”

Figure: Project structure in TIA Portal

© Siemens AG 2023 All rights reserved

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 28
 4 Document TIA Portal project according to “Code2Docu”

Note The chapter names are second order headings. If further folders are subordinate to the
subordinate folder, then the chapter name is composed of the names of all subordinate
folders, whereby the individual folder names are separated with /.
The use of the characters / and \ must be omitted in the designation of the folder names,
since these are used by the operating system for the storage paths.

Note “Code2Docu” can export the standard program or a software unit.

A mixed configuration of standard program and software unit or multiple software units is not
supported.

Note Safety Software Unit's (Safety Unit) have been introduced in TIA Portal V18, and therefore
not supported, as the Development of “Code2Docu” stays on the TIA Portal V17 API.

4.3 Multilingualism in TIA Portal project

“Code2Docu” uses the multilingualism of TIA Portal to generate the documentation in all
projected project languages. You activate the desired languages in the TIA Portal project.
© Siemens AG 2023 All rights reserved

4.3.1 Activate project languages

To select the desired project languages, double-click on Project languages in the project
navigation under Languages & resources.
Then activate the languages that are to be available as project languages.
Figure: Activate project languages

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 29
 4 Document TIA Portal project according to “Code2Docu”

4.3.2 Edit multilingual texts / comments

You can edit the multilingual texts in different ways.

You can change or edit the texts in the following places:
• Directly in the text field: the currently set editing language in the project is always used here.
You can switch the editing language in the Task Card Tasks.
• In the object's properties: All project languages are displayed here. Here you can edit the
texts of the block interface and the program (see figures).
Figure: Multilingualism in properties of the building block interface
© Siemens AG 2023 All rights reserved

Figure: Multilanguage in properties of the block program

• In the exported text list of the object.

– You export the texts in the properties window of the object under Texts, as all texts of
an object are displayed here.
– You can edit the text list or forward it for translation. The text list can be edited with e.g.
Microsoft Excel and checked for spelling.
– You then import the translated text list back into the object's properties window.

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 30
 4 Document TIA Portal project according to “Code2Docu”

Figure: Multilingualism in properties of the block

© Siemens AG 2023 All rights reserved

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 31
 4 Document TIA Portal project according to “Code2Docu”

4.4 General and generic project and document information

The part with the generic project information is mandatory. A non-observance leads to an
incorrect generation!

CAUTION

General and generic project and document information for the introduction and appendix is
provided outside the regular program blocks in a separate block. For this a block in the
programming language SCL is used, which contains this information for “Code2Docu”. This block
is conveniently named with the name of the library and _Description, e.g.
LCode2Docu_Description for the demo project of this documentation.

Note The block can then be delivered together with the library. This way, the entire documentation
of the project is delivered with it.

The document information is divided into three SCL regions in the block.
Figure: Block LCode2Docu_Description
© Siemens AG 2023 All rights reserved

Note Change the background image on the first page:

The new image must contain the keyword TitlePageBackground in the file name (for example
LCode2Docu_TitlePageBackground.png), be saved in the images folder in png or jpg format
and correspond to the aspect ratio of an DIN A4 page (297mmx210mm).
A warning will be issued if the aspect ratio deviates more than 10% from the DIN A4 format,
below that the graphics will be pasted (stretched or compressed) into the page format.

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 32
 4 Document TIA Portal project according to “Code2Docu”

REGION INFO
This region contains all the generic information needed to generate the documentation.
The information is used to store the document, as well as used in the cover page and footers.

REGION INFO
(/*
title: Document title "Code2Docu Demo for TIA Portal STEP 7".
subTitle: Subtitle "STEP 7 Basic/Professional V17 (TIA PORTAL)".
fileName: FileNameForTheOverallDocumentation.
projectId: 1000000
link: https://support.industry.siemens.com/cs/ww/en/view/100000000
version: V1.0.0
date: 04/2022
classification: "Empty" "Free to use" "Internal" "Confidential" "Strictly
Confidential
*/)
END_REGION INFO

Note The Version can be specified by typing the description block, then the specification in the
block header is not necessary.
The specification of Date is optional. If this is not used and is not present, then the current
© Siemens AG 2023 All rights reserved

date of the computer is used.

Note The file name of the overall documentation is then composed of the components of the Info
region as follows:
projectId_fileName_version_LANGUAGE
The file name as well as the file path follow the Universal Naming Convention (UNC) and
therefore must not contain the following characters: <>:"/\|?*

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 33
 4 Document TIA Portal project according to “Code2Docu”

REGION PREAMBLE
This region contains all general information, which is necessary for the use of the library. After
the preamble the generated descriptions of the objects (PLC blocks, data types and global
constants) follow in the documentation.

REGION PREAMBLE
(/*
Here the information of the introduction is written in a multilingual comment.
In these comments you can structure the text using MarkDown syntax and mark it up
accordingly.
*/)
(/*
Several multilingual comments are allowed in the REGION
*/)
END_REGION PREAMBLE

REGION APPENDIX
This region contains the appendix of the documentation. It is inserted in the document after the
global constants and before the global change history of the document.

REGION APPENDIX
(/*
Here the information of the appendix is placed in a multilingual comment.
In these comments you can structure the text using MarkDown syntax and mark it up
© Siemens AG 2023 All rights reserved

accordingly.
*/)
(/*
Several multilingual comments are allowed in the REGION
*/)
END_REGION APPENDIX

Note With the multilingual comment fields, it is possible to integrate the description in multiple
languages.
It is also possible to split the description between several multilingual comments within the
region.

Note Multilingual comment fields are limited in the number of characters. If the character budget of
a multilingual comment is exhausted, create a new multilingual comment block.

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 34
 4 Document TIA Portal project according to “Code2Docu”

4.5 Folder information / descriptions (optional).

A folder, like the whole document, can have an introductory description and an appendix.
For this, as with the entire document, a block in the programming language SCL is used, which
contains and provides this information for “Code2Docu”.
This block is called also here expediently with the name of the library, a further classification
and _Description, e.g. for this documentation LCode2Docu_FOLDERNAME_Description.

Note With the options of “Code2Docu” it is possible to hide a leading numeric prefix in the
documentation (only for folder names). Numeric prefixes are often used for sorting and
structuring in TIA Portal and are not helpful in the documentation and make it difficult to read.
The prefix is removed according to the scheme number(-_. blank)name.
To do this, activate in the Code2Docu settings the option:
Settings > Rendering options > Remove number prefix from folder name.

Note The module can then be delivered together with the library. This way, the entire
documentation is delivered with the project.

The folder description block contains two SCL region's for the content of this information.
© Siemens AG 2023 All rights reserved

Figure: Block LCode2Docu_DemoBlocks_Description

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 35
 4 Document TIA Portal project according to “Code2Docu”

REGION PREAMBLE
This region contains all the general information that is valid and important for this folder. The
preamble is followed by the descriptions of the objects in the documentation.

REGION PREAMBLE
(/*
Here the information of the introduction is written in a multilingual comment.
In these comments you can structure the text using MarkDown syntax and mark it up
accordingly.
*/)
(/*
Several multilingual comments are allowed in the REGION
*/)
END_REGION PREAMBLE

REGION APPENDIX
This region contains the appendix for the folder description. It is inserted in the document after
the descriptions of the objects.

REGION APPENDIX
© Siemens AG 2023 All rights reserved

(/*
Here the information of the appendix is placed in a multilingual comment.
In these comments you can structure the text using MarkDown syntax and mark it up
accordingly.
*/)
(/*
Several multilingual comments are allowed in the REGION
*/)
END_REGION APPENDIX

Note If further subfolders are used in this folder, the appendix is given its own subchapter in the
document, named like the folder itself, with the additional extension / appendix.

Note Due to the multilingual comment fields, it is possible to integrate the description in several
languages.
It is also possible to split the description between several multilingual comments within the
region.

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 36
 4 Document TIA Portal project according to “Code2Docu”

4.6 PLC blocks

For the documentation of PLC blocks information of the blocks is used as follows:
• The block name and type for the heading.
– If the block is typed, the library name is used together with type and library version.
• The block author from the properties as block text after the heading.
• The multilingual comment from the properties for the short description. The detailed
description of the function and the block header can also be inserted here. This is especially
useful if the block is know-how protected.
• The variables are represented in the interface description in the form of a block diagram of
the block:
– Name
– Variables In-, Out-, InOut and Return value (for FCs), incl. data type.
• The variables of Input, Output (with Return value for FCs) and InOut are presented in the
form of tables with the following information (multilingual):
– Name
– Data type
– Default value (for inputs in FBs)
– Retain (Optional: Include Retain in Documentaion)
– Comment
© Siemens AG 2023 All rights reserved

• Block constants are represented as status code table.

• The data structures of PLC data types used in the function block interface can be listed.
• A detailed description of the function can be inserted using a region or network
(multilingual).
• ProDiag Supervisions can be included as a table of supervised parameters.
• The change history of the block is inserted from the generic block header.

Note In this chapter the examples from the demo project are used.

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 37
 4 Document TIA Portal project according to “Code2Docu”

4.6.1 Title, header and short description

From the block properties, the fields General/Name, Information/Author and

Information/Comment as well as the block type are used for the title and the short description.
The two figures below show the relationship:
Figure: Information from block properties in TIA Portal

Figure: Information from block properties in the documentation

© Siemens AG 2023 All rights reserved

Note For the block short description MarkDown can be used.

Note Since no spaces are allowed in the Author field, underscores _ are used for it, which are
replaced by spaces in the documentation. If the Author field is empty, or the text for the
Author keyword in GenericTextsCustomized.csv is empty, the paragraph for it will not be
displayed.

4.6.2 Interface description

Input, Output and InOut Parameters

A block diagram is generated from the block interface information and the individual block
parameters are displayed as a table.
For the documentation of the Input, Output and InOut parameters the following properties are
used for documentation:
• Parameter Name
• Data type & Default value (for inputs in FBs)
• Retain (visible only for Inputs, InOut, Outputs if activated and a non retain value is present)
• Comment (Multilingual)

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 38
 4 Document TIA Portal project according to “Code2Docu”

The following figures show the relationship:

Figure: Block interface in TIA Portal

Figure: Block interface in the documentation

© Siemens AG 2023 All rights reserved

Note In the block diagram, you can use the following setting of “Code2Docu” to specify whether
the data types are on the outside and the parameter names on the inside, or vice versa:
Settings > Rendering options > Block Interface Image.

Note You can achieve a line break within a comment field of a variable by placing two spaces at
the desired position of the line break. This way the texts remain visible in TIA Portal and are
also editable in the comment field.

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 39
 4 Document TIA Portal project according to “Code2Docu”

Retain static parameters

For variables with set retentivity this information can also be included in the documentation, this
option is activated in the settings (Include Retain in Documentation).
For the documentation of Retaining Static Parameters the following properties are used for
documentation:
• Parameter Name
• Data type
• Default Value
• Retain (Only elements that are not ‘NonRetain’)
• Comment (Multilingual)Block interface with retentive variables
For the three possible settings of the retentivity values it is possible to use unicode symbols
(keyword starting with X for value). The displayed symbols for retain variables are defined in the
file UserFiles\Code2Docu\GenericTextsCustomized.csv in the project folder.
Table: Remanence translation values (English;German) of GenericTexts
Key English German Rendering Description
Retain; Retain Retain Retain Table Header
XRetain \u2713; \u2713 ✓ Retain Value
XNonRetain X X X Retain Value
XSetInIDB O O O Retain Value
© Siemens AG 2023 All rights reserved

Figure: Block interface with retentive variables

Note You can use the following setting of “Code2Docu” to render Retain information: Settings >
Rendering options > Include retain in documentation.

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 40
 4 Document TIA Portal project according to “Code2Docu”

Predefined values in Interface

Predefined values in the interface module are displayed as shown in the following image:

Note You can use the following “Code2Docu” setting to specify whether the predefined values
should be displayed: Settings > Rendering options > Display predefined Values....
© Siemens AG 2023 All rights reserved

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 41
 4 Document TIA Portal project according to “Code2Docu”

Constants of the block interface

Constants defined in the block are filtered using keywords to generate a status and error code
table.
The following keywords are provided for this purpose:
• STATUS
• INFO
• DIAG / DIAGNOSTIC
• ERR / ERROR
• WARN / WARNING
• ALARM
• MAINTENANCE
• PROC / PROCESS
• RET / RETURN
The figures below show the relationship:
Figure: Block constants in TIA Portal
© Siemens AG 2023 All rights reserved

Figure: Block constants in the documentation

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 42
 4 Document TIA Portal project according to “Code2Docu”

Note The description and the definition of status and error handling in PLC blocks can be found in
the Programming Style Guide in chapter Design Guidelines/ Architecture in rule DA013 /
Return status / error via “status”/ “error”.
Programming style guide for SIMATIC S7-1200/ S7-1500

Note A line break within a comment field of a constant is achieved by placing two spaces at the
desired position of the line break. This way, the texts remain visible in TIA Portal and can
also be edited in a meaningful way in the comment field of the constant.
© Siemens AG 2023 All rights reserved

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 43
 4 Document TIA Portal project according to “Code2Docu”

PLC data types in the block interface

If PLC data types are used in the block parameters for Input, Output or InOut parameters, you
can include them directly in the block documentation. The data structures of the PLC data types
are listed directly after the block interface.

Note So that the PLC data types are listed in the block description, you must activate the following
option in the settings of “Code2Docu”:
Settings > Rendering options > Include UDTs beside the block documentation.

Figure: PLC data types in the documentation

© Siemens AG 2023 All rights reserved

More information about the documentation of PLC data types can be found in chapter “PLC
data types”.

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 44
 4 Document TIA Portal project according to “Code2Docu”

4.6.3 Functional description

The function description of a block is embedded in SCL in a region with the name DESCRIPTION
and multilingual comment fields.
Due to the multilingual comment fields it is also possible here to integrate the description in
several languages. As in the general part, it is also possible here to split the description into
several multilingual comments within the region.
The following figures show the relationship:
Figure: Function description of a SCL block in TIA Portal

Figure: Functional description in the documentation

© Siemens AG 2023 All rights reserved

Note For functional block description MarkDown can be used for markup.

Note In the programming languages FBD, LAD and STL the second network with the title
Description is used instead of the region. Insert the text into the comment field. Do not use
SCL networks and comment characters, but only the comment field of the network.

Figure: Functional description of a FBD block in TIA Portal

Note In order to keep the hierarchy levels and to make it easier for the user to use, the headings in
the descriptions will again start at the first level (#). “Code2Docu” automatically moves to the
fourth and fifth level.
This means that only levels four (block header) and five (block header with table of contents)
are available to the user in the function description.

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 45
 4 Document TIA Portal project according to “Code2Docu”

Note Through the multilingual comment fields it is possible to integrate the function description in
several languages.
It is also possible to split the description into several multilingual comments within the region.

Together with the block comment

In the case of know-how protected blocks accessing the regions is not possible. Thus the
functional description can also be entered into the multilingual comment field
Information/Comment. The functional description must be separated from the short description
using the keyword [DESCRIPTION] as shown in the next figure:
Figure: Short und functional description in the comment field of a block
© Siemens AG 2023 All rights reserved

Note The short description must always be the very first entry in the comment field.

Note If a block without know-how protection contains the functional description in the comment
field as well as in the regions then these texts will be concatenated in the generated
document, where the functional description from the comment field comes first.

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 46
 4 Document TIA Portal project according to “Code2Docu”

4.6.4 ProDiag Supervisions

If there are ProDiag Supervisons defined, they can be included in the documentation.
Supervisions are displayed as a table containing the following columns:
• Supervised Parameter,
• Trigger,
• Type and
• Category.
Figure: ProDiag Supervisions Table

Note In order to include the ProDiag Supervisions in the documentation, you must activate the
following option in the settings of “Code2Docu”:
Settings > Rendering options > Include ProDiag Supervisions.
© Siemens AG 2023 All rights reserved

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 47
 4 Document TIA Portal project according to “Code2Docu”

4.6.5 Change history

The generic block header contains the change history in addition to the general block
information. “Code2Docu” uses this for the block documentation. The block header is in SCL
always at the first place in the block and is surrounded by the region with the name BLOCK INFO
HEADER.
From the Change log table, in addition to the change history for the block, an overall change
history is also created, which is described in the chapter “Global change history”.
The following figures show the relationship:
Figure: Change history of an SCL block in TIA Portal.
© Siemens AG 2023 All rights reserved

Note The change history is recorded in the reference language, regardless of the type of
programming language selected for the block.
If this does not contain any text, the language setting EN-US is searched for and then the first
available one is used.

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 48
 4 Document TIA Portal project according to “Code2Docu”

Figure: Change history in the documentation

Note Generating the history directly in the block documentation is optional and can be enabled
and disabled via the following Code2Docu setting:
Settings > Code2Docu options > Generate single Changelog beside a block.

Note In the programming languages FBD, LAD and STL the first network with the title BLOCK INFO
HEADER is used instead of the region. The text is inserted into the comment field. Do not use
SCL networks and comment characters, only the comment field of the network.
© Siemens AG 2023 All rights reserved

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 49
 4 Document TIA Portal project according to “Code2Docu”

Figure: Change history of a FBD block in TIA Portal

Together with the block comment

In the case of know-how protected blocks accessing the regions is not possible. Thus the block
header can also be entered into the multilingual comment field Information/Comment. The block
header must be separated from the short and functional descriptions using the keyword
[BLOCK_INFO_HEADER] as shown in the next figure:
© Siemens AG 2023 All rights reserved

Figure: Functional description and block header in the comment field of a block

Note Code2Docu processes the block header in the reference language.

If this does not contain any text, the language setting EN-US is searched for and then the first
available one is used.

Note If a block without know-how protection contains the block header in the comment field as well
as in the regions then the change history entries are concatenated based on their date and
version number. This could lead to an undesirable result. Please keep the change history
only in one place, either in the comment field or in the regions/networks.

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 50
 4 Document TIA Portal project according to “Code2Docu”

4.7 PLC data types

For the documentation of PLC data types, information of the data types are used as follows:
• The name of the data type is used for the heading.
• The comment from the properties is used for the description (Multilingual).
• The variables are displayed in the form of a table:
– Name
– Data type
– Default value
– Comment (Multilingual)
• Subordinate structures:
– Variables of type PLC data types (UDT) are listed with the name of the PLC data type.
– Variables of type Struct are listed within the table with all subordinated elements,
because they have no own PLC data type.

Note In this chapter the examples from the demo project are used.

Note In order to keep the hierarchy levels and make it easier for the user, the descriptions start
© Siemens AG 2023 All rights reserved

with the headings on the first level (#). “Code2Docu” automatically moves to the fourth and
fifth level.
This means that only levels four (block header) and five (block header with table of contents)
are available to the user in the function description.

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 51
 4 Document TIA Portal project according to “Code2Docu”

4.7.1 PLC data type with elementary data type variables

The following figures show a PLC data type with elementary data types in TIA Portal and in the
documentation.
Figure: PLC data type and its properties in TIA Portal
© Siemens AG 2023 All rights reserved

Figure: PLC data type in the documentation

Note You can achieve a line break within a comment field of a variable by placing two spaces at
the desired position of the line break. This way the texts remain visible in TIA Portal and can
also be edited in a meaningful way in the comment field of the variable.

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 52
 4 Document TIA Portal project according to “Code2Docu”

4.7.2 PLC data types with subordinate structures

If subordinate anonymous structures of type Struct are used in a PLC data type, they are
displayed indented as subordinate elements in the data type itself.
Figure: PLC data type with subordinate Struct in TIA Portal

Figure: PLC data type with subordinate Struct in the documentation

© Siemens AG 2023 All rights reserved

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 53
 4 Document TIA Portal project according to “Code2Docu”

4.8 Global constants

Global constants are represented in tables in the documentation in two ways.
• Status and error codes
Here the constants are displayed sorted by their status code in ascending order to make it
easier to find a description belonging to the code.
• General constants
Here the constants are displayed sorted alphabetically in ascending order by their name.
Both tables differ by their names. Their representation as well as the keywords are described in
the following chapters.

Note This chapter uses examples from the demo project.

4.8.1 Status and error codes

The following notation and naming apply to a global status and error code table:
LibraryPrefix_KEYWORDxxxx: e.g. LCode2Docu_ErrorCodes.
All other notations are treated as standard constants table (see chapter “General constants”).
The same keywords are used as for local constants:
© Siemens AG 2023 All rights reserved

• STATUS
• INFO
• DIAG / DIAGNOSTIC
• ERR / ERROR
• WARN / WARNING
• ALARM
• MAINTENANCE
• PROC / PROCESS
• RET / RETURN
Status and error codes are displayed in a table with the code in the left column and the name
with the description from the comment field (Multilingual) in the right column.

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 54
 4 Document TIA Portal project according to “Code2Docu”

Figure: Global error and status constants in TIA Portall

Figure: Global error and status constants in the documentation

© Siemens AG 2023 All rights reserved

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 55
 4 Document TIA Portal project according to “Code2Docu”

4.8.2 General constants

Global constants are displayed in a table with the name and value of the constant in the left
column and the description from the comment field (Multilingual) in the right column.
Figure: Global constants in TIA Portal

Figure: Global Constants in the documentation

© Siemens AG 2023 All rights reserved

Note A line break within a comment field of a constant is achieved by placing two spaces at the
desired position of the line break. This way, the texts remain visible in TIA Portal and can
also be edited in a meaningful way in the comment field of the constant.

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 56
 4 Document TIA Portal project according to “Code2Docu”

4.9 Global change history

4.9.1 General

Based on the change information from the blocks, “Code2Docu” can generate a global change
history. To do this, the current status is compared with the last release status of the history and
the difference is formed from this.
To generate a release state, you must save the current change history as a release state, so
that for the next generations the difference can be formed again over the changes.
To do this, activate the Store Changelog for RELASE option in the Code2Docu add-in before
generation. With it the “Current state” of the change history is stored with the next generation
and compared with the “Previous state”.
Figure: Activate Store Changelog for RELASE in TIA Portal
© Siemens AG 2023 All rights reserved

Note The option is only active for one generation run and is automatically reset.

Figure: Change history in TIA Portal

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 57
 4 Document TIA Portal project according to “Code2Docu”

Figure: Total change history in the documentation

Note The generation of the overall change history is optional and can be enabled and disabled via
the Code2Docu settings:
Settings > Code2Docu options > Generate full Changelog overall versions.
© Siemens AG 2023 All rights reserved

Note The overall change history can be sorted ascending or descending, i.e. V1.0.0 before V2.0.0
or vice versa:
Settings > Rendering options > Sort overall Changelog > Newest version first or Oldest
version first

Note Note that you have to adjust the version and also the date in the generic part of the
description (region BLOCK INFO HEADER / Version and Date).
This is not necessary if the version is automatically generated from the type version of the
description block, as well as the date field is not present and thus the current date of the
computer is used.

4.9.2 Separate change history

You can generate a separate file for the change history. The format corresponds to that of the
overall documentation.

Note You can enable or disable the generation of the separate overall change history via the
following Code2Docu setting:
Settings > Code2Docu options > Generate separate Changelog File.

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 58
 5 Operation of the “Code2Docu” add-in

5 Operation of the “Code2Docu” add-in

This chapter describes the operation and settings of the add-in “Code2Docu”.

5.1 Calling the add-in

The add-in is already installed and activated.
To run the add-in, proceed as follows:
1. Right-click on a block folder or the Program Blocks folder.
2. Select the “Code2Docu” add-in from the context menu.
–> The main menu of the add-in will be displayed.

Figure: Calling the Add-In at the block folder in TIA Portal

© Siemens AG 2023 All rights reserved

Note that all software dependencies expected in the project are also present / installed in the
TIA Portal environment.
If a software package, an HSP, a GSD or a GSDML is not installed, the export of the objects
CAUTION
and thus the generation of the documentation is aborted.

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 59
 5 Operation of the “Code2Docu” add-in

5.2 Functions in the main menu

The “Code2Docu” add-in has several functions.
Figure: Functions in the main menu of the “Code2Docu” add-in

Generate Documentation
With the function Generate Documentation you start the generation of the documentation for all
projected languages.

Generate Documentation for active Language

© Siemens AG 2023 All rights reserved

With the function Generate Documentation for active Language you start the generation of the
documentation for the currently active language in TIA Portal.

Store Changelog for RELEASE

Activate the check box Store Changelog for RELEASE to store the current status of the change
history for a new release during the next generation. During generation, the difference is then
formed over the changes and updated in the documentation. (see chapter “Global change
history”).

Cleanup Export folder

With the function Cleanup Export folder you clean up the folder AddIn\Code2Docu in the project
directory. All export files in the folder are deleted and old states are removed. This is useful, for
example, if an object has been renamed in TIA Portal. The folder can also be cleaned
automatically at each generation. To do this, you must activate the option Cleanup export
folder before to export in the settings under Settings/Export options.

Cleanup Docu folder

With the function Cleanup Docu folder you delete the folder UserDocumentation with the entire
documentation in the project directory under UserFiles. The folder can also be cleaned up
automatically with each generation. To do this, you must activate the option Cleanup Docu
folder prior to export in the settings under Settings/Export options.

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 60
 5 Operation of the “Code2Docu” add-in

Sync Userfiles Folder from LS to SV (TIA Portal >= V17)

When working with a multiuser project, you can synchronize the files and commit them into the
server with the function Sync Userfiles Folder from LS to SV. After transfer and
synchronization, an automatically generated message is entered as a revision comment.

Note The synchronization needs to be done before a check-in or refresh is executed.

Settings
With Settings, you open the menu for the settings of the add-in.

5.3 Settings menu

In the Settings menu you can define settings for the add-in and for the documentation.
Figure: Settings menu of the “Code2Docu” add-in
© Siemens AG 2023 All rights reserved

Open Settings
With Open Settings you open the dialog window for the settings. The possible settings are
described in the following chapters.

Open Settings file

With Open Settings file you open the file Code2DocuSettings.xml in the project folder
\UserFiles\Code2Docu\, where the settings defined here are stored.

Add Name to exclude's

With the function Add Name to exclude's you can add selected objects to the exclude list. This
excludes these objects from the generation of the documentation.
Entire folders or individual objects are possible. If a folder is selected, its subfolders are also
affected. You need this function, for example, for modules such as SafetyRuntimeGroup, for
which no documentation can be generated.

Remove Name from exclude's

With the function Remove Name from exclude's you remove a selected object from the exclude
list again.

Clear exclude's
With Clear exclude's you remove all objects from the exclude list and thus reset them.

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 61
 5 Operation of the “Code2Docu” add-in

5.3.1 Dialog box settings / Export options

Open the Settings dialog box with the Open Settings function. After opening, the Export
options tab is displayed with the export options.
Figure: Dialog box settings / Export options
© Siemens AG 2023 All rights reserved

General area
Cleanup Export folder prior to export
With the option Cleanup Export folder prior to export the folder AddIn\Code2Docu in the
project directory is automatically cleaned up at each generation. All export files in the folder are
deleted and old states are removed. This is useful, for example, if an object has been renamed
in TIA Portal.
Cleanup Docu folder prior to export
With the option Cleanup Docu folder prior to export the folder UserDocumentation in the
project directory under UserFiles with the complete documentation is automatically deleted at
each generation.

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 62
 5 Operation of the “Code2Docu” add-in

Compile prior to export

Activate the option Compile prior to export if you want to compile the TIA Portal project
before export and generation.

Export area
Export UDTs for rendering
With the option Export UDTs for rendering the export of user defined data types can be
deactivated, if no documentation of these is desired.
Export global TagTables to render global constants
The Export global TagTables to render global constants option can be used to disable the
export of user-defined data types if no documentation of them is desired.

Note Dependent options (rendering options) are automatically disabled when export is disabled
and enabled when export is enabled.
© Siemens AG 2023 All rights reserved

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 63
 5 Operation of the “Code2Docu” add-in

5.3.2 Dialog box Settings / Code2Docu options

Select the Code2Docu options tab to set the options for Code2Docu.
The tab is divided into three sections:
• General
• Document
• ChangeLog

Figure: Dialog box Settings / Code2Docu Options

© Siemens AG 2023 All rights reserved

General area
In this section you define general settings for “Code2Docu”.
Overwrite Stylesheet for HTML docu
The option Overwrite Stylesheet for HTML docu allows overwriting the stylesheet for the
HTML documentation with the default stylesheet of “Code2Docu”.

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 64
 5 Operation of the “Code2Docu” add-in

Overwrite Code2Docu Script for HTML docu

The option Overwrite Code2Docu Script for HTML docu allows you to overwrite the Java script
for the HTML documentation with the standard Java script from “Code2Docu”.
Overwrite Text file for default docu texts
The option Overwrite Text file for default docu texts allows to overwrite the text file for the
generic texts.
Show extended log output in CLI
If you activate this option, extended information is displayed in the command line interface (CLI)
during generation. This can be useful if the generation stops unexpectedly in order to facilitate a
more precise localization of a possible problem.
However, all steps during the creation of the documentation are recorded in a log file ( Project
folder/Logs).

Document area
In this section you define settings for the documentation.
Generate single Documentation files
The Generate single Documentation files option generates user-defined documentation (user
help) for TIA Portal for each block. You can call the user help for each block with the key
combination Shift+F1.
Generate overall Documentation file
With the option Generate overall Documentation file an overall documentation for the TIA
Portal project is generated.
© Siemens AG 2023 All rights reserved

ChangeLog area
In this area you define settings for the change history.
Generate single Changelog beside a block
With the option Generate single Changelog beside a block you can generate a change history
for each block.
Generate full Changelog overall versions
With Generate full Changelog overall versions you can generate a project wide change
history.
Generate separate Changelog File
With Generate separate Changelog File you generate a separate file for the change history.

Image Path area

You can select an external folder outside of the project folder structure for your images. Button
... shows a folder open dialog window or you can directly enter the path into the text field.
If no image path is selected here then Code2Docu will look for the images referenced in the
documentation only in the images folder inside the project folder structure.
If a path has been selected then the option Generate overall Documentation file will be set
automatically and deactivated (grayed out). This means that the overall documentation will
always be generated if you select an external folder containing your images.

Note The image files in the folder defined in this setting will be copied to the images folder in the
project folder structure during documentation generation. Please consider that images
having the same file names will be overwritten (updated).

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 65
 5 Operation of the “Code2Docu” add-in

5.3.3 Dialog box Settings / Rendering options

Select the Rendering options tab to set the options for the display (rendering).
The tab is divided into four sections:
• General
• Block Interface Image
• Sort overall ChangeLog
• Full ChangeLog is…

Figure: Dialog box Settings / Rendering Options

© Siemens AG 2023 All rights reserved

General
In this section you define general settings for the display.
Remove number prefix from folder name
With Remove number prefix from folder name you can remove a numeric prefix in the
documentation for sorting folders in the TIA Portal project.

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 66
 5 Operation of the “Code2Docu” add-in

Show return values if type is "VOID "

With Show return values if type is "VOID" you can show the return value of a function (FC)
even if it has the data type VOID.
Include UDTs beside the block documentation
With the option Include UDTs beside the block documentation you can include user defined
data types, which are used in the In-, Out- and InOut-area of the block interface, directly in the
documentation of the blocks.
Include UDTs as separate chapter in documentation
With the option Include UDTs as seperate chapter in documentation you can include a
chapter for user defined data types in the overall documentation.
Include UDTs with nested UDT's in UDT's
With the option ‘Include UDTs with nested UDTs in UDTs’, you can specify that subordinate
UDTs are displayed directly instead of just as a simple data point.
Include global Constant chapter in documentation
With the option Include global Constant chapter in documentation you can include a chapter
for global constants in the overall documentation.
Show Retain for Programming block
With Include Retain in documentation the Retain information will be rendered in the block
tables of the documentation for Inputs, InOut and Static interface members.

Note Retain will only be shown if Interface parameters have other values set as ‘NonRetain’.
Only static interface parameters are rendered that have ‘Retain’ or ‘SetInIDB’ values, the
© Siemens AG 2023 All rights reserved

NonRetain static elements are ignored.

Note The displayed symbols for Retain are defined in the ‘GenericTextsCustomized.csv’ and can
be customized by the user.
You can find the file in the TIA Portal project folder >
UserFiles\Code2Docu\GenericTextsCustomized.csv.

Include ProDiag Supervisions

With the option Include ProDiag Supervisions you can include the supervisions as a table in
the documentation. Supervisions can be created in the window Options under the tab
Supervision definitions.
Here you have the following additional options:
• Show categories and subcategories inline: The specified categories and subcategories
of ProDiag Supervisions will be displayed in a single line separated by a preconfigured
character. The categories are separated by newlines if this option is not selected.
• Show default category if not specified: A preconfigured default text will be displayed
instead of the category / subcategory 1 / subcategory 2 that is not specified in the
Supervision.

Note The category separator as well as the default placeholder text for not specified categories
are defined in ‘GenericTextsCustomized.csv’ and can be customized by the user.
You can find the file in the TIA Portal project folder >
UserFiles\Code2Docu\GenericTextsCustomized.csv.

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 67
 5 Operation of the “Code2Docu” add-in

Display Predefined Values…

The option Display Predefined Values... enables preset interface parameters / values to be
displayed in the documentation if they are available.
• ...in Parameter Table: In the interface table
• ...in Block Image: In the block diagram of the block

Block Interface Image

In this area you select how the block interface parameters are displayed in the block diagram.
You have the choice between:
• Tag names inside, Type outside (Default): Variable names inside, Type outside.
• Tag names outside, Type inside: Variable names outside, Type inside

Sort overall ChangeLog

In this area you select the order for the display of the change history.
You have the choice between:
• Newest version first: Newest version first
• Oldest version first: Oldest version first

Full ChangeLog is…

In this section you choose whether the change history should be displayed as a separate
chapter.
© Siemens AG 2023 All rights reserved

You have the choice between:

• ...separate Chapter: Own chapter
• ...belongs to the Appendix: Subchapter of the "Appendix

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 68
 6 Location of documentation

6 Location of documentation

6.1 User-defined documentation for global TIA Portal libraries

User-defined documentation (user help) can be provided for each object in order to explain the
functionality and its use to the users of the objects. The user-defined documentation per object
is generated based on the project languages and stored as HTML file in the following folder of
the project:
• LANGUAGE: UserFiles\UserDocumentation\<LANGUAGE>\Library Types
• English: UserFiles\UserDocumentation\en-US\Library Types
• German: UserFiles\UserDocumentation\de-DE\Library Types
Images for the documentation and other required files are stored in the following folder of the
project:
• UserFiles\Code2Docu
You can call the user-defined documentation for an object in the project navigation with the key
combination <Shift+F1>. The respective help is always opened with the standard program
defined in Microsoft Windows.
In order to be able to call the user-defined documentation of the objects also in the task card
Library and in the library view, you must copy the complete folder
UserFiles\UserDocumentation with the help files and either the complete folder
UserFiles\Code2Docu or only the necessary files from the folder into the project directory of the
© Siemens AG 2023 All rights reserved

library UserFiles.
The following files from the folder UserFiles\Code2Docu are relevant for the global library and
must be provided:
• images: This is where all images used in the documentation are stored.
This is the initial folder for referencing the images and graphics accessed by code2Docu.
• highlightJS: JavaScript library for user defined documentation.
• katex: JavaScript library for user-defined documentation.
• styleCustomized.css: Stylesheet for the design of the user-defined documentation,
customizable by the user.
• style.css: Stylesheet for the design of the user-defined documentation.
• xxx_ChangeLog_Previous.xml: Previous status at release time of the change history.
The following files from the folder UserFiles\Code2Docu are not relevant for the global library
and can be provided:
• Code2DocuSettings.xml: Settings of “Code2Docu”.
• GenericTexts.csv: Generic texts that are not stored in TIA Portal.
• GenericTextsCustomized.csv": Generic texts that are not stored in TIA Portal, customizable
by the user.
Based on GenericTexts.csv the generic text list is generated. Possible changes can be
traced there. A failure due to incorrect adjustments in the ...Customized.csv is thereby
excluded and the system remains updateable.
• xxx_ChangeLog.xml: Current status of the change history.
• startCode2Docu.bat: Batch file to start the generation again, without previous export from
TIA Portal.
If these files are nevertheless delivered, the documentation can be restored with the help of
“Code2Docu” and thus also further maintained.

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 69
 6 Location of documentation

Central directory for user-defined documentation

Alternatively, you can store user-defined documentation in a central directory for all projects.
To define a central storage location for user help, proceed as follows:
1. Select Settings from the Options menu.
2. Open the General > General section.
3. Navigate to the section User documentation.
4. Check the option Display call log for user-defined documentation to display a log of
the call in the Inspector window.
5. Check the Search for user-defined documentation in a central directory option to
store user-defined documentation in a central directory.
6. Specify the path where the documentation for all projects is stored in the Central directory
for user-defined documentation field.

Figure: Central directory for user-defined documentation

© Siemens AG 2023 All rights reserved

Note File names of help files must correspond exactly to the name of the object in TIA Portal.

Note Further information on user-defined documentation can be found in the “SIMATIC STEP 7
Basic/Professional and SIMATIC WinCC” system manual at:
https://support.industry.siemens.com/cs/ww/en/view/109798671/138092722827

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 70
 7 Further information about multiuser projects and libraries

7 Further information about multiuser projects and

libraries
7.1 Documentation of multiuser projects in project server
environment
Since generated documentation is stored only in the project directory of the local session, it is
not automatically available in the server project.
To save generated documentation from a multiuser project in the project server environment,
proceed as follows:
1. Open the server project view of the multiuser project.
2. Select a module.
3. Remove the selection again. (You can then use this to save the server project).
4. In the Explorer, copy the “UserFiles” folder of the local session “LS”.
5. Paste the copied “UserFiles” folder into the server's “SV” folder.
6. Click “Save changes” in the server project view to save the server project.
7. Refresh your local session by clicking on the “Refresh local session” button.

Figure: Workflow in project server environment

© Siemens AG 2023 All rights reserved

Note In the project server environment it is also possible to create an “Exclusive Engineering
Session”. In this session you work on the server project and the documentation is generated
directly in the project folder “SV”.
Note that all other local sessions are locked as long as the “Exclusive Engineering Session”
exists.

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 71
 8 Tips and Tricks / FAQ (Frequently Asked Questions)

8 Tips and Tricks / FAQ (Frequently Asked

Questions)
In this chapter you will find tips and tricks for handling and questions related to “Code2Docu”,
which are not directly related to the tool, but are useful in the environment of it.

8.1 MS Office Word 365 - Document generation fails

If you are using Office 365, then Word may require document confidentiality classification,
depending on system settings. These settings are associated with the MS Office user account
and are not generated. As a result, saving the document is not possible. The documentations
from TIA Portal with “Code2Docu” can therefore only be generated if Word 365 is used offline
(logging out of the user account).

Note Further information on document classification (Microsoft Information Protection / MIP) can
be found under the following link:
https://docs.microsoft.com/en-us/microsoft-365/compliance/information-
protection?view=o365-worldwide

8.2 Help for documentation with MarkDown

© Siemens AG 2023 All rights reserved

There are several support sites for MarkDown on the Internet.

• Online Editor
– https://stackedit.io/
• Table generator
– https://www.tablesgenerator.com/markdown_tables

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 72
 9 Appendix

9 Appendix

9.1 Service and support

Industry Online Support
Do you have any questions or need assistance?
Siemens Industry Online Support offers round the clock access to our entire service and support
know-how and portfolio.
The Industry Online Support is the central address for information about our products, solutions
and services.
Product information, manuals, downloads, FAQs, application examples and videos - all
information is accessible with just a few mouse clicks:
support.industry.siemens.com

Technical Support
The Technical Support of Siemens Industry provides you fast and competent support regarding
all technical queries with numerous tailor-made offers
- ranging from basic support to individual support contracts. Please send queries to Technical
Support via Web form:
siemens.com/SupportRequest
© Siemens AG 2023 All rights reserved

SITRAIN - Digital Industry Academy

We support you with our globally available training courses for industry with practical
experience, innovative learning methods and a concept that's tailored to the customer's specific
needs.
For more information on our offered trainings and courses, as well as their locations and dates,
refer to our web page:
siemens.com/sitrain

Service offer
Our range of services includes the following:
• Plant data services
• Spare parts services
• Repair services
• On-site and maintenance services
• Retrofitting and modernization services
• Service programs and contract's
You can find detailed information on our range of services in the service catalog web page:
support.industry.siemens.com/cs/sc

Industry Online Support app

You will receive optimum support wherever you are with the “Siemens Industry Online Support”
app. The app is available for iOS and Android:
support.industry.siemens.com/cs/ww/en/sc/2067

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 73
 9 Appendix

9.2 Industry Mall

The Siemens Industry Mall is the platform on which the entire Siemens Industry product portfolio
is accessible. From the selection of products to the order and the delivery tracking, the Industry
Mall enables the complete purchasing processing – directly and independently of time and
location:
mall.industry.siemens.com

9.3 Links and Literature

No. Topic
\1\ Siemens Industry Online Support
https://support.industry.siemens.com
\2\ Link to the entry page of the application example
https://support.industry.siemens.com/cs/ww/en/view/109809007
\3\ Link to the TIA Portal Openness manual
© Siemens AG 2023 All rights reserved

https://support.industry.siemens.com/cs/ww/en/view/109773802
\4\ Programming Guidelines and Programming Style guide for SIMATIC S7-1200 and S7-1500
https://support.industry.siemens.com/cs/ww/en/view/81318674
\5\ Library with PLC data types (LPD) for STEP 7 (TIA Portal) and SIMATIC S7-1200 / S7-1500
https://support.industry.siemens.com/cs/ww/en/view/109482396
\6\ Guideline on Library Handling in Tia Portal
https://support.industry.siemens.com/cs/ww/en/view/109747503
\7\ Libraries in the TIA Portal
https://support.industry.siemens.com/cs/ww/en/view/109738702
\8\ LaTeX project
https://www.latex-project.org/
\9\ LaTeX @ Wikipedia
https://en.wikipedia.org/wiki/LaTeX
\10\ LaTeX compendium & LaTex math compendium @ Wiki Books
https://en.wikibooks.org/wiki/LaTeX
https://en.wikibooks.org/wiki/LaTeX/Mathematics
https://en.wikibooks.org/wiki/LaTeX/Advanced_Mathematics
\11\ PanDoc - Document render (Renders mathematics formula, syntax highlighting)
https://pandoc.org/
\12\ OpenXml - DocX & PDF rendering
https://www.nuget.org/packages/DocumentFormat.OpenXml
\13\ Markdig - Markdown parser & rendering
https://github.com/xoofx/markdig
\14\ QRCoder - QR Code rendering
https://github.com/codebude/QRCoder/

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 74
 9 Appendix

9.4 Changelog / History

Version Date Changes
V1.3.0 11/2023 Feat:
– TIA Portal V16 Support added
– Add predefined value to block interface documentation (optional via
settings)
– Insert references do languages and overview in HTML User
Documentation
– Insert reference to Code2Docu in footer of documentation
– Insert documentation for the use of Software Units
– Store CLI output as logfile in project folder
– Integrate TIA Portal V19 in Installer and Updater
FIX:
– Alignment of block image for interface parameter as well as proper line
breaks
– Wrong rendering of Output / InOut and Return values fixed
– Rework Export messages and handling for no supported objects
– Folder look up during rendering of HTML Doc
– Harmonized rendering of short description between Block and UDT's
– LAD/FBC - using network commends only if text heading matches
Update:
– DocX / PDF templates adjusted - mainly more space at page sides.
© Siemens AG 2023 All rights reserved

– Remove delivery of PANDOC installer, check installation and open

download page if not installed
– Remove delivery of .NET Core Runtime installer as it is not longer
necessary
– Update Markdig to V0.32.0
V1.2.0 05/2023 Feat:
– Synchronize LS and SV functionality
– If TIA Portal is online, the Add-In while show a note to go offline and will
do so if accepted
– Add the ability to exchange / add graphic for the title page
– Add parsing and rendering for ProDiag supervisions
– Add parsing for retain tags
– Rendering of global constants and user defined datatypes optional
– Root path option for images, images can be stored in an attached
network drive
– Parse the comment field of FC / FB for functional description and block
info header (KnowHow protected blocks)
– Insert proving of file name chars, if it contains invalid chars - replace them
by _ and write a notice in console app
– Extent prefixes for constant rendering (block and global constants). PROC
/ PROCESS, RET / RETURN
– Extent note box definitions Read me
– Insert Pictures by extracting ppt & pptx presentations
FIX:
– Extent / rework / improve messages in CLI interface in general
– Extend error messages for failed exports
– Extend error message if description is missed
– Extend error message if DocX to PDF rendering fails
– Insert note if no language tag found -> INFO Region missed
– Insert hint for DocX/PDF rendering regarding Office account
– Display exception if PanDoc installation is missed
– AddIn export crash, if option in TIA Portal is missing like a HSP, a
GSD(ML) or a software packed, TIA Portal will not allow openness to
work on the project.
TIA Portal Add-In Code2Docu for generating documentation
Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 75
 9 Appendix

Version Date Changes

– AddIn export crash, if folder structure in TIA Project contains special
characters
– Closing files problem if title attribute in generic info's is empty
|
– OpenXml, relative links not recognized and just shown as Text
– Links in html root user documentation - HOME.htm wrapper link target to
parent, so that the URL in the browser sees always the real url of the doc
– Do not import nested struct members multiple times and border of table if
containing nested UDTs
– Move exclusive access in front of collecting data to avoid unresponsive
blocking
– Changelog handling for renamed objects
– Folder name and HTML file name does not match
Update:
– Update .NET Core Runtime installer to V6.0.14
– Update Markdig to V0.30.4
– SVG.net to V3.4.4
V1.1.0 04/2022 Public release
V1.0.0 09/2021 First internal pilot release
© Siemens AG 2023 All rights reserved

TIA Portal Add-In Code2Docu for generating documentation

Entry-ID: 109809007, V1.3.0, 11/2023 Generated with Code2Docu 76