return to main XML Books page

The following specifications include detailed instructions on preparing files for ACLS Humanities E-Book. Publishers should provide these specifications to their conversion or composition vendors. ACLS can also provide a list of experienced vendors.

All books must be tagged in XML using the acls-hebook.dtd. A list of all elements and attributes are defined below.

The DTD and specifications are periodically updated, so always check for the latest versions before beginning a new book.

DTD:     acls-hebook.dtd     ver. 1.3; date: 04-25-2007   (view | download | download zipped)
Character Entities:     xhtml-lat1.ent    (view | download | download zipped)
Specifications (this web page):  http://www.humanitiesebook.org/xml/doc/acls-hebook-doc.html

For examples on tagging and usage, refer to the XML template,
acls-hebook-template.xml.

An HEB-specific XSLT style sheet may be used to transform an XML file into HTML to check formatting, links, etc. (The resulting single-page HTML document differs slightly from the version that will ultimately appear online, but will be identical in all relevant aspects.) We strongly recommend using this tool for e-book testing prior to submitting the completed XML file. The file (acls-hebook.xsl) is available for download below. (Note that, in the unzipped folder, the HTML output file should be placed in the main directory at the same level as the XSLT; jpegs for figures must be placed in the figures-directory in order to appear in the HTML.)

Please contact the HEB staff with any questions.

Save files in US-ASCII encoding. Add the encoding type to the XML declaration:

<?xml version="1.0" encoding="us-ascii"?>

In order to ensure that our e-books are properly displayed across a range of standard web browsers, our system can currently only index and display the following characters:

