Template:Ppoem/doc

From Wikisource
Jump to navigation Jump to search

Usage[edit]

Ppoem, a.k.a. Proper Poem.

Twklstar.gif DRAFTTwklstar.gif

This template/module is far from being mature but aspires to become a standard means of formatting poems with correct semantic markup and hanging indents for use on WikiSource. Please note bugs/shortcomings/suggestions on the talk page.

Please don't use it for real works yet.

The plan here is:

  • Make sure the generated markup is acceptable:
    • Semantically decent Seems OK (ish)
    • Works on Wiki, in all layouts Seems OK
    • Works on Mobile Seems OK
    • Works in exports Seems OK
  • Define the "data model": what data does ppoem need?
    • Start/end types
      • So far, start/end, follow and stanza
    • Extra classes, styles etc
  • Define "magic" syntax like <<
  • <<<: Left overfloat (verse num)
  • >>>: Right overloat (line num)
  • >>: Right aligned content
  • <> Centred
  • Can we get away without an extension?
    • Pros of extension:
      • Don't need to escape for template syntax (equals and pipe, mostly)
      • Less on wiki code
      • Less template/Lua resources used (might not be an issue)
    • Cons:
      • Very hard to maintain, minimal dev interest
      • Very slow to roll out
    • If an extension is decided, as long as the data model is set, it should be an easy transition, as long as it's possible to map this template's model to the extension's model. So moving to an extension is always possible.
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.
  • class extra classes to set on the outer ppoem div
  • style extra styles to set on the outer ppoem div

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 &nbsp;
  • Leading colons are converted to &emsp;

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

<> ''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[edit]

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 three options: follow, stanza and open/close (which is the default).

  • 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 three 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 last 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 last 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[edit]

Floated content, such as {{dropinitial}}s, should be placed before the line, using the << syntax:

Example

{{ppoem|1=
{{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.
}}
}}

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.

" 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.

Comparison with <poem>[edit]

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/>:

Wikisource poem formatting - poem tag epub.png

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

Wikisource poem formatting - ppoem epub.png

Advantages[edit]

  • 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> (except for {{di}} and {{fqm}}, which need << before them)

Disadvantages[edit]

  • Some care is needed to match the start and end parameters across pages.
  • The CSS to produce per-line hanging indents can cause minor misalignments
  • 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[edit]

  1. Unless it becomes an extension.

Template data[edit]

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

Ppoem

Format a poem (experimental!)

Template parameters

This template prefers inline formatting of parameters.

ParameterDescriptionTypeStatus
11

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,
Contentrequired
startstart

The start type: one of open, stanza, follow, same-line

Example
stanza
Linesuggested
endend

The closure type: one of close, stanza, follow, same-line

Example
stanza
Linesuggested

See also[edit]