Über strukturiertes Authoring

In Paligo wurde das article-Element so angepasst, dass es als Publication-Komponente dient. Es soll hauptsächlich als Struktur für die Wiederverwendung von Themen dienen.

Obwohl es in Paligo etwas anders verwendet wird als in DocBook, wurde es nicht dahingehend angepasst, dass es als Element den Namen „Publikation“ trägt, um so nah wie möglich am offenen Standard des DocBook Inhaltsmodells zu bleiben.

Wenngleich eine Publikation (Artikel) in DocBook viele untergeordnete Elemente haben kann, sollte es in Paligo in der Publikation hauptsächlich Metadaten geben. In der Regel sollten diese Metadaten in einem info-Element enthalten sein. Beachten Sie, dass es keine tatsächlichen Inhalte als untergeordnete Elemente hat. Alles dies wird in Paligo stattdessen in der Strukturansicht bearbeitet.

<article>
    <info>
        <title>My Publication</title>
        <author>
            <orgname>Organization Name</orgname>
            <address>
                <city>City</city>
                <street>Street</street>
                <postcode>000000</postcode>
                <country>Country</country>
            </address>
            <email>user@example.com</email>
        </author>
    </info>
</article>

In Paligo wurde das section-Element so angepasst, dass es als Topic-Komponente dient. Es soll hauptsächlich als Struktur für die Wiederverwendung von Themen dienen.

Obwohl es in Paligo etwas anders verwendet wird als in DocBook, wurde es nicht dahingehend angepasst, dass es als Element den Namen „Topic“ trägt. Das Wurzelelement eines Topics wird also weiterhin als section bezeichnet, um so nah wie möglich am offenen Standard des DocBook Inhaltsmodells zu bleiben.

Topics (sections) sind in einer Publikation verschachtelt und können eine unbegrenzte Tiefe aufweisen. Obwohl das Nesting von Topics/Abschnitten in einer Publikation am häufigsten vorkommt und die empfohlene Praxis darin besteht, dem Konzept des Authoring auf der Grundlage von Topics zu folgen, ist es auch möglich, das Abschnittselement direkt innerhalb eines Topics als Unterabschnitt zu verwenden.

<section>
  <title>The Engine</title>
  <figure>
    <title>Specifications</title>
    <mediaobject>
      <imageobject>
        <imagedata fileref="UUID-f8b27f8c-70ba-83d6-9223-3c1354c98047" width="400" xinfo:image="UUID-f8b27f8c-70ba-83d6-9223-3c1354c98047"/>
      </imageobject>
      <caption>
        <para>The vehicle is powered by a 3.2-litre straight-six engine (X55C33). The performance figures are:</para>
        <itemizedlist>
          <listitem>
            <para>3,246 cc displacements</para>
          </listitem>
          <listitem>
            <para>343 horsepower (256 kW) at 7,900 rpm</para>
          </listitem>
          <listitem xinfo:product="ACME 2000;ACME 5000">
            <para>269 lb·ft (365 N·m) of torque at 4,900 rpm, 8,000 rpm
              redline.</para>
          </listitem>
          <listitem xinfo:product="ACME 1500">
            <para>269 lb·ft (365 N·m) of torque at 4,900 rpm, 9,000 rpm redline.</para>
          </listitem>
          <listitem>
            <para>Acceleration to 60 mph (96 km/h) comes in 4.8 seconds. (0-62 mph
              / 100 km/h is 5.0) and top speed is limited electronically to 156 mph (251
              km/h)</para>
          </listitem>
          <listitem>
            <para>Output per litre is 95 bhp (80 kW; 108 PS), and power-to-weight
              ratio is 9.9 lb/bhp.</para>
          </listitem>
        </itemizedlist>
      </caption>
    </mediaobject>
  </figure>
</section>

Ein para ist einfach ein Absatz, wahrscheinlich eines der am häufigsten verwendeten Elemente.

Wenn Sie einen Absatz mit einem Titel haben möchten, können Sie hierfür den formalpara verwenden.

Absätze in Paligo unterscheiden sich von denen in DocBook dadurch, dass sie nur Inline-Elemente enthalten können. Wenn Sie ein Blockelement innerhalb eines para hinzufügen, wird es validiert, aber sobald Sie speichern, extrahiert Paligo das Blockelement aus dem para und platziert es außerhalb des para. Dadurch soll die Struktur für mehr Funktionalität in Bezug auf Wiederverwendungsbeziehungen und Übersetzungen optimiert werden.

Eine frei schwebende Überschrift, z. B. eine Unterüberschrift einer unteren Ebene.

Einige Dokumente, in der Regel Legacy-Dokumente, verwenden Unterüberschriften, die nicht an die normale Abschnittshierarchie gebunden sind. Generell sollten Sie beim Authoring auf der Grundlage von Topics keine Unterüberschriften erstellen, sondern diese durch die Nesting-Struktur der Topics in der Publikation automatisch erstellen lassen oder einfach section-Elemente innerhalb eines Topics verwenden.