Characters allowed	Rendered as	Notes
US-ASCII characters (#0–#127)		Only characters in the US-ASCII range are allowed.
ISO 8859-1 Latin-1 entities (#160–#255)		Characters above US-ASCII must be encoded with entities (e.g., é for é) from xhtml-lat1.ent (see 1. Files and Resources above).
—	—
&	&
…	. . .	Make sure spacing and punctuation around … is correct, following book or publisher's in-house style. &hellips; will display as: [ . . . ] i.e. [space.space.space.space]
&lt; &gt;	< >
&ldquo; &rdquo;	"	Curly double quotes will be converted to straight double quotes.
&lsquo; &rsquo; &apos;	'	Curly single quotes and apostrophes will be converted to straight single quotes.
&ndash;	-	Ndash will be converted to hyphen.
&nbsp;		Use non-breaking space only when it is critical to retain original formatting (e.g., for historical documents). Do not use for general styling.

If your book includes special or foreign characters outside this range, please add additional entities at the top of your XML file.

Example of added entity at top of an XML file:

<!ENTITY oelig "&#x0153;"> <!-- LATIN SMALL LIGATURE OE -->

To tag italic, bold, struck out, underlined, superscript, or subscripted type, use the <hi1> tag with the appropriate rend attribute value (see list below). Please note that note reference numbers should NOT be tagged using superscipt (see 3.3.3. Links: Notes, Internal Links, URLs for tagging instructions).

<hi1 rend="italic">text</hi1>
<hi1 rend="italicsunderlined">text</hi1>
<hi1 rend="bold">text</hi1>
<hi1 rend="bolditalic">text</hi1>
<hi1 rend="boldund">text</hi1>
<hi1 rend="strike">text</hi1>
<hi1 rend="und">text</hi1>
<hi1 rend="sup">text</hi1>
<hi1 rend="supbold">text</hi1>
<hi1 rend="supund">text</hi1>
<hi1 rend="sub">text</hi1>

Small caps cannot be easily rendered in HTML browsers, so you must set small cap text in all caps, or convert text to title case. Publisher should advise conversion vendor on how to handle small caps. (It is usually preferable to convert to title case for <div> heads that will appear in the TOC.)

When converting titles from the print version, hyphens inserted to break a word at the end of a line as well as forced end of line breaks must be removed. For example, if "demo-" is on one line and "cracy" on the next, the hyphen should be removed so the word reads "democracy" with no hyphen.

[ back to top]

When tagging titles, please avoid elaborate formatting involving indents, tabs, and extra spaces, if possible. Please also avoid forced line breaks within tags. (This will facilitate further processing of files at HEB.)

Break down the text using <front>, <body>, and <back> tags. Add mandatory HEB number heb900xx (last two digits are specific to title) and ISBN (E-Book) attributes to <text> tag. (Get this info from publisher/production editor.)

<text id="heb90001" isbn="1-234-5678-9">
  <front>Title Page, Copyright, Dedication, etc.</front>
  <body>Introduction, Chapter 1, Chapter 2, etc., Conclusion</body>
  <back>Appendices, Notes, Bibliography, Index, etc.</back>
</text>

Use division tags (<div1>, <div2>, <div3>, <div4>) to subdivide text within <front>, <body>, and <back>. For example, text with chapters and sections can be broken down as follows:

<div1 type="chapter" id="div1_c01">
  <div2 type="section" id="div2_c01.1">
OR
<div1 type="part" id="div1_pt1">
  <div2 type="chapter" id="div2_c01">
    <div3 type="section" id="div3_c01.1">

Every division must have a type and id attribute, and include a <head> tag (see below).

Note that division tags can be used for any type of text subdivision, not necessarily just the traditional chapter and section. For many "born-digital" works or new projects that are developed simultaneously with print editions, the publisher may choose to break down text in other ways (e.g., smaller units).

E-books in our system will be delivered in text chunks by the lowest available division level. For example:

1. If a book is broken down by chapter in <div1> and section in <div2>, text delivery should be by section (i.e., the lowest-level division), by adding the attribute status="hidden" to the <div1> tag.

<div1 type="chapter" id="div1_c01" status="hidden">
  <div2 type="section" id="div2_c01.1">
  <div2 type="section" id="div2_c01.2">

2. For books without clear section breaks, you can break the chapter into smaller chunks (e.g., by tagging every 10 paragraphs in a separate division).

<div1 type="chapter" id="div1_c01" status="hidden">
  <div2 type="section" id="div2_c01.1">Text for paragraphs 1-10.</div2>
  <div2 type="section" id="div2_c01.2">Text for paragraphs 11-20.</div2>
</div1>

If you want to add a separation between a series of paragraphs with a simple skipped line space or asterisks, you can put a milestone tag between paragraphs.

<p>[text text text]</p>
<milestone rend="skipline"/> (for a blank line)
or
<milestone rend="asterisk"/> (for asterisks)
<p>[text text text]</p>

Every division must include a <head> tag. Subparts of heads should be broken down by type in <bibl> tags. Paragraph number ranges for text chunks must also be placed inside a <bibl> tag.

It is only necessary to add paragraph-number ranges for the division level at which text chunks will be delivered, not for higher-level divisions that include the status="hidden" attribute (i.e., if text in e-book will be delivered by section, only add paragraph-number ranges to section heads, not part or chapter heads).

For sections that include a byline containing specific author information (e.g., Introduction by ...), this info should also be added to the head in a separate <bibl> tag.

See example:

<div1 type="chapter" id="div1_c01" status="hidden">
<head>
  <bibl type="number">Chapter 1</bibl>
  <bibl type="title">Chapter Title</bibl>
  <bibl type="subtitle">Chapter Subtitle</bibl>
</head>
<div2 type="section" id="div2_c01.1">
<head>
  <bibl type="title">Section Title</bibl>
  <bibl type="byline">by Author, translated by Translator</bibl>
  <bibl type="para">22-39</bibl>
</head>

(Note: No period or other punctuation should be added after the final number appearing in <bibl type="number"> before the </bibl> closing tag; a colon is added here automatically by our processing script, and adding anything else will result in redundant punctuation. For example, tag as <bibl type="number">1.1</bibl>, not <bibl type="number">1.1.</bibl>.)

Heads, bylines, and paragraph-number ranges (e.g., [para 1-10]) will appear in a hyperlinked Table of Contents. For new e-books in development, the publisher must make sure that all divisions have heads. In print version books, some sections do not have heads (e.g., first section at the beginning of a chapter, dedication page, etc.). Publishers should inform their vendors of the text to be inserted, for example, [Dedication], [Intro], or [No head in print version].

[ back to top]

If your book is one in a series of titles, and the print version contains a list of already published titles in the series, please do NOT include this list in the front matter. (Instead, if desired, add information on the series to the Copyright and Permissions section—see below.)

Begin tagging the <front> section with <titlepage> information. (The information contained within the <titlepage></titlepage> tags is metadata and will not appear as a separate section within the book.) Do not tag the blank and half-title pages.

<front>
  <titlepage>
  <doctitle>
    <titlepart type="main">Title of work</titlepart>
    <titlepart type="subtitle">Subtitle of work</titlepart>
  </doctitle>
  <docauthor>Author's Name</docauthor>
  <docimprint>
    <publisher>Press/Publisher</publisher>
    <pubplace>Publisher's location</pubplace>
  </docimprint>
  </titlepage>

  <div1 type="titlepage" id="div1_tpg">
  <head><bibl type="title">Title Page</bibl></head>
  <p><hi1 rend="bold">Title of work: Subtitle of work</hi1></p>
  <milestone rend="skipline"/>
  <p>Author's Name</p>
  <milestone rend="skipline"/>
  <p>Press/Publisher</p>
  <p>Publisher's location</p>
  </div1>

Continue tagging all other front matter material in <div1> sections. Create a section with copyright and permissions information.

Include:

1. Head—Since each division needs a head, you must the add the head "Copyright and Permissions" to this section.
2. Copyright and Permissions—Include all copyright and permissions information:
   • Publisher
     
   • Location of publisher
     
   • Date and copyright holder
     
   • Other text from print copyright page not pertaining exclusively to print version
3. Information on electronic version:
   
   • Edition info/date: "ACLS Humanities E-Book electronic edition [date]"
   • E-Book ISBN number
     
   • HEB Number
     
   • Information about variations between print and electronic versions—"This electronic book contains the following additional features not available in the print version: [additions/modifications to the electronic version]" (e.g., links or images added)
4. Information on print version:
   • Print ISBN—For books with print counterparts, include ISBN(s) for these editions ("This book is also available in print. ISBN: 1-234-5666-7 (cloth)")
   • Any relevant information pertaining to the print version (e.g., title series information)

Do NOT include:

1. CIP—It is not necessary to include the Cataloging-in-Publication information because each of our electronic books is cataloged in full by a professional librarian.
   
2. Irrelevant print-only information—Do not include any irrelevant information that pertains specifically to the print version, such as paper type, reprint number, etc.

Sample Copyright and Permissions below:

<div1 type="copyright" id="div1_cpy">
<head><bibl type="title">Copyright and Permissions</bibl></head>
  <p>Publisher</p>
  <p>Location</p>
  <p>&copy; 2003 by Author</p>
  <p>Published by University Press, Inc.</p>
  <p>All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form without the prior permission of University Press.</p>
  <milestone rend="skipline"/>
  <p>ACLS Humanities E-Book electronic edition 2003</p>
  <p>ISBN: 1-234-5678-9 (E-Book)</p>
  <p>HEB Number: HEB90001</p>
  <p>This electronic book contains the following additional features not available in the print version:</p>
  <p>Interactive links to informational resources on the Web; 50 additional images.</p>
  <milestone rend="skipline"/>
  <p>This book is also available in print. ISBN: 1-234-5666-7 (cloth), 1-234-5666-8 (paper)</p>
  <p>The print edition was published as part of the <hi1 rend="italic">[Series Title]</hi1> series.</p>
</div1>

The Table of Contents does not need to be tagged because a TOC will be generated and linked dynamically from the heads within each division.

A List of Illustrations is NOT generated dynamically, so you must tag this in a <div1> section. Publishers can choose which text portions to include here (we recommend using the <bibl type="figcap"> portion of each <figure> only, omitting text tagged as <bibl type="figsrc">, and urge consideration of abbreviated descriptions for long figure captions). To create a basic List of Illustrations with links to each individual figure, tag as follows:

<div1>
  <head><bibl type="title">List of Illustrations</bibl></head>
<list>
  <item>Figure 1.1. Caption for figure. [Figure <ptr type="txt" target="fg_heb90001.0001" n="1.1" />]</item>
  <item>Figure 1.2. Caption for figure. [Figure <ptr type="txt" target="fg_heb90001.0002" n="1.2" />]</item>
</list>
</div1>

This section should follow Copyright and Permissions by default, unless there is a pre-existing List of Illustrations which appears in a different order in the print version of the book, and the publisher wishes to retain this order. If the figures are not interspersed in the book text, but rather displayed as a separate section (plates), you do not need to create a separate List of Illustrations. You can simply create a <div1> with the head "Illustrations" that contains all the figures. (See 3.3.5. Figures for specific tagging information.)

Publishers may choose to provide a List of Audio or Film Clips for titles including such media. Formatting should match the List of Illustrations, but link to a clip's container element (e.g., <p>) rather than the clip's (generally id-less) <ref>. (For more on tagging audio and video, see 3.3.6. Audio and Video Files.) Example:

<div1>
  <head><bibl type="title">List of Music Clips</bibl></head>
<list>
  <item>1. Caption for first clip. [Music Clip <ptr type="txt" target="p_102" n="1" />]</item>
  <item>2. Caption for second clip. [Music Clip <ptr type="txt" target="p_155" n="2" />]</item>
</list>
</div1>

Tag other front-matter text in separate <div1> sections within the <front> section. For example:

<div1 type="dedication" id="div1_ded">

<div1 type="acknowledgments" id="div1_ack">

<div1 type="epigraph" id="div1_epi">

<div1 type="frontispiece" id="div1_fnt">

Including a brief Preface to the Electronic Edition, containing such information as a description of elements specific to the e-book, links to external resources associated with the e-book, etc., may be helpful to readers. (Samples provided by HEB upon request.)

[ back to top]

Use <p> to tag paragraphs. Paragraphs in the text should generally be assigned unique number and id values. In the e-book, the paragraph number (n value) will appear in the left margin next to the paragraph and will be used for identification and citation. Number each paragraph sequentially, beginning with the first paragraph of Acknowledgments (or the first significant front-matter text chunk) and continue numbering throughout the main text. You can also continue numbering through the back matter if it contains paragraphs in sections such as Appendices or About the Author.

Unnumbered <p> tags should be used in the following contexts:
1. Paragraphs appearing within notes (<note1> tags).
2. Paragraphs within extracts, such as epigraphs or quotations.
3. Paragraphs that are used just for styling, such as the <p> tags used on the title and copyright pages, those used for certain short lines of text (e.g., text lines that function as heads or footers, such as "<p>Source: ...</p>"), and those used to set apart <pb> tags (see below). Please check with the HEB staff at ACLS if any questions arise regarding paragraph-numbering.

<p n="40" id="p_40"></p>
<p n="41" id="p_41"></p>
<p n="42" id="p_42">
  <q1>
  <p>[text text text]</p>
  </q1>
</p>

Numbered paragraphs will be rendered with justified margins and a text block width of 530 pixels.

For titles that are also published in print, tag print-version page breaks with <pb> tags. Tagging page breaks gives readers a way to find citations based on the print-version pages. It is normally preferable to leave out <pb> tags for blank print pages, unless that page happens to be referenced elsewhere in the book.

Note that page breaks must be placed within the main text, not in or above head tags. Generally, a <pb> tag should placed as if to open a new text-portion rather than close the preceding one (e.g., place tag at the beginning of first <p> of new page rather than at end of last <p> of previous page). In some cases, proper line flow may be disrupted by the insertion of page numbers, and placement of <pb> tags occurring within/preceding certain elements—such as epigraphs or tables—might have to be adjusted, e.g., on/in a separate verse line, table row, or unnumbered paragraph (<p><pb n="10" id="pb_10"></p>). Please confer with the HEB staff at ACLS if any questions arise about <pb> placement.

<div1 type="chapter" id="div1_c01" status="hidden">
  <head><bibl type="title">Chapter Title</bibl></head>
  <div2 type="section" id="div2_c01.1">
  <head><bibl type="title">Section Title</bibl></head>
  <p n="25" id="p_25"><pb n="16" id="pb_16"/>Paragraph text.</p>
  </div2>

Begining of sentence[space]<pb n="121" id="pb_121">rest of sentence.

Our system currently features the following types of links.

<ptr n="1" target="nt_c01.n1"/>
<ptr n="10" target="nt_c01.n10"/>

Note: Do not style note reference numbers as superscript. See 3.4.1. Notes for more information about tagging the text of a note.

You can link to the following elements: <p>, <pb>, <div1>, <div2>, <div3>, <div4>, <figure>, <table>, <list>, <bibl> (bibliography items). Please note that it is not possible to link to divisions including the status="hidden" attribute. (Instead, link to a <div> at the next level down.)

To link to a figure, tag as follows:
  See Figure <ptr type="txt" target="fg_heb90001.0304" n="3.4"/>
which will be rendered as:
  See Figure 3.4

To link to a table, tag as follows:
  This information can be found in Table <ptr type="txt" target="tb_5" n="5"/>.
which will be rendered as:
  This information can be found in Table 5.

To link to a div, tag as follows:
  See Chapter One for a detailed description of <ref type="ptr" target="div2_c01.3">insomnia</ref>.
which will be rendered as:
  See Chapter One for a detailed description of insomnia.

<ref type="url" url="http://www.url.com">http://www.url.com</ref>

Multiple links for the same term can be handled as follows:

Several sites feature an in-depth discussion of insomnia (<ref type="url" url="http://www.url1.com">link 1</ref> | <ref type="url" url="http://www.url2.com">link 2</ref>).

Several sites feature an in-depth discussion of insomnia (link 1 | link 2).

Use <q1> tags to tag extracts formatted as block quotations within a paragraph. Paragraphs within <q1> tags should NOT be numbered.

<p n="20" id="p_20">Paragraph text.
  <q1>
  <p>Text of extract.</p>
  </q1>
Continuation of paragraph text.
</p>

<q1>
<lg>
<l>First line.</l>
<l>Second line.</l>
<l>Third line.</l>
</lg>
</q1>

To tag epigraphs, place <epigraph> around the <q1> tag and add <bibl type="epi"> to tag epigraph author and source. Epigraphs should follow opening tags of whichever divisional level text has been chunked by; e.g., if text is delivered by section, an epigraph opening a chapter should appear within the first <div2> (section-level) tags rather than <div1> (chapter-level) tags.

<div1 type="chapter" id="div1_c01" status="hidden">
<head><bibl type="number">Chapter 1</bibl></head>
<div2 type="section" id="div2_c01.1">
<head><bibl type="para">1-10</bibl></head>
<epigraph>
  <q1>
  <p>Text of epigraph.</p>
  </q1>
  <bibl type="epi">&mdash;Quotation author, <hi1 rend="italic">Title of quotation source</hi1></bibl>
</epigraph>

Image files should be named in accordance with the title's HEB number, followed by the figure number. (Note that the letters "heb" must appear in lower case in figure entity names in order to be processed by our system. Other letters appearing in entities—e.g., heb90001.001a—will NOT be processed by our system and should be avoided.) Keep in mind that figure entity names don't necessarily correspond with figure numbers as they appear in the text (e.g., Figure 2.1, the first figure appearing in Chapter 2 and 12th figure total, might be heb90001.0012 or heb90001.0201).

Please submit all of the following image files:

1. High-Resolution Tiff files
High-resolution tiff files must be submitted for all images. Publishers can submit the high resolution files used for print production. If high-resolution tiff files are not readily available or difficult to create, please discuss the situation with a technical contact at ACLS. These files will be used to create files for the image-viewer tool, and archived in case jpeg files need to be reproduced.
Format/Resolution: TIFF, 300–600 dpi (depending on image type); image quality: high
Size: Variable
File name: heb90001.0001.tif

2. Small JPEG Files
Small JPEG files appear within the text, either embedded in paragraph text or as a series of images in a separate section.
Format/Resolution: JPEG, 72 dpi; image quality: medium or high
Size: 300–450 pixels on the long side, depending on orientation/shape, text flow, clarity, and file size. Please check with the HEB staff at ACLS if questions arise.
File name: heb90001.0001.jpg

3. Large JPEG Files
Large JPEG images appear in a pop-up window when users click on the small JPEGs within a book. (Enlarged jpegs are not needed if image-viewer technology will be used to view large versions of images.)
Format/Resolution: JPEG, 72 dpi; image quality: high
Size: 600–750 pixels on the long side, depending on what is needed for clarity. In cases where images include a lot of detail (e.g., maps), larger images might be required.
File name: heb90001.0001-lg.jpg

NOTE: Before submitting, make sure all images are a.) rotated by 90 degrees to correct orientation if necessary, and b.) properly cropped—i.e., remove extra white space around figure, frames, etc.

