PPTools/Ppgen/Manual

From DPWiki
< PPTools‎ | Ppgen
Jump to: navigation, search

Contents

Ppgen User's Manual

Installation

Instructions for installing PPGEN are here.

Function

Ppgen takes a single source file using simple markup and generates up to three output files: an HTML file, a UTF-8 text file and optionally a Latin-1 text file. The source file may be encoded in Latin-1, but the suggested workflow is for it to be encoded in UTF-8. The generation of a Latin-1 file is provided for legacy requirements and software, but only when the PPer explicitly requests it using the "-ol" command line parameter.

When producing text output files (UTF-8 or Latin-1) ppgen will by default assume a line length of 72, though you can adjust that with the .ll directive. During processing, ppgen will attempt to wrap non-table text as necessary to fit within the specified line length. When wrapping text for any purpose (paragraphs, headers, illustration captions, text within table cells, etc.) ppgen will break the text at blanks if possible. For non-table cases it will try to keep the minimum line length above 55 to meet PG and DP requirements. For less common cases such as long--chapter--summaries--with--words--or--phrases--strung--together--with--em-dashes you can also allow ppgen (3.50d or later) to break in additional places (hyphens, em-dashes) if necessary. For information on that see the "Named Registers" (.nr) section below, specifically the break-wrap-at register. Also, if you have a need to break text at a specific location within wrappable text you can insert <br> at the break point (ppgen 3.50c or later).

Starting with ppgen version 3.42 ppgen will optionally create a Guiguts- and PPQTv1-compatible .bin (metadata) file for each output file. The PPer can provide those files to PPV along with the main output files in case the PPVer wants to make use of Guiguts or PPQT while PPVing. The .bin file associated with an output file would be used by a Guiguts or PPQT user who has also downloaded the proofing images (.png files) for the project. The user can then easily view the original proofing image associated with any line of the output file (except moved footnotes) while checking the project. This may also prove useful for PPers who make use of Guiguts or PPQT as part of their workflow. As some PPVers strongly prefer to have .bin files available, we recommend that PPers who use ppgen and upload for PPV follow the setup steps to enable ppgen to create the files for their projects. For more information on this, see .bin files.

Ppgen is a command line program written in Python 3. It is invoked with a command of this form:

python3 ppgen.py -i filename-src.txt

That will generate all formats from the single source file. For Windows users, a batch file is recommended allowing generation of all outputs with a mouse click.

Advanced ppgen users may want to provide an additional input file that overrides various ppgen functions. This can be done by providing a file named "ppgen.ini" in the directory that contains ppgen or in your project working directory. The name of the file can be adjusted if needed by using the "-ini" option described below. For more detail on the structure and content of that file see ppgen.ini file

Frequently used command line options for ppgen

  • -i specifies the input source file name, which must end with "-src.txt". The source file for a book named "Midnight in December" might be called "midnight-src.txt".
  • -o specifies the output formats to be generated. The default is "hu" (e.g., -ohu) which specifies that the HTML and a UTF-8 text file should be produced. Valid characters to follow the -o are:
    • t - produce the Latin-1 version and (if the source file is encoded in UTF-8) produce the UTF-8 version.
    • l - produce the Latin-1 version but do not produce UTF-8 unless u is also specified.
    • u - produce the UTF-8 version but do not produce the Latin-1 version unless l is also specified. Note that PG no longer requires submission of a Latin-1 version.
    • h - produce the HTML version

Consider these equivalent commands:

python3 ppgen.py -i midnight-src.txt
python3 ppgen.py -i midnight-src.txt -ohu

If either is used to invoke ppgen, the output files generated will be:

midnight.html: XHTML 1.0 Strict, UTF-8 encoded
midnight-utf8.txt: UTF-8 Unicode English text, with CRLF line terminators (only produced if midnight-src.txt is encoded in UTF-8)

The HTML file is compatible with ebookmaker. Specify "UTF-8" as the encoding if passing the HTML file to ebookmaker.

Note: See the Map UTF-8 characters to Latin-1 section for an explanation of the UTF-8 to Latin-1 conversion mapping.

Less-frequently used command line options for ppgen

  • -cvg will produce an output file named ppgen-cvglist.txt which shows the built-in diacritic and Greek characters that ppgen supports. Processing will then terminate.
  • -f <filter-file-name> tells ppgen to load filter-file-name and include it ahead of the input file specified by -i. This will typically be used by a user of some other PPing tool such as Guiguts who wants some ppgen-specific processing run on their file, such as diacritic or Greek conversion. The filter file in that case would contain .cv and/or .gk directives. During filtering ppgen will apply the supplied .cv or .gk directives as well as any .sr directives with the "f" option to the input file. Ppgen will produce an output file named <input-file>-cvgout-utf8.txt and will terminate.
  • -h provides help information about the command line options
  • -img provides a detailed report of file issues in the images directory (files which are not referenced, file names with incorrect suffixes, files which are used multiple times).
  • -ini tells ppgen to use an alternate version of the ppgen.ini option file. For example, ppgen normally uses the file named ppgen.ini if it is present. You can tell it to use ppgen-alt.ini by specifying "-ini alt" on the ppgen command line. (Note the hyphen in the file name.) You can also tell ppgen not to use any .ini file by specifying "-ini none".
  • -l Produces a log of UTF-8 to Latin-1 conversions, diacritic conversions, and Greek conversions
  • -mus (new with ppgen 3.56h) provides a detailed report of file issues in the music directory (files which are not referenced, file names with incorrect suffixes, files which are used multiple times).
  • -pmok tells ppgen that it's OK to run macros written in Python without prompting the user for permission.
  • -ppqt2 tells ppgen to create a .ppqt file (PPQT2 version of a .bin file) for any .bin file that it creates. That will allow PPQT2 users to easily locate the image for any source line (again, this won't work for footnotes if you've physically moved them)
  • -sbin will cause ppgen to produce a .bin file for the source file itself, using the .bn directives contained within the source file. This will allow you to open the source file with Guiguts and locate the image corresponding to the source. Note: This won't work to let you view footnotes if you've moved them from their original physical locations.

Rarely used command line options for ppgen

  • -d supports various debugging flags, and would be used as -d flags or -dflags
    • a - prints some of the lines during processing to help determine roughly where an error is happening
    • d - produces additional diagnostic information for some situations
    • e - forces all messages to stderr, even informational ones (Note: this is primarily intended to help the developers perform regression testing of ppgen.)
    • l - produces additional information during Greek processing
    • m - provides additional debugging info during .pm/<pm> processing (new with ppgen 3.56c)
    • p - prints information about the platform that ppgen is running on
    • r - produces additional information during .sr operations
    • s - tells ppgen to keep the "style=" information in the HTML rather than replacing it with generated CSS. (Note: this is primarily intended to help the developers perform regression testing of ppgen.)
    • x - tells ppgen to use the "title" form of page numbers rather than the "content" form, regardless of the setting of the setting of the ".nr pnstyle" register. (Note: this is primarily intended to help the developers perform regression testing of ppgen. Users should use .nr pnstyle if they want to change the page numbering style.)
  • -v will cause ppgen to terminate after printing the version information

Overview

Input File

The ppgen input file is a text file with a name that should end with -src.txt to help distinguish its purpose among the other project-related files you will have. Within the file you will have the text as produced by the DP proofreaders and marked-up by the DP formatters. That text is not directly ready to use with ppgen, however, as ppgen requires its own markup (commands, or "dot" directives) for certain functions. For some examples:

  1. Chapter headers will come to you with 4 blank lines before them. You can leave the blank lines or remove them, but you need to have a ".h2" directive on the line before the chapter header so ppgen knows what it is.
  2. Poems within a DP project will generally come to you with /* on a line just before it and */ just after it. You would usually change those to ".nf l" and ".nf-" respectively.

There are many other cases where you will locate DP-style structural markup ("out of line", in DP terms) and convert it for ppgen purposes. The inline markup (<i>, etc.) will generally be OK, but you may find situations where you will want to add more (e.g., to mark text in different languages).

When working with your file, if you find that lines are becoming wider than you prefer, and perhaps hard to edit, you may break them at any space character, and replace the space with a "\" character as the final character on the line. During processing ppgen will reassemble the lines, removing the "\", replacing it with a blank, and joining it to the next line.

ppgen commands (aka dot directives)

Commands available within ppgen generator. These are referred to as "dot commands" since they begin with a dot as the first character on the line.


List of Dot Commands
& Their Main Documentation
Code Name Section where found
.ad adjust Turn text justification back on
.bn Guiguts/PPQT .bin file info Guiguts- or PPQT-compatible .bin Files
.ca Caption Illustrations: Captions
.ce Center Entry Centering text
.ci Cover Image Cover Image
.cm Caption Model Configure Multi-line text captions (ppgen version 3.44c and later)
.cv Convert diacritics (version 3.46j or later) See Diacritics and the ppgen Diacritics Tutorial.
.dc Drop Caps Drop Caps (Letters)
.dd Part of Dialog or Definition Lists Dialog and Definition Lists (3.53c or later)
.de Define CSS Defining Custom CSS
.di Drop Cap Image Drop Caps (Images)
.dl Dialog or Definition Lists Dialog and Definition Lists (3.53c or later)
.dm Define Macro Macros
.dt (Outside a .dl block) Sets a temporary title for the HTML version Special Situations
.dt (Within a .dl block) Part of Dialog or Definition List Dialog and Definition Lists (3.53c or later)
.dv Division (HTML) Division (HTML)
.fm Footnote marker Footnotes
.fn Footnote Footnotes
.fs Font size Font Size
.gk Greek Transcription (version 3.46j or later) See Greek and the ppgen Greek Tutorial.
.gl Greek (Latin-1) Greek
.gu Greek (Unicode) Greek
.h1 Main heading Headings
.h2 Chapters, etc. Headings
.h3 Sections, etc. Headings
.h4 Sections, etc. Headings
.h5 Sections, etc. Headings
.h6 Sections, etc. Headings
.hr horizontal rule Horizontal Rules
.if Conditional Conditionals
.ig Ignore Comments
.il Illustrations Illustrations
.in Indentation Indents
.it List Item (Version 3.53b or later) Lists
.ix Indexes Indexes
.li Literal Literal Code
.ll Line length Line Length
.ma Map characters Map UTF-8 characters to Latin-1
.na No adjust Text Justification
.nf No-Fill No-Fill Blocks
.ni no indent for ¶s Paragraph Formatting
.nr Set Named Register Named Registers
.ol Ordered Lists (Version 3.53b or later) Lists (Ordered and Unordered)
.pb Page Break Page Breaks
.pi Paragraph indentation on Paragraph Formatting
.pm Play a macro Macros
.pn Page number Page Numbering
.rj Right justify No-Fill Blocks & Text Justification
.sn Sidenote (New in 3.47b) See Sidenotes and Sidenotes tutorial.
.sp spacing, vertical Vertical spacing
.sr Search/Replace (New in version 3.46b) See tutorial.
.ta Table Tables
.tb Thought Break Thought Breaks
.ti Temporary Indent Temporary Indent
.ul Unordered Lists (Version 3.53b or later) Lists (Ordered and Unordered)

Guiguts- or PPQT-compatible .bin Files

The .bn command allows the PPer to tell ppgen to create metadata (.bin) files that are compatible with those used by Guiguts and PPQT. For more information on the usage of this command see .bin files.

Format:

 .bn <name>.png where <name>.png is a proofing image name, typically something like 001.png or possibly p005a.png

Centering Text

The .ce directive centers the next line of text. An optional count can center more lines. For blocks of text, the .nf c directive is recommended, but the .ce command is still supported and may be used if you wish. It is especially helpful for small blocks (1, or 2 lines). Note! .nf c and closing with .nf- are recommended.

.ce     center next line
.ce 4   centers the next four lines

Conditionals

Sometimes the user faces an unusual construction that cannot be easily coded with ppgen's dot commands. For this, escape out to separate, literal code in text and HTML.

Here's something that would only appear in HTML versions:

 .if h
 .li
 <div style='text-align:center; margin:1em auto;'>
 <img src='images/illus-emb.png' alt= style='width:50px;height:60px;'/>
 </div>
 .li-
 .if-

Note that the opening tag with '-' appended ends the scope of that block element. Here's another example, one way in HTML, another in text:

 .if h
 .de .imgleft { clear:left; float:left; margin:4% 4% 4% 0; }
 .de @media handheld {.imgleft { float:left; }}
 .li
 <div class='imgleft' style='width:20%'>
 <img src='images/illus-ad1.png' alt= style='width:100%' />
 </div>
 .li-
 .if-
 .if t
 [Illustration: small image of book cover]
 .if-

Comments

Comments may be used to document your source code. Anything in a comment is ignored by ppgen.

Form 1, using '//' to comment from there to end of line

 // ppgen source for The Way to the West, by Emerson Hough 
 // last edit: 23-May-2014 

or

 .h1             // every source file needs exactly one of these 
 header text

Note: If you need the string // in your output file, you must "escape" one or both of the slashes using the \ character.

Example:
   Here is a url that won't work: http://some.url
becomes:
   Here is a url that won't work: http:

   Here is a url that will work: http:/\/some.url
becomes
   Here is a url that will work: http://some.url


Form 2, using the .ig (ignore) dot directive:

 .ig ppgen will ignore this single line

or

 .ig
 ppgen will ignore this 
 block of lines
 .ig-

Cover Image

