[Previous] [HWG Homepage] [Gutenberg Index] [Next]

Marking up documents in XHTML II

Here are some notes on using XHTML to markup a document. This section examines the use of the <div> and <span>elements, and the class attribute to give semantic meaning to a document. As this page contains tables of recommended classes, you may want to print this page out for easy reference.

Giving semantic meanings to documents

One of the problems with XHTML is that it describes the structure of a document rather than its content. We can get round this by making use of the 'class' attribute. The best way to do this is to put the attribute on a <div> element.

The <div> element is used to enclose whole sections. It is often a good idea to put a comment with the closing div tags to identify which section they are closing. Here is an example of the <div> in action. First the e-text.

   Chapter 5 
   The last straw

   When Peter got home he was met with depressing news...

Now add the structural markup.


   <h3>Chapter 5 </h3>
  <h3> The last straw</h3>

   <p>When Peter got home he was met with depressing news...</p>
       [the contents of the chapter
        <p>..</p>

And here is how we may mark it up with semantic classes.


  <div="chapter">

   <div="chapnumber"><h3>Chapter 5 </h3>
   </div> <!--end of class="chapnumber"-->
  <div="chaptitle"><h3> The last straw</h3>
  </div><!--end of class="chaptitle"-->

   <p>When Peter got home he was met with depressing news...</p>
       [the contents of the chapter
        <p>..</p>
   <--this div closes the chapter div-->
  </div><!--end of class="chapter"-->

Notice how we have used a comment to document which closing div belongs to which opening div. If you don't do this you will soon get very confused if you have several layers of nesting.Of course we would use a <span> element if we were looking at n inline class. However these will probably be few and far between.

Using the "class" attribute

You may well ask why not just put the class attribute on the XHTML elements themselves. Although this is possible, it is not recommended as it makes it much more difficult to transform an XHTML document type into another document type. Also there would be no way to enclose a block like a chapter, or the opening Gutblurb.

Suggested classes

Before reading this section you may want to read the page on "The parts of a book"

Marking up meta information

It is probably best to put the meta information in a single <pre> tag. Increase the granularity by enclosing the sections in the following <div class=""> elements

Classes for meta information
Class Attribute value	Description
class="gutblurb"	Use this to enclose the whole of the gutblurb meta material
class="endgutblurb"	This is for all the meta material at the end of the document.
class="revhist"	Use this to enclose all the matter pertaining to the markup of a document, including all the revision history. This should come right after the opening Gutenberg blurb.
class="comment"	Use this to enclose a comment in the body of the text. this can be rendered invisible by the style sheet. You can if you wish enclose a link element to link it to another footnote. (Note that this is accomplished in XML by using an idref type of attribute)
class="endmrkup"	Here you can put any footnotes or comments that are refered to from the body of the document. Also any notes on interpretation belong here.
class="footnote"	To identify the footnotes.
class="misc"	Any miscellaneous markup that does not easily fit into another category.

Marking up the document

First mark off the whole book!

class="book"

Make sure that this div encloses the whole of the book. It is often a good idea to put a comment with the closing div tags to identify which section they are closing.

Now divide the book up into front matter, body, and back matter.

Frontmatter

The following are suggested classes to use for enclosing front matter.

class="frontmatter"	Make sure that this div encloses the whole of the front matter. It is often a good idea to put a comment with the closing div tags to identify which section they are closing.
class="half-title"	The half-title page
class="titlepage"	The title page
class="author"	Use to identify the author or authors.
class="copyright"	Use to enclose the materials in the copyright page
class="dedication"	The dedication
class="epigraph"	An epigraph
class="toc"	The table of contents. you can if you wish increase the granularity of markup by defining your own classes. Most markers will just use the regular list elements. Use `<ul>` in preference to `<ol>`
class="loi"	A List of illustrations
class="lot"	A list of tables
class="lom"	A list of maps
class="foreward"	The foreward
class="preface"	The preface and/ or acknowledgements
class="intro"	the introduction
class="frontmisc"	misceleneous matter. It is often a good idea to enclose a user-defined class describing the type, or a comment. (The comment can be retrieved using XML tools)
class="loa"	A List of abbreviations

The document text

The following are suggested classes to use for marking up the body of the book.

class="bookbody"	Use this to enclose the entire body of the book.
class="chapter"	Use this to enclose an entire chapter.
class="chaptitle"	just enclose the chapter title.
class="chapnumber"	A chapter number if any
class="subsect1"	A sub section1
class="subsect2"	A sub section2
class="subsect3"	A sub section3
class="subsect4"	A sub section4. In a chapter with several levels of sub heading the hierachys can get quite confusing. Therefore make sure that you comment the closing `</div>` tags. It is also a good idea to put in the closing tag immediatly you write the opening tag!
class="bookfn"	Distinguish a foot note in the book from a footnote used by the marker. This can also be used for sub heads
class="quote"	Although you can use the XHTML `<blockquote>` element it is better to leave this to distinguish a block quotation. this class can be used for both inline and block quotes
class="reference"	Can enclose a reference in a book.
class="poem"
class="line"	A line in a poem
class="epilogue"	Use this to enclose the epilogue, afterword or conclusion of the book

Back matter

The following are suggested classes to use for enclosing back matter.

class="backmatter"	Use this to enclose all the back matter.
class="appendix"	Enclose the whole appendix
class="apptitle"	The title of the appendix
class="appnumber"	The appendix number
class="glossary"	Enclose the glossary if present.
class="biblio"	The bibliography or reference list if present.
class="index"	If the index is included in the etext then also include it in the marked up document. the page numbers will be meaningless, but future researchers may find them useful!
class="colophon"	The colophone if present

User Defined classes

By all means define your own class, but if you do

Makesure there is not a namespace clash with these classes
Document your class in the revision history
Provide a style sheet for the new classes.

Converting from one Document type to another

Once an e-text has been marked up in this manner it is a relatively easy matter to convert it to another document type. This can be done by either using a script such as a perl script or it can be done manually using the 'search and replace' function of a good text editor.