Referenced Note

Abstract

When an area in text needs to refer to a note that will be placed in a different part of the document, a reference is made to a separate entity using an IDREF.

Problem

Some text needs to make a reference to another piece of text that is located elsewhere with the original text. This could be a footnote, an annotation, or an endnote. The position of the note in the final document will not be known until the document is rendered.

Context

Notes occur when a comment needs to be made about a piece of text, but the author does not want the main text flow to be interrupted. This is a very publication oriented pattern, it is not as relevant in data interchange documents.

Forces

Ease of Use and Ease of Processing is effected by how a note is organized.

Solution

The note is put in a element which is not contained within the flow of the text where the note is referenced from. An attribute of type ID is put on the note element, and an element is inserted into the flow of the text with an IDREF that refers to the note's ID. A different solution would be to simply use an inline element to include the note as such:

        

<Paragraph>This paragraph refers to a note.
<Note>This is the note.</Note>
</Paragraph>

        
      

This solution has a couple of potential disadvantages:

• The note cannot be referred to from more than one place.
• The note is not physically removed from the text in the marked up document. It may more difficult for the author of the document to realize how the note will be used in the published form of the document.

Examples

        

<Paragraph>
This paragraph refers to a note.
<NoteReference ref="1"/>
</Paragraph>
<Note id="1">This is the note.</Note>

        
      

When rendered the document could be made to look like this:

        

This paragraph refers to a note.
1
... rest of page ...

1: This is a note.
...end of page

        
      

Discussion

Using this pattern can lead to easier to use documents. Since authors expect notes to be separated from the flow of text, this pattern can lead to more natural mark up.

Rendering software can be simplified if the notes are declared before they will be used. For example if the note is to go on the bottom of a page, the rendering software can calculate page breaks on the fly if the size of the note is already known when the reference to it is encountered.

Related Patterns

This is an example of a Domain Element from the publishing world.

Also consider using Declare Before First Use with this pattern.

Known Uses

References

This is a generalization of: Footnote Pattern (http://www.utoronto.ca/ian/books/xmlbook/Footnote.html) on the The XML Specification Guide web site.