Aktualisierungen des Formats für Inhaltsverzeichnisse, Überschriften und Links

[Englischsprachiges Original dieses Artikels von Sami Rissanen auf dox.fi]

Version 8.8 von DoX CMS enthält bemerkenswerte Änderungen an der zugrunde liegenden Struktur von Titeln und internen Links. Auch das Inhaltsverzeichnis wird diese Änderungen widerspiegeln. Ich werde diese Änderungen hier auflisten und auf die damit verbundenen Herausforderungen und Chancen eingehen.

Zunächst werde ich die Änderungen, die wir an der Struktur der Publikationsvorlage vorgenommen haben, und die Gründe dafür erläutern. Anschließend werde ich darauf eingehen, wie sich diese Änderungen auf unsere Benutzer auswirken werden. Bei jeder Änderung der Publikationsvorlage müssen Sie sicherstellen, dass Sie Ihre Stylesheets entsprechend anpassen. In diesem Fall ist uns mindestens ein Problem bekannt, für das wir bereits eine empfohlene Lösung für die betroffenen Stile haben. Publikationen, die im Rahmen des Workflows genehmigt wurden, verwenden weiterhin die vorherige Vorlage und sind daher von diesen Änderungen nicht betroffen.

Im Rahmen der Aktualisierung haben wir jedem dieser Teile einer Publikation benannte Unterabschnitte hinzugefügt. Verwenden Sie diese Unterabschnitte, um die Sichtbarkeit, das Layout oder den Stil dieser Teile zu steuern. Dies ist eine erhebliche Erweiterung Ihrer Möglichkeiten, das Aussehen zu ändern.

In jedem der folgenden Abschnitte werden sowohl das alte Format dieser Elemente als auch die neu hinzugefügte Struktur angezeigt. So können Sie die Elemente vergleichen und die Änderungen sehen. Solche Vergleiche sind besonders nützlich, wenn ein Teil Ihrer Stile infolge dieser Aktualisierung nicht mehr funktioniert. Ich werde im Folgenden auf solche potenziellen Probleme sowie auf die Vorteile eingehen, die diese Aktualisierung mit sich bringt.

In der alten Publikationsvorlage gab es nur einen leeren Bereich zwischen der Nummer und dem Titel für jeden Punkt im Inhaltsverzeichnis. Daher konnte der Abstand zwischen ihnen nicht geändert werden. Jetzt haben beide ihre eigenen Rahmen, denen Sie Stile wie z. B. eine feste Breite zuweisen können.

X ist die Organisationsebene für dieses Element im Inhaltsverzeichnis. Y ist die Nummer dieses Kapitels. Z ist die Seitenzahl für dieses Kapitel. "tocdots" und "tocpagenum" sind nur in Publikationen mit Seiten enthalten und werden daher nicht als Teil der Vorschau einer Publikation angezeigt.

<li class="tocline toclineX">
    <a class="toclink" href="topic_link_Y">
        <span class="tocheading tocheadingX">Y Title</span>
        <span class="tocdots" />
        <span class="tocpagenum tocpagenumY">Z</span>
    </a>
</li>

Die von uns hinzugefügten Teile sind

• dox-topic-title-number
• dox-topic-title-space
• dox-topic-title-value.

Diese Werte werden jeweils um die Nummer eines Kapitels, den leeren Bereich und seinen Titel herum angewendet. Der leere Bereich hat eine eigene Kennung, sodass Sie ihn unabhängig steuern können, obwohl wir den Bereich beibehalten, um das Erscheinungsbild der Veröffentlichungen der aktuellen Benutzer nicht zu verändern.

<li class="tocline toclineX">
    <a class="toclink" href="#topic_linkY">
        <span class="tocheading tocheadingX">
            <span class="dox-topic-title-number">Y</span>
            <span class="dox-topic-title-space"> </span>
            <span class="dox-topic-title-value">Title</span>
        </span>
        <span class="tocdots" />
        <span class="tocpagenum tocpagenumY">Z</span>
    </a>
</li>

Zu den betroffenen Titeln gehören sowohl Kapitelüberschriften als auch Elementüberschriften.

Kapitelüberschriften

Im Gegensatz zum alten Inhaltsverzeichnis konnte die Nummer in den Kapitelüberschriften selbst immer unabhängig gesteuert werden.

X ist die Organisationsebene für dieses Kapitel. Y ist seine Nummer.

<hX><span class="titleNumberWrapper">Y </span>Title</hX>yxc