Tip: A quick way to convert image files in one batch is using Adobe Photoshop's Web Photo Gallery feature. First re-name your image files using the figure entity name, e.g., heb90001.0001 (or heb90001.0001-lg for large jpegs). From the File menu, select Automate, Web Photo Gallery. Select location of original files and destination of converted files. Select Large Images from Options pull-down, click on Re-size Images, select Custom in pull-down, and enter 300 (or 600) pixels; then select Contrain: Both, and Quality: Medium (or High). A website with converted images will be created. You can then submit these converted images.

Small jpegs will appear embedded within the text wherever a <figure> tag is inserted. Users will be able to click on these to open a pop-up window showing a larger version of the image. For each title, publishers can select several ways for users to enlarge an image:

1. Simple pop-up: Pop-up window brings up a larger version of the image (large jpeg). Recommended for most images.

2. Image viewer: Pop-up window that shows an image viewer that allows users to zoom in and pan on images (tiff option). Recommended for titles with high-resolution art images or detailed line drawings or maps.

3. External image: Pop-up window opens external URL showing enlarged image. (Used for images housed within other online collections.)

Place figure entity declarations at the top of the XML file:

<!ENTITY heb90001.0001 SYSTEM "heb90001.0001.jpg" NDATA jpeg>

Tag figures within the text as described below. All figure tags must be placed within <p> tags. Break down caption information by figure number, caption, and source/permissions; in some cases, source-information will be incorporated into the main caption text, and it may be desirable to omit <bibl type="figsrc"> altogether.

