Headings

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

< Easy Epub

What does it mean?

Historically, it was common practice to use h1, h2, h3, etc whenever you wanted any larger, centered text. This included the book title and chapter headings, but also typically other text on the title page. However, it is now strongly recommended that the structure defined by the headings matches the structure of the book.

Why should I do it?

The reason related to e-readers is that the ebookmaker software uses heading markup (h1 to h4) to create a Table of Contents (ToC). On the e-reader the user will typically have quick access to this ToC to aid navigation.

However, this is not just a requirement for epubs: it affects anyone who uses screen-readers or other aids to navigation on their computer. Such aids typically allow the user to jump between headings and may announce the level and title of the heading.

How do I see what I have at the moment?

Even without converting your HTML to epub/mobi format, you can easily see the structure your headings currently form. When you validate your HTML at W3C Markup Validator, you can tick Show Outline under More Options. Below the report that your HTML has validated successfully, you will see a Document Outline, looking something like this:

  • [h1] My Book Title
    • [h2] Contents
    • [h2] Chapter 1 - The First
    • [h2] Chapter 2 - The Next
      • [h3] Section A
      • [h3] Section B
    • [h2] Chapter 3 - The Last
    • [h2] Index

Below it you will see the following statement: "If this does not look like a real outline, it is likely that the heading tags are not being used properly. (Headings should reflect the logical structure of the document; they should not be used simply to add emphasis, or to change the font size.)"

Alternatively, if you have converted to epub or Kindle format, then you will be able to see the automatically generated ToC via a Contents button or link on your e-reader. Alternatively, you can see it on the navigation panel of ADE or the Kindle viewer on your computer (see Easy Epub/Viewing for how to get these).

How can I fix it?

If this simple guide does not deal with your situation, there is more detail and examples in the Headings and Title Pages sections of the Best Practices document.

There are two parts to fixing it. The first is making sure the correct things are inside heading markup. The second is dealing with other things that now should not be in heading markup, but you want to be formatted in a similar way.

What to put inside heading markup

  • Put the whole book title, and only the book title (not the author) inside h1 markup. Make sure this is the first use of heading markup in the book. Also, just use h1 once, even if the title appears more than once in the book (see below for formatting subsequent appearances).

Here are a couple of examples:

<h1>My Book Title</h1>
<h1>My Book<br />
  <small>A Model of Perfection</small></h1>
  • Put each whole chapter title (and extras like Contents and Index) inside h2 markup.
<h2>Chapter 1 - The First</h2>
<h2>Chapter 1<br />
  <small>The First</small></h2>
  • Use h3 similarly for section headings if you have them, and you want them to appear in the generated ToC
  • If your book has higher level divisions, such as Parts, then you may make them h2, and chapters h3, but you will possibly want more sophisticated page-break handling.

How to format the rest

So, you've sorted the things that should be in heading markup, and now you need to deal with the things that shouldn't be.

One simple solution

You can define classes ph1, ph2, etc. that format a paragraph more or less like the default h1, h2, etc. How closely the size and margins match will depend on the browser. Then where a heading was being used wrongly, you can replace it with <p class="...">...</p>. You can of course change the sizes and/or margins as you please.

To do this, add to your CSS:

.ph1, .ph2, .ph3, .ph4 { text-align: center; text-indent: 0em; font-weight: bold; }
.ph1 { font-size: xx-large; margin: .67em auto; }
.ph2 { font-size: x-large; margin: .75em auto; }
.ph3 { font-size: large; margin: .83em auto; }
.ph4 { font-size: medium; margin: 1.12em auto; }

Then where the book title is repeated using h1, instead you can use

<p class="ph1">My Book<br />
  <small>A Model of Perfection</small></p>

or if the author on the title page was marked up as

<h3>By<br />
  A. Writer</h3>

replace it with

<p class="ph3">By<br />
  A. Writer</p>

etc.

Another simple solution for your title page

You can set up classes to give you the defined text sizes. You only need to define the ones you want to use:

.xxsmall {font-size: xx-small;}
.xsmall  {font-size: x-small;}
.small   {font-size: small;}
.medium  {font-size: medium;}
.large   {font-size: large;}
.xlarge  {font-size: x-large;}
.xxlarge {font-size: xx-large;}

