Hilfedateien für Bibliotheken erstellen

Sie können Ihre eigene anwenderdefinierte Dokumentation für die in der Bibliothek veröffentlichten Funktion/Funktionsbaustein-POEs hinzufügen. Damit können Sie den Anwender Ihrer Bibliothek mit Hilfeinformationen zu den FU/FB-POEs versorgen (beispielsweise zu deren Funktionsweise und Verwendung). Anwenderdokumentationen können als CHM-Hilfedateien, HTML5-Hilfedateien oder als Beschreibungsdateien beigestellt werden.

Nachdem Sie die anwenderdefinierte Dokumentation erstellt haben, können Sie eine oder mehrere Hilfedateien und Bibliotheks-Beschreibungsdateien zu einer veröffentlichten Bibliothek hinzufügen, indem Sie diese im Dialog 'Als Bibliothek veröffentlichen' auswählen (siehe hierzu auch das Thema "Bibliothek veröffentlichen").

Mit den Hilfedateien können Sie detaillierte Beschreibungen Ihrer Funktion/Funktionsbaustein-POEs an Anwender weitergeben, die die POEs in ihren Projekten verwenden. Die Hilfe zu einer Funktion/einem FB wird geöffnet, wenn der Anwender <Umschalt>+<F1> drückt, während die POE in den KOMPONENTEN markiert ist, oder die 'Hilfe'-Direktschaltfläche für die POE im Code-Arbeitsblatt klickt.

Hinweis
Die Beschreibung der Funktions-/Funktionsbaustein-POE kann in den von PLCnext Engineer unterstützten Sprachen erstellt werden (die Liste der verfügbaren Sprachen sehen Sie im 'Extras > Optionen'-Dialog unter der Kategorie 'Lokalisierung > Internationale Einstellungen'). Abhängig von der aktuellen Sprache der Benutzeroberfläche wird die sprachspezifische POE-Beschreibung angezeigt, wenn die entsprechende Hilfe aufgerufen wird.

Hinweis
Dieses Hilfethema beschreibt nicht, wie Sie CHM-Hilfedateien und HTML5-Hilfedateien erstellen und bearbeiten. Dazu lesen Sie bitte die Dokumentation zu den von Ihnen verwendeten Werkzeugen und Editoren.

Dieses Thema enthält die folgenden Abschnitte:

CHM-Hilfedateien

Zum Erzeugen einer CHM-Hilfedatei (Compiled HTML Help) kann der HTML Help Workshop (freies Microsoft Tool) oder jedes andere, geeignete Autorenwerkzeug für CHM-Hilfen verwendet werden.
Für CHM-Hilfedateien, die Sie zu einer veröffentlichten Bibliothek hinzufügen wollen, gilt folgendes:

Der Name der CHM-Hilfedatei muss mit dem Namen der Bibliothek beginnen, gefolgt von "_FBFun.chm" (z.B. "MeineBibliothek_FBFun.chm"), wobei die Groß-/Kleinschreibung übereinstimmen muss.
Der Dialog 'Als Bibliothek veröffentlichen' gibt eine Fehlermeldung aus, wenn der Hilfename nicht mit dem Bibliotheksnamen beginnt.
Es können lokalisierte CHM-Hilfedateien hinzugefügt werden (d.h. Hilfen in anderen Sprachen). Der Name der sprachspezifischen CHM-Hilfedateien muss wie folgt lauten:
<Bibliotheksname>_<Sprachcode>_FBFun.chm
wobei Sie als <Sprachcode> folgende Kennungen verwenden können: en, en-US, de, de-DE, …
Beispiel: MeineBibliothek_de-DE_FBFun.chm für eine deutsche CHM-Hilfedatei.

Inhalt einer CHM-Datei

Aufrufen eines Hilfethemas für eine Funktion/Funktionsbaustein-POE

Tipp: Der HTML Help Workshop bietet die Möglichkeit zum Dekompilieren bestehender CHM-Hilfedateien und kann dazu verwendet werden, Dateien aus einer CHM zu extrahieren. Dekompilieren Sie die vorhandene CHM-Hilfedatei zu einer mit PLCnext Engineer ausgelieferten Funktion/FB-Bibliothek, um zu sehen, welche Dateien die CHM enthält.

Hinweis
Diese Dokumentation beschreibt nicht, wie Sie CHM-Hilfedateien erstellen. Dazu lesen Sie bitte die Dokumentation zum HTML Help Workshop oder Ihrem Hilfe-Autorensystem.

HMTL5-Hilfedateien

PLCnext Engineer enthält standardmäßig einen Satz von Vorlagendateien, mit deren Hilfe Sie Hilfedateien im HTML5-Format für Ihre FU/FB-POEs erstellen können. Die Hilfedateien werden mit dem HTML-Editor des 'Einstellungen'-Editors der FU/FB-POE erstellt und bearbeitet.

Der Speicherort des Ordners mit den Standard-Vorlagendateien ist im Dialog 'Extras > Optionen' in der Kategorie 'Werkzeug | Beschreibung' definiert. Sie können auch Ihre eigenen Hilfevorlagendateien verwenden. Importieren Sie dazu Ihren Hilfevorlagenordner über den Kontextmenübefehl 'Hilfevorlage importieren' des Projektknotens in das Projekt.