<p>[text text text]
<figure entity="heb90001.0001" id="fg_heb90001.0001">
<head>
<bibl type="figno">Figure 1.</bibl>
<bibl type="figcap">Caption for figure.</bibl>
<bibl type="figsrc">Source info/permission for figure.</bibl>
</head>
</figure>
[text text text]
</p>

Note: Please make sure each <figure> includes a <head> tag. This is necessary for further processing at HEB, but the tag may be left blank if inclusion of a caption is not desired.

In addition to the above, for images to be viewed with the image-viewer tool, type attribute type="ic" should be added to the <figure> tag (<figure entity="heb90001.0001" id="fg_heb90001.0001" type="ic">). For external images, type attribute type="ext" should be added (<figure entity="heb90001.0001" id="fg_heb90001.0001" type="ext">). All external images will also require delivery to HEB of target URLs in a spreadsheet. (This information is not tagged in the XML file itself, but housed in a separate database.) Please contact HEB for more information if external images will be used in your e-book.

(A third attribute that may be added to the <figure> tag is type="imagemap" (<figure entity="heb90001.0001" id="fg_heb90001.0001" type="imagemap">). This applies only to figures classified as interactive images; an additional requirement for these is supplying HEB with coordinates for points in the image from which interactive links will originate. Please contact HEB for details before proceeding with this type of figure.)

