Problem
Der Toolname Help+Manual ist in zahlreichen Topicdateien als fester Text enthalten. Er soll durch die Variable <%DOC_TOOL%> ersetzt werden. Damit lässt sich der Name zentral ändern und überall einheitlich schreiben. Die Ersetzungsfunktion im Help+Manual kann gewöhnlichen Text jedoch nicht durch ein Variablenelement ersetzen. Deshalb werden die Topicdateien im XML bearbeitet.
Kontext
Der Produktname soll in der gesamten Dokumentation einheitlich geschrieben und zentral gepflegt werden. Mit einer Variablen lassen sich spätere Änderungen der Bezeichnung an einer Stelle vornehmen.
Im unkomprimierten Projektformat liegen die Topicdateien als XML vor. Sie lassen sich mit einem Texteditor gemeinsam durchsuchen und bearbeiten.
Vorgehen
Im folgenden Beispiel wird der Text Help+Manual durch ein XML-Variablenelement ersetzt. Der Wert der Variable bleibt zunächst Help+Manual.
Das Variablenelement hat dieses Format: <var translate="false"><%DOC_TOOL%></var>
1. Variable anlegen
In Help+Manual die benutzerdefinierte Variable DOC_TOOL mit dem Wert Help+Manual anlegen. Ist sie bereits vorhanden, ihren Wert kontrollieren.
2. Projekt sichern und schliessen
Alle Änderungen in Help+Manual speichern und das Projekt schliessen. Eine Sicherung des Projektordners erstellen.
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.
4. Fundstellen prüfen
Nach Help+Manual suchen und die Treffer kontrollieren. Ersetzt werden die Textstellen, an denen künftig der Variablenwert erscheinen soll.
Hinweis: In Dateinamen, Pfaden, URLs oder Code kann der Begriff technisch erforderlich sein. Eine Ersetzung kann dort zu Fehlern führen.
5. Text ersetzen
Die Ersetzung ohne Berücksichtigung der Gross-/Kleinschreibung und ohne reguläre Ausdrücke durchführen.
Suchen nach: Help+Manual
Ersetzen durch: <var translate="false"><%DOC_TOOL%></var>
Das Element var kennzeichnet den Variablenverweis. Die Zeichen < und > des Platzhalters werden innerhalb des Elements als < und > gespeichert. Die umgebenden XML-Elemente bleiben erhalten.
6. Dateien kontrollieren und speichern
Die Änderungen im Editor prüfen und die Dateien mit unveränderter Zeichenkodierung speichern. Erneut nach Help+Manual suchen und verbleibende Treffer kontrollieren. Ist der Name durch Formatierungen auf mehrere XML-Elemente verteilt, muss die betreffende Stelle einzeln bearbeitet werden.
7. Ergebnis prüfen
Das Projekt in Help+Manual öffnen und die bearbeiteten Stellen kontrollieren. Der eingefügte Platzhalter muss als Variable erkannt werden. Eine Testausgabe erstellen und prüfen, ob weiterhin Help+Manual erscheint. Optional den Variablenwert vorübergehend ändern und mit einer weiteren Testausgabe prüfen, ob die Änderung an allen vorgesehenen Stellen übernommen wird. Danach den ursprünglichen Wert wiederherstellen.
Einsichten
Es genügt, den Variablenplatzhalter direkt in den Text zu schreiben. Ein eigenes Variablenelement bietet jedoch Vorteile bei der Bearbeitung: Die Variable wird im Help+Manual-Editor optisch hervorgehoben, und ein Doppelklick darauf öffnet den Dialog zum Bearbeiten von Variablen. Durch die direkte XML-Bearbeitung lassen sich Texte dateiübergreifend durch Variablenelemente ersetzen.
Folgerungen
Wiederkehrende Bezeichnungen sollten bereits beim Schreiben als Variablen eingefügt werden. Bei bestehenden Inhalten ermöglicht die XML-Bearbeitung eine nachträgliche Umstellung. Dafür müssen die Fundstellen vor der Ersetzung und die betroffenen Ausgaben danach geprüft werden.
Anschlussfragen
Keine.
