Template:Ppoem

Template documentation

[view] [edit] [history] [purge]

Usage

Ppoem, a.k.a. Proper Poem.

Parameters

• 1 the poem content
• gutter left, right or both. 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).
• class extra classes to set on the outer ppoem div
• align text-alignment to set on the outer ppoem div (e.g. center)
• style extra styles to set on the outer ppoem div
• lang the lang code to set for the outer ppoem div (same codes as {{lang}}, e.g. fr or la, etc.)

Special syntax:

• Lines that start >> are right aligned.
• Lines that start <> are centred.
• Lines that end >>> XXX have a line number "XXX" appended at the right, past the right margin
• Lines that start XXX <<< have a verse/line number "XXX" on the left, past the left margin
• Lines that start {class} have the HTML class named class 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 {class} have the HTML class named class 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.

Example

{{ppoem|
1 <<< {{di|O}}nce upon a midnight dreary, while I pondered, weak and weary,
Over many a quaint and curious volume of forgotten lore,
{{fqm|"}}While I nodded, nearly napping, suddenly there came a tapping,
 As of some one gently rapping, rapping at my chamber door.
"'Tis some visiter," I muttered, "tapping at my chamber door— >>> 5
::::::{raven_green} Only this, and nothing more."
>> {{sc|The Raven}}

{raven_green}
2 <<< This stanza has the class <code>raven_green</code> applied
To the whole stanza.

>>
This stanza is block-right-aligned
Like this

<>
And this stanza is block-centred
Like this

>> {{sc|The Raven}}

<> ''The End''
}}

1 Once upon a midnight dreary, while I pondered, weak and weary,
Over many a quaint and curious volume of forgotten lore,
"While I nodded, nearly napping, suddenly there came a tapping,
As of some one gently rapping, rapping at my chamber door.
5"'Tis some visiter," I muttered, "tapping at my chamber door—
      Only this, and nothing more."

2 This stanza has the class raven_green applied
To the whole stanza.

This stanza is block-right-aligned
Like this

And this stanza is block-centred
Like this

The Raven

The End

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

Example

{{block center|width=25em|style=border:1px solid red;|
{{ppoem|
Once upon a midnight dreary, while I pondered, weak and weary,
Over many a quaint and curious volume of forgotten lore,
While I nodded, nearly napping, suddenly there came a tapping,
As of some one gently rapping, rapping at my chamber door.
"'Tis some visiter," I muttered, "tapping at my chamber door—
::::::Only this, and nothing more."
}}
}}

Once upon a midnight dreary, while I pondered, weak and weary,
Over many a quaint and curious volume of forgotten lore,
While I nodded, nearly napping, suddenly there came a tapping,
As of some one gently rapping, rapping at my chamber door.
"'Tis some visiter," I muttered, "tapping at my chamber door—
      Only this, and nothing more."

Page breaks

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

The start and end parameters control how the sections join up. Each has four options: open/close (which is the default), follow, stanza and same-line:

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

This means that the end parameter of one section and the start 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 start or end.

For example, for a template spanning four pages:

Example

{{ppoem|end=follow|
This is the first
page and the stanza
}}

{{ppoem|start=follow|end=stanza|
continues into this page.

But then, the second
page ends at the end of
a stanza.}}

{{ppoem|start=stanza|end=same-line|
And the next page
is a new stanza.
Then there is a really long
}}

{{ppoem|start=same-line|end=close|
''line that continues onto the next page.''

And finally normal
Lines to the end.
}}

This is the first
page and the stanza
continues into this page.

But then, the second
page ends at the end of
a stanza.

And the next page
is a new stanza.
Then there is a really long line that continues onto the next page.

And finally normal
Lines to the end.

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 start and end parameters).

Drop initials

Floated content, such as {{dropinitial}}s, should be placed as normal:

Example

{{ppoem|
{{dropinitial|B|image=Examination and confession-b24926760-025.jpg|imgsize=80px}}EHOLD these acts and scan them well
behold their pervers way:
These left the lord, these did his truth
which shold have ben their stay.

{{dropinitial|B}}EHOLD these acts and scan them well
behold their pervers way:
These left the lord, these did his truth
which shold have ben their stay.

{{dropinitial|B|fl="}}EHOLD these acts and scan them well
behold their pervers way:
These left the lord, these did his truth
which shold have ben their stay.
}}

EHOLD these acts and scan them well
behold their pervers way:
These left the lord, these did his truth
which shold have ben their stay.

BEHOLD these acts and scan them well
behold their pervers way:
These left the lord, these did his truth
which shold have ben their stay.

"BEHOLD these acts and scan them well
behold their pervers way:
These left the lord, these did his truth
which shold have ben their stay.

Braces

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

Example

{{ppoem|
No Place so Sacred from such Fops is barr'd,
Nor is ''Paul's Church'' more safe than ''Paul's Church-yard'':
Nay, run to ''Altars''; ''there'' they'll talk you dead;
For ''Fools'' rush in where ''Angels'' fear to tread.
Distrustful ''Sense'' with modest Caution speaks; >>> {{brace2|3|r}}
It still ''looks home'', and ''short Excursions'' makes;
But ''ratling'' Nonsense in full ''Vollies'' breaks;
}}

No Place so Sacred from such Fops is barr'd,
Nor is Paul's Church more safe than Paul's Church-yard:
Nay, run to Altars; there they'll talk you dead;
For Fools rush in where Angels fear to tread.
$\scriptstyle {\left.{\begin{matrix}\ \\\\\ \ \end{matrix}}\right\}\,}$Distrustful Sense with modest Caution speaks;
It still looks home, and short Excursions makes;
But ratling Nonsense in full Vollies breaks;

Floating punctuation

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

Example

{{ppoem|
{{fqm}}No Place so Sacred from such Fops is barr'd,
Nor is ''Paul's Church'' more safe than ''Paul's Church-yard'':
Nay, run to ''Altars''; ''there'' they'll talk you dead;
}}

"No Place so Sacred from such Fops is barr'd,
Nor is Paul's Church more safe than Paul's Church-yard:
Nay, run to Altars; there they'll talk you dead;

Gutter width

Some poems have very long line numbers. In this case, the default gutter width of 2em 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 .ws-poem-line elements.

Poems with a left gutter are denoted by the class .ws-poem-left-gutter on the top-level poem container, added automatically when the <<< syntax is used, or gutter is set to left or both). Right gutters (>>> syntax or gutter set to right or both) 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:

/* Increase the gutter because the line numbers have up to 4 digits */
.ws-poem-left-gutter .ws-poem-line {
	padding-left: 3em;
}

Comparison with <poem>

Below is a comparison of the output of this template and the <poem> tag (or manual <br/>, which is equivalent), rendered as an EPUB on an e-reader.

With poem tag/<br/>:

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 <poem>)
• 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 <poem> because the separate elements don't have the same widths)
• Very easy to apply CSS classes to lines or stanzas
• Drop-in replacement for <poem>