If figures appear in a separate section (plates), then just tag as a <div1> section and tag each figure in a <p> tag. It is recommended to move such sections to the front matter (where normally the List of Illustrations would appear) for organizational purposes.

Note: jpg extensions should NOT be included for figure entity names listed within <figure> tags.

Audio and video clips in several standard formats may be included (.mp3 and .mov are currently considered optimal for HEB and are preferred). HEB recommends file size on individual clips be kept to 20 MB and under to minimize download times (longer clips may need to be broken down into subcomponents prior to submission). Dimensions for video should ideally be 320 X 240 pixels to match the default pop-up window in which clips will be displayed. (If these guidelines present production problems, please contact HEB.) Clips formatted to the above specifications should be named in accordance with the title's unique HEB number.

Tag clips using <ref> tags, as follows:

Listen to music clip 1, <ref type="audio" filename="heb90001.0001.mp3">"Title of Clip"</ref>.

View film clip 1, <ref type="video" filename="heb90001.0001.mov">"Title of Clip"</ref>.

In order to reference clips within a text, link to the container-element (e.g., <p> or <table>).

(Also see film clip <ptr type="txt" target="p_158" n="2"/>.)

The same principle applies to creating a List of Audio or Film Clips (see 3.2.6. List of Audio / Film Clips).

Use <table> tags for actual tables, or for text formatted as a table. (Adding heads is optional; the id attribute is necessary if a table will be subsequently referenced/linked.) The border attribute may be used for formatting if desired, as well as colspan and rowspan attributes for cells. Do not repeat column or row header cells if table spans several pages (as they often are in the print version in such cases).

<table id="tb_1" border="1"> (id and border optional)
  <head><bibl type="title">Table Head</bibl></head> (head optional)
  <row>
  <cell></cell>
  <cell></cell>
  </row>
</table>

The attribute type="insert" may be used with the <table> element to section off a specific text portion (e.g., letter, historical document, or text box) from the main text as a text block with a border around it. The insert text should be placed within a single <cell> with attribute type="letter". Often, using extracts or regular paragraphs may be preferable to using this type of formatting.

<table type="insert" id="in_1"> (id optional)
<head> (head optional)
  <bibl type="number">Insert Number</bibl>
  <bibl type="title">Insert Head</bibl>
</head>
<row><cell type="letter">
  <p>[text text text]</p>
  <p>[text text text]</p>
</cell></row>
</table>

Use <list> tag for lists. (Heads are optional; the id attribute is required if a list will be subsequently referenced/linked.) You can also nest lists within list items. Items in a list will be formatted with a hanging indent.

<list id="ls_1"> (id optional)
  <head><bibl type="title">List Head</bibl></head> (head optional)
  <item></item>
  <item></item>
</list>

Text constituting a salutation or signature (e.g., a greeting prefixed to a letter or the closing salutation appended to a foreword) should be tagged using the elements <salute> and <signed>. The element <dateline> should be used to tag the date and/or location prefixed or appended to a letter, transcript, or other document, as well as any text appearing outside this context that serves a similar purpose (e.g., a location/date functioning as a heading of sorts but which is NOT tagged as an actual <head>). The attributes align="center" or align="right" may be added to all three elements for formatting purposes (left alignment is default).

<dateline>Location, Date</dateline>
<salute>Dedicated to ...</salute>
<p n="7" id="p_7">Text of dedication.</p>
<signed>Author's name</signed>
<signed>Institution name</signed>

[ back to top]

In <back> section, create a <div1> with type="notes". Place notes for each chapter in separate <div2> . Each note id should follow this format: "[xxx].n[notenumber]" where xxx is [int] or [c01], [c02], etc.

<div1 type="notes" id="div1_nts">
<head>...
 <div2 type="notes" id="div2_nts.int">
  <note1 n="1" id="nt_int.n1">
  <p>Text of note.</p>
  </note1>
    . . .
  <note1 n="10" id="nt_int.n10">
  <p>Text of note.</p>
  </note1>
 </div2>
</div1>

