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