Fix to manual
[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
34 Paragraphs in Muse must be separated by a blank line.
35
36 *** Centered and right aligned paragraphs and quotations
37
38
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
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   
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
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  
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
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   
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
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   
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   
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. 
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 preserved 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
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
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 a non-breaking space.
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
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
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
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 ** Inserting a horizontal line or anchor
918
919 *** Horizontal Rules
920
921
922 Four or more dashes indicate a horizontal rule.  Be sure to put blank
923 lines around it, or it will be considered part of the proceeding or
924 following paragraph, like this: ---------.
925
926 Example
927
928 <example>
929 ----
930 </example>
931
932 Results:
933
934 ----
935
936 ** Lines to omit from published output
937
938 <example>
939 ; Comment text goes here.
940 </example>
941
942 ; this will disappear completely
943
944 That is, only a semi-colon at the beginning of a line, followed by a
945 literal space, will cause that line to be treated as a comment and
946 **totally removed from the output.** 
947
948 You can alternatively surround the region with the =<comment>= tag. In
949 this case the HTML output will be wrapped in a =<div>= with the
950 =display:none= property, so it can be turned visibile changing the
951 CSS.
952
953 <example>
954 <comment>
955 This won't be published, but in the HTML is there, only hidden
956 </comment>
957 </example>
958
959 <comment>
960 This won't be published, but in the HTML is there, only hidden
961 </comment>
962
963 ** Plays and bibliographies
964
965
966 Unlike the original Muse, this implementation doesn't support external
967 sources for citations, but provides an environment which can used to
968 compose the list of cited works without resorting to lists, wrapping
969 all in a <biblio> tag.
970
971 <example>
972 <biblio>
973 The author, *Title*, published on
974 [[http://theanarchistlibrary.org][The Anarchist Library]], with a
975 very, very, very, very, very, very, very, very, very, very, very,
976 very, long description
977
978 Another author, *Another title*, published in the real world. with a
979 very, very, very, very, very, very, very, very, very, very, very,
980 very, long description
981 </biblio>
982 </example>
983
984 <biblio>
985 The author, *Title*, published on
986 [[http://theanarchistlibrary.org][The Anarchist Library]], with a
987 very, very, very, very, very, very, very, very, very, very, very,
988 very, long description
989
990 Another author, *Another title*, published in the real world. with a
991 very, very, very, very, very, very, very, very, very, very, very,
992 very, long description
993 </biblio>
994
995 The list is wrapped in a =<div>= with class set to biblio, while the TeX
996 source get wrapped in =\startawikibiblio= and =\stopawikibiblio=. You are
997 free to change class and definition. A reversed indentation is
998 suggested.
999
1000
1001 The same goes with the =<play>= environment, which is supposed to wrap
1002 theathrical plays, when you want a reverse indentation and more
1003 spacing between the paragraph (without resorting to =<verse>= and
1004 hardcoding the spaces.
1005
1006 <example>
1007 <play>
1008 **Pol.** Ophelia, walke you heere. Gracious so please ye <br>
1009 We will bestow our selues: Reade on this booke, <br>
1010 That shew of such an exercise may colour <br>
1011 Your lonelinesse. We are oft too blame in this, <br>
1012 'Tis too much prou'd, that with Deuotions visage, <br>
1013 And pious Action, we do surge o're <br>
1014 The diuell himselfe
1015
1016 **King.** Oh 'tis true: <br>
1017 How smart a lash that speech doth giue my Conscience? <br>
1018 The Harlots Cheeke beautied with plaist'ring Art <br>
1019 Is not more vgly to the thing that helpes it, <br>
1020 Then is my deede, to my most painted word. <br>
1021 Oh heauie burthen!
1022
1023 </play>
1024 </example>
1025
1026 <play>
1027 **Pol.** Ophelia, walke you heere. Gracious so please ye <br>
1028 We will bestow our selues: Reade on this booke, <br>
1029 That shew of such an exercise may colour <br>
1030 Your lonelinesse. We are oft too blame in this, <br>
1031 'Tis too much prou'd, that with Deuotions visage, <br>
1032 And pious Action, we do surge o're <br>
1033 The diuell himselfe
1034
1035 **King.** Oh 'tis true: <br>
1036 How smart a lash that speech doth giue my Conscience? <br>
1037 The Harlots Cheeke beautied with plaist'ring Art <br>
1038 Is not more vgly to the thing that helpes it, <br>
1039 Then is my deede, to my most painted word. <br>
1040 Oh heauie burthen!
1041
1042 </play>
1043
1044 * GNU Free Documentation License
1045
1046 <verbatim>
1047
1048                       Version 1.2, November 2002
1049
1050      Copyright (C) 2000,2001,2002  Free Software Foundation, Inc.
1051      51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
1052
1053      Everyone is permitted to copy and distribute verbatim copies
1054      of this license document, but changing it is not allowed.
1055
1056
1057   0. PREAMBLE
1058
1059      The purpose of this License is to make a manual, textbook, or other
1060      functional and useful document "free" in the sense of freedom: to
1061      assure everyone the effective freedom to copy and redistribute it,
1062      with or without modifying it, either commercially or
1063      noncommercially.  Secondarily, this License preserves for the
1064      author and publisher a way to get credit for their work, while not
1065      being considered responsible for modifications made by others.
1066
1067      This License is a kind of "copyleft," which means that derivative
1068      works of the document must themselves be free in the same sense.
1069      It complements the GNU General Public License, which is a copyleft
1070      license designed for free software.
1071
1072      We have designed this License in order to use it for manuals for
1073      free software, because free software needs free documentation: a
1074      free program should come with manuals providing the same freedoms
1075      that the software does.  But this License is not limited to
1076      software manuals; it can be used for any textual work, regardless
1077      of subject matter or whether it is published as a printed book.
1078      We recommend this License principally for works whose purpose is
1079      instruction or reference.
1080
1081
1082   1. APPLICABILITY AND DEFINITIONS
1083
1084      This License applies to any manual or other work, in any medium,
1085      that contains a notice placed by the copyright holder saying it
1086      can be distributed under the terms of this License.  Such a notice
1087      grants a world-wide, royalty-free license, unlimited in duration,
1088      to use that work under the conditions stated herein.  The
1089      "Document," below, refers to any such manual or work.  Any member
1090      of the public is a licensee, and is addressed as "you."  You
1091      accept the license if you copy, modify or distribute the work in a
1092      way requiring permission under copyright law.
1093
1094      A "Modified Version" of the Document means any work containing the
1095      Document or a portion of it, either copied verbatim, or with
1096      modifications and/or translated into another language.
1097
1098      A "Secondary Section" is a named appendix or a front-matter
1099      section of the Document that deals exclusively with the
1100      relationship of the publishers or authors of the Document to the
1101      Document's overall subject (or to related matters) and contains
1102      nothing that could fall directly within that overall subject.
1103      (Thus, if the Document is in part a textbook of mathematics, a
1104      Secondary Section may not explain any mathematics.)  The
1105      relationship could be a matter of historical connection with the
1106      subject or with related matters, or of legal, commercial,
1107      philosophical, ethical or political position regarding them.
1108
1109      The "Invariant Sections" are certain Secondary Sections whose
1110      titles are designated, as being those of Invariant Sections, in
1111      the notice that says that the Document is released under this
1112      License.  If a section does not fit the above definition of
1113      Secondary then it is not allowed to be designated as Invariant.
1114      The Document may contain zero Invariant Sections.  If the Document
1115      does not identify any Invariant Sections then there are none.
1116
1117      The "Cover Texts" are certain short passages of text that are
1118      listed, as Front-Cover Texts or Back-Cover Texts, in the notice
1119      that says that the Document is released under this License.  A
1120      Front-Cover Text may be at most 5 words, and a Back-Cover Text may
1121      be at most 25 words.
1122
1123      A "Transparent" copy of the Document means a machine-readable copy,
1124      represented in a format whose specification is available to the
1125      general public, that is suitable for revising the document
1126      straightforwardly with generic text editors or (for images
1127      composed of pixels) generic paint programs or (for drawings) some
1128      widely available drawing editor, and that is suitable for input to
1129      text formatters or for automatic translation to a variety of
1130      formats suitable for input to text formatters.  A copy made in an
1131      otherwise Transparent file format whose markup, or absence of
1132      markup, has been arranged to thwart or discourage subsequent
1133      modification by readers is not Transparent.  An image format is
1134      not Transparent if used for any substantial amount of text.  A
1135      copy that is not "Transparent" is called "Opaque."
1136
1137      Examples of suitable formats for Transparent copies include plain
1138      ASCII without markup, Texinfo input format, LaTeX input format,
1139      SGML or XML using a publicly available DTD, and
1140      standard-conforming simple HTML, PostScript or PDF designed for
1141      human modification.  Examples of transparent image formats include
1142      PNG, XCF and JPG.  Opaque formats include proprietary formats that
1143      can be read and edited only by proprietary word processors, SGML
1144      or XML for which the DTD and/or processing tools are not generally
1145      available, and the machine-generated HTML, PostScript or PDF
1146      produced by some word processors for output purposes only.
1147
1148      The "Title Page" means, for a printed book, the title page itself,
1149      plus such following pages as are needed to hold, legibly, the
1150      material this License requires to appear in the title page.  For
1151      works in formats which do not have any title page as such, "Title
1152      Page" means the text near the most prominent appearance of the
1153      work's title, preceding the beginning of the body of the text.
1154
1155      A section "Entitled XYZ" means a named subunit of the Document
1156      whose title either is precisely XYZ or contains XYZ in parentheses
1157      following text that translates XYZ in another language.  (Here XYZ
1158      stands for a specific section name mentioned below, such as
1159      "Acknowledgements," "Dedications," "Endorsements," or "History.")
1160      To "Preserve the Title" of such a section when you modify the
1161      Document means that it remains a section "Entitled XYZ" according
1162      to this definition.
1163
1164      The Document may include Warranty Disclaimers next to the notice
1165      which states that this License applies to the Document.  These
1166      Warranty Disclaimers are considered to be included by reference in
1167      this License, but only as regards disclaiming warranties: any other
1168      implication that these Warranty Disclaimers may have is void and
1169      has no effect on the meaning of this License.
1170
1171   2. VERBATIM COPYING
1172
1173      You may copy and distribute the Document in any medium, either
1174      commercially or noncommercially, provided that this License, the
1175      copyright notices, and the license notice saying this License
1176      applies to the Document are reproduced in all copies, and that you
1177      add no other conditions whatsoever to those of this License.  You
1178      may not use technical measures to obstruct or control the reading
1179      or further copying of the copies you make or distribute.  However,
1180      you may accept compensation in exchange for copies.  If you
1181      distribute a large enough number of copies you must also follow
1182      the conditions in section 3.
1183
1184      You may also lend copies, under the same conditions stated above,
1185      and you may publicly display copies.
1186
1187   3. COPYING IN QUANTITY
1188
1189      If you publish printed copies (or copies in media that commonly
1190      have printed covers) of the Document, numbering more than 100, and
1191      the Document's license notice requires Cover Texts, you must
1192      enclose the copies in covers that carry, clearly and legibly, all
1193      these Cover Texts: Front-Cover Texts on the front cover, and
1194      Back-Cover Texts on the back cover.  Both covers must also clearly
1195      and legibly identify you as the publisher of these copies.  The
1196      front cover must present the full title with all words of the
1197      title equally prominent and visible.  You may add other material
1198      on the covers in addition.  Copying with changes limited to the
1199      covers, as long as they preserve the title of the Document and
1200      satisfy these conditions, can be treated as verbatim copying in
1201      other respects.
1202
1203      If the required texts for either cover are too voluminous to fit
1204      legibly, you should put the first ones listed (as many as fit
1205      reasonably) on the actual cover, and continue the rest onto
1206      adjacent pages.
1207
1208      If you publish or distribute Opaque copies of the Document
1209      numbering more than 100, you must either include a
1210      machine-readable Transparent copy along with each Opaque copy, or
1211      state in or with each Opaque copy a computer-network location from
1212      which the general network-using public has access to download
1213      using public-standard network protocols a complete Transparent
1214      copy of the Document, free of added material.  If you use the
1215      latter option, you must take reasonably prudent steps, when you
1216      begin distribution of Opaque copies in quantity, to ensure that
1217      this Transparent copy will remain thus accessible at the stated
1218      location until at least one year after the last time you
1219      distribute an Opaque copy (directly or through your agents or
1220      retailers) of that edition to the public.
1221
1222      It is requested, but not required, that you contact the authors of
1223      the Document well before redistributing any large number of
1224      copies, to give them a chance to provide you with an updated
1225      version of the Document.
1226
1227   4. MODIFICATIONS
1228
1229      You may copy and distribute a Modified Version of the Document
1230      under the conditions of sections 2 and 3 above, provided that you
1231      release the Modified Version under precisely this License, with
1232      the Modified Version filling the role of the Document, thus
1233      licensing distribution and modification of the Modified Version to
1234      whoever possesses a copy of it.  In addition, you must do these
1235      things in the Modified Version:
1236
1237      A. Use in the Title Page (and on the covers, if any) a title
1238      distinct    from that of the Document, and from those of previous
1239      versions    (which should, if there were any, be listed in the
1240      History section    of the Document).  You may use the same title
1241      as a previous version    if the original publisher of that version
1242      gives permission.
1243      B. List on the Title Page, as authors, one or more persons or
1244      entities    responsible for authorship of the modifications in the
1245      Modified    Version, together with at least five of the principal
1246      authors of the    Document (all of its principal authors, if it
1247      has fewer than five),    unless they release you from this
1248      requirement.
1249      C. State on the Title page the name of the publisher of the
1250      Modified Version, as the publisher.
1251      D. Preserve all the copyright notices of the Document.
1252      E. Add an appropriate copyright notice for your modifications
1253      adjacent to the other copyright notices.
1254      F. Include, immediately after the copyright notices, a license
1255      notice    giving the public permission to use the Modified Version
1256      under the    terms of this License, in the form shown in the
1257      Addendum below.
1258      G. Preserve in that license notice the full lists of Invariant
1259      Sections    and required Cover Texts given in the Document's
1260      license notice.
1261      H. Include an unaltered copy of this License.
1262      I. Preserve the section Entitled "History," Preserve its Title,
1263      and add    to it an item stating at least the title, year, new
1264      authors, and    publisher of the Modified Version as given on the
1265      Title Page.  If    there is no section Entitled "History" in the
1266      Document, create one    stating the title, year, authors, and
1267      publisher of the Document as    given on its Title Page, then add
1268      an item describing the Modified    Version as stated in the
1269      previous sentence.
1270      J. Preserve the network location, if any, given in the Document for
1271        public access to a Transparent copy of the Document, and likewise
1272        the network locations given in the Document for previous versions
1273        it was based on.  These may be placed in the "History" section.
1274        You may omit a network location for a work that was published at
1275        least four years before the Document itself, or if the original
1276       publisher of the version it refers to gives permission.
1277      K. For any section Entitled "Acknowledgements" or "Dedications,"
1278      Preserve the Title of the section, and preserve in the section all
1279        the substance and tone of each of the contributor
1280      acknowledgements    and/or dedications given therein.
1281      L. Preserve all the Invariant Sections of the Document,
1282      unaltered in their text and in their titles.  Section numbers
1283      or the equivalent are not considered part of the section titles.
1284      M. Delete any section Entitled "Endorsements."  Such a section
1285      may not be included in the Modified Version.
1286      N. Do not retitle any existing section to be Entitled
1287      "Endorsements"    or to conflict in title with any Invariant
1288      Section.
1289      O. Preserve any Warranty Disclaimers.
1290
1291      If the Modified Version includes new front-matter sections or
1292      appendices that qualify as Secondary Sections and contain no
1293      material copied from the Document, you may at your option
1294      designate some or all of these sections as invariant.  To do this,
1295      add their titles to the list of Invariant Sections in the Modified
1296      Version's license notice.  These titles must be distinct from any
1297      other section titles.
1298
1299      You may add a section Entitled "Endorsements," provided it contains
1300      nothing but endorsements of your Modified Version by various
1301      parties-for example, statements of peer review or that the text has
1302      been approved by an organization as the authoritative definition
1303      of a standard.
1304
1305      You may add a passage of up to five words as a Front-Cover Text,
1306      and a passage of up to 25 words as a Back-Cover Text, to the end
1307      of the list of Cover Texts in the Modified Version.  Only one
1308      passage of Front-Cover Text and one of Back-Cover Text may be
1309      added by (or through arrangements made by) any one entity.  If the
1310      Document already includes a cover text for the same cover,
1311      previously added by you or by arrangement made by the same entity
1312      you are acting on behalf of, you may not add another; but you may
1313      replace the old one, on explicit permission from the previous
1314      publisher that added the old one.
1315
1316      The author(s) and publisher(s) of the Document do not by this
1317      License give permission to use their names for publicity for or to
1318      assert or imply endorsement of any Modified Version.
1319
1320   5. COMBINING DOCUMENTS
1321
1322      You may combine the Document with other documents released under
1323      this License, under the terms defined in section 4 above for
1324      modified versions, provided that you include in the combination
1325      all of the Invariant Sections of all of the original documents,
1326      unmodified, and list them all as Invariant Sections of your
1327      combined work in its license notice, and that you preserve all
1328      their Warranty Disclaimers.
1329
1330      The combined work need only contain one copy of this License, and
1331      multiple identical Invariant Sections may be replaced with a single
1332      copy.  If there are multiple Invariant Sections with the same name
1333      but different contents, make the title of each such section unique
1334      by adding at the end of it, in parentheses, the name of the
1335      original author or publisher of that section if known, or else a
1336      unique number.  Make the same adjustment to the section titles in
1337      the list of Invariant Sections in the license notice of the
1338      combined work.
1339
1340      In the combination, you must combine any sections Entitled
1341      "History" in the various original documents, forming one section
1342      Entitled "History"; likewise combine any sections Entitled
1343      "Acknowledgements," and any sections Entitled "Dedications."  You
1344      must delete all sections Entitled "Endorsements."
1345
1346   6. COLLECTIONS OF DOCUMENTS
1347
1348      You may make a collection consisting of the Document and other
1349      documents released under this License, and replace the individual
1350      copies of this License in the various documents with a single copy
1351      that is included in the collection, provided that you follow the
1352      rules of this License for verbatim copying of each of the
1353      documents in all other respects.
1354
1355      You may extract a single document from such a collection, and
1356      distribute it individually under this License, provided you insert
1357      a copy of this License into the extracted document, and follow
1358      this License in all other respects regarding verbatim copying of
1359      that document.
1360
1361   7. AGGREGATION WITH INDEPENDENT WORKS
1362
1363      A compilation of the Document or its derivatives with other
1364      separate and independent documents or works, in or on a volume of
1365      a storage or distribution medium, is called an "aggregate" if the
1366      copyright resulting from the compilation is not used to limit the
1367      legal rights of the compilation's users beyond what the individual
1368      works permit.  When the Document is included in an aggregate, this
1369      License does not apply to the other works in the aggregate which
1370      are not themselves derivative works of the Document.
1371
1372      If the Cover Text requirement of section 3 is applicable to these
1373      copies of the Document, then if the Document is less than one half
1374      of the entire aggregate, the Document's Cover Texts may be placed
1375      on covers that bracket the Document within the aggregate, or the
1376      electronic equivalent of covers if the Document is in electronic
1377      form.  Otherwise they must appear on printed covers that bracket
1378      the whole aggregate.
1379
1380   8. TRANSLATION
1381
1382      Translation is considered a kind of modification, so you may
1383      distribute translations of the Document under the terms of section
1384      4.  Replacing Invariant Sections with translations requires special
1385      permission from their copyright holders, but you may include
1386      translations of some or all Invariant Sections in addition to the
1387      original versions of these Invariant Sections.  You may include a
1388      translation of this License, and all the license notices in the
1389      Document, and any Warranty Disclaimers, provided that you also
1390      include the original English version of this License and the
1391      original versions of those notices and disclaimers.  In case of a
1392      disagreement between the translation and the original version of
1393      this License or a notice or disclaimer, the original version will
1394      prevail.
1395
1396      If a section in the Document is Entitled "Acknowledgements,"
1397      "Dedications," or "History," the requirement (section 4) to
1398      Preserve its Title (section 1) will typically require changing the
1399      actual title.
1400
1401   9. TERMINATION
1402
1403      You may not copy, modify, sublicense, or distribute the Document
1404      except as expressly provided for under this License.  Any other
1405      attempt to copy, modify, sublicense or distribute the Document is
1406      void, and will automatically terminate your rights under this
1407      License.  However, parties who have received copies, or rights,
1408      from you under this License will not have their licenses
1409      terminated so long as such parties remain in full compliance.
1410
1411  10. FUTURE REVISIONS OF THIS LICENSE
1412
1413      The Free Software Foundation may publish new, revised versions of
1414      the GNU Free Documentation License from time to time.  Such new
1415      versions will be similar in spirit to the present version, but may
1416      differ in detail to address new problems or concerns.  See
1417      http://www.gnu.org/copyleft/.
1418
1419      Each version of the License is given a distinguishing version
1420      number.  If the Document specifies that a particular numbered
1421      version of this License "or any later version" applies to it, you
1422      have the option of following the terms and conditions either of
1423      that specified version or of any later version that has been
1424      published (not as a draft) by the Free Software Foundation.  If
1425      the Document does not specify a version number of this License,
1426      you may choose any version ever published (not as a draft) by the
1427      Free Software Foundation.
1428
1429
1430 ADDENDUM: How to use this License for your documents
1431 ====================================================
1432
1433 To use this License in a document you have written, include a copy of
1434 the License in the document and put the following copyright and license
1435 notices just after the title page:
1436
1437      Copyright (C)  YEAR  YOUR NAME.
1438      Permission is granted to copy, distribute and/or modify this document
1439      under the terms of the GNU Free Documentation License, Version 1.2
1440      or any later version published by the Free Software Foundation;
1441      with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
1442      A copy of the license is included in the section entitled ``GNU
1443      Free Documentation License.''
1444
1445    If you have Invariant Sections, Front-Cover Texts and Back-Cover
1446 Texts, replace the "with...Texts." line with this:
1447
1448      with the Invariant Sections being LIST THEIR TITLES, with the
1449      Front-Cover Texts being LIST, and with the Back-Cover Texts being
1450      LIST.
1451
1452    If you have Invariant Sections without Cover Texts, or some other
1453 combination of the three, merge those two alternatives to suit the
1454 situation.
1455
1456    If your document contains nontrivial examples of program code, we
1457 recommend releasing these examples in parallel under your choice of
1458 free software license, such as the GNU General Public License, to
1459 permit their use in free software.
1460
1461 </verbatim>
1462