Sidenotes

From DPWiki
Jump to navigation Jump to search

Purpose

This article, updated in 2018 and again in 2022, discusses several solutions to implementing sidenotes during post-processing. The original article, written in 2012, is included towards the end, and is identified with that 2012 date. The reason for the article is that sidenotes in books prepared by ebookmaker for use on handheld / mobile devices often will display differently than they will in a Browser. The 2022 update includes handheld CSS using .x-ebookmaker.

NOTE: Future changes to eBookMaker, the utility we use to create .mobi and .epub versions of our HTML books, may make parts of this information obsolete. Also, as this is being written in May, 2022, Amazon has announced its intention to drop support for the .mobi format and add .epub support to all of its current Kindle products.


What's a Sidenote?

Sidenotes usually, but not always, summarize the text that is next to them. Most of the time, they appear on the left or right side of the page, next to the main text. By contrast, Footnotes usually contain further information about the text that refers to them.

In real books, sidenotes are positioned on the outside, so they'll be in the right-margin of right-hand pages. There aren't any left- or right-hand pages in eBooks, so we (normally) just put all of our sidenotes on the left side.

NOTE: The first three images are from pages in real books; the rest are from screenshots of how the accompanying CSS formatted some of the text shown in the first image.


Sidenotes may be in the left margin.
This looks nice, but wastes a lot of space that is in short supply on small "handheld" screens:

Book margin.jpg


They may be "inset" within paragraphs, with the text wrapping around them.
This also looks nice, and it does not waste space:

Book inset.jpg


Some books summarize topics with running headers, which usually appear on the right-hand pages.
We can't create running headers in an eBook, but we can treat them as sidenotes.
(This image contains the tops of eight pages.):

Running headers.jpg

If you know you will be Post-Processing a book with running headers, and want their text to be included in what you receive from the Rounds, you will want to ask the Project Manager to include instructions for that in the Project Comments: by default, headers are removed as early as possible.


Some ways to implement Sidenotes

As Headings

This is DP's de facto default: During the Rounds, Formatters will move sidenotes either just before the paragraphs that were next to them or, if there are no paragraph breaks above them, to the top of the page, preceded by an asterisk. The Post-Processor will move *[Sidenote]'s up further, above the beginning of the paragraph on an earlier page.

Often, this works well enough, and certainly is easy to do. However, if the paragraph is long and the sidenote refers to text towards the end of the paragraph, the sidenote will be less useful than the author intended. If there are several sidenotes next to the same paragaph, and all of them are moved up to precede the paragraph, they still will summarize the content of the paragraph, but will not assist the reader in finding the actual material in the main text.

In the Plain Text version of the final eBook, this kind of sidenote will be almost indistinguishable from an actual Section heading, except for being preceded by one blank line rather than two. That also will make it look similar to a very short sentence.

In the Plain Text version of an eBook, the solution to this is to uniquely-mark the sidenotes: keep the "[Sidenote:]" tag, just as we keep the "[Illustration]" tag between paragraphs; or enclose each sidenote in a distinctive symbol that doesn't appear elsewhere in the text, just as we use _underscores_ and =equals signs= to indicate italics and boldface. Some examples are the vertical bar |, the tilde ~, and the Unicode diamond ♦. When distinctive symbols are used, some ♦sidenotes♦ can be placed inline, like _italic_ text. (See the Note at the end of the Inline example for further information about choosing a symbol.)

In the HTML version, we have more options and more potential problems, and those are the reasons for the rest of this article.

In the Left Margin

If we want the Sidenotes to be in the left margin, so that they will look like this in a Browser:

Browser margin.jpg


we can use this:

CSS
<style type="text/css">
body {
   margin-left: auto;   /* setting left and right to "auto" lets the browser       */
   margin-right: auto;  /* center the body of the document                         */
   max-width: 60em;     /* limit width to help spread out the sidenotes vertically */
}
.all {margin-left: .25em; margin-right: 2em;} /* put ALL of the text of the document in <div class="all"  */
.main {margin-left: 6.5em; margin-right: 0;}  /* within the part of the document that contains sidenotes, */
                                              /* reserve 6.5em on the left exclusively for sidenotes.     */
