(last update: 05-13-03)
PLEASE NOTE: this set of specifications is dated, and should be used for reference purposes only. A current set can be found at: http://www.historyebook.org/xml/doc/acls-hebook-doc.html
The following specifications include detailed instructions on preparing files for the ACLS History E-Book Project. Publishers should provide these specifications to their conversion or composition vendors. ACLS can also provide a list of experienced vendors.Files and Resources
Encoding, Special Characters, and Styling
Front, Body, Back
Copyright and Permissions
Table of Contents
List of Illustrations
Dedication, Acknowledgments, etc.
Links: Notes, Page Breaks, URLs
Extracts: Quotations, Epigraphs
Proofing and Quality Control
List of Elements and Attribute Chart
ACLS Specifications - Log of Specifications Updates
Technical Contacts at ACLS
DTD: acls-hebook.dtd ver. 1.03; date: 07-09-03 (view | download zipped file)
Character Entities: xhtml-lat1.ent (view | download zipped file)
XML Template: acls-hebook-template.xml (view | download zipped file)
Specifications (this web page): http://www.historyebook.org/xml/doc/acls-hebook-doc.html
The dtd and specifications are periodically updated, so always check for the latest versions before beginning a new book.
For examples on tagging and usage, refer to the XML template,
Save files in US-ASCII encoding. Add the encoding type to the XML declaration:
<?xml version="1.0" encoding="us-ascii"?>Special Characters
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:
If your book includes special or foreign characters outside this range, please add additional entities at the top of your XML file. Refer to this list of
<!ENTITY oelig "œ"> <!-- LATIN SMALL LIGATURE OE -->We will need to work with the publisher and our programmers on how to index (for searching) and render the additional characters. Note that this should not affect the way you tag or prepare your text for print or other electronic versions. We just want to make it clear that our system can currently handle the entities listed above, and any additional characters will need to be dealt with as needed. Styling
To tag italic or bold type, use <hi1> tag with rend attribute value italic or bold.
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.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
Break down the text using <front>, <body>, and <back> tags. Add mandatory HEB Number and ISBN (E-Book) attributes to <text> tag.
<text id="heb90`xxx" isbn="x-xxxx-xxxx-x">
Use division tags (<div1>, <div2>, <div3>) 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="c01">
Every division must have a type and id attribute, and include a <head> tag.
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 division level. The publisher can select the division level which will be delivered. For example:
<div1 type="chapter" id="c01" status="hidden">
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="c01" status="hidden">Milestone breaks
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.
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).
<div1 type="chapter" id="c01" status="hidden">
Heads 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]
Begin tagging the <front> section with <titlepage> information. Do not tag the blank and half-title pages.
Continue tagging all other front matter material in <div1> sections. Create a section with copyright and permissions information.
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. The list is not generated dynamically so you can have flexibility in what you include in the list (use shorter description, omit source information, add thumbnails, etc.). To create a basic List of Illustration with links to the page within the text on which the figure appears, tag as follows:
If the figures are not interspersed in the book text, but rather displayed as a separate section (plates), you do not need to create the List of Illustrations. You can simply create a separate <div1> that contains all the figures (see Figures section below).
Tag other front-matter text in separate <div1> sections within the <front> section. For example:
<div1 type="dedication" id="ded">[ back to top]
Use <p> to tag paragraphs. Add a rend="no-indent" attribute to paragraphs in the text that are rendered without indents.
Paragraphs in the text should also 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. Do NOT number <p> tags that used just for styling and are not part of book text, such as the <p> tags used in the copyright page. Also, do NOT number paragraphs within extracts, such as epigraphs or quotations.
<p n="40" id="p40" rend="no-indent"></p>
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. Note that page breaks must be placed within the main text, not in or above head tags.
<div1 type="chapter" id="c01" status="hidden">Page breaks within text should follow this format:
Begining of sentence[space]<pb n="121" id="pb121">rest of sentence.
Our system currently features three types of links.1. Link to note pop-up window
To tag a note number that will link to a note pop-up window, use the empty <ptr> tag, and add the note-reference number in an n attribute and the note id in a target attribute. Our system will take the n attribute value and put brackets around the number and hyperlink it to a pop-up window that will contain the text of the targeted note.
<ptr n="1" target="c01.n1"/>
Note: Do not style note-reference numbers as superscript. See section on Notes below for more information about tagging the text of a note.2. Link to a page break in text
To tag a link to a specific page number in the text, use the empty <ptr> tag, and add "txt" to a type attribute, the page number in an n attribute, and the page break id in a target attribute. Our system will take the n attribute value and hyperlink it to the targeted page break in the text.
<ptr type="txt" target="pb10" n="10"/>3. Link to external URL
To link to external URLs, use <ref> tags.
<ref type="url" url="http://www.url.com" id="url10">http://www.url.com</ref>
Other types of links, such as linking to paragraphs, figures, etc., will be available in the future.
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="p20">Paragraph text.If quote is formatted in lines (e.g., verse), use <l> or <lg> with <l>:
To tag epigraphs, place <epigraph> around the <q1> tag and add <bibl type="epi"> to tag epigraph author and source.
Images will appear in the text where a figure tag is inserted. Users will be able to click on an image to open a pop-up window showing a larger version of the image, either as a large JPEG or within an image viewer. For each title, publishers can select one of two ways for users to enlarge an image:
1. Simple pop-up: Pop-up window brings up a larger version of the image. 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. Recommended for titles with high-resolution art images or detailed line drawings or maps.
1. Small JPEG Files for In-line ImagesTagging Figures in XML
Place figure entity declarations at the top of the XML file:
<!ENTITY heb9xxxx.0001 SYSTEM "heb9xxxx.0001.jpg" NDATA jpeg>>
Tag figures within the text as follows. All figure tags must be placed within <p> tags. Break down caption information by figure number, caption, and source/permissions.
<p>[text text text]
If figures appear in a separate section (plates), then just tag a <div1> section and tag each figure in a <p> tag
Use <table> tags for actual tables, or for text formatted as table. Do not repeat column or row header cells if table spans several pages (as they are in print version in such cases).
Use <list> tag for lists. You can also nest lists within list items. Items in a list will be formatted with a hanging indent.
<list>[ 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="nts">Handling "Ibid." in Notes
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. You must 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."
<note1 n="10" id="c01.10"> <p>Jones and Smith, <hi1 rend="italic">History of the United States</hi1>, Chapters 1 and 2.</p></note1>
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 should be sequentially id'd. Remove 3-em dashes for repeated author names and repeat name.
<div1 type="bibliography" id="bib">
To tag an index, create a <div1> section with type="index" and put each letter into a separate <list>. Terms with subnested items can be placed within another list within an 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. 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.
<div1 type="index" id="ind">[ back to top]
XML files must be quality checked and proofread before submission to ACLS History E-Book Project. We will soon provide a proofing XSL to help view XML in a format closer to the final on-line version.
The following list shows all the elements defined for the ACLS History E-Book Project acls-hebook.dtd. This list is an edited subset of the elements in the TEI Lite XML dtd.
You must submit two JPEG files for the cover image, which will appear on the Title Record Page of each book.
Small cover image: width: 160 pixels; format: JPEG, 72 dpi; image quality: medium or high.
|© 2003 The ACLS History E-Book Project
Technical Contacts: firstname.lastname@example.org and email@example.com