Getting Started with Paligo

Common General Elements

The following are some common general elements, and some of them have partly different usage than in their counterparts in DocBook.

Publication (article)

In Paligo, the article element has been adapted to be used as the Publication component. It is meant mainly to be the structure for reusing topics.

Although slightly differently used in Paligo than in DocBook, it has not been customized to have the name "publication" as an element, in order to stay as close to the open standard DocBook content model as possible.

Although a publication/article can have a lot of child elements in DocBook, in Paligo there should mainly be metadata in the publication. Usually, these metadata should be in an info element. Note that it has no actual content as child elements. All that is handled in the Structure View in Paligo instead.

Example 8. Publication/article
<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>


Topic (section)

In Paligo, the section element has been adapted to be used as the Topic component. It is meant mainly to be the structure for reusing topics.

Although slightly differently used in Paligo than in DocBook, it has not been customized to have the name "topic" as an element. So the root element in a topic is still called section, in order to stay as close to the open standard DocBook content model as possible.

Topics (sections) are nested in a publication, and can have unbounded depth. Although nesting topics/sections in a publication is the most common, and the recommended practice to follow the topic-based authoring concept, it is also possible to use the section element directly inside a topic as a child section.

Example 9. Topic/section
<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>


Paragraph (para)

A para is a simply a paragraph, probably one of the most used elements.

If you'd like to have a paragraph with a title, the formalpara is also available.

Paragraphs in Paligo differ from DocBook in that they may only contain inline elements. If you add a block element inside a para, it will validate, but as soon as you save Paligo will extract the block element from the para placing it outside the para. This is to optimize the structure for more functionality regarding reuse relations as well as translation.

Bridgehead

A free-floating heading, such as a lower-level sub heading.

Some documents, usually legacy documents, use sub headings that are not tied to the normal sectional hierarchy. Usually in topic-based authoring, you should not create sub headings, but instead let these be automatically created by the nesting structure of the topics in the publication.

If however you need to add sub headings nonetheless, such headings may be represented in with the bridgehead element.

Informaltopic (sidebar)

The element sidebar in DocBook has been specialized in Paligo to serve as a general-purpose reuse wrapper element for reuse.

Like section, it can also serve as a separate component. You create it by selecting "Informal Topic" in the Create content dialog.

When you add a sidebar as an element in a topic, it works just like in DocBook. But when created as an "Informal Topic" object, it will be reusable as a component, and there will be no special styling for the element. Its child elements will appear in output just as if they had been used separately.