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