doc/plugins/contrib/poetry.mdwn

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