Then define a class for a div to hold your titlepage, with a page-break before and after it. You also want all paragraphs on that titlepage to have a bigger line spacing, and a gap at the top, as well as being centered and bold.

div.titlepage {
  text-align: center;
  page-break-before: always;
  page-break-after: always;
}
div.titlepage p {
  text-align: center;
  text-indent: 0em;
  font-weight: bold;
  line-height: 1.5;
  margin-top: 3em;
}

Then in the HTML, write

<div class="titlepage">

<h1>My Book Title</h1>

<p>
  <span class="small">By</span><br />
  <span class="large">A. Writer</span>
</p>

<p>LONDON<br />
  <span class="large">1888</span>
</p>

</div>

If you want more control, e.g. for only some of the paragraphs to have the gap at the top, remove that part from the "div.titlepage p" above, and put it in its own class.

.topspace {margin-top: 3em;}

then use that class on those specific paragraphs:

<p class="topspace">LONDON<br />
  <span class="large">1888</span>
</p>

What about page breaks?

Even with the code above, particularly around the title pages you will probably find that the e-reader versions have page-breaks in annoying places. To help avoid this, you can tell the e-reader to force a page-break just before (or after) any of your HTML elements.

To your CSS, add

.break-before {
 page-break-before: always;
}

Then use something like

<p class="break-before">Copyright 1901</p>

Formatting Chapter Headings to Avoid unwanted page breaks mid-chapter

Ebookmaker breaks your file into chunks for epub. These chunks have a limited size, and have a page break at the start of every one. This means that when a chunk gets full mid-chapter, you sometimes get an unwanted page break there. To help avoid this, you can force ebookmaker to start a new chunk at the start of every chapter, using a div with a class of "chapter" or "section". Note it must be a div and the class name must be one of these words, not "chap", "section1", etc.

Although usage of <div class="chapter"></div> or <div class="section"></div> (with nothing between <div...> and </div>) may cause little problem with browser behavior, the W3 Schools "page-break-before" documentation states that it should not be used on an empty div, so it's better to have the div to surround the heading coding as shown below. This code has the advantage of generating a page break in conforming html browsers (if the html edition is to be printed) as well as in epub/mobi readers.

In your CSS add:

div.chapter {page-break-before: always;}
h2.nobreak {page-break-before: avoid;}

In your HTML, surround the h2 for your chapter with the div.

<div class="chapter">
<span class="pagenum">...[27]...</span>
<h2 class="nobreak">Chapter 2</h2>
</div>

<p>Etc., etc....</p>

There's a slightly more technical explanation of this here.

If you decide to add margin or padding to the "chapter" or "section" CSS settings and possibly extend them beyond the <h2> heading, please be aware that nesting of chapter/section elements should be avoided since that the margins of the nested classes are added together for the epub edition and would result in much larger spacing than planned.

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

Return to DP Official Documentation Menu
https://www.pgdp.net/wiki/DP_Official_Documentation:PP_and_PPV/Easy_Epub/Headings
www.pgdp.net
crawl=CC-MAIN-2021-39
29440
application/http; msgtype=response
sha1:JHTI3PSPGKRTFAYI36IUKLBHFBEDBASR
<urn:uuid:761032d9-1caa-4d68-a499-8df42614f90e>
2021-09-23T05:46:56Z
206.210.91.62
text/html
sha1:I7VSQU464NYUD6VWJYT2QRTUPOGBJAFM
<urn:uuid:956a5bc1-b78b-4f1b-a84f-5535e4dcd774>
https://www.pgdp.net/wiki/DP_Official_Documentation:PP_and_PPV/Easy_Epub/Headings
response
<urn:uuid:44032b79-a2ef-4813-994b-58bd3138b01b>
isPartOf: CC-MAIN-2021-39
publisher: Common Crawl
description: Wide crawl of the web for September 2021
operator: Common Crawl Admin (info@commoncrawl.org)
hostname: ip-10-67-67-156
software: Apache Nutch 1.18 (modified, https://github.com/commoncrawl/nutch/)
robots: checked via crawler-commons 1.2-SNAPSHOT (https://github.com/crawler-commons/crawler-commons)
format: WARC File Format 1.1
conformsTo: https://iipc.github.io/warc-specifications/specifications/warc-format/warc-1.1/