Skip to main content

Revision History Topics

A revision history is a list with a summary of the changes made to a document. They are useful as they provide an audit trail of the changes made to a document, with details of who made the changes, what the changes were, and when they were added.

For a PDF output, a revision history looks like this:

Revision history page from a PDF output. There is a list of revisions, each with details of the date, author, and a summary of the changes.

To create a revision history topic:

  1. Create a new topic. Give it a suitable name, such as "Revision History" and then open it in the editor.

    There are many ways to create a new topic, including:

    • Select New Topic from a publication's structure view

    • Select Create Content from a folder's options menu ( ... ) and then choose Topic.

    For details, see Topics.

  2. Use the element context menu to add an info element to the topic.

    To access the element context menu, press Alt and Enter (Windows) or Option ⌥ and Enter (Mac).

  3. Select the info element and then use the element context menu to add a revhistory element.

    When you add a revhistory element, Paligo adds child elements to it automatically.

    revision-history-added-to-topic.png

    The child elements are:

    • revision

      This is a container element for the revnumber, date, authorinitials and revremark elements. You need the revision for the structure, but do not enter any information directly into it.

    • revnumber

      Enter the number of the revision, for example, 6 if this is the sixth revision to the content.

    • date

      Paligo inserts the date automatically, by default. You can overwrite it with a different date if you wish.

    • authorinitials

      Paligo inserts the name of the person who adds the revision element, by default. You can overwrite it with a different name or initials if you wish.

    • revremark

      Enter a brief description of the changes that have been made. This will help other users to understand what each revision included and why the changes were made.

    Tip

    You can delete an element if you do not want to include that information in the revision history, for example, you could delete the date element.

  4. To add more revisions, select the revhistory element and then use the element context menu to add a revision element inside it. Paligo adds the revision element and its revnumber, date, authorinitials, and revremark.

  5. Select Save.

  6. If your revision history topic is not already in a publication, add it by editing the publication structure. Typically, the revision history is added as the first topic so that it appears before the main documentation, but you could add it to any position in the publication. You may also want to put an output filter on the section element so that the revision history is not included in outputs but remains in the publication for internal use. To learn how to filter content, see Filters (Profiling)).

When you publish your content, the revision history topic is included as part of the output (unless you have filtered it out). For HTML outputs, you can use CSS to control the styling of the revision history details (see Branding your HTML Outputs with CSS). For PDF outputs, only the default styling is available, although it is possible to change the styling as part of a customization project (contact customer support for details).

Example 1. Revhistory and revision structure

The following code shows the XML for a valid revision history topic. We have removed the XML IDs and attributes for clarity. When you create your own revision history, the elements will have XML IDs and attributes added when you save.

<?xml version="1.0"?>
<section>
    <title>Revision History</title>
    <info>
        <revhistory>
            <revision>
                <revnumber>2</revnumber> 
                <date>24 May 2022</date> 
                <authorinitials>CW</authorinitials> 
                <revremark>Added information on recycling and ordering replacement parts.</revremark>
            </revision>
            <revision>
                <revnumber>1</revnumber> 
                <date>20 May 2022</date> 
                <authorinitials>CW</authorinitials>
                <revremark>Added legal information in front matter.</revremark>
            </revision>
        </revhistory>
    </info>
</section>