Sollten Sie jedoch in Ausnahmefällen Unterüberschriften hinzufügen müssen, die die natürliche Überschriftenhierarchie brechen, können diese Überschriften innerhalb des bridgehead-Elements dargestellt werden. Sie können dann renderas (gelesen wie engl. „render as“) verwenden, um festzulegen, welche Ebenenüberschrift Sie darstellen möchten (mit Werten wie „sect1“, „sect2“ usw.).

Das DocBook Element Sidebar wurde in Paligo so ausgelegt, dass es sowohl als separate Komponente als auch als allgemein verwendbares Element zur Wiederverwendung dient.

Wenn Sie eine Seitenleiste als Element zu einem Topic hinzufügen, funktioniert sie wie in DocBook und wird zu einer schwebenden Seitenleiste, siehe Ausgleich von Text und Bild, Erstellen mehrerer Spalten im Topic (PDF) und Fließtext um ein Bild herum. Sie kann im Panel „Elementattribute“ gestaltet werden.

Wenn sie als informelles Topic erstellt wird, kann sie als Komponente wiederverwendet, aber nicht gestaltet werden, siehe Ein informelles Topic erstellen. Ihre untergeordneten Elemente erscheinen in der Ausgabe, als wären sie separat verwendet worden.

Es gibt mehrere Arten von Bildelementen in Paligo. Vollständige Beschreibungen dieser Elemente siehe mediaobject, inlinemediaobject, figure und informalfigure.

<figure><title>The Pythagorean Theorem Illustrated</title>
<mediaobject>
  <imageobject>
    <imagedata fileref="figures/pythag.png"/>
  </imageobject>
</mediaobject>
<caption><para>An illustration of the Pythagorean Theorem</para></caption>
</figure>

Es gibt mehrere verschiedene Arten von Listen in Paligo. Zu den gängigsten gehören:

Der in Paligo verwendete Tabellentyp ist einer HTML-Tabelle sehr ähnlich. Sie können eine Tabelle mit oder ohne Titel (caption) verwenden. Ohne Titel heißt das Element informaltable.

Die Tabellenattribute müssen Sie meist nicht manuell im Widget Elementattribute festlegen: Dies erfolgt beim Erstellen der Tabelle im Assistenten, oder Sie klicken mit der rechten Maustaste auf die Tabelle und öffnen die Tabelleneigenschaften. Wenn Sie jedoch Attribute hinzufügen oder ändern müssen, sollten Sie diese gängigsten Attribute kennen:

Vollständige Beschreibungen dieser Elemente siehe table, informaltable.

<table width="100%">
    <caption>A table</caption>
    <thead>
      <tr>
        <th colspan="2">
          <para>Header spanning both columns</para>
        </th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>
          <para>First cell</para>
        </td>
        <td>
          <para>Second cell</para>
        </td>
      </tr>
    </tbody>
  </table>

Es gibt zwei Elemente zum Einfügen von Beispielen in Paligo: example und informalexample. Genau wie bei Zahlen und Tabellen besteht der Unterschied darin, ob das Beispiel einen Titel hat oder nicht. Genau wie eine Abbildung erhält auch ein Beispiel standardmäßig eine Nummer und ein Label, wenn es einen Titel hat. Ein Beispiel kann die meisten anderen Blockelemente enthalten.

Weitere Informationen finden Sie unter example und informalexample.

Paligo hat einen sehr umfangreichen Satz an Elementen für die Softwaredokumentation von DocBook übernommen. Dazu gehören Elemente für GUI-Komponenten sowie Code-Snippets und Ähnliches. Im Folgenden werden einige der gängigsten Elemente beschrieben.

//This example is in itself using the programlisting element 
//to show the code below
public class Factorial
{
        public static void main(String[] args)
        {       final int NUM_FACTS = 100;
                for(int i = 0; i < NUM_FACTS; i++)
                        System.out.println( i + "! is " + factorial(i));
        }
        
        public static int factorial(int n)
        {       int result = 1;
                for(int i = 2; i <= n; i++)
                        result *= i;
                return result;
        }
}

Das footnote-Element erzeugt in der Regel eine Markierung (ein hochgestelltes Symbol oder eine hochgestellte Zahl) an der Stelle im Dokumentenfluss, an der es auftaucht. Der Fußnotentext wird dann an anderer Stelle angezeigt, in der Regel am Ende der Seite oder unter einer Tabelle.

Um in einem Topic mehrfach auf dieselbe Fußnote zu verweisen, verwenden Sie den footnoteref. Dazu benötigt die ursprüngliche footnote ein xml:id-Attribut mit einer eindeutigen Kennung. Verweisen Sie dann im footnoteref auf diese Kennung mit dem linkend-Attribut.

Siehe auch footnote und footnoteref.

<informaltable>
    <thead>
        <tr>
            <th>Variable</th>
            <th>Value</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>foo<footnote xml:id="foo">
                    <para>A meaningless variable name often used in programming examples</para>
                </footnote></td>
            <td>5</td>
        </tr>
        <tr>
            <td>bar<footnoteref linkend="foo"/></td>
            <td>3 </td>
        </tr>
    </tbody>
</informaltable>