1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
|
[[!meta author="spalax"]]
[[!template id=plugin name=poetry author="[[Louis|spalax]]"]]
# Poetry
The poetry plugin provides the [[ikiwiki/directive/poetry]] directive, used to
render poetry (or songs).
## Why?
### Typography
In regular text, there are two different meaning of a new line: a break between
two paragraphs, and the line wrap.
When rendering poetry, we need a third one: the carriage return between two
verse lines. This one should be different from the line wrap carriage return,
otherwise one will not be able to tell apart these two: is a word displayed at
the begenning of its line a new verse line, or the previous verse line,
continuing on a new line because it is too long?
Generally, wrapped text is indented, whereas verse lines are not.
### Markdown
One could use carriage return (two white spaces at the end of a line) between
verse lines, and paragraph break between stanzas, but:
* adding white spaces at the end of lines is painful;
* there is no easy way to render chorus (in a different way from verses).
## Usage
The directive takes only one argument `content`, containing the poetry to
render. Carriage returns are respected.
Chorus are lines with `> ` as a starting character.
Lines starting with `) ` are consored/outdated/crossed out verses.
[[!toggle id=example text="View example"]]
[[!toggleable id=example text='''
\[[!poetry content="""
This is a verse
Made of several lines
> And here is the chorus
> La la la!
> A beautiful chorus
Another verse
A bit longer
Than the previous one
) This one is deleted
) Because I did not like it
"""]]
''']]
## CSS
This plugin is useless without some corresponding CSS. An example is given
below.
[[!toggle id=css text="CSS"]]
[[!toggleable id=css text="""
.poetry {
padding-left: 1em;
border-left: 0.1em solid lightgray;
border-radius: 0.5em;
}
.poetry .stanza {
padding-left: 1em;
}
.poetry .paren {
font-style: italic;
font-size: smaller;
text-decoration: line-through;
}
.poetry .paren:hover {
text-decoration: initial;
}
.poetry .chorus {
margin-left: 0.1em;
padding-left: 2em;
border-left: 0.3em solid slategray;
}
.poetry .line {
display: block;
text-indent: -1em;
}
"""]]
## Example
This plugin is used to render songs on [this choir's
website](http://barricades.int.eu.org/repertoire/bread_and_roses/).
## Code
Code and documentation can be found here : [[https://atelier.gresille.org/projects/gresille-ikiwiki/wiki/Poetry]].
|