Der Hilfevorlagenordner enthält folgende Dateien:

TemplateFunction.htm - HTML-Vorlagendatei für anwenderdefinierte Funktionen.
TemplateFunctionBlock.htm - HTML-Vorlagendatei für anwenderdefinierte Funktionsbausteine.
CSS-Stylesheet - Stylesheet für die HTML-Vorlagendateien und alle POE-, Projektbeschreibungen usw.
In den HTML-Vorlagendateien verwendete Bilddateien (im png-Format).

Hinweis
Wenn Sie eigene Vorlagendateien verwenden möchten, stellen Sie sicher, dass diese Dateien dieselben Namen wie die oben genannten Dateien im Vorlagenordner besitzen.

Um eine HMTL5-Hilfedatei für eine FU/FB-POE auf Basis einer Vorlage zu erstellen, gehen Sie wie folgt vor:

Öffnen Sie im Editorenbereich den Editor 'Beschreibung' der anwenderdefinierten FU/FB, für welche Sie eine Hilfedatei erstellen möchten.
Klicken Sie im Bereich 'Dokumentation' in der Symbolleiste auf das Symbol ('Vorlage einfügen'). Abhängig davon, welchen POE-Typ Sie gerade bearbeiten, wird der Inhalt der Vorlagendatei (TemplateFunction.htm oder TemplateFunctionBlock.htm) aus dem Hilfevorlagenordner (siehe oben) in den Beschreibungsbereich eingefügt.

Hinweis
Der Einfügen-Befehl überschreibt den aktuellen Inhalt des Bereichs (eine entsprechende Meldung wird ausgegeben).

Beispiel für die FU-POE-Vorlage aus dem Standard-Vorlagenordner
Zum Bearbeiten des HTML-Codes klicken Sie in der Symbolleiste auf das Symbol ('Bearbeitungsmodus einschalten').
Optional: Sprachspezifische HMTL5-Hilfedatei erstellen.
1. Wählen Sie in der Combobox Sprache die Sprache für die Beschreibung aus (die Combobox enthält die Oberflächensprachen, die in PLCnext Engineer unterstützt werden).
2. Klicken Sie in der Symbolleiste auf das Symbol ('Bearbeitungsmodus einschalten') und geben dann den HMTL-Code ein.
Abhängig von der aktuellen Sprache der Benutzeroberfläche wird die sprachspezifische POE-Beschreibung angezeigt, wenn die entsprechende Hilfe für die FU/FB-POE aufgerufen wird.

Beschreibungsdateien zu Bibliotheken

Sie können in PLCnext Engineer Beschreibungsdateien für die in einer Bibliothek veröffentlichten POEs und Datentyp-Arbeitsblätter bereitstellen. Eine Bibliotheksbeschreibungsdatei ist eine Datei im XML-Format, für die Struktur und Inhalt vorgeschrieben sind. Die Beschreibungsdatei enthält die folgenden Informationen:

Kategorien, unter denen die Funktion/Funktionsbaustein-POEs und Datentyp-Arbeitsblätter in den KOMPONENTEN erscheinen.
Kurzbeschreibungen der POEs und Datentyp-Arbeitsblätter als Tooltip (dieser erscheint, wenn Sie den Mauszeiger im KOMPONENTEN-Bereich auf ein Element setzen).

Für Beschreibungsdateien zu Bibliotheken gilt:

Der Dateiname muss LibraryDescription.xml sein.
Es können lokalisierte Beschreibungsdateien zu Bibliotheken hinzugefügt werden (d.h. Dateien in anderen Sprachen). Der Name der sprachspezifischen Beschreibungsdateien muss wie folgt lauten:
LibraryDescription.<Sprachcode>.xml
wobei <Sprachcode> das Kürzel gem. Systemgebietsschema für die verwendete Sprache ist (zum Beispiel, "de" für Deutsch, "fr" für Französisch, "zh-CN" für Chinesisch, ...).
Beispiel: "LibraryDescription.de.xml" für die deutsche Bibliotheksbeschreibungsdatei.
Abgesehen vom Inhalt der Description- und Name-Attribute der <ToolboxCategory>-Elemente, die in die Zielsprache zu übersetzen sind, sind Inhalt und Struktur der lokalisierten Bibliothekseschreibungsdatei gleich wie in der englischen Variante.
Das Encoding der XML-Datei muss UTF-8 sein.

Tipp: Verwenden Sie zu Beginn eine automatisch generierte Bibliotheksbeschreibungsdatei als Basis für Ihre eigene Beschreibungsdatei. Alle notwendigen Einträge können aus einer generierten Bibliotheken-Datei (*.pcwlx) kopiert werden. Die *.pcwlx-Datei ist eine gezippte Datei, die mit jedem geeigneten Unzip-Programm extrahiert werden kann. Passen Sie die automatisch generierte Datei nach Bedarf an und fügen Sie sie im Dialog 'Als Bibliothek veröffentlichen' hinzu.