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