Das neue Format für Kapitelüberschriften enthält dieselben neuen Kennungen und Strukturen wie die oben gezeigten Elemente im Inhaltsverzeichnis.

<hX>
    <span class="titleNumberWrapper dox-topic-title-number">Y</span>
    <span class="dox-topic-title-space"> </span>
    <span class="dox-topic-title-value">Title</span>
</hX>

Elementüberschriften

Elemente haben zwei Arten von Überschriften: solche mit einem in einem Überschriftenfeld im Editor hinzugefügten Wert und solche ohne. Streng genommen wären Abschnittselemente, die einen in ihr Überschriftenfeld geschriebenen Wert haben, eine dritte Art, da ihnen nie Nummern zugeordnet sind. Diese fehlende Nummerierung macht sie in diesem Zusammenhang jedoch irrelevant.

Der Wert „Einstellungen für die Überschrift von Elementen“ stellt das im Menü „Einstellungen“ festgelegte Format dar. Sie können diesem Wert auf andere Weise eine interne Struktur hinzufügen.

<div class="dita-title"><span class="anchor-title">[element title settings] </span>Title</div>

<span class="anchor-title">[element title settings]</span>

Hier sind die neuen Werte, die wir hinzugefügt haben,

• dox-dita-title-anchor,
• dox-dita-title-space und
• dox-dita-title-value.

Auch wenn sich diese Werte geringfügig von denen unterscheiden, die für Kapitelüberschriften verwendet werden, haben sie denselben Zweck. Sie machen jeden Teil zu etwas, das unabhängig gesteuert werden kann, aber wir werden keinen Teil entfernen, um alte Stile weiterhin nützlich zu machen.

<div class="dita-title">
    <span class="anchor-title dox-dita-title-anchor">[element title settings]</span>
    <span class="dox-dita-title-space"> </span>
    <span class="dox-dita-title-value">Title</span>
</div>

<span class="anchor-title dox-dita-title-anchor">[element title settings]</span>

Ähnlich wie beim Inhaltsverzeichnis konnte man mit den Links zu den Kapiteln einer Publikation die Sichtbarkeit ihrer Komponenten nur mit den indirekten Mitteln steuern, die ich bereits besprochen habe. Jetzt können Sie Teile der zugehörigen Überschriften bei Bedarf ausblenden, unabhängig davon, ob die Überschriften selbst diese Teile anzeigen oder nicht.

An den Links zu Elementen haben wir keine derartigen Änderungen vorgenommen.

X ist der ID-Wert des Themenelements. Y ist die Nummer des entsprechenden Kapitels.

<a class="doxInnerReference href="#X"><span class="reference-title">Y Title</span></a>

Die interne Struktur der Links zu den Kapiteln ist dieselbe wie die interne Struktur der Überschriften selbst, wie oben dargestellt.

<a class="doxInnerReference" href="#X">
    <span class="reference-title">
         <span class="dox-topic-title-number">Y</span>
         <span class="dox-topic-title-space"> </span>
         <span class="dox-topic-title-value">Title</span>
    </span>
</a>

Jede Änderung der zugrunde liegenden Struktur ist mit Risiken verbunden. Daher müssen Sie Ihre nicht freigegebenen Publikationen unmittelbar nach dieser Aktualisierung besonders sorgfältig überprüfen. Wir sind uns bereits einiger unvermeidlicher Herausforderungen bewusst. Glücklicherweise sind die Lösungen für diese Herausforderungen einfach und auch bereits bekannt. Ich werde diese Lösungen im Folgenden ebenfalls vorstellen.

Kopien eines veralteten Standardstils für Inhaltsverzeichnisse

Dies ist die größte Herausforderung im Zusammenhang mit diesen Änderungen. Es geht um das Layout für das Inhaltsverzeichnis in den Formatvorlagen, bei denen die Regeln dafür aus unseren alten Standard-Formatvorlagen kopiert wurden, bevor wir diese Probleme behoben haben. Zumindest ist die Lösung sowohl einfach als auch bereits in den aktualisierten Standard-Stylesheets verfügbar. Wir können jedoch keine Automatisierung verwenden, um das Problem zu beheben, da wir uns aus diesem Grund von automatisierten Änderungen an den Stylesheets unserer Kunden fernhalten und weil kopierte Regeln nicht durch Änderungen an den Standard-Stylesheets gesteuert werden.

