Problem

Der Name einer benutzerdefinierten Variable lässt sich in der Variablenverwaltung von Help+Manual nicht nachträglich ändern. Soll eine bereits verwendete Variable einen anderen Namen erhalten, müssen sowohl ihre Definition als auch ihre Verwendungen angepasst werden.

Kontext

Beim Aufbau einer Dokumentation können sich Benennungen ändern, beispielsweise um Variablennamen zu vereinheitlichen oder verständlicher zu machen. Eine neue Variable anzulegen genügt dabei nicht: Die bestehenden Verweise verwenden weiterhin den bisherigen Namen.

Im unkomprimierten Projektformat liegen die Topicdateien als XML vor. Sie lassen sich mit einem Texteditor gemeinsam durchsuchen und bearbeiten.

Vorgehen

Im folgenden Beispiel wird die benutzerdefinierte Variable QU_EIGENSCREEN in QU_EIGEN_SCREEN umbenannt. Ihr Wert bleibt unverändert.

1. Projekt sichern und schliessen

Alle Änderungen in Help+Manual speichern und das Projekt schliessen. Eine Sicherung des Projektordners erstellen.

2. Projektdatei anpassen

Die Projektdatei (.hmxp) in Visual Studio Code öffnen und nach der Variablendefinition suchen.

Vor der Änderung prüfen, ob bereits eine Variable mit dem Namen QU_EIGEN_SCREEN vorhanden ist. Anschliessend ausschliesslich den Namen im Attribut id ändern:

<variable id="QU_EIGEN_SCREEN" type="text" translate="true">Quelle: Eigener Screenshot.</variable>

Der Variablenwert und die übrigen Attribute bleiben erhalten. Die Projektdatei sodann speichern und schliessen.

3. Topicsordner öffnen

Den Topicsordner in Visual Studio Code öffnen. Dazu den Ordner aus dem Datei-Explorer in das Programmfenster von Visual Studio Code ziehen. Die Bearbeitung bezieht sich auf das betreffende Projekt und die darin verwendeten Inhalte. Bei gemeinsam genutzten Snippets muss vor einer Änderung geprüft werden, welche weiteren Projekte sie verwenden. Diese Projekte benötigen ebenfalls eine passende Variablendefinition.

4. Fundstellen prüfen

Nach QU_EIGENSCREEN suchen und die Treffer kontrollieren. Im XML-Format hat ein Variablenverweis folgenden Aufbau:

<var translate="false">&lt;%QU_EIGENSCREEN%&gt;</var>

Das Element var kennzeichnet den Variablenverweis. Die Zeichen < und > des Platzhalters werden darin als &lt; und %&gt; gespeichert.

5. Variablenverweise ersetzen

Die Ersetzung unter Berücksichtigung der Gross-/Kleinschreibung und ohne reguläre Ausdrücke durchführen.

Suchen nach: &lt;%QU_EIGENSCREEN%&gt;

Ersetzen durch: &lt;%QU_EIGEN_SCREEN%&gt;

Damit wird beispielsweise aus dem bisherigen Variablenverweis:

<var translate="false">&lt;%QU_EIGEN_SCREEN%&gt;</var>

Die umgebenden XML-Elemente und deren Attribute bleiben erhalten. Weitere Fundstellen des bisherigen Namens einzeln prüfen. Auch direkt geschriebene Platzhalter oder Verweise innerhalb anderer Inhalte müssen gegebenenfalls angepasst werden.

6. Dateien kontrollieren und speichern

Die Änderungen im Editor prüfen und alle bearbeiteten Dateien mit unveränderter Zeichenkodierung speichern. Erneut nach QU_EIGENREF suchen. Verbleibende Treffer kontrollieren und feststellen, ob sie angepasst werden müssen oder den bisherigen Namen bewusst dokumentieren.

Die XML-Struktur darf durch die Bearbeitung nicht verändert werden.

7. Ergebnis prüfen

Das Projekt in Help+Manual öffnen. In der Variablenverwaltung kontrollieren, ob QU_EIGEN_REF mit dem bisherigen Wert vorhanden ist. Anschliessend die bearbeiteten Topics und eingebundenen Snippets prüfen.

Eine Testausgabe erstellen und kontrollieren, ob an den betroffenen Stellen weiterhin Quelle: Eigener Screenshot. erscheint. Bei mehreren verwendeten Ausgabeformaten die Prüfung für diese Ausgaben wiederholen.

In der Praxisumgebung werden nicht gefundene Variablen im Ausgabereport nicht gemeldet. Ein fehlerfreier Report genügt deshalb nicht als Nachweis. Die Suche nach dem bisherigen Namen und die Sichtkontrolle der betroffenen Ausgabestellen gehören zur Prüfung.

Einsichten

Eine Variable besteht aus einer Definition und den Verweisen auf diese Definition. Eine Umbenennung ist erst abgeschlossen, wenn beide denselben Namen verwenden. Durch die direkte XML-Bearbeitung lassen sich die Verweise dateiübergreifend anpassen.

Bei eingebundenen Snippets kann die Änderung über das bearbeitete Projekt hinauswirken. Ein gemeinsam genutzter Inhalt benötigt in allen verwendenden Projekten eine passende Variablendefinition.

Folgerungen

Variablennamen sollten frühzeitig nach einem einheitlichen Schema festgelegt werden. Spätere Umbenennungen sind möglich, erfordern jedoch eine Sicherung, genaue Suchkriterien und die Prüfung aller betroffenen Inhalte. Vor der Bearbeitung muss klar sein, welche Dateien und Projekte von der Änderung betroffen sind.

Anschlussfragen

Keine.