Skip to main content

Bibliography Topic

Bibliographies are useful for keeping an organized record of any information sources that you reference in your publications. They can help improve the credibility of your documentation and also give your audience extra sources of useful information.

Example of a bibliography. It has numbered labels in the left column and the title, author, and other reference information in the right column. A PDF output is shown.

To get started:

  1. Read Raw and Cooked Bibliography Entries.

    There are two approaches to creating bibliography entries in DocBook, often called "cooked" and "raw". You will need to choose which approach you are going to use.

  2. Either create a new bibliography topic or create a bibliography at the end of one of your existing topics. You can then add bibliography entries to it. For details, see Create a Bibliography.

    Note

    If you have imported content into Paligo from elsewhere, Paligo may have already created a bibliography as part of the import process.

  3. In your content topics, add references to the bibliography entries. The references are called citations, see Add a Citation.

  4. If you created a separate topic for your Bibliography, add it to the relevant publication.

  5. Edit the bibliography settings on the Layout you are going to use for publishing. These settings are described in:

  6. Publish your content, see About Publishing.

Note

If you want to publish a bibliography that meets the ISO-690 standard, see Set Up an ISO 690 Bibliography .

Raw and Cooked Bibliography Entries

In DocBook 5.0 there are two different approaches to bibliography entries. They are sometimes called "raw" and "cooked" and Paligo supports them both.

Typically, we recommend that you:

  • Use "raw" entries if you are creating a new bibliography

  • Use "cooked" entries if they already exist in your content, for example, if you have imported content into Paligo and it already has "cooked" entries in place.

  • Only use all "raw" or all "cooked" entries. Do not mix the two types as this may produce inconsistent and unwanted results.

Raw Bibliographies

A "raw" bibliography is more structured than a "cooked" bibliography, as it does not allow for text between the elements. Every part of a bibliography entry has to be inside an appropriate element, such as firstname and surname. The ordering and formatting is handled internally by Paligo when you publish. There is default styling and ordering, but it is also possible to process your bibliography to match a specific standard (we can provide this as a customization project, contact support for details).

The characteristics of a "raw" bibliography are:

  • Uses the biblioentryelement (and not the bibliomixed element)

  • Does not allow text or characters between the elements.

  • Consistent structure and presentation.

  • Can be processed by Paligo to comply with bibliography standards.

If you are creating a new bibliography, we recommend that you use "raw" entries and avoid "cooked" entries. This is to help ensure consistency in your entries.

Note

Do not mix "raw" bibliography entries and "cooked" bibliography entries. If you do mix them, you may get inconsistent and unexpected results when you publish.

Example 1. Raw bibliography structure (bibliography in own topic)

Here is an example of a "raw" bibliography that is in a separate topic. It contains two bibliography entries, one is a single author and the other is a combination of authors. We have provided an example of a valid structure, but have removed the XML ids and other metadata for clarity.

<section >
  <title>Raw bibliography</title>
  <bibliography>
    <bibliodiv>
      <title>Books</title>
      <biblioentry>
        <abbrev>RizwanAJan2011</abbrev>
        <title>SaaS: A Beginner's Guide</title>
        <author>
            <personname>
                <firstname>Rizwan</firstname>
                <surname>Jan</surname>
            </personname>
        </author>
        <date>2011</date>
        <publisher>
            <publishername>McGraw-Hill Education</publishername>
        </publisher>
        <bibliomisc>ISBN: 978-0071753759</bibliomisc>
       </biblioentry>
      <biblioentry>
        <abbrev>MenkenBlokdijk2009</abbrev>
        <title>SaaS and Web Applications Specialist Level Complete Certification Kit
 - Software as a Service Study Guide Book and Online Course</title>
        <authorgroup>
            <author>
                <personname><firstname>Ivanka</firstname> <surname>Menken</surname></personname>
            </author> 
            <author>
                <personname><firstname>Gerard</firstname> <surname>Blokdijk</surname></personname>
            </author>
        </authorgroup>
        <date>2009</date>
        <publisher>
          <publishername>Emereo Publishing</publishername>
        </publisher>
        <bibliomisc>ISBN: 978-1921523311</bibliomisc>
      </biblioentry>
    </bibliodiv>
  </bibliography>
</section>

Cooked Bibliographies

A "cooked" bibliography, while structured, does allow for more freeform bibliography entries. You create a "cooked" entry by using the bibliomixed element and then adding your other bibliography elements inside that, such as firstname and surname. Importantly, you can add characters between the elements and Paligo will include them in the published output. So if you include punctuation between your bibliography entry elements, the punctuation will be present in the output too. Paligo does not change the entries or reorder them.

The key characteristics of "cooked" bibliography entries are:

  • Uses the bibliomixed element (and not the biblioentry element).

  • Give you more control over your entries.

    The information you provide is exactly what you get in the output. Paligo keeps the characters in the elements and between the elements and does not change the order.

  • Can result in inconsistent entries.

    The more freeform nature of "cooked" entries means you could structure each entry in a different order with different punctuation and text between the elements.

If you are creating a new bibliography, we recommend that you avoid "cooked" entries and use "raw" entries instead. This is because "raw" entries are consistent. But if you have "cooked" entries already, perhaps due to importing content, then you can continue using those. Paligo can publish them.

Note

Do not mix "raw" bibliography entries and "cooked" bibliography entries. If you do mix them, you may get inconsistent and unexpected results when you publish.

Example 2. Cooked bibliography structure (bibliography in own topic)

Here is an example of a "cooked" bibliography that is in a separate topic. It contains two bibliography entries, one is a single author and the other is a combination of authors. We have provided an example of a valid structure, but have removed the XML ids and other metadata for clarity.

Note how characters are allowed between some elements, in this case, we have used a pipe character | and a period, and we have used them inconsistently. We have also changed the order of the elements for the second bibliomixed entry, again adding inconsistency.