.sidenote, .sni {     /* .sidenote will be block-level <div>'s; .sni will be inline <span>'s. */
   text-indent: 0;
   text-align: left;
   width: 7em;       /* force all sidenotes to be the same width: it looks better */
   min-width: 7em;
   max-width: 7em;
   padding: 0;
   margin: .6em 0 0 -7.75em;  /* let the sidenotes float out into that reserved space on the left */
   float: left;               /* let the sidenotes float */
   clear: both;               /* keep floating elements separate from each other */
   font-size: 80%;
   line-height: 1.1;
   font-style: italic;
}
.sni {text-indent: -.5em;}      /* with inline sidenotes, move the text left, to fill the space used by the unique symbol */
.sne {visibility: hidden;}      /* make the reserved symbol invisible most of the time */
.sidenote hr {margin: 0 0 .2em 0; visibility: hidden;}   /* a trick for slightly separating consecutive block-level sidenotes */


and this:

HTML
England, and probably also, as has been well
observed by a Portugueze historian,
<span class="sni"><span class="sne">♦</span>Neves, i. 151.<span class="sne">♦</span></span>
secretly resolving to indemnify the sufferers whenever it
should be possible, ... for this is consistent with
his character.
<span class="sni"><span class="sni"><span class="sne">♦</span>Edict for registering the persons and property of the English.<span class="sne">♦</span></span>
Under these feelings he issued an edict for registering all English persons and
property which were still to be found in his dominions. The order was reluctantly given,
and leniently carried into effect; but it compelled the British minister, Lord Strangford, to
take down the arms of Great Britain from his house:
<span class="sni"><span class="sni"><span class="sne">♦</span>The British minister leaves Lisbon.<span class="sne">♦</span></span>
he demanded his passports, and went off to a squadron under Sir Sidney Smith, which had
been ordered to cruise off the mouth of the Tagus, and Lisbon was then declared to be blockaded.
<div class="sidenote">November.
<br /><hr />
A Russian squadron enters the Tagus.</div>
<p>While the court was waiting in the most
anxious incertitude the result of its submission,
the agitation of the Lisbonians was increased
by the appearance of a Russian squadron in the


Unfortunately, it will look like this on a small handheld device that is in portrait orientation:

Smallscreen leftmargin portrait.jpg

It still works, but over a third of the screen has been reserved for the sidenotes, so the body text is in a too-narrow column on the right. Trying to use something like {width: 15%;} in the @media handheld section will not work in many cases: a lot of words in the sidenotes won't fit and, depending on the device, will either be hyphenated in strange places or protrude into and on top of the body text. If the person reading the eBook is willing to turn the device so that it's in landscape orientation, the appearance will be better:

Smallscreen leftmargin landscape.jpg

but still not great, and may be something the reader doesn't think to do or doesn't like. Fortunately, there is another way to format the sidenotes....


"Inset", with main text wrapping around them

If we add this CSS to the "@media print, handheld" section:


handheld CSS

This is updated CSS for use with eBookMaker versions that support .x-ebookmaker. The main section of CSS (for Browsers) has not changed:

  .x-ebookmaker body {max-width: none;}
  .x-ebookmaker .all {margin-right: 0;}
  .x-ebookmaker .main {margin-left: 0;}
  .x-ebookmaker .sidenote, .x-ebookmaker span.sni {
       text-indent: 0;
       text-align: left;
       font-size: smaller;
       float: left;
       clear: left;
       font-weight: bold;
       width: 7.2em;
       max-width: 7.2em;
       min-width: 7.2em;
       margin: .7em 1em 0 0;
       padding: .2em .2em .2em .3em;
   }
  .x-ebookmaker span.sni {text-indent: -.7em;}


This was the CSS before eBookMaker began using .x-ebookmaker. It's been obsolete since 2020:

@media print, handheld
{
   body {max-width: none;}
   .all {margin-right: 0;}
   .main {margin-left: 0;}
   .sidenote, span.sni {
       text-indent: 0;
       text-align: left;
       font-size: smaller;
       float: left;
       clear: left;
       font-weight: bold;
       width: 7.2em;
       max-width: 7.2em;
       min-width: 7.2em;
       margin: .7em 1em 0 0;
       padding: .2em .2em .2em .3em;
   }
   span.sni {text-indent: -.7em;}
}


No changes are needed in the HTML, and the document will use "inset" sidenotes on handheld devices, while still using in-margin sidenotes with Browsers. Notice that ".all" and ".main" have been changed to not reserve any space on the left or right, so the document can use the full-width of the screen. The result should (and usually will) look like this:

Smallscreen inset portrait.jpg


