PPTools/Ppgen/Tutorial/Sidenotes
Overview
Sidenotes are supported without the need to use macros starting with ppgen release 3.47b. They exist in two forms:
- stand-alone, using the new .sn directive;
- contained within something else (paragraph, .nf block, header, table, footnote, etc.) using the new <sn> inline markup tag (and its corresponding end tag, </sn>).
As with drop caps (.dc directive), some experimentation by the PPer will probably be needed to tailor the appearance of the sidenotes and their surrounding text in the HTML. For example, it will be important to choose an appropriate value for the sidenote width, which should be specified based on the length of the longest word in any sidenote in the text. Any necessary tailoring can be done using the .de directive to specify different or additional CSS specifications.
.sn directive
You would use .sn when you have a sidenote that should appear between paragraphs, or outside of all other objects. The format is simply .sn followed on the same line by the complete sidenote text.
Example: .sn Married, 1876
(New in 3.48h) If you have a multi-line sidenote you can use | to separate the lines in .sn.
Example: .sn Kinds of fruit: | Apples | Pears (Note: the blanks around the | characters will be removed.)
<sn>...</sn> inline markup
You would use the inline markup when you have a sidenote within a paragraph, or within a .nf block, header, table cell, footnote, etc. As with other inline markup tags (<i>, <b>, etc.) the sidenote may span lines in your source file when you use the <sn>...</sn> tags.
Format of the <sn> tag:
- Simple form: <sn>Some sidenote text</sn>
- More complex form: <sn class='class-name'>Some sidenote text</sn> where class-name is contained within either single (') or double (") quote marks. By specifying a class name you would be able to tailor some inline sidenotes differently than others, to handle more complex situations.
(New in 3.48h) If the sidenote has multiple lines you can use | to separate them in HTML. In text the | will become blanks.
Example: <sn>Kinds of fruit: | Apples | Pears</sn> (Note: The blanks around the | characters will be removed.)
Notes:
- It is unlikely that inline sidenotes will work well within a .nf block, a table, or a footnote. Ppgen will allow you to specify <sn> in those locations in case you're clever enough to figure out a way to make them work well in both a browser and in epub/mobi through some use of .de or direct modification of the HTML, but we have not found such a method yet. If you have a project that uses real sidenotes in one of those locations, and you find a way to make it work in all cases, please let us know so we can consider implementing it in ppgen.
- <sn> generates an HTML <span>, and so it must be "contained" inside some appropriate HTML object, just as any other span. If you were to put a <sn> in an inappropriate spot (say, between two paragraphs, where you should have used .sn instead) ppgen will not complain, but your HTML file will not validate.
Default CSS for Sidenotes
If your file contains sidenotes ppgen will generate the following CSS in the HTML output file. The .sidenote class applies to the .sn directive, and the .sni class applies to sidenotes created using <sn>. The methodology for this CSS and the HTML that ppgen generates were derived from the Sidenotes article here in the DP Wiki, though some values have been changed. That article will explain several aspects of this CSS (such as the .hidev class) and how they apply both to browsers and epub/mobi.
.sidenote, .sni { text-indent: 0; text-align: left; width: 9em; min-width: 9em;
max-width: 9em; padding-bottom: .1em; padding-top: .1em; padding-left: .3em;
padding-right: .3em; margin-right: 3.5em; float: left; clear: left; margin-top: 0em;
margin-bottom: 0em; font-size: small; color: black; background-color: #eeeeee; "
border: thin dotted gray; font-style: normal; font-weight: normal; font-variant: normal;
letter-spacing: 0em; text-decoration: none; }
.sni { text-indent: -.2em; }
.hidev { visibility: hidden; }")
@media handheld { .sidenote, .sni { float: left; clear: none; font-weight: bold; }}
Tailoring Sidenotes (HTML)
You can use .de to tailor sidenotes. For example, suppose the longest word in any of your sidenotes requires only 5em for proper display, not the 9em that ppgen specifies by default. You could override it by placing this line somewhere in your source file:
.de .sidenote, .sni { width: 5em; min-width: 5em; max-width: 5em; }
You might also want to modify the default margin-right value of 3.5em to something smaller to suit your needs. To do that, in addition to changing the width, you would specify:
.de .sidenote, .sni { width: 5em; min-width: 5em; max-width: 5em; margin-right: 2em;}
You might want all your sidenotes to appear on the right side of the page instead of the left. You could do that by specifying:
.de .sidenote, .sni { margin-left: 1em; margin-right: 0; float: right; clear: right; }
Of course, you could also add the various width specifications to that .de to adjust the overall width of the sidenotes to suit your needs.
If you had one particular kind of sidenote, perhaps generated by <sn>...</sn>, which needed different tailoring, you could do something like the following:
Here is some normal text <sn class='myclass'>Sidenote which needs odd characteristics</sn> perhaps in a paragraph.
.de .myclass { your CSS overrides for that kind of sidenote }
You could also do that if you have some sidenotes that you want on the left and others on the right. Just use a class to specify which you want for each sidenote.
Note: The .sn directive does not support a class= operand as <sn> does. If you need to tailor a specific sidenote generated using .sn you could do it as follows:
.dv class="myclass"
.sn Sidenote Text
.dv-
.de .myclass { your CSS overrides for that kind of sidenote }
Tailoring Sidenotes (Text)
In a text output file sidenotes will appear in one of the following two ways:
From .sn:
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed doeiusmod tempor incididunt ut labore et dolore magna aliqua. [Sidenote: sidenote text] Ut enimad minim veniam, quis nostrud exercitation ullamco laboris nisi ...
From <sn>:
Lorem ipsum dolor sit amet, consectetur adipisicing elit, [Sidenote: sidenote text] sed doeiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enimad minim veniam, quis nostrud exercitation ullamco laboris nisi consequat. ...
(Of course, neither would be bold.)
You can use the Sidenote named register to change the word Sidenote to something else if you want. For example:
.nr Sidenote Sn
Leaving the sidenotes within the text (where you placed the <sn> tag), helps avoid problems the reader might have in understanding the context of the sidenote if it were moved to a different spot. However, if you do not want the sidenotes in the middle of the paragraph, you can make use of .if to place them separately for the text and HTML.
Example:
.if t // put the sidenote before the paragraph in the text version .sn sidenote text .if - Lorem ipsum dolor sit amet, consectetur adipisicing elit, .if h // but put it at the proper spot in the paragraph for HTML <sn>sidenote text</sn> .if- sed doeiusmod tempor incididunt ut labore et dolore magna aliqua.
You might use macros to simplify that, if you choose that style of sidenote processing:
.dm snt $1 .if t .sn $1 .if- .dm- .dm snh $1 .if h <sn>$1</sn> .if- .dm-
Then code your text as:
.pm snt "sidenote text" Lorem ipsum dolor sit amet, consectetur adipisicing elit, .pm snh "sidenote text" sed doeiusmod tempor incididunt ut labore et dolore magna aliqua.