Poetry

From DPWiki
Jump to: navigation, search
DP Official Documentation - Post-Processing and Post-Processing Verification

There is no such thing as poetry in HTML

In many of our books, we have some snippets of poetry. Some of our books are composed entirely of poetry or, what is pretty much the same thing, metrical drama. The trouble is: There is no such thing as poetry in HTML. We don’t have anything like <poetry> or <stanza> elements. HTML was not designed to semantically represent poetry.

So, what can we do about that? We have to make do with the elements we have, using classes to distinguish between different uses of the same element—so that we can style them differently using CSS. We could, for example, code all of our poems as <div class="poetry">, and the stanzas within them as <div class="stanza">.

Definition: What’s in a line?

Before we get started, let's define a term that has the potential to be confusing.

  • A poem consists of one or more stanzas.
  • A stanza consists of one or more lines.

So, just what is a line? In the example below, we will see that what we think of as a line of poetry can actually wrap onto more than one physical line, so we need different terms to distinguish between the two. For this Case Study, we will use “verse” to refer to a metrical line, and “line” to refer to the line as displayed—whether on paper or on a computer or e-reader screen.

Goals for representing poetry

First of all, let’s think about the goals we have when representing poetry in an e-book:


  • Firstly, we do not want our poems to be rewrapped; the line breaks are significant and need to stay exactly where they were in the original.
  • Secondly, poems are often organised into stanzas, with some space between them; if that is the case for our poetry, we want to reproduce that structure and spacing.
  • Thirdly, if a verse does not fit and needs to be broken onto the next line, we want the continuation to be indented by some additional amount in order to visually set it off from a new verse. If there are several verses for which that is the case, we want all the continuations to be indented to the same point, no matter whether the verse is or isn’t indented from the left margin of the poem.
  • Fourthly, we want to preserve relative indenting. In many poems, different verses are indented by different amounts of space—and this has a semantic significance that we want to keep.
  • And finally, many poems are centered on the page, while their individual verses are left-aligned within that centered block. If our book does that, we might want to reproduce that style.

Formatting a poem

Let’s look at an example of a reasonably simple poem that is not centered on the page, but just indented from the left margin:

A Simple Poem


Of our above-stated goals, the first four apply to this poem: We want to preserve the line break at the end of each verse, the spacing between the stanzas and the relative indentation of verses, and if verses are broken onto more than one line, we want to indent the continuations.

Next, let’s look at a representation of this poem in HTML:

<div class="poetry">
  <div class="stanza">
    <div class="verse">When on the ground red apples lie,</div>
    <div class="verse indent2">In piles like jewels shining,</div>
    <div class="verse">And redder still on old stone walls</div>
    <div class="verse indent2">Are leaves of woodbine shining.</div>
  </div>
  <div class="stanza">
    <div class="verse">When comrades seek sweet country haunts,</div>
    <div class="verse indent2">By twos and twos together,</div>
    <div class="verse">And count like misers, hour by hour,</div>
    <div class="verse indent2">October’s bright blue weather.</div>
  </div>
</div>

N.B.: This is just one representation of the poem; there are others that would work just as well. You could, for example, use <p> elements instead of <div> elements for the individual verses, if you prefer.

Now, let’s make sure we are meeting all of our goals!

Firstly, we are already preserving the line breaks by using block elements for the individual verses, which puts each of them onto its own line.

Secondly, since we have set a distinct class on the stanzas, we can easily add some spacing between them:

.poetry .stanza
{
  margin: 1em auto;
}

Thirdly, let’s deal with what happens when a verse overflows onto more than one line. We want to format our verses so that the first line of each verse is positioned to match the image, whether that be flush left or indented—and if any verse needs more than one line, subsequent lines are indented an additional amount so that the continuations will not be confused with the indentation of the verses. For example:

Continued lines in poetry


Note that the indentation of the beginning of each verse matches the image, but if a verse is broken, the second line gets indented an additional amount; all continuation lines align along a vertical axis. This is how most books print poetry, and is probably the least confusing way of dealing with this issue—if and when it arises.

How do we accomplish this additional indentation? For each verse, we want to indent any continuation line, but not the first line. So we use a little trick—one that is often used for hanging indents: We set a negative indent on the verse, and a matching positive value for the left padding to move the verse back to the left margin. The negative indent/positive padding values we choose will determine the position of the indentation we get for our continuation lines. For our example, the CSS is as follows:

.poetry .verse
{
  text-indent: -3em;
  padding-left: 3em;
}

Fourthly, our goal is to keep the relative indentation of the original. We are already using the “text-indent” property for our continuation lines, but it is also the most reasonable way of indenting verses, so the solution requires a tiny bit of arithmetic. For every two characters of indentation in the original (and in the text version), we need about 1em of indentation.

In our example, every second verse is indented by about two characters, so we need 1em of additional indent for these. To arrive at the final value for the “text-indent” property, we have to start with the generic value (in our example, −3em) and add the value for the indentation to it (in our example, 1em); thus, we arrive at an indentation value of −3em + 1em = −2em for our indented verses. In order to be able to apply that indent to the relevant verses, we have put an “indent2” class onto them, in addition to the generic “verse” class—and we can define the CSS like this:

.poetry .indent2
{
  text-indent: -2em;
}