A cover image is required. If you name the cover image "cover.jpg" and place it in the images folder, you do not need to do anything in the source code. If for some reason you want to use a cover with a different name, you can specify it with the ".ci" directive ("cover image"):

 .ci alt-cover.jpg

Provide the filename only and place the image in the images folder.

Defining Custom CSS

You can use the .de command to define custom CSS for your HTML files. The format of the command is:

 .de <text>
   where the <text> is any valid CSS statement

Examples:

 .de .myclass { CSS parameters here }
 .de @media handheld {.myclass { CSS parameters for handheld devices here }}

For ease of reading/editing, you can continue .de commands across multiple lines by ending each line with a \ character:

 .de .myclass { \
        some of the CSS parameters \
        more of the CSS parameters \
        }

Note: .de commands are ignored while processing the text output files; you do not need to put ".if h / .if-" around them.

Diacritics

Sometimes our projects contain characters that cannot be represented in the Latin-1 character set we normally use, and which the proofreaders must "encode" in a form that we can represent in Latin-1. For example, if the book contains the character ā ("a" with a macron over it) the proofreaders will provide it to you as

 [=a]

The Proofreading Guidelines for Characters with Diacritical Marks provides full details of this style of encoding.

Starting with version 3.46j ppgen can convert most of these characters to the proper Unicode (UTF-8) characters automatically, if you enable this processing using the .cv command. Without this automatic processing you would need to find and convert each character individually. Ppgen also allows you to supply your own diacritic definitions in case your book uses a character that ppgen does not know about, or in case the proofreaders have used some unusual encoding for a character that ppgen does understand.

For full details see the ppgen tutorial on Diacritics.

Dialog and Description (or Definition) Lists

