Skip to main content

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>