<section>
<title>Cooked bibliography</title>
<bibliography>
    <bibliodiv>
      <title>Books</title>
      <bibliomixed>
        <abbrev>RizwanAJan2011</abbrev>
        <title>SaaS: A Beginner's Guide</title> | 
        <author><personname><firstname>Rizwan</firstname><surname>Jan</surname></personname></author>
        .
        <pubdate>2011</pubdate>.
        <publishername>McGraw-Hill Education</publishername> |
        <bibliomisc>ISBN: 978-0071753759</bibliomisc>.
       </bibliomixed>
      <bibliomixed>
        <abbrev>MenkenBlokdijk2009</abbrev>
        <title>SaaS and Web Applications Specialist Level Complete Certification Kit</title>.
        <volumenum>2</volumenum>|<issuenum>1</issuenum>.
        <pubdate>Summer, 2009</pubdate>.
        <bibliomisc>ISBN: 978-1921523311</bibliomisc>.
        <author><personname><firstname>Ivanka</firstname><surname>Menken</surname></personname></author> | 
        <author><personname><firstname>Gerard</firstname><surname>Blokdijk</surname></personname></author>.
        <publishername>Emereo Publishing</publishername>.
      </bibliomixed>
    </bibliodiv>
  </bibliography>
</section>

Create a Bibliography

Depending on your requirements, you can either create:

  • A bibliography topic that appears at the end* of a publication.

    * Traditionally, bibliographies appear towards the end of a publication, near the index. You can place the bibliography elsewhere in your publication if you prefer. We call this a stand-alone bibliography.

  • A bibliography inside a topic that contains other content.

    This is useful if you have a topic that acts as a reference article and you want people to be able to see the citations without leaving the page. The bibliography is included immediately after the content, rather than in a topic that is elsewhere in the publication. We call this an end-of-topic bibliography.

Create a Bibliography as a Separate Topic