Disadvantages

• Some care is needed to match the start and end parameters across pages.
• Dropinitials can sometimes cause a line to wrap prematurely
• Because this is a single template and cannot be split, poems must escape = and | character^[1]

Notes

1. Unless it becomes an extension.

Template data

This is the TemplateData documentation for this template used by VisualEditor and other tools.

Ppoem

Format a poem nicely

Template parameters[Edit template data]

This template prefers inline formatting of parameters.

Parameter		Description	Type	Status
1	1	The poem content Example Once upon a midnight dreary, while I pondered, weak and weary, Over many a quaint and curious volume of forgotten lore,	Content	required
start	start	The start type: one of open, stanza, follow, same-line. If this is not "open", this MUST use the same value as the previous {{ppoem}}'s "end" parameter. Example stanza	Line	suggested
end	end	The closure type: one of close, stanza, follow, same-line. If this is not "close", the next {{ppoem}} MUST use the same value for it's "start" parameter. Example stanza	Line	suggested
lang	lang	Language code to apply to the whole poem Suggested values en fr grc la es de ang enm it Example la	Line	optional
class	class	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	Line	optional

See also

• Help:Poetry

The above documentation is transcluded from Template:Ppoem/doc. (edit | history)
Editors can experiment in this template’s sandbox (create | mirror) and testcases (create) pages.
Please add categories to the /doc subpage. Subpages of this template.