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