Since end notes will appear as pop-up windows, for notes that include the word "Ibid." users will not see the referenced note in the pop-up window. We suggest you replace the word "Ibid." with the referenced text, commenting out "Ibid." and commenting where inserted text begins and ends. Note that often it's not such a clear-cut copy and paste replacement, because the referenced note can include lengthy text or multiple books. The question the publisher will need to work out is which portion of the previous note should replace the "Ibid." (If this is too difficult, it may be preferable to leave "Ibid." in place.)

<note1 n="10" id="nt_c01.10"> <p>Jones and Smith, <hi1 rend="italic">History of the United States</hi1>, Chapters 1 and 2.</p></note1>
<note1 n="11" id="nt_c01.11"> <p><!--Ibid.--><!--begin insert-->Jones and Smith, <hi1 rend="italic">History of the United States</hi1>, Chapters 1 and 2. <!--end insert--></p></note1>

For new online titles, publishers may want to consider ending the usage of terms such as "Ibid." and "Op. cit." in their house style, so that notes can be more efficiently processed in the electronic version.

Within <back> section, create a <div1> section with type="bibliography". If there are multiple sections in the bibliography, create subsections using <div2>, etc. All <bibl> tags (starting with the Bibliography, not those appearing in epigraphs) should be sequentially id'd. Remove any 3-em dashes used in print instead of repeated authors' names and repeat actual names instead.

<div1 type="bibliography" id="div1_bib">
<head><bibl type="title">Bibliography</bibl></head>
  <bibl id="bib_1"> ... </bibl>
  <bibl id="bib_2"> ... </bibl>
</div>

To tag an index, create a <div1> section with type="index". Create a main <list>, then put each letter into a separate sub-nested list (placed within the main list's individual <item> tags). Sub-nested lists for terms should be placed within yet another <list> under the term's <item> tag.

To link a page number to a specific page in the text, use the empty <ptr> tag, and add "txt" in a type attribute, the page number in an n attribute, and the page break id in a target attribute. (If an index is being created for a born-digital book, paragraph links can be used instead.) Our system will take the n attribute value, put brackets around the number and hyperlink it to the targeted page break in the text. For page ranges (e.g., "30-35"), only the first page should be tagged.

Note references in Index: For note references, the page number rather than the note number should be tagged. (There may be some exceptions to this rule, such as e-books derived from print titles using footnotes rather than endnotes, in which case page numbers for notes are rendered obsolete. In this event, please confer with HEB staff prior to tagging.)

Figure references in Index: Instead of <hi1 rend="italic">, use [fig.] after a page link to designate a figure reference. Alternatively, such page links may be converted to direct figure links (see 3.2.5. List of Illustrations for tagging instructions).

<div1 type="index" id="div1_ind">
<head><bibl type="title">Index</bibl></head>
<list>
 <item><list>
  <item>Apples, <ptr type="txt" target="pb_1" n="1"/>, <ptr type="txt" target="pb_15" n="15"/>-17</item>
  <item>Apricots, <ptr type="txt" target="pb_133" n="133"/></item>
 </list></item>
 <item><list>
  <item>Bananas, <ptr type="txt" target="pb_34" n="34"/>n18</item>
  <item>Blueberries, <ptr type="txt" target="pb_68" n="68"/> [fig.], <ptr type="txt" target="pb_69" n="69"/></item>
  <item></item>
 </list></item>
</list>
</div1>

As the final <back> matter section, create a <div1> section with information about the author(s). (An author's photo may be included, if desired.)

<div1 type="aboutauthor" id="div1_aut">
<head>
<bibl type="title">About the Author</bibl>
<bibl type="para">999</bibl>
</head>
<p><figure entity="heb90001.0100 id="fg_heb90001.0100"><head>
<bibl type="figcap">Author's name.</bibl>
<bibl type="figsrc">Author Photo: Photographer's name.</bibl>
</head></figure></p>
  <p>[text text text]</p>
</div1>

[ back to top]

XML files must be quality checked and proofread before submission to ACLS Humanities E-Book. We have provided a proofing XSLT style sheet to help view XML in a format closer to the final online version.

The following list shows all the elements defined for the ACLS Humanities E-Book acls-hebook.dtd. This list is an edited subset of the elements in the TEI Lite XML DTD.

<back>

contains any appendices, notes, bibliography, index, etc., following the main part of a text.

<bibl>

contains either a.) a sub-component of a heading, b.) the name(s) of the author(s) of an epigraph, or c.) a bibliographic citation.

<body>

contains the whole body of a single unitary text, excluding any front or back matter.

<cell>

contains one cell of a table.

<dateline>

contains a brief description of the place, date, and/or time of production of a document (usually prefixed or suffixed to it as a kind of heading or trailer).

<div1> ... <div4>

contains a first, second, third, fourth level subdivision of the front, body, or back of a text.

<docauthor>

contains the name of the author of the document, as given on the title page.

<docimprint>

contains the imprint statement (<publisher> name, place of publication <pubplace>), as given (usually) at the foot of a title page.

<doctitle>

contains the title of a document, including all its constituents, as given on a title page. Must be divided into <titlepart> elements.

<epigraph>

contains a quotation, anonymous or attributed, appearing at the start of a section or chapter, or on a title page.

<figure>

marks the spot at which a graphic is to be inserted in a document. Attributes may be used to indicate an entity containing the image itself (in some non-XML notation); <head> within the <figure> element may be used to transcribe captions.

<front>

used to designate any prefatory matter before the start of the text proper.

<head>

contains any heading, for example the title of a section, or the heading of a list or glossary (sub-components should be tagged individually with <bibl> tags).

