Providing help files for libraries 

Libraries can include help files that contain a help page for each POU. The help files can be added in the Compiled Help (.chm) format (all toolchain versions) or in HTML5 format (as of toolchain version 2022.6).

These help files can be provided in different languages and set back to a default if there is no matching file for the current language set in PLCnext Engineer. 

HTML 5 format

From toolchain 2022.6 on, HTML5 is the default option to add help files for your functions and function blocks. These steps are needed only when starting with HTML5 help files in a new project, or when adding another language set ("culture") of files to an existing HTML5 help.

Starting a HTML5 help

• Right-click on the project.
• Select Add → New Item... from the context menu.
• Select the template PLCnext HTML5 Help Culture and press Add.
• In the next dialog, enter the (mandatory) name and (optional) the culture of the function or function block that the help file is made for.
  Note:
  • The entered name and culture are not checked by the dialog. It is your obligation to enter valid content.
  • The culture cannot contain a culture for which a folder already exists in the Help/HTML5/<culture> directory.  If no culture is entered, the help template will be created in a default folder for fallback use.
• Press Create.

The bunch of files that make up the HTML page will be added to the project in the directory Help/HTML5/<culture>.

Adding help files

For each function or function block you will need a separate .htm file with the namespace and name of your function or function block in the following format: <namespace>.<name>.htm. You can copy an existing .htm file, rename it accordingly and translate the content to meet the target culture. 

Once you have a set of files prepared for another culture, add them as described above, providing the culture. That Help/HTML5/<culture> folder will be created.

Building the project

During build the following check on all help files is performed:

• For each existing culture (meaning, the directory Help/HTML5/<culture> is available) it is checked, whether a <namespace>.<name>.htm help file is available in the culture folder for all functions and function blocks. For each missing .htm files a warning will be generated.
• Each culture is checked for validity. For each invalid culture a warning will be generated.
  

After building/rebuilding the project, the help is added to the library.

CHM format

The format of the help file name is <library name>_[<culture>_]FBFun.chm. 

The <culture> part of the file name is optional and allows to create versions for different languages, e.g. en_, en-US_, de_, fr_, zh-CN_. These denominators end up in in the file name, e.g. PLCnextFirmwareLibrary1_zh-CN_FBFun.chm.

Leaving out the culture part creates the default help file, e.g. PLCnextFirmwareLibrary1_FBFun.chm.

The engineering tool (e.g. PLCnext Engineer) searches for the library's functions and function blocks through their names. If the help is generated with Microsoft® HTML Help Workshop then these names must be defined as keys in the *.hhk file.

• Insert the .chm help file into the project's Help folder.
  Note: The help files must be copied into the Help directory of the project. It does not work to insert them as links.
• Set the property Build Action to Content.