Das Problem besteht darin, dass das alte Standard-Stylesheet einige Regeln für das Inhaltsverzeichnis enthielt, die unter der falschen Annahme geschrieben wurden, dass diese Teile immer nur den Standardsatz von Span-Elementen enthalten würden. Daher vergaß der Autor anzugeben, dass diese Regeln nur für die Span-Elemente gelten sollten, die sich direkt innerhalb bestimmter Teile befinden. Diese Regeln in alten Dateien, die auf dieser einen basieren, zielen daher auf alle Span-Elemente innerhalb dieser Teile ab. Dies betrifft auch Fälle wie Variablen innerhalb von Überschriften.

Wir zeigen eine Lösung dafür in unserem Benutzerhandbuch. Es geht nur darum, an mehreren Stellen „>“-Zeichen hinzuzufügen, wie unten gezeigt, wo die Ziele aus Span-Elementen innerhalb eines Elements bestehen. Kopieren Sie nicht alles und fügen Sie es ein, falls Ihr Stil bereits einige Änderungen an den betreffenden Regeln beinhaltet. Fügen Sie einfach die fehlenden Zeichen zu den unten gezeigten Selektoren hinzu.

Auswirkungen der Änderungen auf die Formate der Kunden

Wenn Sie Regeln für ansonsten nicht spezifizierte span-Elemente in Positionen haben, die diesen Ergänzungen der Publikationsvorlage entsprechen, können diese Regeln nun auf die hinzugefügten Teile abzielen. Durch die Änderungen können solche Regeln auch von ihren beabsichtigten Zielen entfernt werden, insbesondere wenn Sie Zähler verwenden, die auf Ordnungswerten basieren. Wenn sich beispielsweise das erste span-Element ändert, wird das neue zum Ziel einer solchen Regel.

Ein weiteres bemerkenswertes Detail ist, dass Leerzeichen jetzt in ihrem eigenen Element stehen, das neben dem Element für Zahlen liegt, anstatt in dem Element, das für Zahlen verwendet wird. Daher entsprechen Details wie die standardisierte Einrückung von Überschriften, bei denen eine bestimmte Breite für den nummerierten Teil erforderlich ist, nicht genau dem ursprünglichen Aussehen. Der Unterschied liegt in der Breite eines Leerzeichens. Sie können die ursprüngliche Breite wiederherstellen, indem Sie die Leerzeichen an diesen Positionen ausblenden, z. B. mit der folgenden Ergänzung in Ihren Stylesheets:

.titleWrapper .dox-topic-title-space {
    display: none;
}

Änderungen an den Formaten für freigegebene Publikationen

Für Publikationen, die vor dieser Aktualisierung freigegeben wurden, wird weiterhin die ursprüngliche Publikationsvorlage verwendet. Die zugehörigen gespeicherten Formate bleiben ebenfalls unverändert. Das System speichert jedoch nur das Format, das für die Verwendung in dieser Publikation vorgesehen ist, wenn diese freigegeben wird. Für einige Publikationen müssen Sie mehrere Formate verwenden. Daher enthalten die anderen verwendeten Formate alle Änderungen, die aufgrund dieser Aktualisierung vorgenommen wurden. Wenn einige dieser Änderungen auch die vorherigen Kennungen oder Regeln betreffen, die ursprünglich auf veraltete Weise auf die neuen Kennungen abzielten, kann es zu Unterschieden kommen, wenn solche Formate mit alten freigegebenen Publikationen verwendet werden.

Am besten lassen sich solche Probleme natürlich vermeiden, indem für solche alten Publikationen separate Formate beibehalten werden. Dadurch würde die Liste der Formate jedoch mit Optionen gefüllt, die für zukünftige Publikationen nutzlos sind. Eine andere Möglichkeit wäre, die alten Regeln für alte Publikationen mithilfe von Selektoren, die nur für diese gelten, einzubeziehen. Wenn die Anzahl solcher Publikationen jedoch groß ist, wäre der damit verbundene Arbeitsaufwand unangemessen hoch.

Glücklicherweise tritt dieses Problem nur dann auf, wenn mehrere Formate für eine Publikation benötigt werden und wenn die Aktualisierungsformate nicht mit der alten Publikationsvorlage kompatibel sind. Benutzer können steuern, inwieweit die zweite Bedingung zutrifft. Wenn Sie also Publikationen haben, die die Verwendung mehrerer Formate erfordern, seien Sie vorsichtig, wenn Sie diese Formate bearbeiten, und stellen Sie sicher, dass Änderungen nicht dazu führen, dass alte Publikationen nicht mehr funktionieren, wenn diese Formate so verwendet werden.