<hi1>

used to tag text as italicized (<hi1 rend="italic">), bold (<hi1 rend="bold">), struck out (<hi1 rend="strike">), underlined (<hi1 rend="und">), superscript (<hi1 rend="sup">), subscripted (<hi1 rend="sub">), or one of several combinations thereof (<hi1 rend="bolditalic">, <hi1 rend="supund">, <hi1 rend="supbold">, <hi1 rend="boldund">).

<item>

contains one component of a list.

<l>

contains a single, possibly incomplete, line of verse.

<lg>

contains a group of verse lines functioning as a formal unit, e.g., a stanza, refrain, verse paragraph, etc.

<list>

contains any sequence of items organized as a list, whether of numbered, bulletted, or other type.

<milestone>

marks a boundary between two sections of a text that does NOT constitute the start of a new division-based section. Attributes are skipline and asterisk.

<note1>

contains a note or annotation.

<p>

marks paragraphs in prose.

<pb>

marks the boundary between one page of a text and the next in a standard reference system.

<ptr>

a pointer (reference) to another location in the current document in terms of one or more identifiable elements.

<publisher>

provides the name of the organization responsible for the publication or distribution of a bibliographic item.

<pubplace>

contains the name of the place where a bibliographic item was published.

<q1>

contains a quotation or apparent quotation.

<ref>

a reference to another location in the current document, in terms of one or more identifiable elements, possibly modified by additional text or comment.

<row>

contains one row of a table.

<salute>

contains a salutation or greeting prefixed to a foreword, dedicatory epistle, or other division of a text, or the salutation in the closing of a letter, preface, etc.

<signed>

contains the closing salutation, etc., appended to a foreword, dedicatory epistle, or other division of a text.

<table>

contains text displayed in tabular form, in rows and columns, or as a block sectioned off from the main text by a border (inserts).

<text>

the entire body of the book.

<titlepage>

contains the title page of a text, appearing within the front matter.

<titlepart>

contains a subsection or division of the title of a work, as indicated on a title page; also used for free-floating fragments of the title page not part of the document title, authorship attribution, etc.

For processing purposes, it is useful to make the order in which attributes appear for any given element consistent throughout the text.

Note: For id attribute values, prefixes with underscores (e.g., p_, pb_) must be used, as listed below; our system will recognize only id's with these prefixes.

Tag	type	n	id	target	rend	miscellaneous
bibl (div head)	number title subtitle byline para
bibl (figure head)	figno figcap figsrc
bibl (epigraph source)	epi
bibl (references)			bib_1 bib_100
cell	(letter)					(colspan="...") (rowspan="...")
dateline						(align="center") (align="right")
div1	part chapter (etc.)		div1_pt1 div1_c01 (div1_cpy, div1_pre...)			status="hidden"
div2	chapter section (etc.)		div2_c01 div2_c01.1 (div2_int.1, div2_nts.c01...)			(status="hidden")
div3	section subsection (etc.)		div3_c01.1 (div3_bib.1.1)			(status="hidden")
div4	subsection (etc.)		div4_c01.1.1 (div4_app01.1.1)
figure	ext ic imagemap		fg_heb90001.0001			entity="heb90001.0001"
hi1					italic italicsunderlined bold bolditalic boldund strike und sup supund supbold sub
list			ls_1
milestone					skipline asterisk
note1		1 10	nt_pre.n1 nt_c01.n10
p		1 10	p_1 p_10
pb		1 10	pb_1 pb_10
ptr (note reference)		1 10		nt_c01.n1 nt_c01.n10
ptr (paragraph)	txt	10		p_10
ptr (page)	txt	10		pb_10
ptr (div)	txt	1 1.1		div1_pt1 div3_bib.1.1
ptr (figure)	txt	1 10		fg_heb90001.0001 fg_heb90001.0010
ptr (table)	txt	1		tb_1
ptr (list)	txt	10		ls_10
ptr (bib)	txt	10		bib_10
ref (paragraph)	ptr			p_10
ref (page)	ptr			pb_10
ref (div)	ptr			div1_pt1 div3_bib.1.1
ref (figure)	ptr			fg_heb90001.0001 fg_heb90001.0010
ref (table)	ptr			tb_1
ref (list)	ptr			ls_10
ref (bib)	ptr			bib_10
ref (to web page)	url					url="http://www...."
ref (audio)	audio					filename= "heb90001.0001.mp3"
ref (video)	video					filename= "heb90001.0001.mov"
salute						(align="center") (align="right")
signed						(align="center") (align="right")
table			tb_1			(border="...")
table (insert)	insert		in_1
titlepart	main sub

6. Cover Image

You must submit a high-resolution TIFF file and two JPEG files for the cover image, which will appear on the Title Record Page of each book.

1. High-resolution tiff image: size: variable; format: TIFF, 300 dpi; image quality: high
File name: heb90001.0001.001.tif

2. Small jpeg image: width: 160 pixels; format: JPEG, 72 dpi; image quality: medium or high
File name: heb90001.0001.001.jpg

3. Large jpeg image for pop-up window: height: 650 pixels; format: JPEG, 72 dpi; image quality: high
File name: heb90001.0001.001-lg.jpg

7. Technical Contact at ACLS

Nina Gielen (ngielen@hebook.org)

8. ACLS Specifications—Log of Specifications Updates

02-20-08 Updates:

New rules and additions:
1. Tagging Text: Added general note on XML file formatting.
2. Figures: All <figure>s now require <head>s.
3. Figures: Removed url attribute for type="ext" figures and added information on alternate delivery of associated urls.

