Structure Guidelines for DAISY/NISO
Last Revised: September 10, 2005
This chapter describes various block elements or structures encountered in books and provides guidance on their markup. Block structures are discrete segments of text that are often separated from surrounding text by blank lines, indentation, etc. The most common block structure is the paragraph. Other examples are lists of various types, quotations set off from adjoining text, sidebars, and footnotes. See the expanded table of contents for a complete list of the block structures covered here.
Block structures are contained within major structures. For example, paragraphs fall inside parts, chapters, sections, and subsections. In turn, the inline elements to be covered in the next chapter are contained inside block structures.
IMPORTANT: Notes of various types, sidebars, line numbers, page numbers, and optional producer's notes may be "skippable," that is, turned on and off by the end user. That is, the end user will be able to, for example, set the playback device to play all sidebars or to skip them all. If this feature is to work these items must be tagged.
Definition: The location at which a person or agency may be contacted. The address element may be used by authors to supply contact information for a document or a major part of a document such as a form. This element often appears at the beginning or end of a document.
Markup: The <address> tag is used for addresses, with the <line> tag being used to mark each line of the address.
Syntax:
<address>
<line>...</line>
</address>
Example 1:
<address>
<line>Joe Smith</line>
<line>500 Eddy Ave. #1</line>
<line>Missoula, MT 59801</line>
<line>USA</line>
</address>
Definition: Identifies the writer of a work other than the present one. Contrast with <docauthor>, which identifies the author of this work.
Markup: Use the <author> tag to indicate the writer of each poem, story, play, chapter, etc. in works where each segment was separately authored. Use it also to indicate the source of a quotation where only the author is given. If a complete citation for a quotation is given, use <cite> rather than <author>. Within a list of authors, use line breaks (<br />) for formatting where needed. The <docauthor> tag however, is used to indicate the author of the entire book.
Syntax:
<author>..</author>
Example 1 - Author of Chapter:
<level1 class="chapter">
<h1>Chapter 2: Reading Aids and Devices</h1>
<author>Leslie L. Clark</author>
...
</level1>
Example 2 - Author of a Quotation:
<blockquote>
<p>It is a certainty that the free market will always generate greater
wealth for the main players than will a planned economy. The question is,
at what cost?</p>
<author>Virginia Hamilton Anderson</author>
</blockquote>
New in DAISY/NISO, Release 2005.
Definition: Bridgehead can be used when a print book contains headings that are clearly not a part of the document hierarchy and, similarly, in the DTB would not be a part of the global navigation. Some documents, textbooks for example, use headings that are not tied to the normal sectional hieararchy.
Markup: The <bridgehead> tag is used to mark up a "free-floating" heading that is not associated with the hierarchical structure of a document. It must be contained within one of the level elements. While <hd> and <h1> ... <h6> are restricted to one occurrence per level or <level1> ... <level6>, respectively, <bridgehead> has no such restriction. It should however be used only when it is clear that none of the structural headings is appropriate.
Syntax:
<bridgehead>..</bridgehead>
Example:
<level2 class="chapter">
<h2>Chapter 3: The Mission</h2>
<bridgehead>Arriving by sea</bridgehead>
...
<bridgehead>Arriving by land</bridgehead>
</level2>
New in DAISY/NISO, Release 2005.
Definition: A byline contains information about the creator of or contributor to a work.
Markup: The <byline> element can appear in a block context, and in elements such as <poem> and <linegroup>. It may contain any inline elements.
Syntax:
<byline>...</byline>
Example:
<div class="article">
<byline>Lois Lane, staff contributor</byline>
</div>
Definition: Computer code in a computer programming language.
Markup: Computer code, which may be displayed in a print book in a monospaced font such as Courier bold, is marked with the <code> tag. This tag can be used in either block or inline settings.
Syntax:
<code>...</code>
Example:
<p>This is an example of drawing and rotating a square using the "o" key.</p> <code> case "o": glBegin(GL_QUAD_STRIP) for(i=0;i<=12; i++) { angle = 3.14159 / 6.0 * i; glVertex2f(0.4 * cos(angle), 0.4 * sin(angle)); glVertex2f(0.5 * cos(angle), 0.5 * sin(angle)); } glEnd(); break; </code>
See also Information Object: Keyboard Input and Information Object: Sample
Playback devices can be configured so that text tagged as <code> will preserve all white space (line breaks, indentation, etc.).
New in DAISY/NISO, Release 2005.
Definition: A dateline contains information about the time and/or place at which a work was authored.
Markup: A dateline can appear in a block context, and in elements such as <poem> and <linegroup>. It may contain any inline elements.
Syntax:
<dateline>...</dateline>
Example:
<div class="article"> <dateline>August 25, 2005</dateline> <p>...</p> </div>
New in DAISY/NISO, Release 2005.
Definition: An epigraph marks a quotation placed at the beginning of a publication.
Markup: The <epigraph> element may contain any inline or block level element, except for images and image groups.
Syntax:
<epigraph> <p>...</p> <linegroup>...</linegroup> <div>...</div> <line>...</line> ... </epigraph>
Example:
<epigraph> <linegroup> <line>In Memory of</line> <line>my loving Mother</line> </linegroup> </epigraph>
Definition: Information that the reader of the book is to input directly into a computer using the keyboard.
Markup: Content that is to be entered into a computer via a keyboard is to be marked with the <kbd> tag. This tag can be used in either block or inline settings.
Syntax:
<kbd>...</kbd>
Example:
<p>To add a filename parameter to the DIR command, you can type the following text.</p> <kbd>DIR C: MYFILE.TXT</kbd> <p>In symbolic notation, MYFILE.TXT would be shown as filename.ext.</p>
See also Information Object: Computer Code and Information Object: Sample
Playback devices can be configured so that text tagged as <kbd> will preserve all white space (line breaks, indentation, etc.).
New in DAISY/NISO, Release 2005.
Definition: A linegroup wraps a set of lines.
Markup: The <linegroup> tags are useful if it is important to maintain the line formatting in the DTB, for example, a stanza in a poem. The <line> tags wrap each individual line within the <linegroup>.
Syntax:
<linegroup> <hd>...</hd> <dateline>...</dateline> <byline>...</byline> <epigraph>...</epigraph> <linegroup>...</linegroup> <line>...</line> <pagenum>...</pagenum> <prodnote>...</prodnote> <noteref>...</noteref> <annoref>...</annoref> <note>...</note> <annotation>...</annotation> <p>...</p> <blockquote>...</blockquote> <img>...</img> <imggroup>...</imggroup> </linegroup>
Example:
<linegroup> <line>With Annie gone,</line> <line>With eyes to compare</line> <line>With the morning sun?</line> </linegroup> <cite>From <title>For Anne</title></cite> <byline>Leonard Cohen: poet, novelist, songwriter, singer</byline>
See also Information Object: Poem.
Definition: A list is a sequence of two or more items. For markup purposes, there are three types of lists:
1. Ordered/unordered/preformatted lists: In ordered lists (type="ol"), list items are numbered or lettered. Such lists are most often used for procedures (e.g., a recipe) or sequential lists (e.g., an agenda). In unordered lists (type="ul"), list items are unnumbered and usually marked with a bullet or other typographical device. In preformatted lists (type="pl"), no ennumeration nor bullets are added by the display agent. Bullets or visuals of the producer's choice may be added to the list items.
2. Definition lists: List items generally consist of term/definition pairs (a term followed by its definition).
Markup: Ordered and unordered lists are created using <list> tags. When a list contains a heading, the heading should be included in the list and marked with the <hd> tag. Individual list items in unordered or ordered lists are indicated with the <li> tag. If list items consist of two or more discrete segments that should be distinguished, those segments should be marked with the <lic> ("list item component") tag. A common example of the use of <lic> is in a table of contents to separately mark each entry and its corresponding page number. The <lic> tag should only be used when there are two or more segments in each list item. However, when there are more than two segments to each list item, consider using the <table> tag instead. See Tables: Information Object: Tables If the information presented contains nesting (see below), this is generally an indication that it should be marked as a list rather than a table.
Definition lists are created using <dl> tags. In addition, definition lists require the <dt> tag to indicate the term being defined, and the <dd> tag to mark the definition.
Nested lists: a list item can also contain within it another list, which may in turn hold another list inside it, and so forth. Such a series of lists is said to be "nested."
Syntax:
<list type="..">
<hd>...</hd>
<prodnote>...</prodnote>
<li>
<lic>...</lic>
<lic>...</lic>
</li>
<pagenum>...</pagenum>
<li>
<lic>...</lic>
<lic>...</lic>
</li>
</list>
<dl>
<dt>...</dt>
<dd>...</dd>
</dl>
New in DAISY/NISO, Release 2005:
Example 1: Unordered list
<list type="ul" class="ingredients"> <li>mango</li> <li>lychee</li> <li>carambola</li> <li>rambutan</li> <li>sugar</li> <li>lime juice</li> </list>
Example 2: Ordered list
<list type="ol" enum="1" class="steps"> <li>peel fruit.</li> <li>cut fruit in bite sized pieces.</li> <li>sprinkle fruit with sugar and lime juice to taste.</li> <li>stir salad.</li> <li>chill for one hour.</li> </list>
Example 3: Nested preformatted lists, showing use of <hd> tag
<list type="pl"> <hd>Tropical Fruit</hd> <li>well-known tropical fruit <list type="pl"> <li>* pineapple </li> <li>* papaya</li> </list></li> <li>exotic tropical fruit <list type="pl"> <li>* rambutan </li> <li>* mangosteen</li> </list></li> </list>
Example 4: Definition List
<dl> <dt>mango</dt> <dd>tropical fruit with sweet golden flesh</dd> <dt>lychee</dt> <dd>tropical fruit with deep red leathery skin and clear white flesh</dd> <dt>carambola</dt> <dd>star shaped tropical fruit with tart lemon-pineapple flavour</dd> <dt>rambutan</dt> <dd>egg-shaped tropical fruit similar to lychees with leathery skin covered in soft red hairs</dd> </dl>
See Major Structural Elements: Information Object: Table of Contents for an example of nested list markup using the <lic> tag.
Definition: Notes annotating the text and corresponding to reference numbers in the text are called footnotes when they are printed at the foot of the page, and notes or endnotes when they are at the back of a book, at the end of a chapter or at the end of an article in a journal. They may be numbered consecutively beginning with 1, throughout each chapter or article.
NOTE: Annotations are similar to footnotes, but normally appear in the margin.
Markup: A note, endnote, annotation or rear-note consists of two parts: the reference number or symbol in the text called the note or annotation reference (<noteref> or <annoref>, respectively) and the note or annotation itself (<note> or <annotation>) which contains the content.
To accurately reflect the print, the <noteref> tag should be placed at the exact point in the text where the reference number or symbol occurs. Wrap the note reference number or symbol with the <noteref> tags as shown below. The attribute "idref" must link the reference to the "id" of the note itself. The text of the note should be left where it occurs in the original text file, whether at the bottom of the page for footnotes or the end of the chapter or book for endnotes.
Syntax:
<noteref class="footnote" idref="fn1">1</noteref> <note class="footnote" id="fn1">...</note> <noteref class="endnote" idref="en4">4</noteref> <note class="endnote" id="en4">...</note>
Example 1:
<p>Morley's favorite vacation spot was the Bay of Islands<noteref idref="fn12" class="footnote">12</noteref> on New Zealand's North Island.</p> <note id="fn12" class="footnote"> <p>12. Morley once described the area as "paradise in twenty shades of blue".</p> </note>
Notice that <p> tags (or others such as for citations, lists, or tables) must be used within the <note> tags to mark the content of the note. Untagged text cannot be contained within <note> tags.
Example 2:
A. The footnote reference appears as follows in the print book:
Of the salvation she engendered she will be recipient, in heaven, where we "repent not, but smile; not at the sin, which cometh not again to mind, but at the Worth that ordered and provided."1
The footnote reference appears as follows when marked up:
<p>Of the salvation she engendered she will be recipient, in heaven, where we "repent not, but smile; not at the sin, which cometh not again to mind, but at the Worth that ordered and provided." <noteref idref ="p21-fn1" class="footnote">1</noteref> </p>
B. The footnote itself appears in the print book as follows:
1. Dante. Paradiso, translated by Philip H. Wickstead (New York: Modern Library/Random House, 1932), Canto 9:103-105, p.458.
Marked up, the footnote appears as follows:
<note id="p21-fn1" class="footnote"> <cite>1. <author>Dante</author>. <title>Paradiso</title>, translated by Philip H. Wickstead (New York: Modern Library/Random House 1932), Canto 9:103-105, p.458.</cite> </note>
Example 3:
Text containing an annotation reference appears as follows in the print book:
The speed of a sailing vessel was measured in knots.
The annotation reference would be marked up as follows:
<p>The speed of a sailing vessel was measured in <annoref idref="anno_4">knots</annoref> </p>
The annotation itself would usually be printed in the margin of the print book. It would appear as follows when marked up:
<annotation id="anno_4"> <p>The term "knot" is derived from the practice of counting the number of knots on a line unreeled in a set period of time from a device known as a chip log. </p> </annotation>
Definition: The paragraph is the fundamental organizational unit for all prose texts. It is the most basic regular unit into which prose can be divided. Paragraphs have no firm internal structure but contain prose encoded as a mix of characters, entity references, phrases and embedded elements such as lists, figures or tables.
Markup: The paragraph is marked by the <p> tag, which surrounds the content of the paragraph.
Syntax:
<p>...</p>
Example:
<p>Of the kindness of Dr. Stephenson, he always spoke with the greatest warmth of gratitude and affection.</p> <p>After he had followed his studies at Edinburgh for four years, on the breaking out of the Rebellion in 1745, he returned to Dumfries, where he resided with Mr. McMurdo, his brother-in-law, in whose house he was treated with kindness and affection; and had an opportunity, from the society which it afforded, of considerably increasing the store of his ideas. In 1746, he published a small collection of his poems, at Glasgow.</p> <p>After the close of the Rebellion, and the complete restoration of the peace of the country, he returned to Edinburgh, and pursued his studies there for six years longer.</p>
Definition: Information added to the DAISY DTB by the producing organization; commonly used to provide descriptions of visual elements such as charts, graphs, etc., supply operating instructions, or describe differences between the print book and the audio version. Traditionally, this has been called a transcriber's note, reader's note, or editor's note.
Markup: Producer's notes are marked with the <prodnote> tag and must be identified as "required" or "optional" using the "render" attribute. Optional producer's notes may be turned on or off by the end user; that is, the playback device or browser includes settings that either automatically play all producer's notes as they are encountered or play only those marked as "required." The producer must decide for each <prodnote> whether it contains critical information and is thus marked as "required" or merely contains helpful information that an end user could skip without harm.
A <prodnote> may contain bare text, inline or block level elements such as <p>.
The "showin" attribute can be used to control in which of three media types a given <prodnote> will be displayed. The allowable values for showin are xxx, xxp, xlx, xlp, bxx, bxp, blx, and blp, where x = inappropriate, b = braille, l = large print, and p = print. Thus the value "xlp" would prompt a player to display the prodnote in large print or print versions, but not in braille.
See Inline Elements: Information Object: Producer's Note for an example of <prodnote> used as an inline element.
Syntax:
<prodnote render="...">
...
</prodnote>
New in DAISY/NISO, Release 2005: The "render" attribute is required, and must have a value of either "optional" or "required."
Example 1:
<prodnote render="required"> The question below refers to a picture showing three glasses. The first glass is 1/4 full, the second glass is 1/2 full and the third is 3/4 full. </prodnote>
Example 2:
<prodnote render="optional"> The map on this page shows all the cities in Europe with a population of more than 100,000. </prodnote>
Definition: A written passage drawn verbatim from another work, usually with the author credited. Longer quotations that are often set off from the surrounding text by paragraph breaks are called block quotations. Shorter quotations that are incorporated within a sentence or paragraph are called inline quotations (there is no block progression or direction regarding spacing). See Inline Elements: Information Object: Quotation.
Markup: Long quotations are marked with the <blockquote> tag. Quotations may be nested one inside the other.
Syntax:
<blockquote>
<p>...</p>
<pagenum>...</pagenum>
</blockquote>
Example:
<p>So you can imagine how Samson was brought up. Shrieks and wails if a razor went near his head, and the whole community involved. Only, as soon as he was grown into the biggest, strongest man around, he started causing trouble by bedding and wedding Philistine girls, not his own kind, to the distress of Manoah and "the woman" who now at least becomes "his mother" though she still never gets to have his name.</p> <blockquote> <p>And she made him sleep upon her knees, and she called for a man, and she caused him to shave off the seven locks of his head: and she began to afflict him and the strength went from him.</p> </blockquote>
The <author> tag can be used within <blockquote> to identify the author of the quotation.
Definition: A sample of work created by the author used as an example or template within the text.
Markup: Items that the author has placed in the text as sample work or examples to follow should be marked with the <samp> tag. This tag can be used in either block or inline settings.
Syntax:
<samp>...</samp>
Example 1:
<p>When writing a business letter, it is a good idea to use block letter style as shown below.</p> <samp> 1234 University Ave.<br /> Missoula, MT 59801<br /> <br /> <br /> <br /> Bill Gates<br /> 1234 Somewhere Ln.<br /> Seattle, WA 98034<br /> <br /> Dear Mr. Gates,<br /> <br /> ......<br /> </samp>
Example 2:
<p>You may use a form like the one below to request a credit report from your bank.</p> <samp> First Name:________________________ Middle Initial:_______ <br/> Last Name:___________________________<br /> Address:_______________________________________________________<br /> City:______________________ State:_______ Zip:________________<br /> Social Security Number:____________________________ <br/> Bank Name:____________________________________<br /> ... </samp>
See also Information Object: Computer Code and Information Object: Keyboard Input
Playback devices can be configured so that text tagged as <samp> will preserve all white space (line breaks, indentation, etc.).
New in DAISY/NISO, Release 2005: The <notice> element has been removed from the DTD and the content model.
Definition: A sidebar contains information supplementary to the main text and/or narrative flow that is positioned as if boxed and floating separate from the main text block. Sidebars may include a heading, followed by paragraphs, lists and other block-oriented elements. For sidebars of this type, use the attribute render="optional".
The <sidebar> tag may also be used to mark warnings, cautions, etc., that must not be skipped by the end user. When it is essential that a sidebar be read by an user, add the attribute render="required".
Syntax:
<sidebar render="...">
<hd>...</hd>
<p>...</p>
</sidebar>
New in DAISY/NISO, Release 2005:
The "render" attribute is required, and must have a value of either "optional" or "required."
Example 1:
<sidebar render="required">Danger: Never crawl under a car that is supported solely by a jack.</sidebar> <p>To loosen the muffler, first jack up the car and put blocks under the frame...</p>
Example 2:
<h2> Chocolate Stars</h2> <list type="ul" class="ingredients"> <li>4 ounces cold unsalted butter</li> <li>1/2 cup sugar</li> <li>1/2 teaspoon vanilla extract</li> </list> ... <sidebar render="optional"> <hd>Cocoa Powder News</hd> <p>Amy uses a "full Dutch" process cocoa called "Jersey cocoa" that has 22 to 24 per cent fat and is available through the San Francisco based cookware chain Williams-Sonoma.</p> </sidebar>
Copyright © 2005 DAISY Consortium