Template:Ppoem/doc



Usage
Ppoem, a.k.a. Proper Poem.


 * Parameters:
 * the poem content
 * ,  or  . You should use this if you use line or verse numbers and they don't occur in the first instance of the template (it's automatically determined if they do).
 * extra classes to set on the outer ppoem div
 * text-alignment to set on the outer ppoem div (e.g. )
 * extra styles to set on the outer ppoem div
 * the lang code to set for the outer ppoem div (same codes as lang, e.g.  or , etc.)

Special syntax:


 * Lines that start  are right aligned.
 * Lines that start  are centred.
 * Lines that end  have a line number "XXX" appended at the right, past the right margin
 * Lines that start  have a verse/line number "XXX" on the left, past the left margin
 * Lines that start  have the HTML class named   applied. This can be targeted by TemplateStyles CSS
 * Leading spaces are converted to
 * Leading colons are converted to

You can control the stanzas with similar syntax:
 * Blank lines start a new stanza.
 * Stanzas prefixed with  have the HTML class named   applied to the whole following stanza. This can be targeted by TemplateStyles CSS
 * Stanzas prefixed with  are block-right-aligned.
 * Stanzas prefixed with  are block-centred.

The lines have a default 4em hanging indent, which is roughly consistent with most printed poetry:

It can be disabled by giving any value to.

Page breaks
The template works across page breaks and produces a single poem container (unlike the  tag).

The and  parameters control how the sections join up. Each has four options:  (which is the default), ,   and  :


 * For the first section, use (or omit the parameter)
 * For a section that ends a stanza, use, and start the next one with
 * For a section that doesn't end a stanza (so the next section continues in the same stanza), the first section sets and the next uses.
 * For a line that continues onto the next page, the first section sets and the next uses.
 * For the last section, use (or omit).

This means that the parameter of one section and the  of the next must always be the same. It also means that for a simple poem in a single section, you do not need either or.

For example, for a template spanning four pages:

In the page namespace, the template always opens and closes the ppoem tags, so it will appear correctly in both page and mainspace (as long as any abutting ppoems on previous/following pages use matching and  parameters).

Drop initials
Floated content, such as dropinitials, should be placed as normal:

Braces
Braced lines work as expected (using the  syntax for right-floats):

Floating punctuation
No changes are needed for floating punctuation, e.g. with fqm

Gutter width
Some poems have very long line numbers. In this case, the default gutter width of  may not be enough. You can modify the gutters of poems using the Index-based CSS and set a wider padding on the left or right of relevant  elements.

Poems with a left gutter are denoted by the class  on the top-level poem container, added automatically when the   syntax is used, or  is set to   or  ). Right gutters (  syntax or  set to   or  ) work the same way.

In the case below, every poem in a given work that has a left gutter has the line padding increased to 3em:

Comparison with
Below is a comparison of the output of this template and the  tag (or manual , which is equivalent), rendered as an EPUB on an e-reader.

With poem tag/ :



With ppoem, there are hanging indents and right-alignment not causing a paragraph break:



Advantages

 * Simple syntax for common cases
 * Handles hanging indent which resolves the problem of ambiguous new lines
 * Semantically more correct: lines are spans, and stanzas are paragraphs, poems are divs
 * Can continue a line across a page break (which can't be done with )
 * Combines into a single element even when transcluded from multiple pages
 * Copy-pastes as separate lines
 * Exports sensibly
 * Automatic block-centering (which can't be done with  because the separate elements don't have the same widths)
 * Very easy to apply CSS classes to lines or stanzas
 * Drop-in replacement for

Disadvantages

 * Some care is needed to match the and  parameters across pages.
 * Dropinitials can sometimes cause a line to wrap prematurely (can be avoided by adding length to the first line, such as with em).
 * Because this is a single template and cannot be split, poems must escape  and   character

Template data
{	"params": { "1": {			"description": "The poem content", "example": "Once upon a midnight dreary, while I pondered, weak and weary,\nOver many a quaint and curious volume of forgotten lore,", "type": "content", "required": true },		"start": { "description": "The start type: one of open, stanza, follow, same-line. If this is not \"open\", this MUST use the same value as the previous 's \"end\" parameter.", "example": "stanza", "type": "line", "suggested": true },		"end": { "description": "The closure type: one of close, stanza, follow, same-line. If this is not \"close\", the next MUST use the same value for it's \"start\" parameter.", "example": "stanza", "type": "line", "suggested": true },		"lang": { "description": "Language code to apply to the whole poem", "example": "la", "type": "line", "suggestedvalues": [ "en", "fr", "grc", "la", "es", "de", "ang", "enm", "it" ]		},		"class": { "description": "CSS classes to add to the entire poem. Use this if you would like to target the whole poem for styling with a CSS rule.", "example": "chapter-head-poem", "type": "line" }	},	"description": "Format a poem nicely", "format": "inline" }