Clarified/refined:
1. Audio / Video Files: .mp3 and .mov now considered preferred formats.
2. DTD, template, and XSLT updated; also added links for non-zipped versions.

04-30-07 Updates:

New rules and additions:
1. Styling: Added new option italic-underlined.
2. Figures: Type attribute added for interactive image-map images.

Clarified/refined:
1. Heads: Added note on redundant punctuation in <bibl type="number"> tag.
2. Audio / Video Files: Added .mov to list of video formats; softened dimension-requirements.
3. DTD, template, and XSLT updated.
4. Attribute Chart updated.

03-12-07 Update:

1. Copy throughout updated from History E-Book to Humanities E-Book.

09-05-06 Updates:

New rules and additions:
1. Updated DTD and template (see 1. Files and Resources).
2. Styling: Added new option subscript.
3. Structure: Added "List of Audio / Video Clips" to front matter.
4. Structure: Added "Preface to the Electronic Edition" to front matter.
5. Links: Added information on tagging multiple links for same term.
6. Figures: Use of letters in entity names now expressly prohibited (except "heb").
7. Figures: Updated size requirements for small JPEGs.
8. Figures: Type attribute added for image-viewer images.
9. Figures: Added suggestion for placement of plate-section.
10. Audio / Video Files: New section created with instructions for submitting and tagging this media.

Clarified/refined:
1. Renumbered sections affected by new additions.
2. Removed reference to obsolete link listing entity names.
3. Text Chunks: Necessity for delivery by lowest-available <div> emphasized.
4. Milestone Section Breaks: Corrected error in tagging sample. (Also renamed section, for clarity.)
5. Copyright and Permissions: Clarified language used in sample for information on print version.
6. List of Illustrations: Corrected error in tagging sample.
7. Paragraphs: Deleted obsolete mention of rend="no-indent".
8. Page Breaks: Guidelines for placement of <pb>s expanded.
9. About the Author: Corrected error in tagging sample.
10. List of Elements updated.
11. Attribute Chart updated.

12-01-04 Updates:

1. Updated DTD, template, XSLT.
2. Elements: <table> attribute type="insert" (in conjunction with <cell type="letter">) replaces separate element <insert>.
3. Styling/<hi1> tag: hyphens deleted from rend="..." values.
4. Technical contact updated.

09-22-04 Updates:

New rules and additions:
1. Updated DTD and template (see 1. Files and Resources).
(Note: For a log of all edits to previous versions of this DTD—versions 1 through 1.04—please see http://www.humanitiesebook.org/xml/dtd/acls-hebook-dtd_log.html.)
2. Added XSLT (see 1. Files and Resources).
3. Elements: Added new elements <dateline>, <insert>.
4. Structure: "Titlepage" <div1> division added to front matter (following <titlepage>); back matter <div1> "About the Author" now required.
5. Special Characters: &nbsp; added to special characters.
6. <hi1> tag: Six new styling options added.
7. Page breaks: Rules for blank pages added.
8. Figures: Cropping of images prior to submitting now required.
9. Figures: Type attribute added for external images.
10. Tables: <border>, <rowspan>, and <colspan> attributes added.
11. Salute, signed, dateline: <align> attribute added.
12. Index: Breakdown into sections now required for overlong index.

Clarified/refined:
1. Numbered all sections.
2. Linked cross-references.
3. Guidelines on punctuation with <hi1> tags added.
4. Guidelines on use of status="hidden" added.
5. Suggested id's for lists, tables, inserts refined.
6. Suggestions for use of figure captions in List of Illustrations refined.
7. Guidelines for use of unnumbered <p>s expanded.
8. Guidelines for placement of <pb>s refined.
9. Guidelines for internal linking expanded; corrected header for 3.3.3. Links: Notes, Internal Links, URLs.
10. Use of <figsrc> clarified.
11. Linking to notes from Index addressed.
12. List of Elements updated.
13. Attribute Chart updated.
14. Technical contact e-mails updated.

09-30-03 Updates:

1. Cover specs: Submission of cover image as TIFF file (in addition to JPEGs) now required.

09-18-03 Updates:

New rules and additions:
1. ID attribute: New tags used for id (and target) throughout; now require underscore as part of prefix (e.g., p_10).
2. <hi1> tag: New styling option added: <hi1 rend="bolditalic">.
3. Heads: Byline attribute added to <bibl>-options.
4. Copyright and Permissions: Instructions have been expanded.
5. List of Illustrations: This now uses direct links to figures (as opposed to print-page number on which figure appears); location of section specified.
6. Paragraphs: "no-indent" attribute for paragraphs now obsolete.
7. Links: Now possible to link to divs, paragraphs, figures, tables, lists, bibl items.
8. Figures: Updates to figure specs (file names, size). Figures now require ids.
9. Index: Request for individually nested sublists, direct figure-link info added. Note-reference tagging in index changed from note number to page number.

Clarified/refined:
1. <text>-tag (in front matter): Instructions for attributes have been refined.
2. Page breaks: Flexibility for location of <pb> for stylistic reasons in specific cases (e.g., extract lines).
3. Extracts: Location of epigraphs has been specified.
4. Salute, Signed: Subsection added to General Elements.
5. List of Elements updated.
6. Attribute Chart updated.

05-13-03 Updates:

1. Epigraph source—bibl tag in epigraph source should include attribute type="epi"<bibl type="epi">
2. All images must be submitted with high resolution tiffs. Small edits to image specs for clarity.
3. Index tagging—removed specs to tag links to note id in index.

02-20-03 Updates:

1. Figures—clarify image size specs. Small images, maximum size 530.
2. Small text copyedits.

[ back to top]