ppgen 3.53c (or later) provides a new directive, .dl, to allow the PPer to produce definition (description) lists (see the bottom of this w3schools page for a brief description of <dl> and it's associated tags). The w3c also recommended use of <dl> for marking up dialogs in HTML4, though there was some disagreement with that and the recommendation has changed in HTML5. For now, ppgen by default follows the earlier recommendation (i.e., style=d is the default) but if you'd like to follow the newer recommendation, or if you believe more in using an HTML element for its "intended" semantic purpose, then you can easily specify style=p for those cases that are not truly definition lists, and ppgen will generate the HTML using <p> elements instead of <dl> elements.

Note: This documentation may refer to definition lists or description lists; please consider them the same thing.

Considering description lists (as opposed to dialog) for the moment, one simple example from w3schools is this one:

<dl>
  <dt>Coffee</dt>
  <dd>Black hot drink</dd>
  <dt>Milk</dt>
  <dd>White cold drink</dd>
</dl>

which produces roughly this in the browser:

Coffee
    Black hot drink

Milk
    White cold drink 

To produce that with ppgen you could use:

.dl float=n
.dt Coffee
.dd Black hot drink
.dt Milk
.dd White cold drink
.dl-

As an alternative you can also use the simpler form:

.dl float=n
Coffee | Black hot drink
Milk | White cold drink
.dl-

Perhaps you would prefer to see the descriptions shifted further to the right, to give:

Coffee 
       Black hot drink

Milk
       White cold drink 

To accomplish that you could leave everything the same except for adding the w= (width) parameter on .dl, as

.dl w=7 float=n

which should give you the new result.

Or, perhaps you would prefer it in this form:

Coffee  Black hot drink

Milk    White cold drink 

For that, you would use the "float=y" option, with everything else the same:

.dl w=7 float=y  (note: float is the default, so that could be just .dl w=7)


Notes:

  1. ppgen supports most other dot directives within a .dl block, too. So if you want to have a table or a poem inside the block you can do that.

Options on .dl

The .dl directive has the following optional parameters:

align=l (default) or r specifies whether the term should be left-aligned or right-aligned in its space.

break=n (default) or y specifies, when combine=y, whether line breaks should be maintained as they were in the source file (y) or whether the text should wrap freely (n).

class=classname (example: class=dlclass) Default: none. Specifies, for HTML output, a class name that you can use as a CSS selector when tailoring the appearance of the definition list or a set of compatible definition lists. If multiple lists use the same class name, but have incompatible CSS characteristics, ppgen will issue a warning message.

collapse=n (default) or y specifies (if y) that wrapped lines of the definition should appear at the left margin, under the term.

combine=n (default) or y specifies (if y) that successive definition entries that do not specify a new term should be combined into a paragraph and wrapped.

dindent=a number (example: dindent=3) Default value: 0. Specifies an added indentation placed to the left of the definition value.

float=y (default) or n. Specifies whether the definition is floated to the same line as the term or placed below it.

hang=y or n specifies (when style=d) whether wrapped lines (when combine=n) are displayed with a hanging indent or not. Style=p supports only hang=n.

id=idvalue (example: id=id1) Default: none. Specifies, for HTML output, an id value that you can use as a CSS selector when tailoring the appearance of the definition list, or that you can use as the reference in a #id:referencing text# construct.

style=d (default) or p. When style=d, the generated HTML will use <dl>, <dt>, and <dd>. When style=p the generated HTML will use <p> elements.

tindent=a number (example: tindent=3) Default value: 0. This specifies an added indentation placed before (to the left of) the term that is being defined, in characters.

w=number (example: w=7). Default value: 10. This specifies the width (in characters) of the longest term in the list, and is used to properly align the display of the definitions with the display of the terms. Ignored in HTML output processing except for .dl with style=paragraph specified.

Each .dl block must end with a .dl- directive. There are no options on the .dl- directive.

Content of the .dl block

A .dl block contains definition (or description) lines (or dialog, as we will see elsewhere). By default, every line between .dl and .dl- represents one entry in the list. Thus, the following represents a list with 3 items and definitions (or descriptions):

 .dl
 item1 | description 1
 item2 | description 2
 item3 | description 3
 .dl-

The word(s) before the "|" provide the term being described (or the speaker for dialog), while the word(s) after the "|" provide the description of the term (or what the speaker said). Definition lines may have several formats:

form a, which specifies only a term (no description will appear):
 term |
form b1, which specifies both the term and definition:
 term | description
form b2, which specifies a "null" term, and a description:
 | description
form c, which like form b2, specifies a "null" term and provides only a description. See notes below regarding leading blanks:
 description
.dt term  
   This provides the term for a following .dd, and operates like form a unless it is immediately
   followed by a .dd whose description text does not start with "|". In that case the .dt and .dd are combined and processed as in form b1.
.dd class=classname description
   (where class=classname is optional) Provides the description for a preceding .dt directive. If the .dd is not immediately preceded by a .dt, or if the description
   text starts with a "|", it operates like a line of form b2. Otherwise, the .dt and .dd are combined and processed as in form b1.
   This allows the specification of a class name to use in CSS selectors to tailor the appearance of this particular description in the HTML output.
   The class= specification is ignored in text processing.
A blank line. The first blank line will separate definitions, and will appear in the output. If additional blank lines are needed use the .sp directive.
Some other dot directive, which will be processed

Any of those line formats (except other dot directives) may be continued to another line by putting a \ character at the end. Therefore the following is a list with only 2 items:

 .dl
 item 1 | A long description\
 for item 1
 item 2 | description 2
 .dl-

Notes:

  1. For definition lines of forms b1 or b2, 1 blank following the | will be ignored. Additional blanks are significant and will be kept.
  2. For definition lines of form c, with style=d all leading blanks are significant and will be kept. With style=p all leading blanks will be removed.
  3. When using style=p, a definition line of form c that follows a definition line of form b1 or b2 will be concatenated to the prior line, just as though the prior line ended with a \ character. That will also happen with style=d if combine=y is specified.

Using .dl for Dialog

See examples here.

Using .dl for Ordered Lists

See examples here.

Division (HTML)

 Syntax: .dv class="classname" fs=<font-size-specification>
             (or class="classname1 classname2 ...") (Note: you may use either " or ' around the classnames)
         other ppgen source statements
         .dv-

Notes:

  1. If you have only a single classname you may omit the quote marks if you have ppgen 3.54d or later.
  2. fs=<font-size-specification> is new with ppgen 3.54n. You may specify any value acceptable to the .fs directive (e.g., fs=80%, fs=2.0em), and that font size will apply to the entire contents of the .dv block. When the block ends the font-size will be the same as it was before the .dv directive.
  3. All parameters are optionsl. You may specify class, or fs, or both, or neither.

This directive allows you to create an HTML <div> to surround an item in the HTML output. The usual reason for doing this is to allow the specification of a .de directive to override the display characteristics of a specific item for which ppgen does not provide the "id=" parameter.

For example, ppgen provides id= on .h2, so if you wanted to change the appearance of one particular .h2 item in your book you could code:

 .h2 id="chap2"
 Header for chapter 2
 .de #chap2 {CSS override parameters here}

However, ppgen does not provide id= on .hr, so you need some other mechanism if you want to, for example, change the thickness of one particular horizontal rule in your book. You could do it using ".if h" and ".li" to supply the HTML yourself, but the .dv directive provides a simpler way.

Example 1: Suppose you have one particular horizontal rule that should have a thickness of 3px rather than the default 1px that ppgen specifies. Here's one way to do it:

 .dv class="hr3px"
 .hr 
 .dv-
 
 .de .hr3px {border-bottom:3px}

The .dv/.dv- will surround the <hr> that ppgen generates with <div class='hr3px'> and </div>, allowing your CSS definition to affect the appearance of the horizontal rule.


Example 2: Special Situations item 3 (below) shows one method to create a transcriber's note at the front of your book documenting that you've added a cover image of your own.

 Without using .dv this requires:
  .if h
  .de div.tnotes { padding-left:1em;padding-right:1em;background-color:#E3E4FA;border:1px solid silver; margin:2em 10% 0 10%; }
  .de .covernote { visibility: hidden; display: none; }
  .de div.tnotes p { text-align:left; }
  .de @media handheld { .covernote { visibility: visible; display: block;} }
  .li
  <div class="tnotes covernote">
    <p><b>Transcriber's Note:</b></p>
    <p>The cover image was created by the transcriber and is placed in the public domain.</p>
  </div>

 Using .dv you can remove some of the explicit HTML, simplifying that to:
  .if h
  .de div.tnotes { padding-left:1em;padding-right:1em;background-color:#E3E4FA;border:1px solid silver; margin:2em 10% 0 10%; }
  .de .covernote { visibility: hidden; display: none; }
  .de div.tnotes p { text-align:left; }
  .de @media handheld { .covernote { visibility: visible; display: block;} }
  .dv class="tnotes covernote"
  <b>Transcriber's Note:</b>

  The cover image was created by the transcriber and is placed in the public domain.
  .dv-
  .if-

Example 3: Suppose you want a block of text that is 80% of the normal font size. You have several choices.

 // approach 1a
 .fs 80%
 Text
 Text
 .fs- (or .fs 100%)

or

 // approach 1b (starting with ppgen 3.54n)
 .fs push
 .fs 80%
 Text
 Text
 .fs-


or

 // approach 2
 .de .fs80 {font-size: 80%; }
 .dv class='fs80'
 Text
 Text
 .dv-

or (starting with ppgen 3.54n)

 // approach 3
 .dv fs=80%
 Text
 Text
 .dv-

Approach 1a has the disadvantage that you need a .fs before the text and after, and you need to know what the size was before the ".fs 80%" if you want to restore it to the original size at the end of the text block. Approach 1b simplifies that by "pushing" the current value (whatever it may be) onto a stack and restoring it at the end of the block. However, it requires 3 .fs directives overall. Both approach 1a and 1b do not apply to everything you might use. In particular, they do not apply to tables.

Approach 2 has the advantage that it will apply to everything inside the .dv (including tables) but it requires use of .de to define the CSS.

Approach 3 requires the least coding on your part. No .de is needed, and the font size change applies to everything within the .dv as in approach 2.

Drop Caps (Letters)

Drop caps using a single capital letter.

 .dc 0.4 0.4
 Switzerland, to be seen aright, must be entered from
 Germany. Many travellers rush from Paris to Geneva, and
 beginning with Chamouni and Mont Blanc come down...

This puts the first letter of the paragraph following the .dc command as a large capital letter at the start of the paragraph. The first parameter (0.4 in this example) moves the first line of text after the drop cap to the left by as many ems are specified. The second parameter (also 0.4 in this example) moves the drop cap up or down relative to the other text on the line. You will need to experiment with these parameters to get the effect you want.

The named register "dcs" may be used to customize the font size used for the drop cap.

See this page for some examples of different .dc parameter settings.

Notes:

  1. Firefox bug: At this time it seems that Firefox ignores the second parameter of the .dc command. I recommend testing your drop caps with both Firefox and another browser to see the effect your users may see when reading the HTML version of your book.
  2. Firefox bug (affects versions of ppgen < 3.40): If you end up with a page number on the same line as a drop cap Firefox ignores the drop-cap specification and shows a normal letter instead.
  3. Drop caps do not work in .nf blocks, only in paragraph text.

Drop Caps (Images)

Drop caps using an illustration:

 .di i_b_009.jpg 100 170 1.1
 SWITZERLAND, to be seen aright, must be entered from
 Germany. Many travellers rush from Paris to Geneva, and
 beginning with Chamouni and Mont Blanc come down...

That first line means

 .di  drop-cap illustration
 i_b_009.jpg  the name of the illustration in the images folder
 100  the image width in pixels
 170  the image height in pixels
 1.1  empirical adjustment depending on letter width 
       (smaller moves first line of text right, larger moves left)

That's all the PP needs to put in. That one line generates a ton of CSS and the correct HTML at the drop-cap per the Easy Epub guidelines.

Starting with ppgen version 3.43 the .di command has two formats, one with 4 operands and one with 3.

Original (4 operand) format: 
   .di filename width height adjustment
New (3 operand) format: 
   .di filename width adjustment

Note: ppgen's illustrated drop caps uses a CSS3 property, explicitly permitted at Project Gutenberg, but its use must be mentioned in the upload. When run, ppgen issues this:

 **warning: CSS3 drop-cap. Please note in upload.

to remind you.

Additional Notes:

  1. Drop caps do not work in .nf blocks, only in paragraph text.

Em-dashes

In UTF-8 Projects

When a PPer selects a project from the PP pool, any em-dashes in the project will be represented by "--" as DP has us proof them. For a UTF-8 project you should manually change those to a UTF-8 emdash, "—", using the appropriate search/replace commands in the editor you're using.

When ppgen generates its output files, it will use "—" for the em-dashes in the utf8.txt file and the .html file. For the lat1.txt file ppgen will convert the em-dashes back to "--".

In Latin-1 Projects

(Note: The following applies to source files encoded in Latin-1 (iso-8859-1) rather than UTF-8. However, it also applies to source files encoded in UTF-8, and saved without a BOM, that contain only Latin-1 characters as such source files will appear to be Latin-1 when ppgen examines them.)

Handling is different if you keep your project file in Latin-1, rather than UTF-8. In that case your em-dashes will remain "--" in the project file. Ppgen will produce a lat1.txt file and a .html file, but no utf8.txt file. In the lat1.txt file all the em-dashes will remain as "--", but things are more complicated for the .html output file.

In the .html file, by default, ppgen will convert each "--" to "&mdash;" (the HTML entity for an em-dash), which will render in the browser as "—".

If you have two em-dashes in a row, "----" (a DP "long-dash), the .html file will contain "&mdash;&mdash;" and the browser will display "——".

Sometimes you may have a longer string of hyphens in your project. If that string of hyphens has an even length (6, 8, ...) you'll simply get a string of several "&mdash;" in the .html file. However, for an odd-length string of hyphens (3, 5, 7, etc.) you'll get several "&mdash;" followed by the remaining single hyphen. So, for example, given a string of 5 hyphens, "-----", ppgen will convert it in the .html file to "&mdash;&mdash;-" which will display as "——-".

Depending on the font used, there might be visual difference between the "—" characters and the "-" character above, perhaps in apparent density (blackness) or perhaps height. There might also be a small gap between the two characters. You may not want that, and may decide you would rather have a string of hyphens rather than a mixture of em-dashes and hyphens. In that case, you can escape the hyphens using the \ character.

 Example:
   ----- in your Latin-1-encoded file will display ——-
 but
   \-\-\-\-\- will display as -----

Font Size (HTML)

Note: Affects HTML output only; ignored for text processing.

Font sizes can be changed for subsequent text with the ".fs" command. The .fs command also affects text controlled by .rj, .ce, and .nf blocks, as well as paragraphs and .nf blocks within footnotes. Starting with 3.54m/n ".fs" also reliably adjusts the size of text and other content within lists (.ul, .ol, .dl) and divs (.dv) and should more reliably affect the content of footnotes in a variety of situations.

Syntax:

 .fs <value> where value can be a numeric percentage (e.g., 80%) or a relative size in em units (e.g.,  2.0em)
or
 .fs push (available starting in ppgen 3.54n)
or
 .fs

If a value is specified, that value affects text (paragraphs, .nf blocks) not contained within other ppgen blocks or contained within footnotes. Starting with 3.54m/n the content of lists (.ul/.ol/.dl) and divs (.dv) are also affected, and additional elements such as tables within footnotes are affected.

If "push" is specified, ppgen saves (stacks) the current font-size so that it can easily be restored later using ".fs" without a value. This can be especially useful for statements generated by macros, since the writer of a macro may not be able to predice the font size before the macro was issued. The macro could issue ".fs push" and then make font adjustments, generate the rest of its data, and at the end issue ".fs".

If ".fs" is issued without a value, and there is no prior font-size stacked (via ".fs push") then ppgen will set the font size to 100% of the current base value (font size of the containing HTML element). If there is a value stacked, ppgen will set the font-size to that value and remove it from the stack. (Prior to ppgen 3.54n ".fs" without a value always sets the size to 100%.)

Font size specification is relative to the size of the font in the containing HTML element. For example, a normal paragraph's font size is the same size as the outer <body> element of the HTML document produced by ppgen. This is to be compatible with base font scaling in mobile devices. Example:

.fs 80%
“This book will be hailed with delight by all girls who have a mechanical
turn.”—<i>Watchman-Examiner.</i>
“Girls will love just such a book and will find interest for every day of
the year in it.”—<i>St. Louis Globe-Democrat.</i>
.fs 100%   (or, simply, .fs)

Starting with ppgen 3.54n the font-size in effect at the beginning of a .dv, .ol/.ul/.dl, or .fn block will affect all other elements contained in the block. ppgen will supply the current font-size as part of the <div> that starts the block. For example, if the font-size at the start of a .dv is 80%, then ppgen will generate <div style='font-size: 80%'> (with the style converted to a class specification). It will then affect all of the content of that division.

The following two notes apply to ppgen 3.54n and later:

  1. Font size changes specified in % and em (all that ppgen can allow) are relative to the base size of the containing element (e.g., for a .dv the containing element is the outer <body> element, unless the .dv is contained inside something else (another .dv, a footnote, or a list). Thus, for the usual case, if the font size specification is 80% at the beginning of a .dv that means 80% of the font size of the <body> element that contains it. If, within the .dv, you were to specify ".fs 80%" again, the subsequent text would have a font-size of 80% of 80% of the <body> size, or 64%. However, if you do not make further adjustments of the font size within a container then everything should work simply and as you would expect.
  2. Font size changes within .fn, .dv, .ul/ol/dl blocks are entirely self-contained, and have no effect on text that follows the block closing. After the block is closed the font-size and font-size stack are the same as before the block was opened. Thus, you can freely change the font size within the block without affecting text outside of the block, and you do not need to restore the font size before ending the block.

Font sizes can also be changed for shorter spans of text using the various inline markup tags (<s>, <l>, etc.) and (starting in ppgen 3.54n) using the fs= operand on the .dv directive

Note that font size changes specified by the inline markup apply a font size change as a span and not a class. Applied as a span, line spacing in paragraphs does not change. As a class, it does, so inline changes should use the inline form (<s>, etc.) while paragraph and higher-level changes should use the ".fs" directive or the fs= operand on a .dv directive.

Footnotes

Note: Version 3.48c of ppgen introduced a new style of using the .fm and .fn commands that you may find more convenient and simpler to use. The footnote tutorial has full details, but basically the enhancements allow you to keep one copy of each footnotes in your source file, on the page where each appears in the book, but have them output in separate locations in the text and HTML outputs. For example, you might have the footnotes output at the ends of chapters or paragraphs in the text but at the end of the book for HTML, all based on where you place the .fm directives and which options you choose on them.

For simplicity, the following describes the original ppgen footnote support with a few minor enhancements (such as non-numeric footnote labels) but does not describe that new mode of operation, which is what I would recommend using. Note that whichever form of the footnote support you use, you need to watch out for the situation where footnotes at the bottom of a page interrupt a paragraph. In that case, you must move either the footnotes or the paragraph text so the footnotes are between paragraphs. Otherwise the paragraph will be broken (split) in the output file.

Footnotes may be specified by the PPer with either numeric labels or (starting with ppgen 3.46f) non-numeric labels. If numeric, they can be numbered by the PPer or, more often, autonumbered by ppgen. Numeric and non-numeric footnote labels may be mixed in a project if necessary. Examples of non-numeric footnote labels: A, 1:1, 1_1, IV-1.

Footnotes may contain ppgen markup, such as for a poem, etc. However, the line after the .fn command must either be blank or contain normal text. You cannot have a dot command (e.g., .ta or .nf) immediately after the .fn command. If your footnote starts with a table or a poem the formatters should already have put a blank line before the /* that marks the table or poem; make sure you leave the blank line in place.

In the text, numbered by PPer:

 “Have you ever heard of a man named
 Ashton Sanborn, Mr. Bright?”
 “Yes, I have, Mr. Bolton. Wasn’t he
 the detective who helped you unearth
 that fiendish scheme of old Professor
 Fanely?”[1]
 “Bull’s eye!” grinned Bill. “Only Ashton
 Sanborn is quite a lot more than a mere
 detective.

At the footnote location:

 .fm
 .fn 1
 See Bill Bolton and The Winged Cartwheels.
 .fn-

where .fm is a footnote mark.

If autonumbering is desired, replace the [1] with [#] and use ".fn #" at the footnote location.

Notes:

  1. Use of .fm is optional. All it does in that simple format is produce a short horizontal line to separate the footnoes from the preceding text.
  2. Ppgen will handle any text in the form [#] or [digits] (e.g., [1831]) as a footnote reference. Any text in that format that is not a footnote reference may cause issues in your HTML output. To avoid that problem, you can "escape" the leading bracket using a "\". For example, [1831] is a footnote reference, but \[1831] is the normal text "[1831]".
  3. For non-numeric footnote labels, the label may contain A-Z, a-z, 0-9, "-", "_", ":", or ".".

Greek

Since Ppgen is full UTF-8, you can use actual Greek characters. They will show up in the HTML (which is encoded as UTF-8) and in the UTF-8 text file, if you use one. We are no longer expected to provide a Latin-1 file to PG, so the processing done by .gu and .gl is really not necessary any more, but as it still exists in ppgen we will still describe it for now.

Extended Processing (new with ppgen 3.46j)

With ppgen 3.46j, ppgen has support to take a Greek transliteration and turn it into a basic Greek transcription, although without the accents. You can enable this using the .gk command.

Additionally, ppgen provides a method similar to that used in Guiguts to allow you to add the accents the proofers omitted. You would add the accent markings to the Greek transliterations provided by the proofers, and then ppgen will provide the full Greek transcription in the UTF-8 output files.

For details see the ppgen Greek tutorial.

Older Processing

It is customary to provide a Greek transliteration for Latin-1, and usually these come to you in concatenated text file from the project, but of course you need to check them. Additionally, it is common to provide a proper Greek transcription of the transliteration, to match what the book had, including any accents that the proofers did not provide. The default is for proofers to ignore the accents.

The WWer's unitame and Ppgen work the same way by default. In converting UTF-8 to Latin-1 it will do what it can, but Greek will come through as "described characters." What you should do with ppgen is provide both the Greek and the Greek transliteration for any phrases you encounter. To do this, use the ".gu" (Greek, UTF-8) and the ".gl" (Greek, Latin-1) dot directives to differentiate. Here is an example:

Testing Greek inline.
.gu Μία γλώσσα δεν είναι ποτέ αρκετή,
.gl Mia glôssa den einai pote arketi,
or, in English, “One language is never enough.”

In HTML and in the UTF-8 text, that will appear like this:

Testing Greek inline. Μία γλώσσα δεν είναι ποτέ αρκετή, or, in English,
“One language is never enough.”

The generated Latin-1 file will downcast the curly quotes as usual and will use the transliteration in the ".gl" line to create this, rewrapping if it is ever necessary:

Testing Greek inline. Mia glôssa den einai pote arketi, or, in English,
"One language is never enough."

It is recommended that even for small amounts of Greek, the PPer prepare and submit both a Latin-1 and a UTF-8 file.

Headings

The PPer must provide the level 1 heading (book title) and may also provide level 2 headings (for example, chapters) and level 3 headings (for example, sections).

.h1 for main heading. use once.
.h2 for chapters
.h3 for sections
.h4, .h5, and .h6 for lower-level headings

Optional attributes allowed only for .h1, .h2:

 title=  specifies a title string for .h1 or .h2. Ebookmaker will use this when constructing the epub/mobi Table of Contents 
         and the bookshelf info for the book rather than using the full contents of the .h1 or .h2 line.
         (Requires ppgen version 3.49c or later.)

Optional attributes for .h1, .h2, .h3:

 break (default) or nobreak  
          If omitted (or specified as break) ppgen will generate a page break before the heading.
 id=      specifies an ID for the header, allowing links to it from the ToC or other locations
 pn=      page number (an actual number or +number, as used on .pn command)
 align=   c (center, default) or l (left) or r (right)

Optional attributes for .h4, .h5, .h6:

 nobreak (default) or break
          If specified as break ppgen will generate a page break before the heading.
 id=      specifies an ID for the header, allowing links to it from the ToC or other locations
 pn=      page number (an actual number or +number, as used on .pn command)
 align=   c (center, default) or l (left) or r (right)

(Note: .h4, .h5, and .h6 are new with ppgen 3.44b.)

example:

 think of means to have some more.

 .sp 4
 .h2 id=ch03 pn=+1
 Chapter III||GALE’S ADVENTURE
 .sp 2

 The Arizona night was cool, the sky studded

alternate:

 think of means to have some more.
 .pn +1

 .sp 4
 .h2 id=ch03
 Chapter III||GALE’S ADVENTURE
 .sp 2

 The Arizona night was cool, the sky studded

The vertical pipe "|" forces a line break when used in a heading.

Horizontal Rules

.hr     horizontal rule 
.hr nnn% (defaults to 100% if omitted; w=nnn% is also allowed)

Example:

.hr 30%
.hr w=20%

Illustrations

Example: Centered illustrations:

 with link to larger image:
   .il fn=illus-fpc.jpg w=346px link=illus-fpcf.jpg
   .ca “If he wanted to fight, he’d hardly be in an office”
 no link:
   .il fn=illus-fpc.jpg w=346px
   .ca “If he wanted to fight, he’d hardly be in an office”

Attributes for .il:

 fn     filename of displayed image
 id     image id, perhaps used in LOI
 link   filename of image linked-to on click
 w      width of image when viewing HTML, specified in px or % (height determined from aspect ratio)
        (example: w=348px or w=50%) 
 ew     width of image in percent when viewing epub/mobi (example: ew=50%) (default: whatever was specified for w=)
 eh     experimental: height of image in % when viewing epub/mobi (example: eh=70%) (width determined from aspect ratio)
 alt    alternate text (in quotes) to accompany image (See Notes below.)
 cw     caption width (percentage) - default is illustration width in HTML, 80% in epub
 cj     caption justification (=l/r/c for left/right/center align, f for fill/fully justified)
 cm     provides an optional name for a caption model for multi-line captions in text output formats
 align  image alignment (=l/r/c for left/right/center align)
 pn     page number (a decimal or Roman number or an increment like +1)

all images must be in the images subfolder of the folder containing the -src.txt file.

full example:

 .il id=i01 fn=i02.jpg w=40% link=i02f.jpg alt='frontispiece'
 .ca “Ah there, girls! How are you?”—Page 11.

a manual illustration block. this is for a title page illustration that only appears in the HTML:

 .if h
 .il fn=illus-tpg.jpg w=70%
 .if-

An illustration may have an id assigned. Used for list of illustrations link.

 .ce
 <l>ILLUSTRATIONS</l>

 .nf b
 #Sally Placed the Black Box on the Study Table:i01#
 etc.

and then at the illustration

 .il id=i01 fn=illus-01.jpg w=60%
 .ca Sally Placed the Black Box on the Study Table

left adjusted with specialized text illustration markup. this is used when in HTML we want an illustration (example: a small book cover used on an ad page) and in text we want to say that the illo was there and what it was showing.

  .if h
  .de .imgleft { clear:left; float:left; margin:4% 4% 4% 0; }
  .de @media handheld {.imgleft { float:left; }}
  .li
  <div class='imgleft' style='width:20%'>
  <img src='images/illus-ad1.png' alt='' style='width:100%' />
  </div>
  .li-
  .if-
  .if t
  [Illustration: image of book cover]
  .if-

As part of the generation process, ppgen requires and will check that any image you have specified exists in the images subfolder.

Notes:

  1. When generating the text output file, if a .il directive that contains alt="some text" and does not have a caption, ppgen will use the alt text as the caption. This might be useful if you have, for example, an illustration without a caption that you want present as-is in the HTML output but described in the text version. For example, on the title page of a book you might have a publisher's logo that you want to describe, rather than simply having [Illustration]. (This requires ppgen 3.49d or later.)

Captions

Simple captions are placed all one line of source. Text will wrap according to the width of the illustration. Complex captions require an escape to HTML, though often they can (and should) be simplified. There is one intermediate case that ppgen can handle: captions consisting of several lines, each centered by default.

The desired effect is a multi-line caption with each line centered:

Screen Shot 2014-07-12 at 3.56.03 AM.png

The source:

 .il fn=illus-fpc.jpg w=382px
 .ca
 "The evidence is compelling,"
 accused the Sheriff.
 .ca-

In plain text, before ppgen 3.44c, this becomes:

 [Illustration: "The evidence is compelling,"
 accused the Sheriff.]

There can be a problem with that format, if the two lines are supposed to remain separate and someone rewraps the text file later during processing. To avoid that potential problem, in ppgen 3.44c and later that example will become:

 [Illustration: 
 
   "The evidence is compelling,"
   accused the Sheriff.
 ]

If you want a different format for those captions in ppgen 3.44c and later you can specify it using the .cm (Caption Model) command. Further details about .cm are available in Multi-Line Captions, specifically the section for ppgen version 3.44c and later. (Note: this change applies only to the text output format, and only when the caption is provided using a .ca/.ca- block. If the caption is provided directly on the .ca command ppgen assumes it is wrappable text, and generates the older style output.

A .ca command may take one of the following three forms:

  .ca A single line caption.

or

  .ca A single line caption that is longer\
  than you want to type on a single line\
  so you spread it across several source lines.

or

  .ca
  first caption line
  second caption line
  another one; all of which will be centered by default
  .ca-

(Note: The caption width and alignment (left, right, centered, or fully justified) are controlled by options on the .il command that must immediately precede the .ca command.)

More details on captions can be found in the [tutorial section]

Indents

Change the left margin until told to change it back or change to a new left margin indent.

.in ±N Change indent according to ±N
.in N Set indent to n
.in restore indent to last value (nests)

Also see Temporary Indent

Indexes

The .ix directive starts a book index. It is followed by the individual index entries. At the end of the index use the .ix- directive to end the index.

Prior to ppgen version 3.52d the common way to generate an index was to use .nf l, then the individual index entries, then .nf- to end the index. This required the PPer to specify .in to indent the index entries by at least 1 space for the text version. It generated the index using poetry-style CSS for the HTML version. This worked, but was incompatible with the DP Best Practices which suggest that indexes are better styled as list entries using <ul> and <li>. The .ix directive generates indexes using list markup, and thus is more compliant with DP's Best Practices.

Note that in the text output the index will automatically be indented 1 space if ".in 0" is in effect. The PPer is still responsible for setting up any page-links that are needed; .ix just changes the style of output.

Usage:

 .ix
 Main entry, page numbers, all as one long unwrapped line as produced by the formatters following the standard DP Formatting Guidelines
   sub-entry, page numbers, all as one lone unwrapped line
   sub-entry, ...

 Another main entry, ...
   ...
 .ix-

Example:

 .ix
 Mines, #23#, #45#.
   Silver, #35#, #56#.
   Tin, #37#, #43#.

 Mining, #18#, #23#.
 .ix-

Inline Markup

Inline markup changes the appearance of text. The current complete list of inline markup is:

                      <l> This is <l>large</l> text.
                     <xl> This is <xl>extra large</xl> text.
                    <xxl> This is <xxl>extra, extra large</xxl> text.                     
                      <s> This is <s>small</s> text.
                     <xs> This is <xs>extra small</xs> text.
                    <xxs> This is <xxs>extra, extra small</xxs> text.
               <fs=value> This is <fs=1.2em>1.2em sized</fs> text.

                <c=color> This is <c='#f00'>red colored</c> text.

              <lang=name> This is <lang=fr>French</lang> text.

             <abbr=value> <abbr=Saint>St.</abbr> Gertrude lived on Warren <abbr=Street>St.</abbr>
        <abbr rend=spell> I live in the <abbr rend=spell>USA</abbr>
       <abbr rend=arabic> This book was published in <abbr rend=arabic>MCMVI</abbr>
             Note: ppgen ignores (deletes) all the markup above this note when producing a text output file.
                      <i> This is <i>italic</i> text.       (Also <I> - see below)
                     <em> This is <em>emphasised</em> text.
                      <b> This is <b>bold</b> text.         (Also <B> - see below)
                 <strong> This is <strong>strongly emphasised</strong> text.

                     <sc> This is <sc>Small Caps</sc> text. (Also <SC> - see below)
                      <g> This is <g>gesperrt</g> text.
                      <u> This is <u>underlined</u> text.
                   <cite> This is <cite>cited</cite> text.
                   
                     <sn> <sn>This is a sidenote</sn>
                          <sn class='class-name'>This is a special sidenote</sn>
 
                     <br> Use <br> to insert a line break if needed at a specific location in 
                             a paragraph, header, illustration caption, or table cell. Note: <br>
                             applies only within wrappable text, not in other locations (e.g., not in .nf blocks)
 
                     <al= Use <al= to override the alignment of data or headers in table cells.
                              
                   <span> Use <span> in tables to indicate data or headers that should span
                             multiple columns. (Implements the HTML colspan attribute.)
 
                  <target Use <target to specify link targets in your text. For more details see
                             the Links documentation.
 
                     <th> Use <th> to indicate that a row in a table contains headers rather than
                             data.
 
                     <pm ...> Included here for completeness, but not really inline markup. This "plays" a macro. 
                             See the macro documentation for more details.

Notes:

  1. The <c='color'> tag supports all the standard CSS color specifications. See, for example, this part of the w3schools CSS color tutorial.
  2. For further information on the <sn> markup (new in ppgen 3.47b) see the Sidenotes tutorial.
  3. <abbr> is supported in ppgen version 3.47m or later.
  4. <br> is supported in ppgen 3.50c and later.
  5. <al= is supported in ppgen 3.49e and later. See the Tables documentation for more details.
  6. <span> is supported in ppgen 3.50a and later. See the Tables documentation for more details.
  7. <th> is supported in ppgen 3.50g and later. See the Tables documentation for more details.
  8. For <fs> be careful if you specify sizes in "em" units, as an "em" is relative to the font size of the containing element in HTML. Thus, "1em" is the same size as the text in the containing element, "2em" is twice that size, and ".5em" is 1/2 that size. You might have fewer surprises if you specify the <fs> units in % rather than em. E.g., <fs=80%>.

Emphasis and decoration

By default the emphasis and decoration markup is interpreted as follows:

       <i>  italic in HTML, underscores in text
      <em>  emphasised with italics in HTML, underscores in text
       <b>  bold in HTML; '=' in text
  <strong>  strong emphasis using bold in HTML; '=' in text
      <sc>  small-caps in HTML, ALLCAPS in text (see below for special handling)
       <g>  letter-spaced in HTML, and surrounded by _ (as for italic) in text
       <u>  underlined in HTML; no effect in text
    <cite>  citation using italics in HTML, underscores in text

"<i>", "<b>" and "<sc>" also exist in uppercase forms: "<I>", "<B>" and "<SC>". These behave the same as the lowercase forms in HTML, but in the text version they do not produce underscores, equals signs or ALLCAPS. This may be used where text in the original is italic, bold or small-caps purely for presentational purposes, not for emphasis, and it is felt that the default text markup of underscore, equals signs or ALLCAPS would be intrusive. Note that "removing markup" is considered an error during PPV, and using the above may not be universally approved.

You can change the characters that ppgen uses for decoration in the text output using the .nr directive. For example,

 .nr tag-b +

tells ppgen to surround bold text with + rather than = in the text output. The register names used for this are tag-i, tag-em, tag-b, tag-strong, tag-sc, tag-g, tag-u, and tag-cite. See the Named Registers section of this manual for more information.

By default, tag-sc has a null value, which tells ppgen to make the text UPPER-CASE in the text output. If you specify a value for tag-sc, ppgen will instead surround the small-capped text with that character. In the HTML output, small caps markup can generate three different outcomes depending on what is between the tags:

"1947 <sc>A. D.</sc>"
  Everything inside the <sc> markup is uppercase, so it will
  be rendered in HTML with a relative font size of 75%.

"<sc>J. P. Lippincott, Publishers</sc>"
  Mixed upper and lower case, so it will be rendered with
  font-variant:small-caps

"It was 9:30 <sc>p. m.</sc>"
  This is considered incorrect markup and results in a warning.

Language markup

In order to help screen-readers pronounce words correctly, the PPer may mark words that are in a different language to the main body of the book.

To indicate that a word is in a specific language, perhaps so that a screen-reader can pronounce it differently, use <lang=name>...</lang> where name is the value given for the language in the IANA Language Subtag Registry, which will be passed on appropriately to the HTML version. The <lang> tag by itself does not affect formatting. In particular, if you want the phrase to be italicized, you would put the phrase in the usual <i>...</i> brackets.

Notes:

  1. As with HTML markup (and DP markup such as <i>, <b>, etc.) the tags cannot cross paragraph boundaries. If <lang=name> occurs in a paragraph (or table cell, header, etc.) the corresponding </lang> must be in the same paragraph (or table cell, header, etc.) (Basically, the markup must be wholly contained within its parent object, whatever that is.)
  2. By default the base language for the book is English (en). To specify a different base language use the ".nr lang" command (documented here).

Accessibility markup (<abbr>)

In order to help screen-readers pronounce words correctly, the PPer may mark several situations:

  • words that are abbreviations, where the full word should be pronounced,
  • words that should be spelled rather than pronounced,
  • words that are in Roman numerals where the screen-reader should pronounce the value as a Arabic (decimal) number.

When the full word is to be pronounced, rather than the abbreviation itself, use the form <abbr=full-word>abbreviation. In the example above:

 <abbr=Saint>St.</abbr> Gertrude lived on Warren <abbr=Street>St.</abbr>

the screen-reader will pronounce the first "St." as "Saint" and the second "St." as "Street". This is done with HTML that will look like:

 <abbr title='Saint'>St.</abbr> Gertrude lived on Warren <abbr title='Street'>St.</abbr>

Note that you can also use the forms <abbr="Saint"> or <abbr='Saint'>

When an abbreviation should be spelled rather than spoken, use the form <abbr rend=spell>abbreviation. In the example above:

 I live in the <abbr rend=spell>USA</abbr>

a screen-reader that supports the CSS options associated with speech will pronounce the individual letters, U S A, rather than trying to make it a word like "oosa". When you use this form of the tag, ppgen will generate both CSS and HTML:

  CSS: abbr.spell { speak: spell-out; }
 HTML: I live in the <abbr class='speak'>USA</abbr>

You can also use <abbr> when you have Roman numerals and want the screen reader to read them as Arabic (decimal) numbers rather than trying to pronounce them as a word. For this case use the form <abbr rend=arabic>Roman-numerals-here. In the example above,

 This book was published in <abbr rend=arabic>MCMVI</abbr>

For this case ppgen will generate HTML like:

 This book was published in <abbr title='1906'>MCMVI</abbr>

Note: By default many browsers will decorate the abbreviations in some way, often a thin gray dotted line underneath. You can adjust that with CSS via the .de directive if you want to. Additionally, for forms of <abbr> that generate HTML with the title= attribute, if the user hovers the mouse over the abbreviation many browsers will display the title-value as a tool-tip.

Superscripts and subscripts

Superscripts and subscripts are also supported using these rules: In text, superscripts drop the "{}" scaffolding if it's a single character. Otherwise, they are retained. They are always retained for subscripts.

Examples of text formatting for superscripts, subscripts:

 Rob^{t} Wheeler --> Rob^t Wheeler
 The 2^{nd} paragraph --> The 2^{nd} paragraph
 A drink of H_{2}O --> A drink of H_{2}O

Some post-processors may want to control how the text representation looks and override the default. For example, they might want this transformation in text:

The 2^{nd} paragraph --> The 2nd paragraph

To do that, escape out of ppgen and put your preferred text representation:

 There is a
 .if t
 2nd
 .if-
 .if h
 2^{nd}
 .if-
 inscription dated "18th March 1823" on the flyleaf.

Notes:

  1. If your book actually includes the character ^ you may bypass ppgen's normal superscript processing by "doubling" the ^ character. Example: "abc^def" will generate "abc^{d}ef" in the text output, but "abc^^def" will generate "abc^def" in the text output. This works similarly in HTML, too. This requires ppgen 3.56e or later.
  2. If your book actually includes a character string like _{text} you may bypass ppgen's normal subscript processing by "doubling" the _ character. Example: "a_{bcd}" will generate bcd as a subscript in HTML, with the _ and {} removed. To avoid that, use "a__{bcd}" instead. In both text and HTML that will generate the string "a_{bcd}". This requires ppgen 3.56e or later.

Within no-fill blocks

In no-fill blocks, such as ".nf c", though each line is considered separate, users can use "natural" inline markup and the generator will remap it correctly, invisibly closing and opening tags on consecutive lines as needed. For example, this will work as expected:

 .nf c
 <sc>Copyright 1921
 Frostbite Publishing Company</sc>
 <i>Fergus Falls, Minnesota</i>
 .nf-

Line Length

Line length affects the right margin. Changes are persistent.

 .ll ±N Set line length according to ±N
 .ll N Set line length according to N
 .ll Change to previous line length. (nests)

Links

Surround a page link with '#' for example #132# will create a link to Page 132.

in index, links to page numbers:
 Geography, a lost art: #260#.
 Georgia: few whites there in 1800, #46#;
   part included in Free State of Franklin, #125#;
   refuses to interfere in North Carolina-Franklin controversy, #137#-8;
   sells a portion of its territory, #140#.
 Germans, The: #76#.

Because mobile devices repaginate, a line to what was originally page 41 might be on a different page for the tablet user. It's better to have the link go to the exact word no matter where the device puts it.

A basic index entry looks like this:

Africa #41#

This generates a link to Page_41, which is associated with page 41 in the original text. There has to be a "Page_41" for this to work, of course. That would be generated if you are generating page numbers for your book.

An additional form is preferred:

Africa #41:Africa#

That will show up as "41" in the index, but in HTML will link to a specific place set by the user. At the target in the text is this:

“He did not go to <target id='Africa'>Africa,” he said. “Instead,his destination was the South Pacific.

Note: <target...> supports 3 formats:

  1. <target id='some value'>
  2. <target id="some value">
  3. <target id=some value>
  4. (new with ppgen 3.56b) <target=some value>

It does not need to be the same word. It just needs to be unique. This approach is tablet-safe, linking to the actual location of the reference, not to what was originally a full page that may span several ebook reader pages.

In summary, ppgen supports two forms of link construct:

  1. #page-number#
  2. #text-that-ppgen-will-display:link-id# (see Notes below)

If you use the second form then you should also include a <target="link-id"> string somewhere within the text of your book, unless you are referring to a link that ppgen will create some other way (e.g., from the id= value on a .il directive, or on an .h2 directive, or automatically generated as part of a footnote, etc.).

As part of the generation process, ppgen requires and will check that any link you have specified exists within the input source or the generated HTML.

Notes:

  1. The "link-id" must start with an alphabetic character (A-Z or a-z) and the following characters must be alphabetic, digit (0-9), hyphen (-), underscore (_), colon (:) or dot (.) characters.

Lists (Ordered and Unordered)

Starting with release 3.53b ppgen supports unordered and ordered lists using the .ul, .ol, and .it directives. Note that unordered lists implement the same item markers in the text output that HTML supports natively: disc (●), circle (○), square (▪), and none. Those characters are UTF-8 characters, and so if you create a Latin-1 output file you will need to do some editing to replace them with something appropriate for Latin-1. (Automatic translation of those characters to something reasonable in Latin-1 may be added later, but it is a low priority.)

Spacing between list items (and after the list) is controlled either using the space= option of .ul/.ol directive or by .sp directives. The .ol and .ul directives provide the space=n (default) or y option. With space=n ppgen will not automatically add a blank line after line items, except for the last one, and any other spacing desired by the PPer must be supplied using .sp directives. With space=y ppgen will provide a blank line between each item of the list, as well as after the list.

Lists may be nested, but ppgen enforces the same rules as HTML. That is, a nested list must exist within a list item. For more information, see Nested Lists below.

Note: Ordered lists are best used for information entered by the PPer, such as TNs, rather than for text contained within the book. These lists are designed for dynamic content (where the numbers are not known, for example), not for static text. If your book contains an ordered list you will probably have better success using either a definition list, via .dl, or an unordered list (.ul with style=none) rather than .ol. There are several reasons for that, but the key ones are:

  1. You can better match what was actually printed, and
  2. You will have less work to do because the text provided by the formatters already contains the item numbers, and using .ol you will need to delete that text.

Unordered Lists

The .ul directive begins an unordered list. Within the list, the .it directive (described later) specifies list entries. The .ul- directive ends the unordered list.

Format of the .ul directive: .ul optional-options where the optional options are:

 style=disc or 
       circle or 
       square or 
       none            (default: circle)
 indent=number         (default: see notes)
 id=id_value           (default: none)
 class=classname_value (default: none)
 space=n or y          (default: n) Indicates whether the item should be followed by a blank line
 hang=n or y           (default: n) Indicates whether, if the item wraps, the additional lines should have a hanging indent

Notes:

  1. The indent value is added to the current indent to determine where the list item marker will appear. If the current indent is 0 a default of 1 will be forced for text output. Additionally, for nested lists the inner list will be indented so its marker lines up under the text of the outer list. Note that the alignment may not be exact in HTML for nested lists.
  2. The id operand applies only to HTML, and allows you to specify an id for a particular list so you can tailor it more finely using CSS.
  3. The class operand applies only to HTML, and allows you to specify a class name that you can use when tailoring the appearance of a set of lists using CSS. If multiple lists use the same class name, ppgen will issue a warning message if they have conflicting CSS characteristics.

Ordered Lists

The .ol directive begins an ordered list. Within the list, the .it directive (described later) specifies list entries. The .ol- directive ends the ordered list.

Format of the .ol directive: .ol optional-options where the optional options are:

 style=decimal or
       lower-alpha or
       lower-roman or 
       upper-alpha or
       upper-roman           (defalt: decimal)
 w=number              (default: 2) 
 indent=number         (default: see notes)
 id=id_value           (default: none)
 class=classname_value (default: none)
 space=n or y          (default: n) Indicates whether the item should be followed by a blank line
 hang=n or y           (default: n) Indicates whether, if the item wraps, the additional lines should have a hanging indent
 align=r or l          (default: r) 

Notes:

  1. The w value specifies, for the text output, the maximum width required for the number of items contained in the list. The default allows for 99 items. If you have only 9 items or fewer you could specify w=1, or accept the default of 2. The w value is ignored when generating the HTML output.
  2. The indent value is added to the current indent to determine where the list item marker will appear. In the text, lists will be indented by at least one space from the left margin. If lists are nested, the "marker" for the inner list will be placed below the text for the outer list, though this may be less accurate in HTML than in text.
  3. The id operand applies only to HTML, and allows you to specify an id for a particular list so you can tailor it more finely using CSS.
  4. The class operand applies only to HTML, and allows you to specify a class name that you can use when tailoring the appearance of a set of lists using CSS. If multiple lists use the same class name, ppgen will issue a warning message if they have conflicting CSS characteristics.
  5. The align operand applies only to text.
  6. As mentioned in the intro to this section of the manual, .ol should probably not be used for lists printed within a book. It's best for PPer-provided, TNs, etc.

List Items

Use the .it directive to specify the content of a list item. You can specify items in several ways.

Basic method:

 .it Contents of the list item, if reasonably short

 .it For a longer list item, you may continue the lines for ease of editing,\
 using the backslash character. Simply write as much as you want, but end each\
 line with the backslash until you are done.

Note: Having anything except simple text within a list item has not been extensively tested, though it does appear to work, and the output passes CSS and HTML validation. To do that, you could have, for example:

 .ol
 .it Here is item 1
 .nf l // which happens to also contain a poem
 poem here
 .nf-
 .it Here is item 2
 .ol-

Nested Lists

You may nest lists within other lists if you need to.

Example:

 .ul   // outer list, unordered
 .it First list item
 .ul   // a nested, unordered list
 .it 1st item of nested ul
 .it 2nd item of nested ul
 .ul-
 .it Second item of outer list
 .ul-

 or

 .ul
 .it First item
 .ol // an ordered list within an unordered list
 .it 1st item of nested ordered list
 .ol-
 .ul-

Literal Code

Sometimes the PPer needs to take complete control over what will be generated in a small section of the book. This is called "escaping." To "escape to HTML" is to tell the generator the specific HTML (and CSS) you want at that point. No ppgen processing (dot commands, page links, etc.) should take place within the .li block. If you want your literal block to appear only in the HTML output file, you should surround it with ".if h / .if-". If you want it to appear only in the text output file(s) you should surround it with ".if t / .if-".

Here is an example.

What is wanted is a green box. There is no ppgen directive for that. Let's look at this with line numbers added:

 1   .if h
 2   .de hr.greenbox { height:40px;width:60px; border:2px solid green; }
 3   .li
 4   <hr class='greenbox' />
 5   .li-
 6   .if-
 7   .if t
 8   [Illustration: a green box]
 9   .if-
 Line 1: starts a conditional block for what to do in HTML. This will end on line 6.
 Line 2: define CSS for an hr with class of "greenbox"
 Line 3: start a literal code section. Whatever follows goes directly to HTML
 Line 4: this line will be in the HTML file at this point
 Line 5: this ".li-" closes the ".li" block, ending the literal block
 Line 6: this ".if-" closes the ".if" block, ending the "if" conditional for HTML
 Line 7: starts a block for the text output
 Line 8: this line shows up in text
 Line 9: this ".if-" closes the ".if" block, ending the "if" conditional for text.

Note that any images included in the literal block will not be counted in the html error checking. E.g.

 .li
 <img src="images/i_142d.jpg" class="id" alt="" />
 .li-

will give the following warning during ppgen html processing

 **warning: 52 images apparently not used:
 **warning:   i_142d.jpg

Macros

Macros give you a way to automate some repetitive processing. For example, you might have a standard set of options you want to use on your illustrations (.il directive) across many of the illustrations in your book. You could define a macro to generate your .il directives, with parameters for those options that are specific to a given illustration.

Beginning with ppgen version 3.54, ppgen allows you to have two forms of macro:

  • The older form, which is simpler to use and still suitable for most cases, provides simple parameter substitution into lines of text. These may be tailored using .if directives to work differently between the text output file and the HTML output file.
  • The newer form allows more flexibility in processing, by allowing you to write short programs in the Python programming language. These macros have the ability to do calculations and to manipulate the parameter text, rather than doing simple substitutions.

You can invoke macros in several ways:

  1. Via the .pm directive (shown below).
  2. In ppgen 3.54 or later you can invoke macros written in Python to perform replacement processing in the .sr directive (see the tutorial).
  3. In ppgen 3.55g or later you can invoke macros in-line with other text (or in tables, etc.) via the <pm ...> inline tag (shown below). Note: Macros that are invoked using the inline invocation are limited to returning a single line of text.

Defining a macro: the .dm (define macro) directive

Syntax of the .dm directive:

 .dm <macro-name> <optional macro parameters> <optional: lang=python>
 macro statements
 .dm-
 The macro-name is a required parameter, which should be a character string without blanks.
 The optional macro parameters take the form $"n", e.g., $1, $2, $3, etc. to represent the 1st, 2nd, 3rd, etc. parameters to the macro, but are meaningful only for non-Python macros.
 If your macro is written in Python, then you must specify lang=python somewhere on the .dm directive.


Defining a simple macro:

 .dm ilcc $1 $2 $3
 .il fn=$1 w=$2
 .ca $3
 .dm-

This .dm defines a macro named ilcc with 3 parameters. The macro is of the older style, allowing simple text substitution, which will generate a .il directive followed by a .ca directive.

Using a macro: the .pm (play macro) directive

Syntax of the .pm directive:

 .pm <macro-name> <optional macro parameters> 

 As with .dm, the macro-name is required.
 The optional parameters are positional. When invoking a non-Python macro ppgen uses the first one to substitute for $1 within the macro definition,
  the second for the second parameter ($2), etc.

Using the macro:

 .pm ilcc illus-fpc.jpg 382px "\"Think how you love me,\" She whispered."

Resulting code placed in source file at runtime:

 .il fn=illus-fpc.jpg w=382px
 .ca "Think how you love me," She whispered.

Notice that the user-supplied parameters are positional, and are substituted into the macro definition where the $1, $2, etc. tokens are. Notice, too, that macro parameters containing blanks must be quoted. You may use single quote characters (') or double quote characters ("). If your parameter contains a single-quote mark you can make coding simpler by enclosing it in double-quote marks. Similarly, if it contains double-quote marks you can make things simpler by enclosing it in single-quote marks. Or, as shown in this example, you can "escape" the inner quote marks using a \ character.

Using a macro: the <pm ...> inline tag

Syntax of the tag: <pm macro-name parameter-1 parameter-2 ...> E.g.,

Here is a line of text <pm mac1 parm1 "parm 2"> with a macro invocation in it.


This inline tag may appear anywhere in the ppgen source, but it may be especially useful within normal paragraphs and within tables. The parameters are specified just as they are when using the .pm directive.

Notes:

  1. If a parameter contains a greater-than sign (>), less-than sign (<) or space then you must surround the parameter with paired ' or " marks to ensure proper processing.
  2. The invocation must be physically on a single line of the ppgen source, or (starting with ppgen 3.56e) if it is split across lines you may use the \ character to continue the line.
  3. The macro is limited to returning at most one line of text, but a macro defined like the following will work via <pm ...> without problems, even though at first glance you might think it wouldn't:
.dm macname $1 $2
.if t
$1
.if-
.if h
$2
.if-
.dm-

The reason it works is that .if processing happens earlier in ppgen processing than macro invocation. Therefore, as ppgen sees it the macro really has two forms. During text processing it looks like:

.dm macname $1 $2
$1
.dm-

and during HTML processing it looks like:

.dm macname $1 $2
$2
.dm-

More Information

For more information and examples, see the tutorial on macros.

Map UTF-8 Characters to Latin-1

Ppgen will automatically map many UTF-8 characters in the source file to the corresponding Latin-1 characters when creating the Latin-1 output file. For example, it will map an em-dash (—) to --, "curly" quotes such as “ or ” to "straight" quotes ("), and the œ ligature to oe, among many others. It basically implements the standard Unitame processing used at Project Gutenberg to convert UTF-8 into Latin-1.

Sometimes, however, you will have a UTF-8 character such as ♂ (male) or ♀ (female) that Ppgen does not know how to handle. When that situation occurs, you can use the .ma (map) command to tell Ppgen how to do the mapping from UTF-8 to Latin-1 for that character.

For example:

.ma ♂ [M]
.ma ♀ [F]

Ppgen will only apply this mapping process when the source file is encoded in UTF-8 and contains UTF-8 characters.

The general form of the command is:

.ma "input character string" "output character string"

The "input character string" must be one or more characters, and must be enclosed in " marks if it contains blanks. The "output character string" must be one or more characters, and must be enclosed in " marks if it contains blanks.

While generating the Latin-1 output file, Ppgen will apply the mappings in the order it encounters them, and before doing any of its standard mappings. Note that if you used a mapped character string in a table, that the UTF-8 and Latin-1 versions of the table may have different column widths due to the mapping. Ppgen will account for this if you let it determine the column widths, but if you specify the widths yourself you should take the mappings into account when you specify the widths.

Music Files

Starting with version 3.56h ppgen provides support for you to include music (.mid) files in their ppgen projects without having to use .if h and .li to embed them directly. To do this, you would use a link of the form

 #text to display:music/filename.mid# 

in your ppgen source where you would like the link to display. The "music/" and ".mid" are required.

In HTML output "text to display" will be a link to play the music file. In text output the text "text to display" will appear, but will not be a link. If you want the "text to display" to appear only in the HTML output you will still need to use .if h to accomplish that.

Examples:

 Click #here:music/song1.mid# to play song 1.
 Click #here (HTML only):music/song1.mid# to play song 1.
 .il fn=music.jpg w=50% alt="A short piece of music"
 .if h
 .ca Click #here:music/song1.mid# to play song 1.
 .if-


Note: Music files will not work in the epub or mobi files created by Project Gutenberg's ebookmaker. The link to play them will not be present, though any text associated with the link will be there unless you use CSS to hide it. Here's one approach that I believe should work to do that (but which I have not yet tested):

 // define a CSS class that won't display in epub/mobi
 .de @media handheld {
   .hideepub {visibility: hidden;}
   }

 // more of the source file

 .il fn=image13.jpg w=50% alt='short bar of music for theme of Beethoven C Minor Symphony'

 // provide a caption (with the "play" link) for HTML, epub, mobi. (Text output will use the alt= value)
 // (the %% will be used in .sr later to hide the link in epub/mobi)
 .if h  
 .ca theme of Beethoven C Minor Symphony %%[#Listen:music/shorttheme.mid#]%%
 .if-

 // use .sr to wrap locate the %% and wrap the "play" link in a span that won't display in epub/mobi
 .sr h +%%(.*?)%%+\1+

Named Registers

Some adjustments to ppgen processing are accomplished by setting the value of internal ppgen variables (named registers) via the ".nr" command.

Currently ppgen supports the following named registers:

  • break-wrap-at -- The break-wrap-at register allows you to tell ppgen that when wrapping text it can break at additional characters, not just blanks. You specify the additional characters (or character strings) separated by blanks.
 Examples:
             To allow wrapped text to break on blanks or hyphens:
               .nr break-wrap-at "-"

             To allow wrapped text to break on blanks, hyphens, or UTF-8 em-dashes:
               .nr break-wrap-at "- —"

             To allow wrapped text to break on blanks, hyphens, or Latin-1 em-dashes:
               .nr break-wrap-at "- --"

 For a real-world example, see this page.


  • dcs -- The dcs register controls the font size used for drop caps (.dc command). The default value is 250%.
 Example: This will set the drop cap font size to 420% of the base font size:
            .nr dcs 420%


  • Footnote -- In the output text files, ppgen formats footnotes as "Footnote nn:" followed by the footnote text. The Footnote register allows you to change the word "Footnote" to another word or phrase of your choice, for example when the base language for the book is not English.
 Example: .nr Footnote Nota     (or "Nota" or 'Nota'; the quotes are required if you specify a phrase rather than a single word)


  • Illustration -- In the output text files, ppgen formats illustrations or illustration captions as [Illustration] or [Illustration: caption]. The Illustration register allows you to change the word "Illustration" to another word or phrase of your choice, for example when the base language for the book is not English.
 Example: .nr Illustration Ilustración (or "Ilustración" or 'Ilustración'; the quotes are required if you specify a phrase rather than a single word)


  • lang -- The lang register sets the base (main) language for the book, and specifies the language code that ppgen will place in the HTML header. The default value is en (English). Any valid ISO 639-1 language code may be specified. If other languages exist in the book, the usual <lang=...> tag may be used to specify them.
 Example: This will set the language for the book to Spanish: 
            .nr lang es


  • nfl -- The nfl register sets a default indentation amount for ".nf l" blocks. Supported values are whole numbers (0, 1, 2, etc.) and "-1" (the default). This specification works together with the ".in" (indent) directive. When nfl has the value -1 ppgen will warn you if it encounters any ".nf l" blocks with ".in 0" is in effect. If you specify a value of 0 or higher ppgen will not issue the warnings. Instead it will automatically indent any ".nf l" blocks it finds by the specified amount, unless there is already a non-zero ".in" value in effect. (This requires ppgen 3.49h or later.)
 Example: .nr nfl 2 // will indent subsequent ".nf l" blocks by 2 automatically if ".in 0" is in effect.


  • pnc -- The pnc register sets the color used for page numbers in the HTML output, if you have chosen to have them visible. The default value is "silver", but you may set it to any valid CSS color specification. Colors may be specified in hexadecimal values or using English names. The 23chools site has the full reference on [Colors] as well as a [list of the named colors].
 Example: This will set the page-number color to black:
            .nr pnc black 
  • pnstyle -- (ppgen version 3.53c7 and later) The pnstyle register tells ppgen which style of visible page numbering to use. The values are "content" which actually places the page number into the visible page text (similar to the style used in Guiguts) or "title" which generates the visible page number using CSS. Prior to ppgen 3.53c7 ppgen used the "title" style, but that has started generating error messages from the w3 CSS validator. Though the error message is invalid (in my opinion) and has been reported to w3 as a bug, it bothers the PPers, PPVers, and the WWers, so with 3.53c7 ppgen was changed to use the "content" format by default.
 Example: A PPer who wants to use the other page-numbering style can specify:
            .nr pnstyle title
  • psb -- The psb register controls the vertical spacing between non-indented paragraphs (the ppgen default paragraph format). The default spacing is 1em between paragraphs. This is equivalent to the dot command: ".nr psb 1.0em" but the PPer can set it to any desired value. For more examples see the lesson on Paragraph Formatting.
 Example: This will set the vertical space between non-indented paragraphs to 0.5em:
            .nr psb .5em


  • psi -- The psi register controls the vertical spacing between indented paragraphs. Normally ppgen does not add additional vertical space between indented paragraphs, but you can add some if you want. For more examples see the lesson on Paragraph Formatting.
 Example: This will set the vertical space between indented paragraphs to 0.5em:
            .nr psi .5em


  • pti (Paragraph Text Indent) -- (New in ppgen 3.47c) The pti register controls the amount of indentation for indented paragraphs. By default ppgen indents such paragraphs by 1.0em. Using the pti register you can control the amount of indentation yourself. For more examples see the lesson on Paragraph Formatting.
 Example: This will set the amount of indentation for an indented paragraph to 2em instead of 1em:
            .nr pti 2em


  • Sidenote -- (New with ppgen 3.47b) In the output text files, ppgen formats sidenotes as "[Sidenote: " followed by the sidenote text. The Sidenote register allows you to change the word "Sidenote" to another word or phrase of your choice, for example when the base language for the book is not English or if you want something shorter.
 Example: .nr Sidenote Sn     (If you specify more than one word you must enclose the phrase in paired " or ' marks.)


  • Table-related registers -- Table processing has a large number of registers that you can use to tailor the output in both HTML and text output files, too many to describe here. For complete details, see Tailoring table appearance in the tables (.ta) documentation.
  • tag-<something> -- (all these are new with ppgen 3.54o) These tags specify the character to be used to replace <i>, <b>, etc. in the text output. Before ppgen 3.54o the characters were fixed (<i> became "_", <b> became "=", etc. The defaults remain the same, but with 3.54O the PPer can change the characters if they conflict with other text in the book. For example, in a math text, specifying that <b> becomes "=" may not work well. The following list shows the complete .nr directive for each tag, and gives the default value and, optionally, notes.
    • .nr tag-i _
    • .nr tag-b =
    • .nr tag-g _
      • Gesperrt text; by default uses the same character as italic, because most books have one or the other but not both.
    • .nr tag-sc ""
      • By default, ppgen turns text marked by <sc> into UPPER-CASE in the text output. If you specify a character for tag-sc then ppgen will place it around the small-capped text, treating it more like bold, italic, etc. and will not UPPER-CASE it.
    • .nr tag-f ""
      • By default, ppgen ignores the <f> tag in text output and simply deletes the tag(s). If you use that tag, and want to mark the output text, you can specify a character using this .nr directive.
    • .nr tag-em" _
      • By default, <em> uses the same tag character as <i>.
    • .nr tag-strong =
      • By default, <strong> uses the same tag character as <b>.
    • .nr tag-cite _
      • By default, <cite> uses the same tag character as <i>.
    • .nr tag-u ""
      • By default, ppgen ignores the <u> tag in text output and simply deletes the tag(s). If you use that tag, and want to mark the output text, you can specify a character using this .nr directive.
    • Additonal Notes for tag-<something>:
      1. If you use, e.g., <b> and have it specified as "=" and also have any "=" characters in the book ppgen will give you a warning message. You might want to change the tag character, or provide a TN. (Actually, you might want to provide a TN about any of the characters you use, to make sure the reader knows how to interpret them.)
      2. If the same character is used for two different tags (e.g., <i> and <g>) and both tags are used in the book, ppgen will give you a warning message. In those cases you might want to either change the character or include a TN explaining the conflict.
      3. You should specify at most 1 character for a tag. You can specify more, but it will adversely affect text wrapping in some cases if you do.

No-Fill Blocks

No-fill blocks do not wrap. They are processed line-at-a-time.

.nf     begin no-fill until .nf- (same as ".nf l")
.nf l   no-fill and left-adjust each line until .nf- (default)
.nf c   no-fill and center each line until .nf-
.nf b   begin no-fill and center as a block until .nf-
.nf r   begin no-fill and right justify until .nf-

You can also supply an optional second parameter of "0" (zero) to .nf l. Example:

 .nf l 0

This parameter indicates that in the HTML output ppgen should ignore any indent value (.in) that is currently in effect. This provides an easy way that you can have the text output indented (e.g., to satisfy the PG rules about non-wrappable text being indented at least one space) while allowing the block to start at the left margin in the HTML. Otherwise, if you wanted the text indented and the HTML flush left you would need to use .if t/.if- around your .in directives.

If text is not in a .nf block, it is filled (wrapped)

Notes:

  1. .nf honors the .in and .ll settings in effect when the .nf command is encountered. If lines are longer than the .ll value they will be wrapped. During wrapping (but not otherwise) ppgen will also remove extra blanks between words.
  2. The PP Guidelines point out that non-wrappable text should be indented from the left margin. If you use ".nf l" it is your responsibility to ensure that the text is indented by issuing, e.g., ".in 1" before the ".nf l" directive (and ".in" after the ".nf-" directive) if rewrapping would cause problems. Alternatively, with ppgen 3.49h or later you could use the "nfl" named-register to establish an automatic indentation of ".nf l" blocks when ".in 0" is in effect. For example, you could specify ".nr nfl 1" to tell ppgen to automatically indent ".nf l" blocks by 1 character.
  3. .nf l, .nf b and .nf r honor .ce and .rj commands within the .nf block.
  4. For blank lines within a .nf block you may use either blank lines or .sp directives.

Here is a summary of line and block alignment for the no-fill block types:

individual lines entire block
.nf c centered centered
.nf b left-aligned centered*
.nf r left-aligned right-aligned*
.nf l left-aligned left-aligned
.ce centered -----
.rj right-aligned -----

* Note: In epub/mobi, a .nf b (or .nf r) block will be placed at a fixed indent from the left margin, rather than centered (or right-aligned), due to technical limitations in the way that ereader devices and apps handle blocks of text.

More details on no-fill blocks can be found in the tutorial section

Spaces (Non-breaking, and other kinds)

Non-breaking Spaces)

In UTF-8 you can put a hard space, but for readability, it's better to show the non-breaking space with a backslash escape.

 .nf c
 THE SAALFIELD PUBLISHING
 COMPANY
 Akron, Ohio\ \ \ \ \ \ \ \ New York
 .nf-

To accomodate some user's editors, an alternate form for the hard space is "\_".

Zero-width Spaces

Perhaps you need to separate two letters in a word but keep it appearing as one word even though it's really two. (OK, I don't really know why anyone would want that.) Or, perhaps you want to use a drop-cap, such as for O'Neill without having the ' mark also appear large.

To do either of those, you might use a zero-width space, represented in ppgen by the characters "\&". So, for the drop-cap case, you might code

  .dc 0.4 0.4
  O\&'Neill

Note: This will not appear as a visible space in any of the output files.

Thin Spaces

If you need a thinner space than usual (perhaps, for a better visual effect after an italic word or punctuation mark?), you can use a "\^" to get one. E.g.,

   <i>Welcome!</i>\^to DP

Note: In the text output file this will appear as a regular space.

Thick Spaces

If you need a thicker space, e.g., between ellipsis dots, you can use "\|" to get one.

   It came to pass that .\|.\|. and they lived happily ever after.

Note: In the text output file this will appear as a regular space.

Page Breaks

.pb page break

Use a page break where you want to preserve a physical page boundary. This is most common in front and back matter. The generator creates code that causes corresponding page breaks in the downstream formats, like for Epub or Kindle.

Page Numbering

The PPer can include page numbers that will be displayed in the HTML version.

 .pn +N advance page number by N.
 .pn N Set page number N.

If the source file does not contain .pn directives that specify page numbering (or linking, see below) ppgen will not generate CSS or HTML to support displayable page numbers.

There is another way to handle page numbers that is used by some post-processors. They want the original page numbers to be in the file as link targets but they don't want the page numbers to show. This allows every page to have a unique id and name. To enable this, use the ".pn link" directive. These two lines would be used near the top of the source file:

 .pn off // turn off visible page numbers
 .pn link // turn on page number links

As as side benefit to enabling these internal links, you can refer to a specific page in an HTML text if desired.

Ordinal page numbers can be either numeric or Roman numerals. The format is the same for Roman numerals as regular numbers:

 .pn xiii  sets page number
 .pn +1  advances page number to xiv (in this example)

Notes:

  1. Rarely used non-ordinal page numbers are free-form. They cannot be incremented with ".pn +1". Also, they cannot be referenced as links by using #<value>#. That form of link works only for numeric or Roman numeral page numbers.
  2. You should set the first page number explicitly, e.g., via something like ".pn 1" or ".pn i". If you start with an increment, e.g., ".pn +1" then your first page number will be Roman numeral I, not 1.
  3. Page numbering can also be specified on .il or .h1-.h6 directives.

Paragraph Formatting

The usual paragraph formatting is to have no indent on the first line of a paragraph and to have a blank line between paragraphs. This will always be the case for the text versions. It is also the default paragraph formatting for the HTML versions and those versions derived from HTML, such as PDF, Mobi and Epub. Some post-processors will chose to select an alternate paragraph formatting style that indents the first line of the paragraph and has no extra whitespace between paragraphs. This more closely matches the way books were printed and is a better match especially for the table formats.

To switch ppgen to indented paragraphs, the PPer inserts a ".pi" dot command ("paragraph indent") in the text. All paragraphs from that point on will be indented without additional paragraph spacing. Note: If you want both indentation and additional vertical space between paragraphs you can use the "psi" named register to specify the vertical spacing.

Typically, the front matter uses the default, the body of the text could follow the ".pi" command, and the back matter needs to go back to the block form. The ".ni" command switches back to "no (paragraph) indent". The PPer has complete control. Note: starting with ppgen 3.47c the PPer can also control the amount of indentation when using indented paragraphs. It defaults to 1em, but by using the "pti" named register the PPer can set the desired indentation value. For more information see the Named Registers section of this document, or the Paragraph Formatting lesson mentioned below.

With control comes responsibility. If the PPer doesn't want a particular line to be indented, they must use a ".ti 0" command. That overrides the indent. This typically happens for the first paragraph of a chapter or perhaps a continued text after poetry in the middle of a paragraph.

Please note that ".pi" and ".ni" commands only apply to HTML and derived versions. Text formatting is not affected.

See also: The ppgen lesson on Paragraph Formatting.

Search/Replace

ppgen provides the .sr directive to allow you to perform regex-based search/replace operations against either your source file or the generated output file, at various times during processing. Starting with ppgen 3.54e the replacement operation can be performed by a standard regex replacement string or (for more complex situations) by a macro written in Python.

The .sr directive provides another opportunity for you to tailor ppgen's output for situations that ppgen cannot handle natively. For full usage details see the ppgen Search/Replace tutorial.

Sidenotes

Starting with ppgen 3.47b you can use sidenotes in your projects without needing to use macros to implement them.

You would use either the .sn directive for sidenotes between paragraphs or at the beginning of a paragraph, or the inline tags <sn> and </sn> for sidenotes appearing within a paragraph or other text. For full details see the ppgen Sidenotes tutorial.

Special Situations

1. The PPer may want to set the display title as shown in a browser for a book. Use the "display title" command:

 .dt The Project Gutenberg eBook of The Highflyers, by C. B. Kelland

or

 .dt The Highflyers, by C. B. Kelland—A Project Gutenberg eBook

Note this is for convenience during post-processing only. As posted, the display title may be altered by the whitewasher.

2. Suggestions for first chapter formatting in a book:

 .pb
 .pn 7
 .h1 nobreak
 The Adventure Girls at K-Bar-O
 .sp 2
 .h2 id=ch01 nobreak
 Chapter I||ARRIVAL
 .sp 2
 The thing that went under the name of automobile wheezed into the
 ranchyard and rattled to a halt. With creaks and groans in every
 joint the car discharged its six very dusty, very weary occupants.

3. Cover image Transcriber Note example. Under present guidelines, this TN should be placed near the start of the file. This is also an example of how to escape for very specific HTML. In this case the TN box color is lavender.

 .if h
 .de div.tnotes { padding-left:1em;padding-right:1em;background-color:#E3E4FA;border:1px solid silver; margin:2em 10% 0 10%; }
 .de .covernote { visibility: hidden; display: none; }
 .de div.tnotes p { text-align:left; }
 .de @media handheld { .covernote { visibility: visible; display: block;} }
 .li
 <div class="tnotes covernote">
   <p><b>Transcriber's Note:</b></p>
   <p>The cover image was created by the transcriber and is placed in the public domain.</p>
 </div>
 .li-
 .if-

Tables

.ta directive

For tables, use the .ta dot directive. The overall structure of a ppgen table in your source file will be:

 .ta with parameters
 row data
 row data
 row data
 .ta-

Beginning with ppgen 3.50b any of those "row data" lines may also be used to specify horizontal border information instead of data. More on this later.

The parameters on the .ta directive allow you to specify the number, size, and layout of the table cells. Also, beginning with ppgen 3.50b you may specify vertical borders for the cells if you have also specified their widths.

The basic format of the .ta directive is:

 .ta cell-specification cell-specification ... cell-specification optional-parameters

Cell Specifications:

Before ppgen 3.50b a cell specification has one of three forms:

 h where h specifies the horizontal alignment of the cell's text, and is one of: l (left-aligned), c (centered), 
         r (right-aligned), or h (hanging-indent; requires ppgen 3.49d or later)
   or
 h:n where h is as above, and n is a number that gives the width (in characters) of the cell for the text output file; see below for HTML.
   or
 hv:n where h and n are as above, and v specifies the vertical alignment of the cell's text: t (top), m (middle), or b (bottom)

If you use the first form of cell specification (without the : and width) then ppgen will figure out your cell widths. All cells will be single-line cells, with no wrapping of the data. This may give you tables that are wider than DP and PG will allow. To avoid that you can use the second or third form of cell specification and provide the width for each cell. When you do that ppgen will wrap the cell data if necessary to the widths you have specified.

Beginning with ppgen 3.50b a cell specification that includes a width can also tell ppgen that you want to have vertical (left, right) cell borders, and what kind of borders you want to use. To do this the cell-specification is extended with a character on the left to represent the left-border style and a character on the right to represent the right-border style. The general form is then:

 lhv:nr where l and r indicate the border styles for the cell's left border and right border and h, v, and n are as above.

The left- and right-border styles you can specify are:

 | for a thin single line in text and HTML
 || for a medium-weight single line in HTML and a thin single line in text
 = for a thin double line in text and a medium-weight double line in HTML (note: the medium-weight double line in HTML has approximately
       the same density/weight as a thin single line)
 == for a thin double line in text and a thick double line in HTML (note: the thick double line in HTML has approximately the same
       density/weight as the medium-weight single line)


Notes on cell specifications:

  • If ppgen has had to wrap any cells of the table onto multiple lines, then ppgen will insert a blank line between each table row unless:
    • you have already put blank lines between the rows; or
    • (new with ppgen 3.50b) you have specified the use of horizontal borders for the table.
  • For the HTML, epub, or mobi output the browser, app, or device will handle the final text layout within the cells. However, ppgen will use your specified widths to calculate the relative percentage of the table width each column should occupy, and will specify that in the HTML output. You will probably want to use the w= and ew= parameters described below to tailor the overall width for the HTML output forms.
  • If you specify hanging-indentation for a cell (requires ppgen 3.49d or later) and the cell content is long enough to require wrapping, then any lines after the first one will be indented by 2 characters (in the text output file) or 1em (in the HTML output file).
  • When specifying vertical borders you can specify both the left and right borders for each cell, but you probably will not want to do that. Generally you will probably specify only the left border for each cell except the right-most. For the right-most you will probably specify both the left and right borders. You can use other combinations, of course, but this is a good starting point if you are not familiar with constructing bordered tables.


Optional Parameters:

w= specifies the percentage width for the table in the HTML output. If you do not specify w=, ppgen will calculate a table width for you. Starting with ppgen 3.52d, if you specify w=none then ppgen will not generate width information for the table or the table cells in the HTML output, leaving more of the table layout in the hands of the browser or ereader device. This may give better results in some cases depending on the user's chosen browser window size, or various font size selections in ereaders, but it may also mean that the tables will not match those in the text version or printed book as well as if a value were specified.

 Example:  .ta rlr w=50%
           .ta rlr w=none

ew= specifies the percentage width for the table in the epub/mobi output. Valid ew= values will be ignored if w=none is also specified, as w=none overrides the cell and table width specifications for epub/mobi, too.

 Example:  .ta rlr ew=50%

s= specifies a summary for the table.

 Example:  .ta rlr s="sample table"

id= specifies an id-value for the table, which may be useful for tailoring the table's appearance in the HTML versions by using .de directives of the form

 .de #id-value {CSS specifications}
    or
 .de #id-value .class-name {CSS specifications}

bl=y (default) or n determines whether ppgen will automatically add a blank line between rows in the text output when one or more cells wrap to multiple lines and the table does not contain horizontal borders. The default is to add the blank lines. Specifying bl=n tells ppgen not to add blank lines automatically, in which case if you want a blank line between rows you'll need to add it yourself. (New with ppgen 3.55l.)

 Example:  .ta rlr bl=n

Notes on optional parameters:

  • All ppgen tables are centered. Note, though, that if you do not specify w= to set the width in HTML, and ppgen has to calculate it, the calculation will assume a page width of 72 characters (as for the text version). Tables close to 72 characters wide in the text version may thus end up with a calculated HTML width value of 100%, and may not center well if the user has a wide browser window. To avoid such problems, you should specify an appropriate width via w= to get the HTML margins you prefer. This applies to epub/mobi as well, where you may wish to specify ew= and a value to get a good appearance.
  • As with all HTML id values, the value for id= must start with an alphabetic character (A-Z, a-z) and the following characters must be alphabetic, numeric, "-", "_", ".", or ":".

Rows in the table:

You may have several different kinds of row specifications for tables in ppgen: header rows (two kinds), data rows, blank rows (two kinds), and horizontal borders.

Header Rows

A header row contains table headers rather than data. Most will define as many cells (columns) as described on the .ta directive, but it is also possible to define a header that spans columns, such that you might have one header value covering two, three, or more columns.

Recommended header format:

 <th>Column 1 header-text | Column 2 header-text | Column 3 header-text etc.

For a table with "n" columns defined on the .ta directive the header row will have "n-1" | characters to contain the text for the cells/columns.

The <th> (ppgen 3.50g or later) at the start of the line will cause ppgen to use <th> elements (rather than <td>) to define the header values in HTML. This is recommended by DP's latest PPV Guidelines and in the DP Best Practices for Tables.

In many tables the header-text has different alignment than the data in the data rows. For example, you might want the header for a column centered, but have the data for that column left- or right-aligned. With ppgen 3.49e or later you can accomplish that by putting <al=x> at the beginning of the header-text for the cell (where x is l (left-aligned), c (centered), r (right-aligned), or h (hanging-indent).

 Example:
           .ta l:15 r:15  // setup a table with 2 cells, the first left-aligned, the second right-aligned
           <th><al=c>Centered heading | right-aligned heading
           left-aligned data | right-aligned data
           .ta-

To allow a header to span multiple columns (HTML colspan attribute) you can use the <span> specification for the additional columns to be spanned. For example, if you have 3 columns, and want a single header that covers columns 1 and 2, and a header over column 3, you would use:

 <th>Header for columns 1 and 2 | <span> | Header for column 3

(This requires ppgen 3.50a or later.)

If you want a header line that spans all 3 columns you would use:

 <th>Header for columns 1 through 3 | <span> | <span>

Headers which are too long for the column width will wrap, just as data will, if the .ta directive specified the column widths.

This form of header is recommended if:

  • your table has vertical borders specified on the .ta directive; or
  • you want headers for individual columns, rather than one over the whole table; or
  • you want the header to wrap to stay within the overall width of the table.

Older header format:

Prior to ppgen 3.50g you cannot use <th> at the start of a header row. Upgrading to ppgen 3.50g or later is recommended to get this support. However, with earlier releases you can still specify headers for each column simply by treating them as data. However, you cannot have a header that spans multiple columns, except for the case of a header line that centers over all the columns.

For such a centered header you would use a line containing just the text, with no | characters:

 Text to center over all the columns

That form is not recommended if you are using vertical table borders, as it does not support them at all. Additionally, such a header line will not wrap to stay within the overall width of the table.

Data Rows

The format for a data row is similar to that for a header row, though it would not have <th> at the start, and usually will not include any <span> nor <al= specifications.

Basic format:

 data for cell 1 | data for cell 2 | data for cell 3 | etc.

For a table with "n" columns defined on the .ta directive each data row will have "n-1" | characters to contain the text for the cells in that row.

Data which is too long for the column width will wrap, just as headers will, if the .ta directive specified the column widths.

Notes:

  1. You can force data in a cell to wrap at a specific location by inserting <br> where you want the break to occur.
  2. When wrapping the cell data, ppgen will normally break lines only at blanks. You an enable breaking at additional characters, for example hyphens or dashes, by specifying them using the named register break-wrap-at.
 Example 1: to also allow breaking at a hyphen you could specify 
             .nr break-wrap-at "-"

 Example 2: to also allow breaking at a hyphen or UTF-8 em-dash you could specify
             .nr break-wrap-at "- —" (note the space between them, which is required)

 Example 3: to also allow breaking at a hyphen or Latin-1 em-dash you could specify
             .nr break-wrap-at "- --" (note the space between them, which is required)

Blank Rows

If you specify column widths, and ppgen needs to wrap any of the text in the header or data rows, and you are not using horizontal borders, ppgen will automatically insert a blank line between each row unless you have already provided one.

If you do want to provide a blank row, you have two choices:

  • The older style is simply a row that is all blank. However, this style does not support vertical border characters; it really is a completely blank row.
  • The newer style (ppgen 3.50a or later) does support vertical borders. It has two forms:
    • First form (will show all the vertical column borders):
   |  |  (for as many columns as the .ta directive specifies)
    • Second form (will show only the left and right borders for the table, no internal cell borders):
   | <span> | <span> (for as many columns as the .ta directive specifies)

Horizontal Borders

Starting with ppgen 3.50b you may specify horizontal borders for your tables. These borders can appear at the top or bottom of the table, or between rows. In the overall table structure they will look like this:

 .ta 
 optional-horizontal-border-specification (top of table border)
 row-data (header or data)
 optional-horizontal-border-specification
 row-data
 optional-horizontal-border-specification
 etc.
 optional-horizontal-border-specification (bottom of table border)
 .ta-

Each horizontal border specification will consist of 1 or two characters, placed at the beginning of the line, with the remainder of the line blank. You may specify the following characters:

 _ (underscore) for a thin single line in text and HTML
 __ (two underscores) for a medium-weight single line in HTML and a thin single line in text
 = for a thin double line in text and a medium-weight double line in HTML (note: the medium-weight double line in HTML has approximately
       the same density/weight as a thin single line)
 == for a thin double line in text and a thick double line in HTML (note: the thick double line in HTML has approximately the same
       density/weight as the medium-weight single line)

Notes on tables

  • Long .ta directives or long rows may be continued by using \ as the last character of the line. ppgen will replace the \ with a blank.
  • A table may contain .pn (page number) commands.
  • A table may contain .if command blocks, and the lines produced by the .if can form all or part of the table.
  • Similarly, a table may contain .pm commands, and the output of the macro can form all or part of the table.
  • You can use <span> to implement cells that span multiple columns (e.g., the colspan attribute in HTML).
  • You can use .sr to implement cells that span multiple rows (e.g., the rowspan attribute in HTML). For an example of this, see [PPTools/Ppgen/Tutorial/DotSR#User-contributed_Examples_of_.sr_Usage User-contributed Examples of .sr Usage]

Tailoring table appearance

Starting with ppgen 3.50b you can use several named registers, via the .nr directive, to adjust how the tables appear. The following show the default values and what they control:

HTML: (If changed, these affect the entire book, and must appear before any tables are processed.)

 .nr btb_ "thin solid"    Specifies the characteristics of the horizontal borders (top/bottom) specified by _ in HTML.
              
 .nr btb__ "medium solid" Specifies the characteristics of the horizontal borders (top/bottom) specified by __ in HTML.

 .nr btb= "medium double" Specifies the characteristics of the horizontal borders (top/bottom) specified by = in HTML.

 .nr btb== "thick double" Specifies the characteristics of the horizontal borders (top/bottom) specified by == in HTML.

 .nr blr| "thin solid"    Specifies the characteristics of the vertical (left/right) borders specified by | in HTML.

 .nr blr|| "medium solid" Specifies the characteristics of the vertical (left/right) borders specified by || in HTML.

 .nr blr= "medium double" Specifies the characteristics of the vertical (left/right) borders specified by = in HTML.

 .nr blr== "thick double" Specifies the characteristics of the vertical (left/right) borders specified by == in HTML.

HTML: (If changed, these affect only those tables that occur after the .nr command.)

 .nr html-cell-padding-left ".5em"   Specifies the padding between the left-border character and the cell text in HTML. Should end in "em".

 .nr html-cell-padding-right ".5em"  Specifies the padding between the cell text and the right-border character in HTML. Should end in "em".

 .nr border-collapse "collapse"      Specifies the border-collapse property for tables that have vertical (left/right) 
                                     cell borders. Specify as "separate" if you do not want the borders to collapse for
                                     a table.

Text: (If changed, these affect only those tables that occur after the .nr command.)

 .nr text-cell-padding-left ""   (default: empty string) Specifies the padding characters (if any) to be used between the
                                 left-border character and the cell contents in text output. Specify, for example a single
                                 blank (" ") if you want a space between the border and the data)

 .nr text-cell-padding-right ""  (default: empty string) Specifies the padding characters (if any) to be used between the
                                 cell content and the right-border character in text output. Specify, for example a single
                                 blank (" ") if you want a space between the border and the data)

Examples:

For examples of tables see Table examples.

Temporary Indent

A temporary indent applies by default to the single line following the dot command. However, using the "begin" and "end" operands you can also apply it to the first line of each paragraph that follows.

 .ti value ±N Indent next line (default value if omitted: 2).
              Positive values indent to the right; negative values indent to the left (useful to implement
              a hanging indentcan be left or right.
     begin    If specified, causes the temporary indent to apply to the first line of each paragraph that follows.
     end      If specified, cancels the persistent temporary indentation established by previous ".ti <value> begin" directive
              (Note: begin and end require ppgen 3.49d or later.)

Example 1:

 enim ipsam voluptatem quia voluptas sit aspernatur aut odit
 aut fugit, sed quia consequuntur magni dolores eos qui
 ratione voluptatem sequi nesciunt.
 
 .in +6
 .ll -6
 
 .ti -2
 Emmylou Harris
  
 an American singer and songwriter. She has released many
 popular albums and singles over the course of her career,
 and has won 12 Grammys and numerous other awards.
 
 .ti -2
 Linda Rondstadt
  
 an American
 popular music singer. She has earned 11 Grammy Awards, two
 Academy of Country Music awards, an Emmy Award, an ALMA
 Award, and numerous United States and internationally
 certified gold, platinum and multiplatinum albums. She has
 also earned nominations for a Tony Award and a Golden Globe
 award.
 
 .ti -2
 Shania Twain
  
 born Eilleen Regina Edwards is a Canadian country pop
 singer-songwriter. Her 1995 album The Woman in Me brought
 her fame, and her 1997 album Come On Over became the
 best-selling studio album of all time by a female act in any
 genre and the best-selling country album of all time,
 selling over 40 million copies worldwide
 
 .in
 .ll
 
 Phasellus volutpat, metus eget egestas mollis, lacus lacus
 blandit dui, id egestas quam mauris ut lacus. Fusce vel dui.
 Sed in libero ut nibh placerat accumsan. Proin faucibus arcu

Example 2:

 .in 4        // indents following text by 4 spaces
 .ti -2 begin // indents the first line of each following paragraph by -2, giving
              // a hanging indent
 enim ipsam voluptatem quia voluptas sit aspernatur aut odit // indented -2
 aut fugit, sed quia consequuntur magni dolores eos qui
 ratione voluptatem sequi nesciunt.

 Phasellus volutpat, metus eget egestas mollis, lacus lacus // indented -2
 blandit dui, id egestas quam mauris ut lacus. Fusce vel dui.
 Sed in libero ut nibh placerat accumsan. Proin faucibus arcu
 .ti end      // cancels the persistent hanging indentation
 .in          // resets indentation value
 

Note: A value of 0 may be useful if you use indented paragraphs and have a paragraph that continues (unindented) after an interruption such as a verse of poetry.

Text Justification

Fully Justified (Default in HTML) or Ragged Right

Normally text is fully justified in HTML, spanning from the left-margin to the right margin.

In some cases, however, the PPer wants text that is "ragged right" instead of the normal justified left and right margins. Typically this is when displaying a list of short entries. To switch from fully justified to ragged right, use the ".na" or "no adjust" dot directive. The ".ad" dot directive turns justification back on. (Note: ragged right is the only option available for the text output files created by ppgen.)

Here is an example in a transcriber's note:

 .nf c
 Transcriber’s Notes
 .nf-
  
 .na
 .in +3
 .ti -3
 1. Copyright notice provided as in the original printed
 text—this e-text is public domain in the country of publication.
  
 .ti -3
 2. Silently corrected palpable typographical errors; retained
 non-standard spellings and dialect.
  
 .if t
 .ti -3
 3. Italic text in the original is delimited by _underscores_.
 .if-
 .in -3
 .ad

Right-Justified

Right justification for text is specified by the ".rj" dot command immediately before the line or lines.

 .rj     right justify next line
 .rj 3   right justfify next three lines

This is different than ".nf r" because with ".nf r" the entire block is right-justified but the individual lines of text within the block are left justified.

Centered

Centering for text is specified by the ".ce" dot command immediately before the line or lines. NOTE: .nf c provides an alternative to .ce which may be more convenient in some cases.

 .ce     center next line
 .ce 3   center next three lines

.rj can be used inside a block for such elements as titles and attributions.

Thought Breaks

A thought break will be rendered in the HTML as a thin line, 30% of the page width, centered on the page.
In the text output a thought break will be rendered as a centered row of 5 asterisks with 7 spaces between each.

.tb

Example of the format in text output files:

                 *       *       *       *       *

Vertical Spacing

Vertical spacing is used to assure a fixed gap, such as before a chapter header.

 .sp   Space one line vertically.
 .sp N Space N lines vertically.