renamed: man.muse -> MANUAL.muse
[amuse-wiki:amuse-wiki.git] / doc / MANUAL.muse
1 #author Various
2
3 #title The Wiki Muse Manual
4
5 #lang en
6
7 #subtitle The writer's guide
8
9 #SORTauthors John Wiegley, Michael Olson, Marco Pessotto
10
11 #date 2012
12
13 #SORTtopics markup; how-to; syntax, test;
14
15 #source [[http://theanarchistlibrary.org]]
16
17 #notes This document describes Muse, which was written by John
18 Wiegley, then maintained by Michael Olson and edited for this
19 implementation by Marco Pessotto.
20
21
22 Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software
23 Foundation, Inc.
24
25      Permission is granted to copy, distribute and/or modify this
26      document under the terms of the GNU Free Documentation License,
27      Version 1.2 or any later version published by the Free Software
28      Foundation; with no Invariant Sections, no Front-Cover Texts, and
29      no Back-Cover Texts.  A copy of the license is included in the
30      section entitled “GNU Free Documentation License.”
31
32 * The Muse markup
33
34 A Muse document uses special, contextual markup rules to determine how
35 to format the output result.  For example, if a paragraph is indented,
36 Muse assumes it should be quoted. Indentation is heavily used to
37 determine if the paragraph is something different from “normal” text.
38
39 There are not too many markup rules, and all of them strive to be as
40 simple as possible so that you can focus on document creation, rather
41 than formatting.
42
43
44 ** Paragraphs
45
46 [[idx][paragraphs]]
47 Paragraphs in Muse must be separated by a blank line.
48
49 *** Centered and right aligned paragraphs and quotations
50
51 [[idx][centering]]
52 A line that begins with six or more columns of whitespace
53 (but less than 20) indicates a centered paragraph.
54
55 Alternatively, you can use the =<center>= tag to surround regions that
56 are to be published as centered paragraphs.
57
58            Like this
59
60 [[idx][right-align]]
61 But if the line begins with more than 20 spaces, you'll have a right
62 aligned paragraph. This is handy for signatures.
63
64                                      Like this right-aligned one.
65
66 The same result is done with the =right= tag.
67
68 Using the tags:
69
70 <center>
71 Like this centered one
72 </center>
73
74 <right>
75 And this is right
76 </right>
77
78 This is a quotation:
79
80   [[idx][quotations]]
81   But if a line begins with whitespace (at least 2 spaces), though
82   less than six columns, it indicates a quoted paragraph.
83   Alternatively, you can use the =<quote>= tag to surround regions that
84   are to be published as quoted paragraphs.
85
86 **** Source
87
88 <example>
89 A line that begins with six or more columns of whitespace
90 (but less than 20) indicates a centered paragraph.
91
92 Alternatively, you can use the =<center>= tag to surround regions that
93 are to be published as centered paragraphs.
94
95            Like this
96
97 But if the line begins with more than 20 spaces, you'll have a right
98 aligned paragraph. This is handy for signatures.
99
100                                      Like this right-aligned one.
101
102 The same result is done with the =right= tag.
103
104 Using the tags:
105
106 <center>
107 Like this centered one
108 </center>
109
110 <right>
111 And this is right
112 </right>
113
114 This is a quotation:
115
116   But if a line begins with whitespace (at least 2 spaces), though
117   less than six columns, it indicates a quoted paragraph.
118   Alternatively, you can use the =<quote>= tag to surround regions that
119   are to be published as quoted paragraphs.
120 </example>
121
122 [[idx][indentation]]
123 **Please keep in mind that indentation must be consistent if you prefer
124 to keep the lines short** and break them inserting a new line. Long
125 lines (using the rule 1 line, 1 paragraph) are perfectly fine. The
126 rule of paragraphs separated by blank lines still apply, though.
127
128 Also, =<tags>= which start and stop blocks, **must be placed on a line by
129 themselves**.
130
131 *** Literal paragraphs
132
133 [[idx][verbatim]] [[idx][examples]]
134 The =<example>= tag is used for examples, where whitespace should be
135 preserved, the text rendered in monospace, and any characters special
136 to the output style escaped.
137
138 Example:
139
140 <example>
141  <example>
142  The =<example>= tag is used for examples, where whitespace
143  should be preserved, the text rendered in monospace, and any
144  characters special to the output style escaped.
145  </example>
146 </example>
147
148 There is no =<literal>= tag as in the original Muse markup, because it's
149 not a private tool and will be exposed to the internet.
150
151 *** Line breaks
152
153 [[idx][line breaks]]
154 If you need a line break, then use the =br= tag.  Most of the time
155 this tag is unnecessary, because Muse will automatically detect
156 paragraphs by means of blank lines.  If you want to preserve newlines in
157 several lines of text, then use =verse= markup instead.
158
159 <example>
160 This line will break <br> And continue
161 </example>
162
163 Yields:
164
165 This line will break <br> And continue.
166
167 <br>
168
169 If you want to add a blank, line, put the =br= tag on a line by itself:
170
171 <example>
172 Here we add a blank line
173 <br>
174 Here we go.
175 </example>
176
177 Here we add a blank line
178 <br>
179 Here we go.
180
181
182 ** Levels of headings
183
184 [[idx][headings]] [[idx][chapters]] [[idx][sectioning]]
185 A heading becomes a chapter or section in printed output - depending on
186 the style.  To indicate a heading, start a new paragraph with one or
187 more asterices, followed by a space and the heading title.  Then begin
188 another paragraph to enter the text for that section.
189
190 All levels of headings will be published. There is support for 5 levels.
191
192 The first level is a "part", and should be used only for larger texts. In this document is used for the License and for the main title.
193
194 The second level is a "chapter". It starts a new page on the PDF output.
195
196 The third level is undoubtely the most used. It usually separate a
197 section of an article. For example the "Literal paragraph" above.
198
199 The forth level goes down further.
200
201 **** Forth level, a “subsection”
202
203 The fifth level is very, very low. It's handy to create description
204 lists, too. It's not dumped on the Table of Contents.
205
206 ***** item 1
207
208 A description
209
210 ***** item 2
211
212 Another description
213
214 **** The example of levels
215
216 <example>
217 * First level, aka part
218
219 ** Second level, aka chapter
220
221 *** Third level, aka section
222
223 **** Fourth level, aka subsection
224
225 ***** Fifth level, aka subsubsection
226 </example>
227
228 ** Directives at the beginning of a document
229
230 Directives are lines beginning with the `#' character that come before
231 any paragraphs or sections in the document.  Directives are of the form
232 "#directive content of directive".
233
234 Directives are lines beginning with the `#' character that come before
235 any paragraphs or sections in the document.  Directives are of the form
236 "#directive content of directive".  You can use any combination of
237 uppercase and lowercase letters for directives, even if the directive
238 is not in the list below.
239
240    The following is a list of directives that Muse uses.
241
242  - `#author'
243    The author of this document.
244
245  - `#date'
246     The date that the document was last modified.
247
248  - `#desc'
249    A short description of this document.
250
251    This is used to embed information inside of an RSS/RDF feed.
252
253  - `#title'
254    The title of this document.
255
256    If this is not specified, the name of the file is used.
257
258
259
260
261 ** Bold, italicized and emphatized text
262
263 [[idx][emphasis]] [[idx][bold]] [[idx][monospace]]
264 To emphasize text, surround it with certain specially recognized
265 characters.
266
267 The following example will produce:
268
269      *emphasis*
270      **strong emphasis**
271      ***very strong emphasis***
272      =verbatim and monospace=
273
274 <example>
275      *emphasis*
276      **strong emphasis**
277      ***very strong emphasis***
278      =verbatim and monospace=
279 </example>
280
281 Each of these forms may span
282 multiple lines, but not multiple paragraphs.
283
284 You can also use the =<code>= tag to indicate verbatim and monospace
285 text. This is handy for regions that have an "=" in them.
286
287 If the “*” confuse you or the preview is screwed up, you can use
288 inline tag =<em>= and =<strong>=, which are guarantee to work in any case.
289
290 The above example rewritten with tags:
291
292 <example>
293      <em>emphasis</em>
294      <strong>strong emphasis</strong>
295      <strong><em>very strong emphasis</em></strong>
296      <code>verbatim and monospace</code>
297 </example>
298
299 And produces the same thing.
300
301      <em>emphasis</em>
302      <strong>strong emphasis</strong>
303      <strong><em>very strong emphasis</em></strong>
304      <code>verbatim and monospace</code>
305
306 Please note that there is no support for the underline. Underlining is
307 an handwritten substitute for the italics. You simply don't need it.
308
309 Also, small caps are missing, mainly because on the HTML they look
310 awful and a very few fonts have decent small caps.
311
312 [[idx][superscript]] [[idx][subscript]] [[idx][overstriking]]
313 Other tags are =<sub>= and =<sup>= for subscript and superscript. And
314 there is also a =<del>= tag for overstriking.
315
316 <example>
317 This is the <sup>superscript</sup> and this is a
318 <sub>subscript</sub>, and this is <del>something deleted and
319 overstriked</del>
320 </example>
321
322 This is the <sup>superscript</sup> and this is a
323 <sub>subscript</sub>, and this is <del>something deleted and
324 overstriked</del>
325
326 *** Making notes to be shown at the end
327
328 A footnote reference is simply a number in square brackets.  To define
329 the footnote, place this definition starting the line with a digit in
330 square brackets. [[idx][footnotes]]
331
332 <example>
333 This is the text, and we refer to a footnote [1]
334
335 Here the text continues.
336
337 [1] This footnote
338     spans more lines in the source
339
340  [2] But this is not, because of the initial whitespace.
341
342 [3] Footnotes which don't have a referrer will disappear on the PDF
343     output and preserverd in the HTML. But will lead to incorrect
344     code, as it will point to a non-existent anchor
345 </example>
346
347 This is the result:
348
349 ----
350
351 This is the text, and we refer to a footnote [1]
352
353 Here the text continues.
354
355 [1] This footnote
356     spans more lines in the source
357
358  [2] But this is not, because of the initial whitespace.
359
360 [3] Footnotes which don't have a referrer will disappear on the PDF
361     output and preserverd in the HTML. But will lead to incorrect
362     code, as it will point to a non-existent anchor
363
364 ----
365
366 You can break the footnotes lines (even if it's not reccomended), but keep the indentation consistent, as shown above
367
368 *** Indicating poetic stanzas
369
370 [[idx][poetry]]
371 Poetry requires that whitespace be preserved, but without resorting to
372 monospace.  To indicate this, use the following markup, reminiscent of
373 email quotations, or use the =verse= tag.
374
375 <example>
376 > A line of Emacs verse;
377 >   forgive its being so terse.
378
379 <verse>
380      A line of Emacs verse;
381        forgive its being so terse.
382 </verse>
383 </example>
384
385 This yields:
386
387 > A line of Emacs verse;
388 >   forgive its being so terse.
389
390 <verse>
391      A line of Emacs verse;
392        forgive its being so terse.
393 </verse>
394
395 Multiple stanzas may be included in one set of <verse> tags, as
396 follows.
397
398 <example>
399 <verse>
400 A line of Emacs verse;
401   forgive its being so terse.
402
403 In terms of terse verse,
404   you could do worse.
405 </verse>
406
407 Or this
408
409 > A line of Emacs verse;
410 >   forgive its being so terse.
411
412 > In terms of terse verse,
413 >   you could do worse.
414
415 </example>
416
417 <verse>
418 A line of Emacs verse;
419   forgive its being so terse.
420
421 In terms of terse verse,
422   you could do worse.
423 </verse>
424
425 Or this
426
427 > A line of Emacs verse;
428 >   forgive its being so terse.
429 >
430 > In terms of terse verse,
431 >   you could do worse.
432
433 ** Lists
434
435 [[idx][lists]]
436 Lists are given using special characters at the beginning of a line.
437 Whitespace must occur before bullets or numbered items, to distinguish
438 from the possibility of those characters occurring in a real sentence.
439
440 <example>
441 Normal text.
442
443       - bullet item one
444       - bullet item two
445
446 An enumerated list follows.
447
448       1. Enum item one
449       2. Enum item two
450
451 A list with roman numbering
452
453  i.   First
454  ii.  Second
455  iii. Third
456
457 A list with upper roman numbering
458
459  I.   First
460  II.  Second
461  III. Third
462
463 A list with upper letters
464
465  A. first
466  B. second
467  C. third
468
469 A list with upper letters
470
471  a. first
472  b. second
473  c. third
474 </example>
475
476 Please note the consistent indentation, **expecially** for roman numbering.
477
478 Normal text.
479
480       - bullet item one
481       - bullet item two
482
483 An enumerated list follows.
484
485       1. Enum item one
486       2. Enum item two
487
488 A list with roman numbering
489
490  i.   First
491  ii.  Second
492  iii. Third
493
494 A list with upper roman numbering
495
496  I.   First
497  II.  Second
498  III. Third
499
500 A list with upper letters
501
502  A. first
503  B. second
504  C. third
505
506 A list with upper letters
507
508  a. first
509  b. second
510  c. third
511
512 While the original Emacs Muse had the description lists, this
513 implementation has not. You should use the fifth level of headings for
514 those. The outcome is mostly the same (yes, you can't nest them in
515 lists, but crazy nesting is beyond the scope of this markup).
516
517 *** Nested lists
518
519 It is possible to nest lists of the same or different kinds.  The
520 "level" of the list is determined by the amount of initial whitespace.
521
522 <example>
523 Normal text.
524
525  - Level 1, bullet item one
526    1. Level 2, enum item one
527    2. Level 2, enum item two
528  - Level 1, bullet item two
529    1. Level 2, enum item one
530    2. Level 2, enum item two
531       i.  Level 3, enum item i
532       ii. Level 3, enum item ii
533    3. Level 2, enum item three
534  - Back to Level 1, third bullet
535    a. Level 2, enum item “a”
536    b. Level 2, enum item “b”
537       I. Level 3, enum item “I”
538  - Back to the bullets
539 </example>
540
541 Normal text.
542
543  - Level 1, bullet item one
544    1. Level 2, enum item one
545    2. Level 2, enum item two
546  - Level 1, bullet item two
547    1. Level 2, enum item one
548    2. Level 2, enum item two
549       i.  Level 3, enum item i
550       ii. Level 3, enum item ii
551    3. Level 2, enum item three
552  - Back to Level 1, third bullet
553    a. Level 2, enum item “a”
554    b. Level 2, enum item “b”
555       I. Level 3, enum item “I”
556  - Back to the bullets
557
558 *** Breaking list items
559
560 If you want to break up a line within any list type, just put one blank
561 line between the end of the previous line and the beginning of the next
562 line, using the same amount of initial indentation.
563
564 Keep in mind that if you put random indentation you'll get random and
565 probably unexpected results (but it should not crash -- if it does,
566 please contact me).
567
568 Also, you can be lazy with numbered list. The parser actually doesn't
569 care if you number them properly, or just do something like that.
570
571 <example>
572  1. first
573  1. second
574  1. third
575
576 or
577
578  a. first
579  a. second
580  a. third
581 </example>
582
583 There results will always be:
584
585  1. first
586  1. second
587  1. third
588
589 or
590
591  a. first
592  a. second
593  a. third
594
595 If you need to switch type while the list is running, put a =br= tag
596 between them, or some invisible material like an anchor.
597
598 <example>
599 This won't get you what you expect:
600
601  1. first
602  a. first item
603
604 So you'll have to do:
605
606  1. first
607 <br>
608  a. first item
609 </example>
610
611 Which yields:
612
613 ----
614
615 This won't get you what you expect:
616
617  1. first
618  a. first item
619
620 So you'll have to do:
621
622  1. first
623 <br>
624  a. first item
625
626 ----
627
628 *** Complete example
629
630 <example>
631 Normal text.
632
633  - Level 1, bullet item one, this is the first paragraph. I can break
634    the line, keeping the same amount of indentation
635
636    Here I have the same amount of indentation, and it continues the
637    item above.
638
639    1. Level 2, enum item one. i can break the line, keeping the same
640       amount of indentation
641
642       Here I have the same amount of indentation, and it continues the
643       item above.
644
645    2. Level 2, enum item two
646       which continues
647
648       Here I have the same amount of indentation, and it continues the
649       item above.
650
651  - Level 1, bullet item two
652    which continues
653
654    Here I have the same amount of indentation, and it continues the
655    item above.
656
657    1. Level 2, enum item one
658       which continues
659
660       Here I have the same amount of indentation, and it continues the
661       item above.
662
663    2. Level 2, enum item two
664       which continues
665
666       Here I have the same amount of indentation, and it continues the
667       item above.
668
669       i.  Level 3, enum item i
670
671           Here I have the same amount of indentation, and it continues
672           the item above.
673
674       ii. Level 3, enum item ii
675
676           Here I have the same amount of indentation, and it continues
677           the item above.
678
679    3. Level 2, enum item three
680       which continues
681
682       Here I have the same amount of indentation, and it continues the
683       item above.
684
685  - Back to Level 1, third bullet
686
687    Here I have the same amount of indentation, and it continues the
688    item above.
689
690    a. Level 2, enum item “a”
691       which continues
692
693       Here I have the same amount of indentation, and it continues the
694       item above.
695
696    b. Level 2, enum item “b”
697       which continues
698
699       Here I have the same amount of indentation, and it continues the
700       item above.
701
702          I. Level 3, enum item “I”
703
704             Here I have the same amount of indentation, and it continues the
705             item above.
706
707  - Back to the bullets
708
709    Here I have the same amount of indentation, and it continues the
710    item above.
711
712 </example>
713
714 Normal text.
715
716  - Level 1, bullet item one, this is the first paragraph. I can break
717    the line, keeping the same amount of indentation
718
719    Here I have the same amount of indentation, and it continues the
720    item above.
721
722    1. Level 2, enum item one. i can break the line, keeping the same
723       amount of indentation
724
725       Here I have the same amount of indentation, and it continues the
726       item above.
727
728    2. Level 2, enum item two
729       which continues
730
731       Here I have the same amount of indentation, and it continues the
732       item above.
733
734  - Level 1, bullet item two
735    which continues
736
737    Here I have the same amount of indentation, and it continues the
738    item above.
739
740    1. Level 2, enum item one
741       which continues
742
743       Here I have the same amount of indentation, and it continues the
744       item above.
745
746    2. Level 2, enum item two
747       which continues
748
749       Here I have the same amount of indentation, and it continues the
750       item above.
751
752       i.  Level 3, enum item i
753
754           Here I have the same amount of indentation, and it continues
755           the item above.
756
757       ii. Level 3, enum item ii
758
759           Here I have the same amount of indentation, and it continues
760           the item above.
761
762    3. Level 2, enum item three
763       which continues
764
765       Here I have the same amount of indentation, and it continues the
766       item above.
767
768  - Back to Level 1, third bullet
769
770    Here I have the same amount of indentation, and it continues the
771    item above.
772
773    a. Level 2, enum item “a”
774       which continues
775
776       Here I have the same amount of indentation, and it continues the
777       item above.
778
779    b. Level 2, enum item “b”
780       which continues
781
782       Here I have the same amount of indentation, and it continues the
783       item above.
784
785          I. Level 3, enum item “I”
786
787             Here I have the same amount of indentation, and it continues the
788             item above.
789
790  - Back to the bullets
791
792    Here I have the same amount of indentation, and it continues the
793    item above.
794
795 ** Generation of data tables
796
797 [[idx][tables]]
798 Only very simple tables are supported.  The syntax is as follows (just keep the indentation consistent and separate each cell by one or more textbars.
799
800 <example>
801      Triple bars ||| Separate footer fields
802      Double bars  || Separate header fields
803      Single bars   | Separate body fields
804      Here are more | body fields
805      |+ This is the caption +|
806 </example>
807
808      Triple bars ||| Separate footer fields
809      Double bars  || Separate header fields
810      Single bars   | Separate body fields
811      Here are more | body fields
812      |+ This is the caption +|
813
814 The ordering of the footer, header and table body blocks is irrelevant
815 for the output (HTML requires you put first the header, then the
816 footer, then the body). Ordering of the single rows is of course
817 preserved. From this we come to the conclusion that you can't normally
818 typeset the pipe symbol without triggering a list. In =<example>= you
819 can type it freely. Inside the cells you can do pretty much what you
820 want (beside headers and lists): mark them up freely.
821
822 ** Hyperlinks with or without description (and images)
823
824 [[idx][links]]
825 A hyperlink can reference a URL or a place on the same document.  In
826 addition, descriptive text can be specified, which should be displayed
827 rather than the link text in output styles that supports link
828 descriptions.  The syntax is as follows.
829
830 <example>
831      [[link target][link description]]
832      [[link target without description]]
833
834 So, the home of this project is
835 [[http://theanarchistlibrary.org][The Anarchist Library]],
836 which can be found at [[http://theanarchistlibrary.org]]
837 Bare links will not get the hyperlinking.
838 So http://thisisspam.org won't get the hyperlinking.
839 </example>
840
841 So, the home of this project is
842 [[http://theanarchistlibrary.org][The Anarchist Library]],
843 which can be found at [[http://theanarchistlibrary.org]]
844 Bare links will not get the hyperlinking.
845 So http://thisisspam.org won't get the hyperlinking.
846
847 *** Images
848
849 [[idx][images]]
850 Images are special case of this kind of linking.
851
852 <example>
853 [[titlebanner.png]]
854 </example>
855
856 We assume that we have the “titlebanner.png” file on the same
857 directory of the file, and the result is:
858
859 [[titlebanner.png]]
860
861 Now, let's add a caption.
862
863 <example>
864 [[titlebanner.png][This is our banner]]
865 </example>
866
867 [[titlebanner.png][This is our banner]]
868
869 Remote urls are not permitted. Also, the patch checking is rather strict, so please use just alphanumeric filenames for your images.
870
871 If you just want to link to the image, add the URL:
872
873 <example>
874 [[URL:titlebanner.png]]
875 </example>
876
877 [[URL:titlebanner.png]]
878
879 ** Inserting a horizontal line or anchor
880
881 *** Horizontal Rules
882
883 [[idx][rules]]
884 Four or more dashes indicate a horizontal rule.  Be sure to put blank
885 lines around it, or it will be considered part of the proceeding or
886 following paragraph, like this: ---------.
887
888 Example
889
890 <example>
891 ----
892 </example>
893
894 Results:
895
896 ----
897
898 *** Anchors
899
900 [[idx][anchors]]
901
902 <example>
903 #anchordesc If you begin a line with "#anchor" - where "anchor" can be
904 any word that doesn't contain whitespace - it defines an anchor at
905 that point into the document.  This point can be referenced using
906 "#anchor" as the target in a Muse link. [[#anchordesc][Muse link]]
907 </example>
908
909 #anchordesc If you begin a line with "#anchor" - where "anchor" can be
910 any word that doesn't contain whitespace - it defines an anchor at
911 that point into the document.  This point can be referenced using
912 "#anchor" as the target in a Muse link. [[#anchordesc][Muse link]]
913
914 As you can see, in the pdf output the page number is added
915 automatically. So you have to pay attention and add the relevant keyword PDF: **and** WEB:
916
917 <example>
918 #anchordesc2 If you begin a line with "#anchor" - where "anchor" can be
919 any word that doesn't contain whitespace - it defines an anchor at
920 that point into the document.  This point can be referenced using
921 "#anchor" as the target in a Muse link.
922 [[#anchordesc2][PDF: See page WEB:See here]]
923 </example>
924
925 #anchordesc2 If you begin a line with "#anchor" - where "anchor" can be
926 any word that doesn't contain whitespace - it defines an anchor at
927 that point into the document.  This point can be referenced using
928 "#anchor" as the target in a Muse link.
929 [[#anchordesc2][PDF: See page WEB:See here]]
930
931 ** Lines to omit from published output
932
933 <example>
934 ; Comment text goes here.
935 </example>
936
937 ; this will disappear completely
938
939 That is, only a semi-colon at the beginning of a line, followed by a
940 literal space, will cause that line to be treated as a comment and
941 **totally removed from the output.** [[idx][comments]]
942
943 You can alternatively surround the region with the =<comment>= tag. In
944 this case the HTML output will be wrapped in a =<div>= with the
945 =display:none= property, so it can be turned visibile changing the
946 CSS.
947
948 <example>
949 <comment>
950 This won't be published, but in the HTML is there, only hidden
951 </comment>
952 </example>
953
954 <comment>
955 This won't be published, but in the HTML is there, only hidden
956 </comment>
957
958 ** Plays and bibliographies
959
960 [[idx][bibliographies]]
961 Unlike the original Muse, this implementation doesn't support external
962 sources for citations, but provides an environment which can used to
963 compose the list of cited works without resorting to lists, wrapping
964 all in a <biblio> tag.
965
966 <example>
967 <biblio>
968 The author, *Title*, published on
969 [[http://theanarchistlibrary.org][The Anarchist Library]], with a
970 very, very, very, very, very, very, very, very, very, very, very,
971 very, long description
972
973 Another author, *Another title*, published in the real world. with a
974 very, very, very, very, very, very, very, very, very, very, very,
975 very, long description
976 </biblio>
977 </example>
978
979 <biblio>
980 The author, *Title*, published on
981 [[http://theanarchistlibrary.org][The Anarchist Library]], with a
982 very, very, very, very, very, very, very, very, very, very, very,
983 very, long description
984
985 Another author, *Another title*, published in the real world. with a
986 very, very, very, very, very, very, very, very, very, very, very,
987 very, long description
988 </biblio>
989
990 The list is wrapped in a =<div>= with class set to biblio, while the TeX
991 source get wrapped in =\startawikibiblio= and =\stopawikibiblio=. You are
992 free to change class and definition. A reversed indentation is
993 suggested.
994
995 [[idx][plays]]
996 The same goes with the =<play>= environment, which is supposed to wrap
997 theathrical plays, when you want a reverse indentation and more
998 spacing between the paragraph (without resorting to =<verse>= and
999 hardcoding the spaces.
1000
1001 <example>
1002 <play>
1003 **Pol.** Ophelia, walke you heere. Gracious so please ye <br>
1004 We will bestow our selues: Reade on this booke, <br>
1005 That shew of such an exercise may colour <br>
1006 Your lonelinesse. We are oft too blame in this, <br>
1007 'Tis too much prou'd, that with Deuotions visage, <br>
1008 And pious Action, we do surge o're <br>
1009 The diuell himselfe
1010
1011 **King.** Oh 'tis true: <br>
1012 How smart a lash that speech doth giue my Conscience? <br>
1013 The Harlots Cheeke beautied with plaist'ring Art <br>
1014 Is not more vgly to the thing that helpes it, <br>
1015 Then is my deede, to my most painted word. <br>
1016 Oh heauie burthen!
1017
1018 </play>
1019 </example>
1020
1021 <play>
1022 **Pol.** Ophelia, walke you heere. Gracious so please ye <br>
1023 We will bestow our selues: Reade on this booke, <br>
1024 That shew of such an exercise may colour <br>
1025 Your lonelinesse. We are oft too blame in this, <br>
1026 'Tis too much prou'd, that with Deuotions visage, <br>
1027 And pious Action, we do surge o're <br>
1028 The diuell himselfe
1029
1030 **King.** Oh 'tis true: <br>
1031 How smart a lash that speech doth giue my Conscience? <br>
1032 The Harlots Cheeke beautied with plaist'ring Art <br>
1033 Is not more vgly to the thing that helpes it, <br>
1034 Then is my deede, to my most painted word. <br>
1035 Oh heauie burthen!
1036
1037 </play>
1038
1039 ** Indexing
1040
1041 You can create a index in your document, simply adding a special link
1042 with a particular target: [[idx][creating indexes]] [[idx][index]]
1043
1044 <example>
1045 [[idx][index entry]]
1046 </example>
1047
1048 I.e., the =idx= keyword as target and the item for the index in the description.
1049
1050 On the PDF the last page of the document will have an index, while the
1051 HTML will get a =<span>= with the name of the reference. While
1052 writing this document I've added this kind of special links.
1053
1054 * GNU Free Documentation License
1055
1056 [[idx][license]]
1057 <verbatim>
1058
1059                       Version 1.2, November 2002
1060
1061      Copyright (C) 2000,2001,2002  Free Software Foundation, Inc.
1062      51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
1063
1064      Everyone is permitted to copy and distribute verbatim copies
1065      of this license document, but changing it is not allowed.
1066
1067
1068   0. PREAMBLE
1069
1070      The purpose of this License is to make a manual, textbook, or other
1071      functional and useful document "free" in the sense of freedom: to
1072      assure everyone the effective freedom to copy and redistribute it,
1073      with or without modifying it, either commercially or
1074      noncommercially.  Secondarily, this License preserves for the
1075      author and publisher a way to get credit for their work, while not
1076      being considered responsible for modifications made by others.
1077
1078      This License is a kind of "copyleft," which means that derivative
1079      works of the document must themselves be free in the same sense.
1080      It complements the GNU General Public License, which is a copyleft
1081      license designed for free software.
1082
1083      We have designed this License in order to use it for manuals for
1084      free software, because free software needs free documentation: a
1085      free program should come with manuals providing the same freedoms
1086      that the software does.  But this License is not limited to
1087      software manuals; it can be used for any textual work, regardless
1088      of subject matter or whether it is published as a printed book.
1089      We recommend this License principally for works whose purpose is
1090      instruction or reference.
1091
1092
1093   1. APPLICABILITY AND DEFINITIONS
1094
1095      This License applies to any manual or other work, in any medium,
1096      that contains a notice placed by the copyright holder saying it
1097      can be distributed under the terms of this License.  Such a notice
1098      grants a world-wide, royalty-free license, unlimited in duration,
1099      to use that work under the conditions stated herein.  The
1100      "Document," below, refers to any such manual or work.  Any member
1101      of the public is a licensee, and is addressed as "you."  You
1102      accept the license if you copy, modify or distribute the work in a
1103      way requiring permission under copyright law.
1104
1105      A "Modified Version" of the Document means any work containing the
1106      Document or a portion of it, either copied verbatim, or with
1107      modifications and/or translated into another language.
1108
1109      A "Secondary Section" is a named appendix or a front-matter
1110      section of the Document that deals exclusively with the
1111      relationship of the publishers or authors of the Document to the
1112      Document's overall subject (or to related matters) and contains
1113      nothing that could fall directly within that overall subject.
1114      (Thus, if the Document is in part a textbook of mathematics, a
1115      Secondary Section may not explain any mathematics.)  The
1116      relationship could be a matter of historical connection with the
1117      subject or with related matters, or of legal, commercial,
1118      philosophical, ethical or political position regarding them.
1119
1120      The "Invariant Sections" are certain Secondary Sections whose
1121      titles are designated, as being those of Invariant Sections, in
1122      the notice that says that the Document is released under this
1123      License.  If a section does not fit the above definition of
1124      Secondary then it is not allowed to be designated as Invariant.
1125      The Document may contain zero Invariant Sections.  If the Document
1126      does not identify any Invariant Sections then there are none.
1127
1128      The "Cover Texts" are certain short passages of text that are
1129      listed, as Front-Cover Texts or Back-Cover Texts, in the notice
1130      that says that the Document is released under this License.  A
1131      Front-Cover Text may be at most 5 words, and a Back-Cover Text may
1132      be at most 25 words.
1133
1134      A "Transparent" copy of the Document means a machine-readable copy,
1135      represented in a format whose specification is available to the
1136      general public, that is suitable for revising the document
1137      straightforwardly with generic text editors or (for images
1138      composed of pixels) generic paint programs or (for drawings) some
1139      widely available drawing editor, and that is suitable for input to
1140      text formatters or for automatic translation to a variety of
1141      formats suitable for input to text formatters.  A copy made in an
1142      otherwise Transparent file format whose markup, or absence of
1143      markup, has been arranged to thwart or discourage subsequent
1144      modification by readers is not Transparent.  An image format is
1145      not Transparent if used for any substantial amount of text.  A
1146      copy that is not "Transparent" is called "Opaque."
1147
1148      Examples of suitable formats for Transparent copies include plain
1149      ASCII without markup, Texinfo input format, LaTeX input format,
1150      SGML or XML using a publicly available DTD, and
1151      standard-conforming simple HTML, PostScript or PDF designed for
1152      human modification.  Examples of transparent image formats include
1153      PNG, XCF and JPG.  Opaque formats include proprietary formats that
1154      can be read and edited only by proprietary word processors, SGML
1155      or XML for which the DTD and/or processing tools are not generally
1156      available, and the machine-generated HTML, PostScript or PDF
1157      produced by some word processors for output purposes only.
1158
1159      The "Title Page" means, for a printed book, the title page itself,
1160      plus such following pages as are needed to hold, legibly, the
1161      material this License requires to appear in the title page.  For
1162      works in formats which do not have any title page as such, "Title
1163      Page" means the text near the most prominent appearance of the
1164      work's title, preceding the beginning of the body of the text.
1165
1166      A section "Entitled XYZ" means a named subunit of the Document
1167      whose title either is precisely XYZ or contains XYZ in parentheses
1168      following text that translates XYZ in another language.  (Here XYZ
1169      stands for a specific section name mentioned below, such as
1170      "Acknowledgements," "Dedications," "Endorsements," or "History.")
1171      To "Preserve the Title" of such a section when you modify the
1172      Document means that it remains a section "Entitled XYZ" according
1173      to this definition.
1174
1175      The Document may include Warranty Disclaimers next to the notice
1176      which states that this License applies to the Document.  These
1177      Warranty Disclaimers are considered to be included by reference in
1178      this License, but only as regards disclaiming warranties: any other
1179      implication that these Warranty Disclaimers may have is void and
1180      has no effect on the meaning of this License.
1181
1182   2. VERBATIM COPYING
1183
1184      You may copy and distribute the Document in any medium, either
1185      commercially or noncommercially, provided that this License, the
1186      copyright notices, and the license notice saying this License
1187      applies to the Document are reproduced in all copies, and that you
1188      add no other conditions whatsoever to those of this License.  You
1189      may not use technical measures to obstruct or control the reading
1190      or further copying of the copies you make or distribute.  However,
1191      you may accept compensation in exchange for copies.  If you
1192      distribute a large enough number of copies you must also follow
1193      the conditions in section 3.
1194
1195      You may also lend copies, under the same conditions stated above,
1196      and you may publicly display copies.
1197
1198   3. COPYING IN QUANTITY
1199
1200      If you publish printed copies (or copies in media that commonly
1201      have printed covers) of the Document, numbering more than 100, and
1202      the Document's license notice requires Cover Texts, you must
1203      enclose the copies in covers that carry, clearly and legibly, all
1204      these Cover Texts: Front-Cover Texts on the front cover, and
1205      Back-Cover Texts on the back cover.  Both covers must also clearly
1206      and legibly identify you as the publisher of these copies.  The
1207      front cover must present the full title with all words of the
1208      title equally prominent and visible.  You may add other material
1209      on the covers in addition.  Copying with changes limited to the
1210      covers, as long as they preserve the title of the Document and
1211      satisfy these conditions, can be treated as verbatim copying in
1212      other respects.
1213
1214      If the required texts for either cover are too voluminous to fit
1215      legibly, you should put the first ones listed (as many as fit
1216      reasonably) on the actual cover, and continue the rest onto
1217      adjacent pages.
1218
1219      If you publish or distribute Opaque copies of the Document
1220      numbering more than 100, you must either include a
1221      machine-readable Transparent copy along with each Opaque copy, or
1222      state in or with each Opaque copy a computer-network location from
1223      which the general network-using public has access to download
1224      using public-standard network protocols a complete Transparent
1225      copy of the Document, free of added material.  If you use the
1226      latter option, you must take reasonably prudent steps, when you
1227      begin distribution of Opaque copies in quantity, to ensure that
1228      this Transparent copy will remain thus accessible at the stated
1229      location until at least one year after the last time you
1230      distribute an Opaque copy (directly or through your agents or
1231      retailers) of that edition to the public.
1232
1233      It is requested, but not required, that you contact the authors of
1234      the Document well before redistributing any large number of
1235      copies, to give them a chance to provide you with an updated
1236      version of the Document.
1237
1238   4. MODIFICATIONS
1239
1240      You may copy and distribute a Modified Version of the Document
1241      under the conditions of sections 2 and 3 above, provided that you
1242      release the Modified Version under precisely this License, with
1243      the Modified Version filling the role of the Document, thus
1244      licensing distribution and modification of the Modified Version to
1245      whoever possesses a copy of it.  In addition, you must do these
1246      things in the Modified Version:
1247
1248      A. Use in the Title Page (and on the covers, if any) a title
1249      distinct    from that of the Document, and from those of previous
1250      versions    (which should, if there were any, be listed in the
1251      History section    of the Document).  You may use the same title
1252      as a previous version    if the original publisher of that version
1253      gives permission.
1254      B. List on the Title Page, as authors, one or more persons or
1255      entities    responsible for authorship of the modifications in the
1256      Modified    Version, together with at least five of the principal
1257      authors of the    Document (all of its principal authors, if it
1258      has fewer than five),    unless they release you from this
1259      requirement.
1260      C. State on the Title page the name of the publisher of the
1261      Modified Version, as the publisher.
1262      D. Preserve all the copyright notices of the Document.
1263      E. Add an appropriate copyright notice for your modifications
1264      adjacent to the other copyright notices.
1265      F. Include, immediately after the copyright notices, a license
1266      notice    giving the public permission to use the Modified Version
1267      under the    terms of this License, in the form shown in the
1268      Addendum below.
1269      G. Preserve in that license notice the full lists of Invariant
1270      Sections    and required Cover Texts given in the Document's
1271      license notice.
1272      H. Include an unaltered copy of this License.
1273      I. Preserve the section Entitled "History," Preserve its Title,
1274      and add    to it an item stating at least the title, year, new
1275      authors, and    publisher of the Modified Version as given on the
1276      Title Page.  If    there is no section Entitled "History" in the
1277      Document, create one    stating the title, year, authors, and
1278      publisher of the Document as    given on its Title Page, then add
1279      an item describing the Modified    Version as stated in the
1280      previous sentence.
1281      J. Preserve the network location, if any, given in the Document for
1282        public access to a Transparent copy of the Document, and likewise
1283        the network locations given in the Document for previous versions
1284        it was based on.  These may be placed in the "History" section.
1285        You may omit a network location for a work that was published at
1286        least four years before the Document itself, or if the original
1287       publisher of the version it refers to gives permission.
1288      K. For any section Entitled "Acknowledgements" or "Dedications,"
1289      Preserve the Title of the section, and preserve in the section all
1290        the substance and tone of each of the contributor
1291      acknowledgements    and/or dedications given therein.
1292      L. Preserve all the Invariant Sections of the Document,
1293      unaltered in their text and in their titles.  Section numbers
1294      or the equivalent are not considered part of the section titles.
1295      M. Delete any section Entitled "Endorsements."  Such a section
1296      may not be included in the Modified Version.
1297      N. Do not retitle any existing section to be Entitled
1298      "Endorsements"    or to conflict in title with any Invariant
1299      Section.
1300      O. Preserve any Warranty Disclaimers.
1301
1302      If the Modified Version includes new front-matter sections or
1303      appendices that qualify as Secondary Sections and contain no
1304      material copied from the Document, you may at your option
1305      designate some or all of these sections as invariant.  To do this,
1306      add their titles to the list of Invariant Sections in the Modified
1307      Version's license notice.  These titles must be distinct from any
1308      other section titles.
1309
1310      You may add a section Entitled "Endorsements," provided it contains
1311      nothing but endorsements of your Modified Version by various
1312      parties-for example, statements of peer review or that the text has
1313      been approved by an organization as the authoritative definition
1314      of a standard.
1315
1316      You may add a passage of up to five words as a Front-Cover Text,
1317      and a passage of up to 25 words as a Back-Cover Text, to the end
1318      of the list of Cover Texts in the Modified Version.  Only one
1319      passage of Front-Cover Text and one of Back-Cover Text may be
1320      added by (or through arrangements made by) any one entity.  If the
1321      Document already includes a cover text for the same cover,
1322      previously added by you or by arrangement made by the same entity
1323      you are acting on behalf of, you may not add another; but you may
1324      replace the old one, on explicit permission from the previous
1325      publisher that added the old one.
1326
1327      The author(s) and publisher(s) of the Document do not by this
1328      License give permission to use their names for publicity for or to
1329      assert or imply endorsement of any Modified Version.
1330
1331   5. COMBINING DOCUMENTS
1332
1333      You may combine the Document with other documents released under
1334      this License, under the terms defined in section 4 above for
1335      modified versions, provided that you include in the combination
1336      all of the Invariant Sections of all of the original documents,
1337      unmodified, and list them all as Invariant Sections of your
1338      combined work in its license notice, and that you preserve all
1339      their Warranty Disclaimers.
1340
1341      The combined work need only contain one copy of this License, and
1342      multiple identical Invariant Sections may be replaced with a single
1343      copy.  If there are multiple Invariant Sections with the same name
1344      but different contents, make the title of each such section unique
1345      by adding at the end of it, in parentheses, the name of the
1346      original author or publisher of that section if known, or else a
1347      unique number.  Make the same adjustment to the section titles in
1348      the list of Invariant Sections in the license notice of the
1349      combined work.
1350
1351      In the combination, you must combine any sections Entitled
1352      "History" in the various original documents, forming one section
1353      Entitled "History"; likewise combine any sections Entitled
1354      "Acknowledgements," and any sections Entitled "Dedications."  You
1355      must delete all sections Entitled "Endorsements."
1356
1357   6. COLLECTIONS OF DOCUMENTS
1358
1359      You may make a collection consisting of the Document and other
1360      documents released under this License, and replace the individual
1361      copies of this License in the various documents with a single copy
1362      that is included in the collection, provided that you follow the
1363      rules of this License for verbatim copying of each of the
1364      documents in all other respects.
1365
1366      You may extract a single document from such a collection, and
1367      distribute it individually under this License, provided you insert
1368      a copy of this License into the extracted document, and follow
1369      this License in all other respects regarding verbatim copying of
1370      that document.
1371
1372   7. AGGREGATION WITH INDEPENDENT WORKS
1373
1374      A compilation of the Document or its derivatives with other
1375      separate and independent documents or works, in or on a volume of
1376      a storage or distribution medium, is called an "aggregate" if the
1377      copyright resulting from the compilation is not used to limit the
1378      legal rights of the compilation's users beyond what the individual
1379      works permit.  When the Document is included in an aggregate, this
1380      License does not apply to the other works in the aggregate which
1381      are not themselves derivative works of the Document.
1382
1383      If the Cover Text requirement of section 3 is applicable to these
1384      copies of the Document, then if the Document is less than one half
1385      of the entire aggregate, the Document's Cover Texts may be placed
1386      on covers that bracket the Document within the aggregate, or the
1387      electronic equivalent of covers if the Document is in electronic
1388      form.  Otherwise they must appear on printed covers that bracket
1389      the whole aggregate.
1390
1391   8. TRANSLATION
1392
1393      Translation is considered a kind of modification, so you may
1394      distribute translations of the Document under the terms of section
1395      4.  Replacing Invariant Sections with translations requires special
1396      permission from their copyright holders, but you may include
1397      translations of some or all Invariant Sections in addition to the
1398      original versions of these Invariant Sections.  You may include a
1399      translation of this License, and all the license notices in the
1400      Document, and any Warranty Disclaimers, provided that you also
1401      include the original English version of this License and the
1402      original versions of those notices and disclaimers.  In case of a
1403      disagreement between the translation and the original version of
1404      this License or a notice or disclaimer, the original version will
1405      prevail.
1406
1407      If a section in the Document is Entitled "Acknowledgements,"
1408      "Dedications," or "History," the requirement (section 4) to
1409      Preserve its Title (section 1) will typically require changing the
1410      actual title.
1411
1412   9. TERMINATION
1413
1414      You may not copy, modify, sublicense, or distribute the Document
1415      except as expressly provided for under this License.  Any other
1416      attempt to copy, modify, sublicense or distribute the Document is
1417      void, and will automatically terminate your rights under this
1418      License.  However, parties who have received copies, or rights,
1419      from you under this License will not have their licenses
1420      terminated so long as such parties remain in full compliance.
1421
1422  10. FUTURE REVISIONS OF THIS LICENSE
1423
1424      The Free Software Foundation may publish new, revised versions of
1425      the GNU Free Documentation License from time to time.  Such new
1426      versions will be similar in spirit to the present version, but may
1427      differ in detail to address new problems or concerns.  See
1428      http://www.gnu.org/copyleft/.
1429
1430      Each version of the License is given a distinguishing version
1431      number.  If the Document specifies that a particular numbered
1432      version of this License "or any later version" applies to it, you
1433      have the option of following the terms and conditions either of
1434      that specified version or of any later version that has been
1435      published (not as a draft) by the Free Software Foundation.  If
1436      the Document does not specify a version number of this License,
1437      you may choose any version ever published (not as a draft) by the
1438      Free Software Foundation.
1439
1440
1441 ADDENDUM: How to use this License for your documents
1442 ====================================================
1443
1444 To use this License in a document you have written, include a copy of
1445 the License in the document and put the following copyright and license
1446 notices just after the title page:
1447
1448      Copyright (C)  YEAR  YOUR NAME.
1449      Permission is granted to copy, distribute and/or modify this document
1450      under the terms of the GNU Free Documentation License, Version 1.2
1451      or any later version published by the Free Software Foundation;
1452      with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
1453      A copy of the license is included in the section entitled ``GNU
1454      Free Documentation License.''
1455
1456    If you have Invariant Sections, Front-Cover Texts and Back-Cover
1457 Texts, replace the "with...Texts." line with this:
1458
1459      with the Invariant Sections being LIST THEIR TITLES, with the
1460      Front-Cover Texts being LIST, and with the Back-Cover Texts being
1461      LIST.
1462
1463    If you have Invariant Sections without Cover Texts, or some other
1464 combination of the three, merge those two alternatives to suit the
1465 situation.
1466
1467    If your document contains nontrivial examples of program code, we
1468 recommend releasing these examples in parallel under your choice of
1469 free software license, such as the GNU General Public License, to
1470 permit their use in free software.
1471
1472 </verbatim>
1473