Die oben aufgeführten Herausforderungen sind nichts im Vergleich zu den Vorteilen, die diese Änderungen mit sich bringen. Wenn dies nicht der Fall wäre, hätten wir diese Änderungen an der Vorlage für Publikationen nicht vorgenommen. Die wichtigsten Vorteile sind unten aufgeführt. Um Teile, die Sie zuvor nicht unabhängig voneinander steuern konnten, in Teile umzuwandeln, mit denen Sie Einschränkungen für die Ziele der Benutzer mit ihren Formatvorlagen aufheben können.

Volle Kontrolle über die Sichtbarkeit

Wollten Sie schon immer die Kapitelnummer oder die Kapitelüberschrift in Links zu den Kapiteln einer Publikation ausblenden? Vor allem, wenn mehrere Organisationsebenen beteiligt sind, kann die Nummer zusammen mit der vollständigen Überschrift ziemlich lang werden. In einer gedruckten Publikation ist diese Nummer jedoch hilfreicher, um den entsprechenden Teil zu finden. In einer elektronischen Publikation, die sich mehr auf die Suche nach Inhalten und Links stützt, kann dieser Wert jedoch völlig überflüssig sein. Nun können Sie mit gezielteren Formaten beiden Situationen gerecht werden, da Sie solche Details nun nach Belieben ein- oder ausblenden können.

Dasselbe gilt für das Inhaltsverzeichnis, in dem Sie nun beliebige Informationen aus jedem aufgeführten Kapitel ausblenden können. Daher müssen Online-Publikationen wie WebHelp-Handbücher überhaupt keine Kapitelnummern enthalten, da diese weniger wichtig sind, wenn nicht davon ausgegangen wird, dass verschiedene Teile linear gelesen werden.

Nachträglich zusammengestellte Publikationen

Ein wichtiger Grund für diese Änderung war auch der Wunsch einiger unserer Kunden, Publikationen auf der Grundlage von Entscheidungen über Optionen zusammenzustellen, die ihre Benutzer nur wenige Augenblicke zuvor in ihrem Portal getroffen hatten. Wir könnten dies im Prinzip erreichen, indem wir solche Anfragen an ihre Umgebung senden, aber dies würde eine recht komplizierte Integration erfordern, an der mehrere Anbieter beteiligt wären. Daher haben wir empfohlen, dass alle diese Inhalte zunächst von unserem System als HTML-Datei veröffentlicht werden, die jede Option enthält, die ihren Benutzern zur Auswahl zur Verfügung steht. Unsere Kunden können diese HTML-Publikationen dann als Vorlagen verwenden, aus denen sie Teile ausblenden können, je nachdem, was ihre eigenen Benutzer auswählen, bevor solche Publikationen mit angepassten Formaten auf ihrem eigenen Server in PDF-Dateien kompiliert werden. Durch diese Option entfällt die Notwendigkeit, mit Schnittstellen zwischen mehreren Systemen zu arbeiten, sowie die Notwendigkeit, dass mehrere Unternehmen zusammenarbeiten, und so weiter. Ohne dieses Update wäre sie jedoch nicht verfügbar.

Dieses Update war notwendig, um dabei zu helfen, denn das Ausblenden verschiedener Abschnitte allein würde die Werte für die verschiedenen harten Zähler, die mit Kapitelnummern verwendet werden, sowie die Nummerierung von Abbildungen und Tabellen in einer bereits kompilierten Publikation nicht ändern. Dadurch würden die entfernten Teile Lücken in diesen Werten hinterlassen.

Wenn diese Werte jedoch von Anfang an in dieser Publikation ausgeblendet und durch die gleichen Werte aus Zählern ersetzt würden, die an ein Stylesheet gebunden sind, würden diese neuen Werte immer nur die angezeigten Teile zählen. Dadurch würde die Nummerierung für jede Publikation, in der Sie die angezeigten Teile ändern, fortlaufend bleiben.

Diejenigen, die eine ähnliche Implementierung basierend auf dem, was ich gesagt habe, planen, sollten beachten, dass der betreffende Kunde eine Implementierung für seine Dokumentation verwendet hat, die den geringstmöglichen Arbeitsaufwand erfordert. Insbesondere Links zu Tabellen und Abbildungen machen die Implementierung erheblich komplexer, wenn Sie eine solche aktualisierte Nummerierung für sie verwenden möchten.

Andere Formate