To create a bibliography topic that you can add to the end of your publication (or elsewhere if you prefer):

  1. Create a new topic, give it a name, and then add it to a publication. For this procedure, we will assume that you named the topic "Bibliography".

    For details, see Create a Topic and Add Content to a Publication.

  2. Save the publication.

  3. In the Content Manager, select your "Bibliography" topic to open it in the editor.

  4. Select a position after the title element but before the first para element (the para element is included in the topic by default).

  5. Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.

    Element context menu shows a search field and a list of elements that are valid at the current position.

  6. Use the element context menu to add the bibliography element.

  7. Build your bibliography structure inside the bibliography element. To build the structure, you will need to use the various bibliography elements, as described in the DocBook 5.2 documentation (see https://tdg.docbook.org/tdg/5.2/bibliography.html).

    We have included an example bibliography at the end of this article. It shows a valid bibliography structure, so you can copy that structure as a starting point.

  8. Select Save. Save icon.

You have now created a bibliography. Over time, you may find that you want to add extra bibliography entries, in which case, edit the bibliography topic and add more biblioentry ("raw") or bibliomixed ("cooked") elements.

Now that you have a bibliography, you can add references (citations) to it from your other topics, see Add a Citation.

Example 3. Bibliography as a separate topic

The following code samples show the underlying structure of a valid bibliography topic. When you are creating your own bibliography, look at the examples to see how the various bibliography elements are used. Some are "parents" and others are "children", for example, author is a parent of personname and personname is a parent of firstname.

Here is an example of a bibliography that uses "raw" entries:

<bibliography>
    <title>A Test Bibliography</title>
    <bibliodiv>
        <title>Books</title>
        <biblioentry>
            <abbrev>AhoSethiUllman96</abbrev>
            <authorgroup>
                <author>
                    <personname>
                        <firstname>Alfred V.</firstname>
                        <surname>Aho</surname>
                    </personname>
                </author>
                <author>
                    <personname>
                        <firstname>Ravi</firstname>
                        <surname>Sethi</surname>
                    </personname>
                </author>
                <author>
                    <personname>
                        <firstname>Jeffrey D.</firstname>
                        <surname>Ullman</surname>
                    </personname>
                </author>
            </authorgroup>
            <copyright>
                <year>1996</year>
                <holder>Bell Telephone Laboratories, Inc.</holder>
            </copyright>
            <editor>
                <personname>
                    <firstname>James T.</firstname>
                    <surname>DeWolf</surname>
                </personname>
            </editor>
            <biblioid class="isbn">0-201-10088-6</biblioid>
            <publisher>
                <publishername>Addison-Wesley Publishing Company</publishername>
            </publisher>
            <title>Compilers, Principles, Techniques, and Tools</title>
        </biblioentry>
        <biblioentry>
            <authorgroup>
                <author>
                    <personname>
                        <firstname>Andrea</firstname>
                        <surname>Bahadur</surname>
                    </personname>
                </author>
                <author>
                    <personname>
                        <firstname>Mark</firstname>
                        <surname>Shwarek</surname>
                    </personname>
                </author>
            </authorgroup>
            <copyright>
                <year>1974</year>
                <year>1975</year>
                <holder>Product Development International Holding N. V.</holder>
            </copyright>
            <biblioid class="isbn">0-88459-021-6</biblioid>
            <publisher>
                <publishername>Plenary Publications International, Inc.</publishername>
            </publisher>
            <title>Kites</title>
            <subtitle>Ancient Craft to Modern Sport</subtitle>
            <pagenums>988-999</pagenums>
        </biblioentry>
    </bibliodiv>
    <bibliodiv>
        <title>Periodicals</title>
        <biblioentry>
            <abbrev>Walsh97</abbrev>
            <biblioset relation="journal">
                <title>XML: Principles, Tools, and Techniques</title>
                <publisher>
                    <publishername>O'Reilly &amp; Associates, Inc.</publishername>
                </publisher>
                <biblioid class="issn">1085-2301</biblioid>
                <editor>
                    <personname>
                        <firstname>Dan</firstname>
                        <surname>Connolly</surname>
                    </personname>
                </editor>
            </biblioset>
            <biblioset relation="article">
                <title>A Guide to XML</title>
                <author>
                    <personname>
                        <surname>Walsh</surname>
                        <firstname>Norman</firstname>
                    </personname>
                </author>
                <copyright>
                    <year>1997</year>
                    <holder>ArborText, Inc.</holder>
                </copyright>
                <pagenums>97-108</pagenums>
            </biblioset>
        </biblioentry>
    </bibliodiv>
</bibliography>

Note

The "raw" bibliography does not contain any formatting between the elements.

The next code sample shows the same bibliography, but using cooked entries. Here, there is formatting between the elements, such as commas between the firstname and surname entries, and periods after some surname elements. Paligo will keep this formatting when you publish. Notice how this can result in inconsistent entries.

<bibliography>
    <title>A Test Bibliography</title>
    <bibliodiv>
        <title>Books</title>:
        <bibliomixed>
            <abbrev>AhoSethiUllman96</abbrev>
            <authorgroup>
                <author>
                    <personname>
                        <firstname>Alfred V.</firstname>,<surname>Aho</surname>.
                    </personname>
                </author>
                <author>
                    <personname>
                        <firstname>Ravi</firstname>, <surname>Sethi</surname>.
                    </personname>
                </author>
                <author>
                    <personname>
                        <firstname>Jeffrey D.</firstname>, <surname>Ullman</surname>.
                    </personname>
                </author>
            </authorgroup>
            <copyright>
                <year>1996</year>
                <holder>Bell Telephone Laboratories, Inc.</holder>.
            </copyright>
            <editor>
                <personname>
                    <firstname>James T.</firstname>, <surname>DeWolf</surname>.
                </personname>
            </editor>
            <biblioid class="isbn">0-201-10088-6</biblioid>
            <publisher>
                <publishername>Addison-Wesley Publishing Company</publishername>.
            </publisher>
            <title>Compilers, Principles, Techniques, and Tools</title>
        </bibliomixed>
        <bibliomixed>
            <abbrev>Kites74</abbrev>
            <authorgroup>
                <author>
                    <personname>
                        <firstname>Andrea</firstname>, <surname>Bahadur</surname>.
                    </personname>
                </author>
                <author>
                    <personname>
                        <firstname>Mark</firstname>, <surname>Shwarek</surname>.
                    </personname>
                </author>
            </authorgroup>
            <copyright>
                <year>1974</year> -
                <year>1975</year>.
                <holder>Product Development International Holding N. V.</holder>
            </copyright>
            <biblioid class="isbn">0-88459-021-6</biblioid>
            <publisher>
                <publishername>Plenary Publications International, Inc.</publishername>
            </publisher>
            <title>Kites</title>
            <subtitle>Ancient Craft to Modern Sport</subtitle>
            <pagenums>988-999</pagenums>
        </bibliomixed>
    </bibliodiv>
    <bibliodiv>
        <title>Periodicals</title>
        <bibliomixed>
            <abbrev>Walsh97</abbrev>
            <biblioset relation="journal">
                <title>XML: Principles, Tools, and Techniques</title>
                <publisher>
                    <publishername>O'Reilly &amp; Associates, Inc.</publishername>
                </publisher>
                <biblioid class="issn">1085-2301</biblioid>
                <editor>
                    <personname>
                        <firstname>Dan</firstname>, <surname>Connolly</surname>.
                    </personname>
                </editor>
            </biblioset>
            <biblioset relation="article">
                <title>A Guide to XML</title>
                <author>
                    <personname>
                        <surname>Walsh</surname>,<firstname>Norman</firstname>.
                    </personname>
                </author>
                <copyright>
                    <year>1997</year>.
                    <holder>ArborText, Inc.</holder>
                </copyright>
                <pagenums>97-108</pagenums>
            </biblioset>
        </bibliomixed>
    </bibliodiv>
</bibliography>

Create an End-Of-Topic Bibliography

To create a bibliography that appears at the end of a topic:

  1. In the Content Manager, select the topic that you want to edit.

    Alternatively, you can create a new topic and edit that (see Create a Topic).

  2. Position the cursor after the content in your topic. It needs to be on a new line, as if you were going to add a new paragraph.

  3. Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.

    Element context menu shows a search field and a list of elements that are valid at the current position.

  4. Add the bibliolist element.

    Note

    We recommend that you use bibliolist instead of bibliography for end-of-topic bibliographies.

  5. Build your bibliography structure inside the bibliolist element. To build the structure, you will need to use the various bibliography elements, as described in the DocBook 5.2 documentation (see https://tdg.docbook.org/tdg/5.2/bibliography.html).

    We have included an example bibliography at the end of this article. It shows a valid bibliography structure, so you can copy that structure as a starting point.

  6. Select Save. Save icon.

  7. In the content of your topic, add references (citations) from the content to the bibliography entries, see Add a Citation.

Example 4. Bibliography at the end of a topic

The following code shows the underlying structure of a valid end-of-topic bibliography. When you are creating your own bibliography, look at the example to see how the various bibliography elements are used. Some are "parents" and others are "children", for example, author is a parent of personname and personname is a parent of firstname.

<?xml version="1.0"?>
<section>
  <title>Security in websites and data-centric applications</title>
  <para>As websites and other data-centric applications become increasingly common, users are required to trust the confidentiality and integrity of the data the applications collect, store and present <citation>Harauz, Kaufman &amp; Potter, 2009</citation>.</para>
  <para>Because of this,  these types of applications have become enticing targets for hackers wanting to input or access information without the owner’s permission. Inadequate security on the data input can allow hackers to create scams or spam, misleading or harassing users using automated bots <citation>Yan &amp; El Ahmad, 2009</citation>.</para>
  <para>These bots are capable of performing actions at a significantly higher rate than any human could. Bot creators have used this advantage to rig online polls, create large amounts of email addresses used for spamming and to attempt dictionary attacks against password systems <citation>von Ahn et al., 2003</citation>.</para>
  <para>Furthermore, insufficient security when it comes to storing or accessing data can allow hackers access to confidential and private information such as credit card information and personal security details.</para>
  <bibliolist>
    <biblioentry>
        <title>Data Security in the World of Cloud Computing</title>
        <abbrev>Harauz, Kaufman &amp; Potter, 2009</abbrev>
        <author>
            <personname>Harauz J</personname>
        </author>
        <author>
            <personname>Kaufman L.M</personname>
        </author>
        <author>    
            <personname>Potter B</personname>
        </author>
        <pubdate>2009</pubdate>
        <citetitle>IEEE Security &amp; Privacy. 7</citetitle>
    </biblioentry>
    <biblioentry>
        <title>CAPTCHA security: A Case Study. IEEE Security &amp; Privacy</title>
        <abbrev>Yan &amp; El Ahmad, 2009</abbrev>
        <author>
            <personname>Yan J</personname>
        </author>
        <author>
            <personname>El Ahmad A.S</personname>
        </author>
        <pubdate>2009</pubdate>
        <citetitle>IEEE Security &amp; Privacy. 7</citetitle>
    </biblioentry>
    <biblioentry>
        <title>CAPTCHA: Using Hard AI Problems for Security</title>
        <abbrev>von Ahn et al., 2003</abbrev>
        <author>
            <personname>Von Ahn L</personname>
        </author>
        <author>
            <personname>Blum M</personname>
        </author>
        <author>
            <personname>Hopper, N.J</personname>
        </author>
        <author>
            <personname>Langford J</personname>
        </author>
        <pubdate>2003</pubdate>
        <citetitle>Lecture Notes in Computer Science. 2656</citetitle>
    </biblioentry>
  </bibliolist>
</section>

Add a Citation

Abstract

Learn how to add a citation in Paligo. A citation is a reference to an entry in a bibliography.

A citation is a reference to a bibliography entry, such as a book's author, title, and publisher. You can add citations to your topics and when you publish, Paligo will convert them into hyperlinks to the appropriate bibliography entries.

Note

Depending on how bibliographies are set up, the hyperlink could navigate to a dedicated bibliography page or to a bibliography list at the end of the current section.

To learn about setting up these different types of bibliography, see Create a Bibliography.

There are two ways of using citations. You can:

  • Add a citation that uses the same text as an abbrev element in a bibliography entry. The text has to match exactly.

  • Add a citation that uses different text to the bibliography entry.

    For this, you add a citation and then add a cross-reference to a bibliography element's xml:id attribute. The xml:id attribute is on a biblioentry element or a bibliomixed element, depending on whether you use "raw" or "cooked" entries.

Add a Citation with the Same Text as a Bibliography Entry

You can add a citation to a topic and use it to reference a bibliography entry. For the reference to work, you need:

  • A bibliography entry that has an abbrev element in its structure

  • A citation that contains the exact same text as the bibliography entry's abbrev element.

Note

If your bibliography does not have an abbrev element, you can use the element context menu to add one. For details, see Create a Bibliography.

To add a citation that references the abbrev element of a bibliography entry:

  1. In the Content Manager, select the topic that contains your bibliography.

    Paligo opens the topic in the Editor.

  2. Select the bibliography entry that you want to reference and select the text in its abbrev element.

    A partial screenshot of a bibliography topic that is open in the Paligo editor. The abbrev element is highlighted in the Element Structure Menu at the top. A callout arrow points to a highlighted bibliography entry in the topic's body area.

  3. Copy the text inside the abbrev element.

    Note

    This may produce unexpected results if the text in your abbrev element contains special characters, such as an ampersand ( & ). If your text has special characters, open the topic in the Source Code Editor instead and copy the text in the abbrev element from there instead.

  4. In the Content Manager, select the topic that will contain the citation.

    Note

    This step only applies if you want to add a reference to a bibliography that is in a different topic to the citation. If they are both in the same topic, ignore this step.

    Paligo opens the topic in the editor.

  5. Position the cursor where the citation is to be added.

  6. Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.

    Element context menu shows a search field and a list of elements that are valid at the current position.

  7. Search for the citation element and then add it.

    A screenshot of a paragraph in the Paligo editor. Part way through the paragraph the Element Content Menu is shown. The user has searched for "cita" and as a result, the menu has found the citation element.

  8. Paste the text from the bibliography entry's abbrev element into the citation element. Paligo uses the text to match the citation to the bibliography entry, so make sure that they are identical. Look out for extra spaces or similar characters that might be included in the citation accidentally, as these may stop the reference from working correctly.

    A paragraph that contains a citation. A callout arrow points to the citation.

  9. Select Save. Save icon.

Note

If you publish with a Layout that has bibliography auto-numbering activated, your citation text is replaced with a number in square brackets. The number is a hyperlink to the matching entry in your bibliography.

As the number replaces the citation text, you may want to include a reference to the authors or document in the text before the citation.

To learn how to set up numbered bibliographies, see Bibliography Auto-Numbering.

Add a Citation that is Different to a Bibliography Entry

If you want to add a citation that has different text to the bibliography entry, use a citation element and add a cross-reference inside it. The cross-reference needs to be to the xml:id of the relevant biblioentry element.

  1. In the Content Manager, select the topic that will contain the citation.

    Note

    This step only applies if you want to add a reference to a bibliography that is in a different topic to the citation. If they are both in the same topic, ignore this step.

    Paligo opens the topic in the editor.

  2. Position the cursor where you want to add the citation.

  3. Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.

    Element context menu shows a search field and a list of elements that are valid at the current position.

  4. Add the citation to the topic.

    You may need to use the search at the top of the menu to locate the citation element.

  5. Add a new para element below the citation and click inside it. You are going to use this para to get the correct link to the bibliography entry.

  6. Select Insert and then Link followed by Cross-reference.

  7. Find your bibliography topic in the New cross-reference dialog.

  8. Expand the bibliography topic so that you can see its elements.

    New cross-reference dialog. It shows the user has browsed to the bibliography topic and expanded it to reveal its elements. Callout arrows point to three different biblioentry elements.

    Note

    If you cannot see the biblioentry element for the bibliography element you want to reference, it is because it has no XML:ID. You will need to open the bibliography topic and generate an ID for the biblioentry element. When you have done that, it will be available to use as a cross-reference.

  9. Select the biblioentry element that you want the citation to reference.

    Paligo adds a cross-reference to the bibliography entry.

  10. Click on the link and look at the Element attributes panel. It should show that the link (xref) has an xlink:href attribute and the value of that attribute is the target of the link. Highlight the entire value and copy it to your clipboad (ctrl + C or cmd + C).

    Element attributes panel. The link element is selected. It has an xlink:href attribute and the value is a URL. A callout box highlights the xlink:href attribute and its value.

  11. Click inside the citation element.

  12. In the Element attributes panel, make sure citation is shown as the selected element. Add the the linkend attribute and paste in the value that you copied from the cross-reference.

    Element attributes panel. The citation element is selected. It has a linkend attribute and the value is a URL. A callout box highlights the linkend attribute and its value.

  13. Delete the para that contains the cross-reference.

  14. Select Save. Save icon.

When you publish your content, Paligo turns the citation into a hyperlink to the relevant bibliography entry.

Note

If you publish with a Layout that has bibliography auto-numbering activated, your citation text is replaced with a number in square brackets. The number is a hyperlink to the matching entry in your bibliography.

As the number replaces the citation text, you may want to include a reference to the authors or document in the text before the citation.

To learn how to set up numbered bibliographies, see Bibliography Auto-Numbering.

Bibliography Auto-Numbering

Paligo can automatically number the entries in your bibliography and replace citations to them with a number. The number also acts as a hyperlink from the topic with the citation to the bibliography.

When you activate bibliography auto-numbering, Paligo numbers your bibliography entries. The number is a prefix to the entry and is shown in square brackets.

A bibliography topic. It contains several bibliography entries. Each entry has a number inside square brackets as a prefix to the entry.

Example of a bibliography with numbered entries

Paligo also sets your citations to reference the number of a bibliography entry instead of the text in its abbrev element.

A paragraph that contains a citation element. Where the citation appears, Paligo inserts square brackets and the number of the referenced bibliography entry.

Example of a citation in a topic that has had its text replaced with a number reference.

To set your bibliography and citations to use numbers instead of text:

  1. Select Layout in the top menu.

    Paligo editor. The Layout option in the header menu is highlighted.

    Paligo displays a list of Layouts. The list is empty if there are no custom Layouts in your Paligo instance.

  2. Select the Layout you want to use for publishing.

    The bibliography auto-numbering feature is available for HTML5 Help Center, HTML, and PDF Layouts.

  3. Select the relevant category.

    For PDF Layouts, select Glossary, Index, and Bibliography.

    For HTML and HTML5 Help Center Layouts, select General.

  4. Use the Bibliography auto numbering setting to control the numbering of bibliography entries and citations.

    Choose either:

    • Enable to turn on auto-numbering for bibliographies.

    • Disable to turn off auto-numbering for bibliographies.

    • Default to inherit the value for this setting from the base Layout. The base Layout is either a built-in Layout provided by Paligo or another custom Layout, see Layout Relationships - Base, New, Duplicate.

  5. Select Save.

When you use the Layout for publishing, Paligo will apply your choice to the bibliography entries and citations.

Cooked Bibliography Entries in a List

By default, "cooked" bibliography entries appear with a hanging indent (start indent and text indent) in PDF outputs. If you prefer, you can set them to be displayed as a list with a label and spacing.

Example of a bibliography. It has numbered labels in the left column and the title, author, and other reference information in the right column. A PDF output is shown.

In the image shown, the "cooked" bibliography is set to use numbered entries and also to display as a list. Notice that the numbers are "labels" and there is equal spacing between those and the bibliography entries.

Note

The following instructions only apply to "cooked" bibliographies in PDF outputs.

To learn about "cooked" bibliographies, see Raw and Cooked Bibliography Entries.

To set a "cooked" bibliography to display as a list with labels for PDF:

  1. Select Layout in the top menu.

    Paligo editor. The Layout option in the header menu is highlighted.

    Paligo displays a list of Layouts. The list is empty if there are no custom Layouts in your Paligo instance.

  2. Select the PDF Layout you are going to use for publishing. Alternatively, create a new one (see Create a Layout).

  3. Select General in the sidebar. New_Layout.jpg

    Select_General_PDF_small.jpg

  4. Select Glossary, Index, and Bibliography.

  5. Set Display bibliomixed as a list to:

    • Enable if you want the bibliography to be presented as a list with labels and a space between the labels and entries.

    • Disable if you want the bibliography to be presented as a regular list without spacing.

    PDF Layout setting "Display bibliomixed as a list". It is set to Enable.

  6. Use the bibliomixed label separation field to set the amount of space between the labels and the bibliography entries. Enter the value and the units of measurement, for example, 3em.

    PDF Layout setting "bibliomixed label separation". It is set to 3em.

  7. Select Save.

When you use this PDF Layout to publish your content, Paligo will apply the list and label separation settings to your bibliography.

If your labels do not appear as expected, see Troubleshooting Labels for "Cooked" Bibliography Entries

Troubleshooting Labels for "Cooked" Bibliography Entries

If the labels are not displaying as you would expect, it is likely because of how you have set up your bibliography entries and PDF Layout. The label for an entry can come from various sources, but Paligo looks for these in a specific order:

  1. Automatically-generated number.

    If the Layout setting Bibliography Auto numbering is on, Paligo will display a number in square brackets []. This is used as the label.

  2. abbrev element.

    If the first child element of bibliomixed is abbrev, Paligo will use the contents of abbrev as the label.

  3. xreflabel element.

    If the attribute xreflabel is set on the bibliomixed element, Paligo will use the value of xreflabel as the label.

  4. id attribute

    If the attribute id is set on the bibliomixed element, Paligo will use the the value of id as the label.

    Note

    Paligo looks for the id attribute, not the xml:id attribute.

  5. If none of the above exist, Paligo will use an empty label.

Using the information above, you can try to fix your labels, either by changing the Layout settings or changing the structure of your bibliography elements (see Create a Bibliography).

Deactivate Bibliography Auto-Titles

By default, Paligo automatically adds a "Bibliography" title to bibliographies in HTML, HTML5 and PDF outputs. You can choose to disable this feature if you prefer.

For example, if you have a bibliography inside a topic named "Bibliography", you will get two "Bibliography" titles, one for the topic and one for the bibliography. In this scenario, you will most likely want to disable the auto-title so that you only get the topic title.

A topic with the title "Bibliography". Inside the topic, there is a second title "Bibliography" and this is an auto-generated title.
A topic with the title "Bibliography". Inside the topic, there is no second title. The auto-title feature is turned off.

Tip

For PDF output, this setting is found under General → Glossary, Index, and Bibliography in Layout Editor.

To control the bibliography auto-titles:

  1. Select Layout in the top menu.

    Paligo editor. The Layout option in the header menu is highlighted.

    Paligo displays a list of Layouts. The list is empty if there are no custom Layouts in your Paligo instance.

  2. Select the Layout you want to update or Create a Layout.

    Tip

    You can copy the URL of the Layout Editor and paste it into a new tab in your browser. This can be useful if you frequently switch between your Paligo content and the Layout settings.

  3. Select General in the sidebar.

  4. Select Glossary, Index, and Bibliography. This step only applies when editing a PDF Layout.

  5. Use Bibliography auto-title to turn the automatic title on or off.

    Choose:

    • Enable to turn on auto-titles. Default

    • Disable to turn off the auto-titles.

    Bibliography_Auto_Title.png

  6. Select Save.

Set Up an ISO 690 Bibliography

The ISO 690 standard defines rules for bibliography entries. It is designed to help make sure bibliography entries are consistent and contain appropriate information. You can set Paligo to publish your bibliographies to meet the ISO 690 standard.

Note

We assume that you have a working knowledge of the ISO 690 standard and have purchased a copy from www.iso.org or a local equivalent. It is beyond the scope of this documentation to explain the standard.

We explain what you need to set up in Paligo and what elements are available for structuring the information needed for ISO 690. For details on the individual elements, refer to the DocBook documentation .

To create an ISO 690 bibliography:

  1. Create a bibliography. You can create one in a dedicated "bibliography" topic or add one to the end of a topic. For instructions, see Create a Bibliography.

    Note

    For an ISO 690 bibliography, you will need to create a "raw" bibliography. This means you cannot have any characters or punctuation between the bibliography elements (see Raw and Cooked Bibliography Entries).

  2. When you have created a bibliography, you will need to add your bibliography entries. For ISO 690, you will need to add a variety of bibliography elements and you will also need to give some of them attributes and values. These vary depending on the type of bibliography entry you are making.

    For information on the elements you need to add, see:

    If you need to make references to patent documents, please contact support for help.

  3. Set your Layout to use the ISO 690 bibliography style. With this in place, when you publish, Paligo will create an output that has the various bibliography elements organized into the correct order for ISO 690.

    Note

    The published output will have the bibliography entry information in an order that meets the ISO 690 standard. But the elements will remain in their original order when viewed in the Paligo editor. Paligo only changes the order in the published output.

  4. Publish your content using the same Layout you edited in the previous step.

Tip

The full name of the standard is ISO Standard 690 - Information and Documentation — Guidelines for bibliographic references and citations to information resources. You can find it at www.iso.org.

References to a Monograph (Book or Similar Publication)

To comply with the IS0 690 standard, your references to monographs (entire documents, such as books) can include various types of information. Some of the information has to be included while other parts are optional.

Note

For some elements, you will need to add attributes and values. For instructions on adding these to an element, see Add Attributes.

Required elements

You must include the following elements:

  • biblioentry element with a role attribute. Set the attribute value to monograph. This is a wrapper element. All of the other required elements for this bibliography entry must be children of this biblioentry element.

Optional Elements

The following elements are optional:

Examples of Monograph References

Example 5. Book Monograph Reference for ISO 690 bibliography

The following code shows a valid entry for a reference to a monograph that is a book.

Note

The abbrev element is required by Paligo to match citations in your topics to the appropriate bibliography entry. It is not a requirement for ISO 690.

<biblioentry role="monograph">
    <abbrev>Rand18</abbrev>
    <author>
        <personname>
            <surname>Henry</surname>
            <firstname>MP.</firstname>
        </personname>
    </author>
    <editor>
        <personname>
            <surname>James</surname>
            <firstname>LP.</firstname>
        </personname>
    </editor>
    <author>
        <orgname>Acme Industries</orgname>
    </author>
    <authorgroup>
        <author>
            <personname>
                <surname>Scott</surname>
                <firstname>TJ.</firstname>
            </personname>
        </author>
        <author>
            <personname>
                <surname>Boswell</surname>
                <firstname>JM.</firstname>
            </personname>
        </author>
    </authorgroup>
    <title>Microbial Adaptations in Space Environments</title>
    <subtitle>Survival Strategies and Evolutionary Responses</subtitle>
    <bibliomisc role="secondary">revised by D.J Keane</bibliomisc>
    <edition>5th ed.</edition>
    <publisher>
        <publishername>General Press</publishername>
        <address>
            <city>London</city>
        </address>
    </publisher>
    <pubdate>1998</pubdate>
    <pagenums>206 p.</pagenums>
    <bibliomisc role="serie">International series in space microbiology</bibliomisc>
    <bibliomisc>Text in English and French</bibliomisc>
    <biblioid class="isbn">0-08-021680-3</biblioid>
</biblioentry>

Example 6. Online Resource Monograph for IS0 690 Bibliography

The following code shows a valid structure for a bibliography entry that references an online resource monograph.

Note

The abbrev element is required by Paligo to match citations in your topics to the appropriate bibliography entry. It is not a requirement for ISO 690.

<biblioentry role="monograph">
    <abbrev>Rand20</abbrev>
    <title>Advancements in Lunar Rovers</title>
    <subtitle>Enhancing Mobility on Extraterrestrial Surfaces</subtitle>
    <bibliomisc role="medium">online</bibliomisc>
    <edition>v1.3</edition>
    <author>
        <orgname>Stellar Innovations Consortium</orgname>
    </author>
    <pubdate>2023</pubdate>
    <date role="upd">Updated 2023</date>
    <date role="cit">Viewed 6 June 2023</date>
    <publisher>
        <publishername>Stellar Publications</publishername>
        <address>
            <city>London</city>
        </address>
    </publisher>
    <bibliomisc>Text in English and French</bibliomisc>
    <biblioid class="uri">
        <link xlink:href="https://stellaradvancements.com/books/advancements-lunar-rovers.html" />
    </biblioid>
</biblioentry>

References to a Contribution (Book or Similar Publication)

If your bibliography needs to comply with ISO 690 and reference a contribution to a book, make sure you include the required elements. You will need to reference each contribution separately. For example, if you reference chapters 4 and 10, you will need two separate references, one for chapter 4 and one for chapter 10. This is because each chapter of the book has different authors.

Note

For some elements, you will need to add attributes and values. For instructions on adding these to an element, see Add Attributes.

Required elements

You must include the following elements in your bibliography entry structure:

  • biblioentry element with a role attribute. Set the value of the attribute to contribution. This is a wrapper element. All of the other elements for this bibliography entry must be children of this biblioentry element.

    For example:

    <biblioentry role="contribution">
    <!-- other elements for bibliography entry details -->
</biblioentry>

  • biblioset with relation attribute and value set to part.

    This is a wrapper element for the contribution creator details and the title.

    <biblioset relation="part">
        <!-- other elements for reference to part -->
</biblioset>

  • Use the author details define the name of the contributors.

  • Use for the title of the chapter or section that you are referencing.

  • biblioset with role attribute and value set to book.

    This is a wrapper element for details about the book in its entirety. Inside the biblioset, you must include the elements listed below. These elements are mostly the same as those used for a monograph reference, so refer to References to a Monograph (Book or Similar Publication) for more detail and examples.

Optional elements

The following elements are optional:

  • The following elements are optional inside a biblioset with role attribute and value set to book:

Contribution Reference for ISO 690 Bibliography

The following code shows the structure for a bibliography reference for a contribution. Note that it includes details of the contribution and also the entire book, of which the contribution is a part. We have included comments to show where the information is defined.

<biblioentry role="contribution">
<abbrev>R100</abbrev>
    <!-- Contribution information -->
    <biblioset relation="part">
        <author>
            <personname>
                <surname>Allsop</surname>
                <firstname>RB.</firstname>
            </personname>
        </author>
        <title>Data Processing in Orbital Mechanics</title>
        <subtitle>Enhancing Satellite Trajectory Calculations</subtitle>
        <!-- Overall Book Title -->
        <biblioset relation="book">
            <author>
                <personname>
                    <surname>Keane</surname>
                    <firstname>DJ.</firstname>
                </personname>
            </author>
            <title>Advancements in Space Technology</title>
            <publisher>
                <publishername>SpaceTech Foundation</publishername>
                <address>
                    <city>London</city>
                </address>
            </publisher>
            <pubdate>2022</pubdate>
            <volumenum>vol. 3</volumenum>
            <pagenums>p. 155-167</pagenums>
        </biblioset>
    </biblioset>
</biblioentry>

References to Parts of a Monograph

If you need your bibliography to comply with ISO 690 and you want to reference part of a monograph (such as a book), add the Required elements.

Note

For some elements, you will need to add attributes and values. For instructions on adding these to an element, see Add Attributes.

Required elements

You must include the following elements:

  • biblioentry element with a role attribute. Set the attribute value to part. This is a wrapper element. All of the other required elements for this bibliography entry must be children of this biblioentry element.

  • bibliomisc element with a role attribute. Set the attribute value to secnum. This is for the section number.

  • bibliomisc element with a role attribute. Set the attribute value to sectitle. This is for the title of the section.

Optional Elements

The following elements are optional:

Example of Part of Monograph Bibliography Entry

The following code shows a valid entry for a reference to part of a monograph (book).

Note

The abbrev element is required by Paligo to match citations in your topics to the appropriate bibliography entry. It is not a requirement for ISO 690.

<biblioentry role="part">
    <abbrev>Rand18</abbrev>
    <author>
          <personname>
                <firstname>Sophia</firstname>
                <surname>Garcia</surname>
          </personname>
    </author>
    <editor>
        <personname>
            <surname>James</surname>
            <firstname>LP.</firstname>
        </personname>
    </editor>
    <orgname>Cosmic Industries</orgname>
    <bibliomisc role="secnum">12</bibliomisc>
    <bibliomisc role="sectitle>Navigating Celestial Trajectories</bibliomisc>
    <title>Advancements in Space Technology</title>
    <editor>Alex Johnson</editor>
    <pagenums>55-78</pagenums>
    <publisher>
        <publishername>General Press</publishername>
        <address>
            <city>London</city>
        </address>
    </publisher>
    <pubdate>2023</pubdate>
    <bibliomisc>Text in English and French</bibliomisc>
    <biblioid class="isbn">0-08-021680-3</biblioid>
</biblioentry>

References to a Serial Publication

To comply with the IS0 690 standard, your references to serials (publications issued in successive parts, continued indefinitely) can include various types of information.

Note

For some elements, you will need to add attributes and values. For instructions on adding these to an element, see Add Attributes.

Required elements

You must include the following elements:

  • biblioentry with a role attribute. Set the attribute value to serial. This is a wrapper element. All of the other required elements for this bibliography entry must be children of this biblioentry element.

Optional elements

The following elements are optional:

Reference to a Serial Publication for ISO 690 Bibliography

The following example shows a bibliography entry that references a serial. It references the serial as an entire document and does not reference a particular article inside the serial.

<biblioentry role="serial">
    <abbrev>ISSR</abbrev>
    <title>Interstellar Scientific Review</title><biblioset>
    <edition>5th ed.</edition>
    <publisher>
        <publishername>General Press</publishername>
        <address>
            <city>London</city>
        </address>
    </publisher>
    <pubdate>2022-2023</pubdate>
    <issuenum>no.12</issuenum>
    <biblioid class="issn">0700-0758</biblioid>
</biblioentry>

References to Articles in a Serial Publication

If your bibliography needs to comply with ISO 690 and reference a specific article in a serial, make sure you include the required elements. (A serial is a publication issued in successive parts, continued indefinitely).

Note

For some elements, you will need to add attributes and values. For instructions on adding these to an element, see Add Attributes.

Required Elements

The following elements are required:

  • biblioentry with role attribute. Set the value of the role attribute to article. This is a wrapper element and all other elements for this bibliography entry should be inside it.

  • biblioset with relation attribute. Set the value of the attribute to article.

  • biblioset with relation attribute. Set the value of the attribute to journal. This is a wrapper element. Add the elements that describe the publication that contains the article inside this biblioset.

    The following elements are required in the journal biblioset:

    • Use this to provide information about the article's page numbers in the journal.

Optional Elements

The following elements are optional:

  • This is the subtitle for the article.

  • Use for the subtitle of the journal that contains the article. This has to be a child of the journal biblioset.

Example Reference to an Article in a Serial

The following code shows the structure of a biblioentry for referencing an article that appears in a journal.

<biblioentry role="article">
<abbrev>R100</abbrev>
    <!-- Contribution information -->
    <biblioset relation="article">
        <author>
            <personname>
                <surname>Allsop</surname>
                <firstname>RB.</firstname>
            </personname>
        </author>
        <title>Data Processing in Orbital Mechanics</title>
        <subtitle>Enhancing Satellite Trajectory Calculations</subtitle>
        <!-- Overall Document Info -->
        <biblioset relation="journal">
            <title>Journal of Space Technology</title>
            <edition>2nd Edition</edition>
            <publisher>
                <publishername>SpaceTech Foundation</publishername>
                <address>
                    <city>London</city>
                </address>
            </publisher>
            <pubdate>2022</pubdate>
            <volumenum>vol. 3</volumenum>
            <issuenum>3</issuenum>
            <pagenums>p. 155-167</pagenums>
            <date role="cit">June 2023</date>
        </biblioset>
    </biblioset>
</biblioentry>

References to Electronic Message Systems

If you need your bibliography to comply with ISO 690 and you want to reference an electronic message system, you will need to add certain elements, as described below.

Note

For some elements, you will need to add attributes and values. For instructions on adding these to an element, see Add Attributes.

  1. Add a biblioentry element to your bibliography. Give the biblioentry element a role attribute. Set the value of the role attribute to messagesystem.

  2. To create the structure for the rest of the bibliography entry, use the elements that are described in References to a Monograph (Book or Similar Publication). Message system references use the same elements as monograph references, except that you set the biblioentry's role to "messagesystem" instead of "monograph".

References to Electronic Messages

If you need your bibliography to comply with ISO 690 and you want to reference an electronic message, you will need to add certain elements and attributes.

Note

For some elements, you will need to add attributes and values. For instructions on adding these to an element, see Add Attributes.

  1. Add a biblioentry element to your bibliography. Give the biblioentry element a role attribute. Set the value of the role attribute to message.

  2. To create the structure for the rest of the bibliography entry, use the elements that are described in References to a Contribution (Book or Similar Publication). Message references use the same elements as contribution references, except that you set the biblioentry's role to "message" instead of "contribution".

References to Patents

If your bibliography needs to comply with ISO 690 and you need to reference a patent, make sure you include the required elements.

Note

For some elements, you will need to add attributes and values. For instructions on adding these to an element, see Add Attributes.

Required Elements

You must include the following elements:

  • biblioentry with a role attribute. Set the attribute value to patent. This is a wrapper element. Add the other elements for this bibliography entry as children of this biblioentry.

  • country

  • address

  • bibliomisc with a role attribute. Set the attribute value to patenttype.

  • biblioid with a class attribute and an otherclass attribute. Set the class attribute value to other. Set the otherclass attribute value to patentnum.

  • The date on which the patent was published.

Optional Elements

The following elements are optional:

  • The title of the invention.

Choose your Bibliography Style

When you have added the appropriate elements and attributes to your bibliography, the next step is to set your Layout to use a Bibliography Style. The Bibliography Style affects how Paligo will process your bibliography content. It will either use the:

  • Default "Normal" style, where elements are not reordered

  • Style for a particular standard, such as ISO 690. During processing, Paligo will reorganize the elements in the output so that they match the order and format required for the standard. The reordering only applies to your published output, Paligo does not reorder the elements in your topics in the editor.

To set the bibliography style:

  1. Select Layout in the top menu.

    Paligo editor. The Layout option in the header menu is highlighted.

    Paligo displays a list of Layouts. The list is empty if there are no custom Layouts in your Paligo instance.

  2. Select the Layout that you are going to use for publishing. The Bibliography Style feature is available on HTML5 and PDF Layouts.

  3. Navigate to the Layout's Bibliography Style setting:

    • On HTML5 Layouts, select General.

    • On PDF Layouts, select General and then Glossary, Index, and Bibliography.

  4. Choose the Bibliography Style:

    • Normal

      To keep the default bibliography style, which does not change the order of your elements.

    • ISO 690

      To produce an output that reorganizes the elements to match the order for ISO 690. For this option, your bibliography entries must contain the required elements and attributes for ISO 690 (see Set Up an ISO 690 Bibliography.

  5. Select Save.

You can now use the Layout to publish your content. Paligo will process the bibliography content to match your chosen bibliography style.