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