PPTools/Ppgen/Tutorial/DescriptionLists
Overview
The ppgen .dl directive provides a way for a PPer to easily generate description (or definition) lists, dialog within plays, and ordered lists contained within the book. (Ordered lists generated by the PPer, such as for TNs, should probably use the .ol directive.) The basic documentation for .dl shows how to do simple description lists, which are straightforward and closely mirror the use of <dl>, <dt>, and <dd> in HTML.
This tutorial will demonstrate the use of the .dl directive to handle dialog, such as within plays, and ordered lists.
Dialog
To begin our discussion, you have a choice to make between using style=d (which uses <dl> elements in HTML) or style=p (which uses <p> elements in HTML). W3c initially recommended using <dl> elements to handle both description lists and dialog when they developed the HTML4 specifications. Some users objected to that, I believe on semantic grounds (much as we say not to use tables for data that is not tabular in nature), but it is possible in HTML4, which we use today for our books. However, the semantics of <dl> have changed in HTML5, where the definition of the element states that each term should be defined at most once. That means that, in HTML5, using <dl> for dialog would not work, as each speaker could speak only once. Instead, for HTML5 they suggest using <p> elements instead, with appropriate styling via CSS.
In preparation for HTML5 (which is now accepted by Project Gutenberg and according to Distributed Proofreaders standards), and somewhat in agreement with the semantic arguments, I'll use style=p for the following examples. I've taken them from the Formatting Guidelines and the Library of Formatting Examples.
Example 1
Consider this example from the Formatting Guidelines:
From the rounds, the text you received as the PPer should have been something like this:
THE NICE VALOUR, OR <sc>Act iv</sc> /* Has not his name for nought, he will be trode upon: What says my Printer now? <i>Clow.</i> Here's your last Proof, Sir. You shall have perfect Books now in a twinkling. <i>Lap.</i> These marks are ugly. <i>Clow.</i> He says, Sir, they're proper: Blows should have marks, or else they are nothing worth. <i>La.</i> But why a Peel-crow here? <i>Clow.</i> I told 'em so Sir: A scare-crow had been better. <i>Lap.</i> How slave? look you, Sir, Did not I say, this <i>Whirrit</i>, and this <i>Bob</i>, Should be both <i>Pica Roman</i>. <i>Clow.</i> So said I, Sir, both <i>Picked Romans</i>, And he has made 'em <i>Welch</i> Bills, Indeed I know not what to make on 'em. <i>Lap.</i> Hay-day; a <i>Souse</i>, <i>Italica</i>? <i>Clow.</i> Yes, that may hold, Sir, <i>Souse</i> is a <i>bona roba</i>, so is <i>Flops</i> too. */
You would turn that into the following ppgen source (note the .dl directive and the | added after the speakers' names):
.h2 THE NICE VALOUR, OR <sc>Act iv</sc> Has not his name for nought, he will be trode upon:
What says my Printer now? .dl w=7 tindent=3 style=p collapse=y combine=y break=y hang=n <i>Clow.</i> | Here's your last Proof, Sir. You shall have perfect Books now in a twinkling. <i>Lap.</i>| These marks are ugly. <i>Clow.</i>| He says, Sir, they're proper: Blows should have marks, or else they are nothing worth. <i>La.</i>| But why a Peel-crow here? <i>Clow.</i>| I told 'em so Sir: A scare-crow had been better. <i>Lap.</i>| How slave? look you, Sir, Did not I say, this <i>Whirrit</i>, and this <i>Bob</i>, Should be both Pica Roman. <i>Clow.</i>| So said I, Sir, both <i>Picked Romans</i>, And he has made 'em <i>Welch</i> Bills, Indeed I know not what to make on 'em. <i>Lap.</i>| Hay-day; a <i>Souse</i>, <i>Italica</i>? <i>Clow.</i>| Yes, that may hold, Sir, <i>Souse</i> is a <i>bona roba</i>, so is <i>Flops</i> too. .dl-
Running that through ppgen, you would get this text output:
THE NICE VALOUR, OR ACT IV Has not his name for nought, he will be trode upon: What says my Printer now? _Clow._ Here's your last Proof, Sir. You shall have perfect Books now in a twinkling. _Lap._ These marks are ugly. _Clow._ He says, Sir, they're proper: Blows should have marks, or else they are nothing worth. _La._ But why a Peel-crow here? _Clow._ I told 'em so Sir: A scare-crow had been better. _Lap._ How slave? look you, Sir, Did not I say, this _Whirrit_, and this _Bob_, Should be both Pica Roman. _Clow._ So said I, Sir, both _Picked Romans_, And he has made 'em _Welch_ Bills, Indeed I know not what to make on 'em. _Lap._ Hay-day; a _Souse_, _Italica_? _Clow._ Yes, that may hold, Sir, _Souse_ is a _bona roba_, so is _Flops_ too.
And this is how the HTML would look in a browser:
Example 2
Consider this example from the Formatting Guidelines:
From the rounds, the text you received as the PPer should have been something like this:
/* <sc>Clin.</sc> And do I hold thee, my Antiphila, Thou only wish and comfort of my soul! <sc>Syrus.</sc> In, in, for you have made our good man wait. (<i>Exeunt.</i> */ ACT THE THIRD. <sc>Scene I.</sc> /* <sc>Chrem.</sc> 'Tis now just daybreak.--Why delay I then To call my neighbor forth, and be the first To tell him of his son's return?--The youth, I understand, would fain not have it so. But shall I, when I see this poor old man Afflict himself so grievously, by silence Rob him of such an unexpected joy, When the discov'ry can not hurt the son? No, I'll not do't; but far as in my pow'r Assist the father. As my son, I see, Ministers to th' occasions of his friend, Associated in counsels, rank, and age, So we old men should serve each other too. */ <sc>Scene II.</sc> <i>Enter</i> <sc>Menedemus</sc>. /* <sc>Mene.</sc> (<i>to himself</i>). Sure I'm by nature form'd for misery Beyond the rest of humankind, or else 'Tis a false saying, though a common one, "That time assuages grief." For ev'ry day My sorrow for the absence of my son Grows on my mind: the longer he's away, The more impatiently I wish to see him, The more pine after him. <sc>Chrem.</sc> But he's come forth. (<i>Seeing</i> <sc>Menedemus</sc>.) Yonder he stands. I'll go and speak with him. Good-morrow, neighbor! I have news for you; Such news as you'll be overjoy'd to hear. */
You would turn that into the following ppgen source. Notes:
- I chose to specify the term width (speaker name length) differently for the text output and the HTML, and defined a macro to accomplish that
- The (Exeunt. line is shown right-aligned in the image; I did not handle that, but it could easily be approximated by using protected spaces (\ ) instead of regular spaces. or by dropping it to its own line and putting a .rj directive in front of it.
.dt .dl test from Formatting Guidelines (style=p)
.h1
.dl test from Formatting Guidelines (style=p)
.dm issuedl
.dl combine=y break=y collapse=y hang=n tindent=2 style=p\
.if t
w=5
.if-
.if h
w=7
.if-
.dm-
.de .narrower { padding-left: 10% }
.pm issuedl
<sc>Clin.</sc>| And do I hold thee, my Antiphila,
Thou only wish and comfort of my soul!
<sc>Syrus.</sc>| In, in, for you have made our good man wait. (<i>Exeunt.</i>
.dl-
.sp
.hr 20%
.dv class=narrower
.h2 align=l
ACT THE THIRD.
.h3 align=l
<sc>Scene I.</sc>
.dv-
.pm issuedl
<sc>Chrem.</sc> |'Tis now just daybreak.--Why delay I then
To call my neighbor forth, and be the first
To tell him of his son's return?--The youth,
I understand, would fain not have it so.
But shall I, when I see this poor old man
Afflict himself so grievously, by silence
Rob him of such an unexpected joy,
When the discov'ry can not hurt the son?
No, I'll not do't; but far as in my pow'r
Assist the father. As my son, I see,
Ministers to th' occasions of his friend,
Associated in counsels, rank, and age,
So we old men should serve each other too.
.dl-
.dv class=narrower
.h3 align=l
<sc>Scene II.</sc>
.h4 align=l
<i>Enter</i> <sc>Menedemus</sc>.
.dv-
.pm issuedl
<sc>Mene.</sc>| (<i>to himself</i>). Sure I'm by nature form'd for misery
Beyond the rest of humankind, or else
'Tis a false saying, though a common one,
"That time assuages grief." For ev'ry day
My sorrow for the absence of my son
Grows on my mind: the longer he's away,
The more impatiently I wish to see him,
The more pine after him.
<sc>Chrem.</sc>| But he's come forth. (<i>Seeing</i> <sc>Menedemus</sc>.)
Yonder he stands. I'll go and speak with him.
Good-morrow, neighbor! I have news for you;
Such news as you'll be overjoy'd to hear.
.dl-
Running that through ppgen, you would get this text output Note: The horizontal rules below (in text and HTML) are the wrong length due to a mistake I made when running the examples; I forgot the 20% on the .hr directive, though I showed it above in the example source.
.dl test from Formatting Guidelines (style=p) CLIN. And do I hold thee, my Antiphila, Thou only wish and comfort of my soul! SYRUS. In, in, for you have made our good man wait. (_Exeunt._ ------------------------------------------------------------------------ ACT THE THIRD. SCENE I. CHREM. 'Tis now just daybreak.--Why delay I then To call my neighbor forth, and be the first To tell him of his son's return?--The youth, I understand, would fain not have it so. But shall I, when I see this poor old man Afflict himself so grievously, by silence Rob him of such an unexpected joy, When the discov'ry can not hurt the son? No, I'll not do't; but far as in my pow'r Assist the father. As my son, I see, Ministers to th' occasions of his friend, Associated in counsels, rank, and age, So we old men should serve each other too. SCENE II. _Enter_ MENEDEMUS. MENE. (_to himself_). Sure I'm by nature form'd for misery Beyond the rest of humankind, or else 'Tis a false saying, though a common one, "That time assuages grief." For ev'ry day My sorrow for the absence of my son Grows on my mind: the longer he's away, The more impatiently I wish to see him, The more pine after him. CHREM. But he's come forth. (_Seeing_ MENEDEMUS.) Yonder he stands. I'll go and speak with him. Good-morrow, neighbor! I have news for you; Such news as you'll be overjoy'd to hear.
And this is how the HTML would look in a browser:
Ordered Lists
When your book contains an ordered list, you may get something like the following from the rounds:
/* 1. Item 1 2. Item 2 3. Item 3 ... 9. Item 9 10. Item 10 */
As ppgen has a .ol directive to handle ordered lists, you might be tempted to use something like this in your ppgen source:
.ol style=decimal .it Item 1 .it Item 2 .it Item 3 ... .it Item 9 .it Item 10 */
However, note the extra work you needed to do to make use of .ol: you had to remove the numbers that were already present.
Or, you might have a list like this from the rounds:
/* a) Item 1 b) Item 2 c) Item 3 ... i) Item 9 j) Item 10 */
For that, you might want to try:
.ol style=lower-alpha .it Item 1 .it Item 2 .it Item 3 ... .it Item 9 .it Item 10 */
Again, you had to delete information that was already present. Worse, if you like duplicating the style of the book, HTML doesn't support use of the ")" after the alpha characters. It only allows "." and ppgen will mimic that for the text. So you did extra work, and (if you wanted to) did not duplicate the style of the book.
Using .dl you can avoid both those problems. You could simply use:
.dl align=r w=3 1.| Item 1 2.| Item 2 3.| Item 3 ... 9.| Item 9 10.| Item 10 .dl-
or:
.dl align=r w=2 a)| Item 1 b)| Item 2 c)| Item 3 ... i)| Item 9 j)| Item 10 .dl-
You might want additional options, as well. See the basic .dl documentation for the rest of the options. Also, you might consider using "style=p" if you don't believe that semantically those lists are "description lists".