"Usually" ... not "always", because some Kindles do not support "float", and because the next image shows what sometimes happens with some implementations of Adobe Digital Editions (ADE), which, according to Adobe, is [one of] the most widely-used eReader apps in existence (maybe they've never heard of Kindle or Google Play Books or Apple's iBooks or even Calibre):

Solving a problem with Adobe Digital Editions

Ade inset overlap.jpg

Occasionally, sidenotes overlap each other and/or the body text (only with ADE). This usually doesn't happen with ADE, and it never seems to happen with Barnes&Noble's "Nook", which is ADE-based and widely used.

Again, there is a solution. Usually, when you use "float", you will also use "clear", either specifying the same side as the "float" or "both" (clear on both sides). Replacing "clear: left;" with "clear: both;" does not solve the overlap problem, but "clear: right;" does solve it. And, it doesn't break any other handheld devices, whether they are using .epub or .mobi files. The result does not look quite the way we want, but it's meaning is clear (no pun intended):


Ade inset solution.jpg

When there isn't enough space for everything, "clear: right;" causes ADE to put some of the sidenotes next to each other. Everything else finds a way to put them below one another.

The problem only seems to occur when there isn't enough room on the side for all of the "floats" that belong to the paragraph that contains them, or when the last "float" is too near the end of the containing paragraph. Once you do some research (e.g., look for "clearfix"), you'll find that this is a well-known problem ... and most Browsers and eReaders apparently found solutions to it years ago. If you only have occasional sidenotes and they aren't too long or too close together, you probably will never encounter this problem and can just use the normal "clear: left;".


Inline, as part of the main text

The original Kindle, and the Kindle for IOS (iPhones, iPads, etc.) apps do not support "floats", among other limitations, so the document will look like this on those devices:

Kindle for IOS iPhone.jpg

And that's the reason for including the diamonds or some other special symbol: like the _underscores_ we use in Plain Text, they call the reader's attention to text that's supposed to be formatted "differently". No new CSS or changes to the HTML are involved: all of was included in the samples shown above.

Note: When this was written in 2018, some eReaders had very limited support for Unicode characters. One of the reasons the "diamond" symbol ♦ was chosen is that everything seemed to be able to display it. The other reasons were that it's unlikely to occur in actual text and it stands out.

The rest of this article, which was written in 2012, goes into further detail about this.


2012: More about "Inset" Sidenotes, where main text wraps around the Sidenotes.

This is being written in December of 2012 to show a way of formatting sidenotes for browsers, epub, and various Kindles. The basic problem is that the basic Kindle does not support "float" or "background-color," and the Kindle application "app" for the iPad/iPhone doesn't support "float."

It feels a bit strange to be writing this now, thinking that, if anyone reads it in a few years, they'll have no idea why I wasted my time finding a solution to a problem that no longer exists. Well, because right now, it's still a problem.

OK, here's a book at The Internet Archive that will be used in these examples. We will be using text from the middle of page 14 through the top of page 16.

This excerpt contains two sidenotes. The first one is so close to the start of the paragraph that I decided to place it above the paragraph, like a left-justified sub-section heading. That was straightforward. The second one, at the top of page 16, is the problem: it's in the middle of the paragraph and only makes sense if it stays there; moving it to the start of the paragraph (two pages back) destroys its usefulness and actually makes it misleading, since it contains a date.

Well, with today's browsers, this is not a problem: just use CSS and a span to "float" it to one side or the other of the text. That also works with [at least some] devices that use the .epub format, and with the latest Kindles from Amazon (if you're reading this 50 years from now, this stuff must be in your history books if you want to know more about it).

But it does not work at all with the basic, original Kindle, and there are tens of millions of them out there. The text of the sidenotes just appears as part of the regular text, not marked or shaded in any way, except that the text following the sidenote starts on the next line, which looks weird and is hard to read.



A SOLUTION

Here is some CSS and HTML that renders sidenotes perfectly on most devices and quite well on those basic Kindles. Below the code are some commented pictures of the results. Currently at DP, we are using a Project Gutenberg utility program (ebookmaker) that converts our HTML to epub and mobi files, and we include some extra CSS in our HTML just for those "handheld" devices.

