Providing Help Files

You can add your own user-defined documentation to the function/function block POUs contained in a released library. This allows you to provide documentation on the function/function block POUs that will help, for example, other users to understand how the POUs have to be used. The user-defined documentation can be provided by CHM help files, HTML5 help files and library description files.

Once you have created your user-defined documentation, you can add one or more help files and library description files to a released library by selecting the file(s) in the 'Release As Library' dialog (see "How to release a library" for details).

With the help files you can provide a detailed description of the function/function block POUs to other users who will include the POUs in their projects. The help information will be displayed for the function/function block POU when the user presses <Shift>+<F1> for the POU selected in the COMPONENTS area or selects the in-place help button for the POU in the worksheet.

Note
The function/function block POU description can be provided in the languages that are supported by PLCnext Engineer (the list of available user interface languages is shown in the 'Extras > Options' dialog under the 'International > International Settings' category). Depending on the active user interface language, the language-specific POU description is displayed when calling the help.

Note
This help topic does not describe the procedures how to create and edit CHM help files and HTML5 files. For details, refer to the documentation provided for the tools or editors you use.

This topic contains the following sections:

CHM help files

For creating a CHM (Compiled HTML help) help file, the HTML Help Workshop (free tool provided by Microsoft) or any other help authoring tool that can produce a CHM file can be used.
For CHM help files to be added to a released library, the following applies:

The CHM help file name must start with the name of the library followed by "_FBFun.chm", for example, "MyLibrary_FBFun.chm" (case must match).
An error message is shown in the Release As Library' dialog when the help file name does not begin with the library name.
Localized CHM help files (chm files in other languages) can be added. The name of the language-specific CHM help files must be as follows:
<libraryname>_<languagecode>_FBFun.chm
where <languagecode> is, for example, en, en-US, de, de-DE, ...
Example: MyLibrary_de-DE_FBFun.chm for German CHM help file.

Contents of a CHM file

Calling a help topic for a function/function block POU

Tip: The HTML Help Workshop provides a decompile command which can be used to extract the files in a CHM help file to a directory on your computer. Use this command to decompile an existing CHM help file for a function/function block library provided with PLCnext Engineer to see which files the CHM help contains.

Note
This help does not describe the procedure how to create CHM help files. For details on this, refer to the documentation provided with the HTML Help Workshop or the help authoring tool you use.

HTML5 help files

PLCnext Engineer provides by default a set a of template files which you can use to create help files in HTML5 format for your FU/FB POUs. The help files are created and edited using the HTML editor available in the 'Description' editor of the FU/FB POU.

The folder with the template files used by default is defined in the 'Extras > Options' dialog under the 'Tool | Description' category. If you want to use your own help template files, you can import another help template folder by selecting the 'Import Help Template' command from the project's context menu.

The help template folder contains the following files:

TemplateFunction.htm - template HTML file for user-defined functions.
TemplateFunctionBlock.htm - template HTML file for user-defined function blocks.
CSS stylesheet - used for the template HTML files and all project, POUs, documentation descriptions, etc.
image files (png) used by the template HTML files.

Note
If you want to use your own template files, ensure that the template HTML files in the template folder are named as mentioned above.

To create an HTML5 help file for an FU/FB POU based on a template, proceed as follows:

In the editors area, open the 'Description' editor for the user FU/FB for which you want to create the help file.
Under the 'Documentation' section, click the icon ('Insert template') on the toolbar. Depending on the POU type you are editing, the content of the TemplateFunction.htm or TemplateFunctionBlock.htm stored in the help template folder (see above) is inserted into the description area.

Note
The 'Insert template' command overwrites the current content in the description area (a corresponding message appears).

Example for the FU POU template contained in the default template folder
To edit the content, click the icon ('Enable edit mode') on the toolbar to switch to the edit mode and enter the HTML code.
Optional: Create language-specific HTML5 help file.
1. In the language combobox, select the language for the description (the combobox contains the user interface languages that are supported by PLCnext Engineer).
2. Click the icon ('Enable edit mode') on the toolbar and enter the HTML code.
Depending on the active user interface language, the language-specific POU description is displayed when calling the help for the function/function block POU.

Library description files

PLCnext Engineer allows you to provide library description files with the POUs and data type worksheets contained in your released libraries. The library description file is a file in XML format which has a pre-defined structure and content (see below). The description file contains the following information:

Categories under which the function/function block POUs and data type worksheets appear in the COMPONENTS area.
Short descriptions of the POUs and data type worksheets that are shown when hovering with the mouse over an element in the COMPONENTS area.

For library description files, the following applies:

The file name must be LibraryDescription.xml.
Localized library description files (library description files in other languages) can be added. The name of the language-specific library description files must be as follows:
LibraryDescription.<langcode>.xml
where <langcode> represents the locale code of the used language (for example, "de" for German, "fr" for French, "zh-CN" for Chinese, ...).
Example: "LibraryDescription.de.xml" for German library description file.
The content and structure of the localized library description file is the same as with the English version, except that the content of all Description attributes and the Name attributes of the <ToolboxCategory> elements must be translated.
The XML file must be saved with UTF-8 encoding.

Tip: When providing an own library description file, please start with the automatically generated library description file (when not providing an own file) as a base. All necessary entries are generated and can be found in the library file (*.pcwlx). The .pcwlx file is a zipped file which can be opened and extracted with any unzip program. Modify this automatically generated file according to your needs and then add the file in the 'Release As Library' dialog.