Subscribe to Updates

Click here to subscribe to new posts by email. We use Google FeedBurner to send these notifications.

BookBuilder Tech Tips: Proper HTML Syntax

Posted on: September 27th, 2006 by Craig Rairdin 1 Comment

The HTML parsing engine we use in BookBuilder is more sensitive to HTML syntax errors than your typical Web browser. Some commonly held bad habits will cause errors when you try to build your book. Here are some specific examples.

Improper use of <p> tag

There are two common but incorrect ways to use the <p> tag. Most people understand that the closing </p> tag is optional, but some have a habit of not using the opening <p> tag and instead using only </p>. This works in many browsers but not in BookBuilder. Others put <p> at the end of their paragraphs. This is actually interpreted by the browser or BookBuilder as a <p> at the beginning of the next paragraph. This may not cause problems but it leaves the first paragraph without a <p> tag and it adds an extra <p> tag at the end.

We’ve also seen people not use the <p> tag at all. Some use line breaks (<br> tags) at the end of paragraphs. The problem with this is that our readers load and display whole paragraphs at a time. If you write a long section of text with no <p> tags (using <br> tags to break lines at the end of your “paragraphs”), the program will have to load the entire section into memory before any of it can be displayed. This will cause noticeable delays in displaying your text.

Improper construction of lists

The <ul> and <ol> tags demarcate unordered (bulleted) and ordered (numbered) lists. Between <ul> and </ul> (or <ol> and </ol>) you are allowed only list items (<li> tags). You cannot intermix paragraphs (<p> tags) and list items.

Some browsers allow you to create a bulleted list by using <li> tags with no enclosing <ul> or <ol> tag. This is not proper HTML and will cause errors in BookBuilder.

The rule that disallows anything but list items within a list can also be inadvertently violated when embedding a list in another list. When creating an outline using list tags, make sure the sublists are enclosed inside the list item above them, as in the following example:

<ol type=I>
  <li>Main Point I
    <ol type=A>
      <li>Point A under I</li>
      <li>Point B</li>
    </ol></li>
  <li>Main Point II
    <ol type=A>
      <li>Point A under II
        <ol type=1>
          <li>Point 1 under A</li>
          <li>Point 2</li>
        </ol></li>
      <li>Point B under II</li>
    </ol></li>
</ol>

Note that all sublists are inside the <li>…</li> tags of the point directly above them.

As an efficiency consideration, remember that our readers load the entire outer list in memory at one time. If your outlines are long, they can take a long time to load and display. To avoid this problem, break your outermost list into pieces corresponding to list items. The list above would be rewritten as follows:

<ol type=I>
  <li>Main Point I
    <ol type=A>
      <li>Point A under I</li>
      <li>Point B</li>
    </ol></li>
</ol>
<ol type=I>
  <li value=2>Main Point II
    <ol type=A>
      <li>Point A under II
        <ol type=1>
          <li>Point 1 under A</li>
          <li>Point 2</li>
        </ol></li>
      <li>Point B under II</li>
    </ol></li>
</ol>

Note that it’s important to set the value parameter on list items after the first one so that the reader program knows this is a continuation of the previous list.

Improper use of tables

Tables, like lists, can be misued by including tags other than those allowed inside the <table>…</table> tags. You can not intermix paragraphs and table rows. The following might display correctly in your browser, but it will cause errors in BookBuilder:

<table>
  <tr><td>First row, first column</td><td>second column</td></tr>
  <p>This is a paragraph of text.</p>
  <tr><td>Second row, first column</td><td>second column</td></tr>
  Text without any tags
</table>

Both of the bold rows will cause errors.

Surrounding paragraphs with inline tags

Many browsers will allow you to create several bold paragraphs using syntax like this:

<b>
<p>This is the first bold paragraph…</p>
<p>This is the second…</p>
<p>And this is the third…</p>
</b>

This is illegal HTML. BookBuilder requires you to put inline tags like <b>, <i>, and <font> inside your paragraphs to comply with proper HTML syntax:

<p><b>This is the first bold paragraph…</b></p>
<p><b>This is the second…</b></p>
<p><b>And this is the third…</b></p>

Not reading the documentation

Finally, our best advice is to read and understand the BookBuilder documentation! It’s surprising how many questions we get are answered in the documentation. Spending a few minutes there will help you save hours of frustration later.

One Response

  1. […] The HTML parsing engine we use in BookBuilder is more sensitive to HTML syntax errors than your typical Web browser. We continue our article from a couple months ago regarding some common tagging habits that may cause errors when you try to build your book. […]

Leave a Reply

©2014 Laridian