This method takes advantage of the Kindle's own limitations: not only is it unable to "float" anything to the side, it also doesn't support the CSS property "visibility: hidden;", so the sidenote text can be surrounded by some unique characters (a vertical bar in these examples), and that bar will be visible on those Kindles, but hidden on almost everything else. The basic Kindle also doesn't support "text-indent: -.2em;", so it won't cover up the bar afterwards, but most other display systems will both hide the bar and move the text of the sidenote to the left, thereby eliminating a first-line indent.

In situations where "float" could work but has been disabled (e.g., a future version of PG's ebookmaker removes it from the @media section), the fallback still works: sidenotes between paragraphs will look like sub-section headers and sidenotes mid-paragraph will be displayed mid-paragraph, in boldface, and shaded/bordered if the device supports those decorations.

NOTE: When this was written, some devices did not have good support for soft hyphens "&shy ;" so the CSS shown below was revised on 2012-12-27 14:00 to make the sidenote widths large enough to accommodate the widest single word in the sample text, thereby avoiding the need for hyphenation.

Main CSS:

.sidenote, .sni {
    text-indent: 0;
    text-align: left;
    min-width: 9em;  /*optional, but making all sidenotes the same width looks better*/
    max-width: 9em;  /*make this just big enough for the widest word in any sidenote */
    padding-bottom: .3em;
    padding-top: .3em;
    padding-left: .3em;
    padding-right: .3em;
    margin-right: 1em;
    float: left;
    clear: left;
    margin-top: 1em;
    margin-bottom: .3em;
    font-size: smaller;
    color: black;
    background-color: #eeeeee;
    border: thin dotted gray;
}
.sni {text-indent: -.2em;}
.hidev {visibility: hidden;}

Secondary CSS in the @media handheld section:

.sidenote, .sni {
   float: left;
   clear: none;
   font-weight: bold;
}

You can change just about all of those values; the last two class definitions in the main section make the results a bit prettier and easier to read. The things that make this work are the highlighting used for in-line sidenotes and the class definition in the Secondary CSS. "float: left;" overrides ebookmaker's attempt to disable floats (on devices that, in fact, support the feature), and "clear: none;" prevents the basic Kindle from starting a new line for the text that follows the sidenote. As mentioned earlier, if the secondary "float" is discarded by a future version of ebookmaker, the sidenotes still will be visually prominent because they are bold, smaller, and/or have a shaded background.

For the HTML, if the sidenote is outside a paragraph and should be on its own lines, use a div:

  ... of unbounded popularity during his
  life, of idolatry after his death.</p>
  <div class="sidenote">Parentage and education.</div>
  <p>The father of Becket, according to
  the distinct words of one contemporary ...

If the sidenote needs to be mid-paragraph, use a span:

  ... office of sheriff, but his fortune
  was injured by fires and other
  casualties. <span class="sni"><span class="hidev">|</span>Born A. D. 
  1118.<span class="hidev">|</span></span>
  The young Becket received
  his earliest education among the monks
  of Merton in Surrey, towards whom he ...

(If you're comparing this to the original image, I deliberately omitted the footnote anchor and the small caps "A. D." for clarity.)

Here's how it'll look in various display devices. For reference purposes, the Browser version is exactly how I wanted it to be:

Browser:

Sidenote-browser.jpg



ePub (simulated by Adobe Digital Editions). Same nice result, including "float" support:

Sidenote-epub.jpg



Kindle Paperwhite and 'Kindle Fire' (using Kindle Previewer). This, too, is what I wanted:

Sidenote-paperwhite.jpg



Kindle-iPad application. Shows the mid-paragraph sidenote in-line and highlighted; it can't show a mid-paragraph sidenote in a cut-out on the left margin, but this method makes it stand out, and in the right place, so it's still useful. The excessively-tall box for the inter-paragraph sidenote apparently is an artifact, and it appears that way on a real iPad as well as in the simulator:

Sidenote-ipad.jpg



Android: Aldiko app, using .ePub version of the sample eBook. Displays them as true sidenotes:

Sidenote-android-Aldiko.jpg




And finally, the original Kindle, which can't show shading or move mid-paragraph sidenotes to the left. But it can use boldface and a slightly smaller font size, and the reason for those vertical bars becomes apparent:

Sidenote-kindle.jpg



People at DP have confirmed that this method works on an actual basic Kindle, Kindle PaperWhite, Kindle for IOS, Nook Tablet v 1.4.3, Sony PRS-900, and the Aldiko app. running under Android 2.3.5.



The Transcriber's notes explain the possible renderings.

Needless to say, comments, suggestions, and improvements to the method will be most welcome.