Look at this!

N.B.: If you have very large indentations, e.g., if you are working on metrical drama and have verses that are split between two or more speakers, it would make sense to reduce the amount of indentation for “mobile” devices. See the Introduction to @media for DP/PG Use and the Case Study on Media Types for more information and examples of how to do something like this.

Centering poetry on the page

So, in the above example, we have met the first four goals we had set for ourselves—but what about the fifth one? What if our poetry is centered on the page? This is often done in books of poetry, and also for snippets of poetry in fiction or non-fiction.

Now, since we already have a fully working poetry example, let’s just pretend that it was centered on the page and we want to reproduce that. What do we have to change in order to nudge the poem into the center of the screen or printed page?

First of all, we have to put our poem into yet another <div>:

<div class="poetry-container">
  <div class="poetry">
    <div class="stanza">
    ...
    </div>
    <div class="stanza">
    ...
    </div>
  </div>
</div>

We need this <div> to act as a container for our poem; we are going to make the poem exactly as wide as it needs to be, and to center it within this container. So the next step is to set the text-alignment for the container to centered, and for the poem itself to left-aligned—since we want left-aligned verses inside the centered poem:

.poetry-container
{
  text-align: center;
}

.poetry
{
  text-align: left;
}

This alone does not actually change anything yet, however, since both the container and the poem itself are <div> elements—and thus block elements, which are always exactly as wide as the element within which they are nested. In our case, this means that both the poetry container and the poem itself are as wide as the body text of the book, and therefore centering the poem within the container will not make any difference.

In order to make this work, we have to change the type of the poem <div>, using the “display” CSS property:

.poetry
{
  display: inline-block;
  text-align: left;
}

“What’s an ‘inline-block’ element?” you ask? “I thought there were only inline elements and block elements!” Well … there are those two … and then there are some very special types of elements that do not occur quite as frequently, among which there is the “inline-block” type. An element set to “display: inline-block” is positioned like an inline element, but otherwise behaves like a block element.

In our case that means that the poem takes up exactly as much width as the longest line needs instead of the whole width of the text block—and thus gets centered inside its container. But since it otherwise behaves like a block element, we can still neatly nest stanzas and verses inside it.

And that’s the whole magic! With those few changes to our initial poetry example, we get a poem that is truly centered on the screen or page.

There is one more recommended change, however: Since some “mobile” devices do not understand “display: inline-block” correctly, which can result in undesirable layouts, it is best to override the relevant part of the CSS for “mobile” devices. On these smaller devices, centering poetry is not quite as important anyway, since the verses of poems often barely fit within the device’s screen width—or are even broken onto more than one line. The missing CSS to finish our example reads:

.x-ebookmaker .poetry
{
  display: block;
  margin-left: 1.5em;
}

The “display” property is restored to “block” for the poetry <div>, and we are also setting a left margin to visually set the poem off from the surrounding text. Note that the latter is not required, and in some books it might be better to leave it out, e.g., in poetry books—where there is no “surrounding text”.

Look at this!

N.B.: This approach works well in all modern browsers. In some very old browsers, however, the poetry will not be centered; it will still meet the first four goals, but will be positioned near the left margin. If you are bothered by that, the next section might be for you.

Approximately centering poetry—even in old browsers

If you do not want to use the above approach, here is a second method for (approximately, in this case) centering poetry. Let’s again start with our simple example, and add the relevant code to it.

For this approach, we do not need another container around our poems; instead, we set a second class on each poem. We estimate how wide the poem needs to be so that the longest line will fit, add an appropriately-named class to the poem, and set the maximum width of the poem using that class. That way, the poem <div> isn’t as wide as the text block any more, and can be centered using left and right margins set to “auto”.

First, let’s adjust our HTML accordingly:

<div class="poetry <span class="highlight">width21</span>">
  <div class="stanza">
    ...
  </div>
  <div class="stanza">
    ...
  </div>
</div>

We are measuring the width in em, because that is a unit that adjusts to the user’s choice of font and font size—which is important to make sure the code will work for most people. Here’s the CSS for the class we used above:

.width21
{
  max-width: 21em;
}

N.B.: Different fonts need different widths (in em) for the same text to fit—because fonts differ in the widths of their characters, and measure the em unit differently. This means that it is always a good idea to try out your poems in several different fonts before settling on a final value for the width. Additionally, we set the left and right margins of poems to “auto”, so that the poem <div>s will be centered on the page:

.poetry
{
  margin: auto;
}

Look at this!

Note that it will often take some experimentation to arrive at an appropriate value for each poem, and you will seldom guess right at the first attempt. To make this task a little easier, it helps a lot to set a background colour or a border on the poem, so that you can see how wide it is. Here is an example:

.poetry
{
  margin: auto;
  <span class="highlight">border: 1px solid orange;</span>
}

(Make sure you remove this line from your code again before uploading the book to PPV or PG!)

N.B.: You will need a different class for each different width that you wish to center. Because you are setting a width based on an estimation, and perhaps allowing some extra for different fonts, the centering is approximate. For some users, some verses that would fit into the browser window’s width may be broken onto two lines, depending on your estimation and their font choice.

To comment or request edits to this page, please contact lhamilton or hdmtrad.

Return to DP Official Documentation Menu