Natürlich können Sie die Formate dieser Teile jetzt auch allgemein gezielt verwalten. Die wichtigsten Möglichkeiten hierfür sind wahrscheinlich die Festlegung standardisierter Einzüge zwischen Kapitelnummern und Überschriften im Inhaltsverzeichnis. Bisher gab es nur einen leeren Abstand zwischen den beiden, und beide waren Teil desselben Elements ohne zusätzliche Struktur.

Jetzt können Sie diese Einrückung steuern, indem Sie beispielsweise eine standardisierte Breite für die Kapitelnummer definieren oder links neben der Überschrift etwas Abstand hinzufügen. Bei beiden Änderungen müssen Sie diese Teile als „inline-block“ anzeigen lassen, damit sie als Inline-Elemente erhalten bleiben, die weiterhin Funktionen für Blockelemente wie standardisierte Breite oder Abstand aufweisen können. Die erste dieser Optionen standardisiert den Abstand zwischen dem Beginn der Kapitelnummer und dem Beginn der Überschrift. Wenn diese Zahl länger wird, rückt die Überschrift nicht weiter nach rechts. Die andere Option standardisiert den Abstand zwischen dem Ende der Zahl und dem Beginn der Überschrift.

Weitere Alternativen sind Texteffekte wie Fettdruck, die nur auf die Teile abzielen, die zuvor nicht unabhängig voneinander gesteuert werden konnten. Sie können auch Farben wie diese verwenden, wenn Sie beispielsweise die Überschriftennummern heller gestalten möchten, um sie sichtbar zu halten, aber auch, um die Aufmerksamkeit der Leser auf die eigentlichen Überschriften zu lenken.

Version 8.8 von DoX CMS enthält Änderungen an der Struktur der Publikationsvorlage. Sie können nun alle Teile für Kapitelüberschriften unabhängig voneinander an verschiedenen Stellen neben den Elementüberschriften steuern. Obwohl darin Links zu Kapiteln enthalten sind, sind Links zu Elementen nicht enthalten. Eine ähnliche Implementierung wäre für sie wesentlich komplexer, da beispielsweise nur einige Elemente Überschriften haben.

Jede Änderung an der zugrunde liegenden Struktur von Publikationen ist mit Risiken verbunden. Wenn alte Formatvorlagen Regeln enthalten, die auf eine Weise ausgerichtet sind, die sich auf die neuen Strukturen auswirkt, oder wenn die neuen Strukturen die Ziele der Selektoren außerhalb ihrer Reichweite verschieben, müssen Sie diese Formatvorlagen an die neue Vorlage anpassen. Leider enthalten viele alte Formatvorlagen einen Fehler, der von unseren alten Standardformatvorlagen kopiert wurde, und dieser Fehler führt zu einem fehlerhaften aktualisierten Inhaltsverzeichnis. Leider ist die Lösung für diesen Fehler recht klein, aber wir haben bereits Anweisungen dafür in unser Benutzerhandbuch aufgenommen. Bereits freigegebene Publikationen verwenden noch die alte Publikationsvorlage, sodass solche Details in ihren gespeicherten Formaten die Ergebnisse nicht beeinflussen. Dies bedeutet jedoch auch, dass spätere Änderungen an Formaten möglicherweise nicht mit diesen alten Publikationen kompatibel sind, wenn sie für die Veröffentlichung mit mehreren verschiedenen Formaten konzipiert sind.

Die Vorteile dieser Änderung sind es jedoch wert. Durch diese Aktualisierung können Teile, die nicht unabhängig voneinander mit Formatvorlagen gesteuert werden konnten, nun unabhängig voneinander gesteuert werden. So können Sie endlich die Sichtbarkeit, das Layout und das Format von Teilen wie den Kapitelnummern und Überschriften im Inhaltsverzeichnis festlegen. Zu den Optionen gehört beispielsweise eine standardisierte Einrückung von mehr als einer Leerstelle zwischen diesen beiden Teilen. Sie können nun auch alle derartigen Nummerierungen ausblenden und mit Ihrer Formatvorlage Ersetzungen hinzufügen. Dies hat den Vorteil, dass solche Nummerierungen aktualisiert werden, wenn Sie Teile der Publikation nach der Veröffentlichung ausblenden. So können Sie nummerierte Teile herausfiltern, wenn Sie beispielsweise PDF-Dateien basierend auf Optionen erstellen, die Ihre Benutzer aus einer HTML-Publikation mit allen Optionen ausgewählt haben. Hierfür ist keine umfangreiche Systemintegration erforderlich.

Wie immer beantworten wir gerne alle Fragen zu den idealen Möglichkeiten, um die Vorteile dieses Updates voll auszuschöpfen.