documentation update !bibliography & !glossary
[software/sisu] / data / doc / sisu / markup-samples / manual / en / sisu_markup.sst
1 % SiSU 4.0
2
3 @title: SiSU
4 :subtitle: Markup
5
6 @creator:
7 :author: Amissah, Ralph
8
9 @date:
10 :created: 2002-08-28
11 :issued: 2002-08-28
12 :available: 2002-08-28
13 :published: 2008-05-22
14 :modified: 2012-10-03
15
16 @rights:
17 :copyright: Copyright (C) Ralph Amissah 2007
18 :license: GPL 3 (part of SiSU documentation)
19
20 @classify:
21 :topic_register: electronic documents:SiSU:document:markup;SiSU:document:markup;SiSU:document:markup;SiSU:manual:markup;electronic documents:SiSU:manual:markup
22 :subject: ebook, epublishing, electronic book, electronic publishing, electronic document, electronic citation, data structure, citation systems, search
23
24 :A~? @title @creator
25
26 :B~? SiSU Markup
27
28 1~markup Introduction to SiSU Markup~{ From sometime after SiSU 0.58 it should be possible to describe SiSU markup using SiSU, which though not an original design goal is useful. }~
29
30 2~ Summary
31
32 SiSU source documents are plaintext (UTF-8)~{ files should be prepared using UTF-8 character encoding }~ files
33 ={ SiSU markup:description }
34
35 All paragraphs are separated by an empty line.
36
37 Markup is comprised of:
38
39 _* at the top of a document, the document header made up of semantic meta-data about the document and if desired additional processing instructions (such an instruction to automatically number headings from a particular level down)
40
41 _* followed by the prepared substantive text of which the most important single characteristic is the markup of different heading levels, which define the primary outline of the document structure. Markup of substantive text includes:
42
43 _1* heading levels defines document structure
44
45 _1* text basic attributes, italics, bold etc.
46
47 _1* grouped text (objects), which are to be treated differently, such as code blocks or poems.
48
49 _1* footnotes/endnotes
50
51 _1* linked text and images
52
53 _1* paragraph actions, such as indent, bulleted, numbered-lists, etc.
54
55 2~ Markup Rules, document structure and metadata requirements
56 ={ SiSU markup:rules and requirements }
57
58 minimal content/structure requirement:
59
60 [metadata]
61
62 @title:
63
64 @creator:
65
66 [levels]
67
68 ``` code
69 A~ (level A [title])
70
71 1~ (at least one level 1 [segment/(chapter)])
72 ```
73 ={ output:code markup example;SiSU markup output:code block (tic syntax);code block:tic syntax }
74
75 structure rules (document heirarchy, heading levels):
76
77 there are two sets of heading levels ABCD (title & parts if any) and 123 (segment & subsegments if any)
78 ={ SiSU markup:heading levels }
79
80 sisu has the fllowing levels:
81
82 ``` code
83 A~ [title] .
84 required (== 1) followed by B~ or 1~
85 B~ [part] *
86 followed by C~ or 1~
87 C~ [subpart] *
88 followed by D~ or 1~
89 D~ [subsubpart] *
90 followed by 1~
91 1~ [segment (chapter)] +
92 required (>= 1) followed by text or 2~
93 text *
94 followed by more text or 1~, 2~
95 or relevant part *()
96 2~ [subsegment] *
97 followed by text or 3~
98 text *
99 followed by more text or 1~, 2~ or 3~
100 or relevant part, see *()
101 3~ [subsubsegment] *
102 followed by text
103 text *
104 followed by more text or 1~, 2~ or 3~ or relevant part, see *()
105
106 *(B~ if none other used;
107 if C~ is last used: C~ or B~;
108 if D~ is used: D~, C~ or B~)
109 ```
110
111 ``` code
112 * level A~ is the tile and is mandatory
113 * there can only be one level A~
114 * heading levels BCD, are optional and there may be several of each
115 (where all three are used corresponding to e.g. Book Part Section)
116 * sublevels that are used must follow each other sequentially
117 (alphabetically),
118 * heading levels A~ B~ C~ D~ are followed by other heading levels rather
119 than substantive text
120 which may be the subsequent sequential (alphabetic) heading part level
121 or a heading (segment) level 1~
122 * there must be at least one heading (segment) level 1~
123 (the level on which the text is segmented, in a book would correspond
124 to the Chapter level)
125 * additional heading levels 1~ 2~ 3~ are optional and there may be several
126 of each
127 * heading levels 1~ 2~ 3~ are followed by text (which may be followed by
128 the same heading level)
129 and/or the next lower numeric heading level (followed by text)
130 or indeed return to the relevant part level
131 (as a corollary to the rules above substantive text/ content
132 must be preceded by a level 1~ (2~ or 3~) heading)
133 ```
134
135 2~ Markup Examples
136 ={ SiSU markup:locating examples }
137
138 3~ Online
139 ={ SiSU markup:examples online }
140
141 Online markup examples are available together with the respective outputs produced from http://www.jus.uio.no/sisu/SiSU/examples.html or from http://www.jus.uio.no/sisu/sisu_examples/
142
143 There is of course this document, which provides a cursory overview of sisu markup and the respective output produced: http://www.jus.uio.no/sisu/sisu_markup/
144
145 an alternative presentation of markup syntax: /usr/share/doc/sisu/on_markup.txt.gz
146
147 3~ Installed
148 ={ SiSU markup:examples installed }
149
150 With SiSU installed sample skins may be found in: /usr/share/doc/sisu/markup-samples (or equivalent directory) and if sisu-markup-samples is installed also under: /usr/share/doc/sisu/markup-samples-non-free
151
152 1~headers Markup of Headers
153 ={ SiSU markup:headers}
154
155 Headers contain either: semantic meta-data about a document, which can be used by any output module of the program, or; processing instructions.
156
157 Note: the first line of a document may include information on the markup version used in the form of a comment. Comments are a percentage mark at the start of a paragraph (and as the first character in a line of text) followed by a space and the comment:
158
159 code{
160
161 % this would be a comment
162
163 }code
164 ={ output:code markup example;SiSU markup output:code block (curly brace syntax);code block:curly brace syntax }
165
166 2~ Sample Header
167 ={ SiSU markup:sample header}
168
169 This current document is loaded by a master document that has a header similar to this one:
170
171 code{
172
173 % SiSU master 4.0
174
175 @title: SiSU
176 :subtitle: Manual
177
178 @creator:
179 :author: Amissah, Ralph
180
181 @publisher: [publisher name]
182
183 @rights: Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL 3
184
185 @classify:
186 :topic_register: SiSU:manual;electronic documents:SiSU:manual
187 :subject: ebook, epublishing, electronic book, electronic publishing,
188 electronic document, electronic citation, data structure,
189 citation systems, search
190
191 % used_by: manual
192
193 @date:
194 :published: 2008-05-22
195 :created: 2002-08-28
196 :issued: 2002-08-28
197 :available: 2002-08-28
198 :modified: 2010-03-03
199
200 @make:
201 :num_top: 1
202 :breaks: new=C; break=1
203 :bold: /Gnu|Debian|Ruby|SiSU/
204 :home_button_text: {SiSU}http://sisudoc.org; {git}http://git.sisudoc.org
205 :footer: {SiSU}http://sisudoc.org; {git}http://git.sisudoc.org
206 :manpage: name=sisu - documents: markup, structuring, publishing in multiple standard formats, and search;
207 synopsis=sisu [-abcDdeFhIiMmNnopqRrSsTtUuVvwXxYyZz0-9] [filename/wildcard ]
208 . sisu [-Ddcv] [instruction]
209 . sisu [-CcFLSVvW]
210
211 @links:
212 { SiSU Homepage }http://www.sisudoc.org/
213 { SiSU Manual }http://www.sisudoc.org/sisu/sisu_manual/
214 { Book Samples & Markup Examples }http://www.jus.uio.no/sisu/SiSU/examples.html
215 { SiSU Download }http://www.jus.uio.no/sisu/SiSU/download.html
216 { SiSU Changelog }http://www.jus.uio.no/sisu/SiSU/changelog.html
217 { SiSU Git repo }http://git.sisudoc.org/gitweb/?p=code/sisu.git;a=summary
218 { SiSU List Archives }http://lists.sisudoc.org/pipermail/sisu/
219 { SiSU @ Debian }http://packages.qa.debian.org/s/sisu.html
220 { SiSU Project @ Debian }http://qa.debian.org/developer.php?login=sisu@lists.sisudoc.org
221 { SiSU @ Wikipedia }http://en.wikipedia.org/wiki/SiSU
222
223 }code
224
225 2~ Available Headers
226 ={ SiSU markup:headers available }
227
228 Header tags appear at the beginning of a document and provide meta information on the document (such as the Dublin Core), or information as to how the document as a whole is to be processed. All header instructions take the form @headername: or on the next line and indented by once space :subheadername: All Dublin Core meta tags are available
229
230 !_ @identifier:
231 information or instructions
232
233 where the "identifier" is a tag recognised by the program, and the "information" or "instructions" belong to the tag/identifier specified
234
235 Note: a header where used should only be used once; all headers apart from @title: are optional; the @structure: header is used to describe document structure, and can be useful to know.
236
237 This is a sample header
238
239 % (Dublin Core in fuschia, other information headers in cyan, markup instructions in red):
240
241 code{
242
243 % SiSU 2.0 [declared file-type identifier with markup version]
244
245 }code
246
247 code{
248
249 @title: [title text] [this header is the only one that is mandatory]
250 :subtitle: [subtitle if any]
251 :language: English
252
253 }code
254
255 code{
256
257 @creator:
258 :author: [Lastname, First names]
259 :illustrator: [Lastname, First names]
260 :translator: [Lastname, First names]
261 :prepared_by: [Lastname, First names]
262
263 }code
264
265 code{
266
267 @date:
268 :published: [year or yyyy-mm-dd]
269 :created: [year or yyyy-mm-dd]
270 :issued: [year or yyyy-mm-dd]
271 :available: [year or yyyy-mm-dd]
272 :modified: [year or yyyy-mm-dd]
273 :valid: [year or yyyy-mm-dd]
274 :added_to_site: [year or yyyy-mm-dd]
275 :translated: [year or yyyy-mm-dd]
276
277 }code
278
279 code{
280
281 @rights:
282 :copyright: Copyright (C) [Year and Holder]
283 :license: [Use License granted]
284 :text: [Year and Holder]
285 :translation: [Name, Year]
286 :illustrations: [Name, Year]
287
288 }code
289
290 code{
291
292 @classify:
293 :topic_register: SiSU:markup sample:book;book:novel:fantasy
294 :type:
295 :subject:
296 :description:
297 :keywords:
298 :abstract:
299 :loc: [Library of Congress classification]
300 :dewey: [Dewey classification
301
302 }code
303
304 code{
305
306 @identify:
307 :isbn: [ISBN]
308 :oclc:
309
310 }code
311
312
313 code{
314
315 @links: { SiSU }http://www.sisudoc.org
316 { FSF }http://www.fsf.org
317
318 }code
319
320 code{
321
322 @make:
323 :num_top: 1
324 :headings: [text to match for each level
325 (e.g. PART; Chapter; Section; Article; or another: none; BOOK|FIRST|SECOND; none; CHAPTER;)
326 :breaks: new=:C; break=1
327 :promo: sisu, ruby, sisu_search_libre, open_society
328 :bold: [regular expression of words/phrases to be made bold]
329 :italics: [regular expression of words/phrases to italicise]
330 :home_button_text: {SiSU}http://sisudoc.org; {git}http://git.sisudoc.org
331 :footer: {SiSU}http://sisudoc.org; {git}http://git.sisudoc.org
332
333 }code
334
335 code{
336
337 @original:
338 :language: [language]
339
340 }code
341
342 code{
343
344 @notes:
345 :comment:
346 :prefix: [prefix is placed just after table of contents]
347
348 }code
349
350 % header ends here, NB only @title: is mandatory [this would be a comment]
351 % NOTE: headings/levels below refer to 0.38 expermental markup (a conversion script provided in sisu-examples, modify.rb makes conversion between 0.37 and 0.38 markup simple)
352
353 1~ Markup of Substantive Text
354 ={ SiSU markup:substantive text }
355
356 2~heading_levels Heading Levels
357 ={ SiSU markup:heading levels }
358
359 Heading levels are :A~ ,:B~ ,:C~ ,1~ ,2~ ,3~ ... :A - :C being part / section headings, followed by other heading levels, and 1 -6 being headings followed by substantive text or sub-headings. :A~ usually the title :A~? conditional level 1 heading (used where a stand-alone document may be imported into another)
360
361 !_ :A~ [heading text]
362 Top level heading [this usually has similar content to the title @title: ]
363 NOTE: the heading levels described here are in 0.38 notation, see heading
364
365 !_ :B~ [heading text]
366 Second level heading [this is a heading level divider]
367
368 !_ :C~ [heading text]
369 Third level heading [this is a heading level divider]
370
371 !_ 1~ [heading text]
372 Top level heading preceding substantive text of document or sub-heading 2, the heading level that would normally be marked 1. or 2. or 3. etc. in a document, and the level on which sisu by default would break html output into named segments, names are provided automatically if none are given (a number), otherwise takes the form 1~my_filename_for_this_segment
373
374 !_ 2~ [heading text]
375 Second level heading preceding substantive text of document or sub-heading 3 , the heading level that would normally be marked 1.1 or 1.2 or 1.3 or 2.1 etc. in a document.
376
377 !_ 3~ [heading text]
378 Third level heading preceding substantive text of document, that would normally be marked 1.1.1 or 1.1.2 or 1.2.1 or 2.1.1 etc. in a document
379
380 code{
381
382 1~filename level 1 heading,
383
384 % the primary division such as Chapter that is followed by substantive text, and may be further subdivided (this is the level on which by default html segments are made)
385
386 }code
387
388 2~ Font Attributes
389 ={ SiSU markup:font attributes }
390
391 !_ markup example:
392
393 code{
394
395 normal text, *{emphasis}*, !{bold text}!, /{italics}/, _{underscore}_, "{citation}",
396 ^{superscript}^, ,{subscript},, +{inserted text}+, -{strikethrough}-, #{monospace}#
397
398 normal text
399
400 *{emphasis}* [note: can be configured to be represented by bold, italics or underscore]
401
402 !{bold text}!
403
404 /{italics}/
405
406 _{underscore}_
407
408 "{citation}"
409
410 ^{superscript}^
411
412 ,{subscript},
413
414 +{inserted text}+
415
416 -{strikethrough}-
417
418 #{monospace}#
419
420 }code
421
422 !_ resulting output:
423
424 normal text, *{emphasis}*, !{bold text}!, /{italics}/, _{underscore}_, "{citation}",
425 ^{superscript}^, ,{subscript},, +{inserted text}+, -{strikethrough}-, #{monospace}#
426
427 normal text
428
429 *{emphasis}* [note: can be configured to be represented by bold, italics or underscore]
430
431 !{bold text}!
432
433 /{italics}/
434
435 _{underscore}_
436
437 "{citation}"
438
439 ^{superscript}^
440
441 ,{subscript},
442
443 +{inserted text}+
444
445 -{strikethrough}-
446
447 #{monospace}#
448
449 2~ Indentation and bullets
450 ={ SiSU markup:indentation and bullets }
451
452 !_ markup example:
453 ={ SiSU markup:indentation }
454
455 code{
456
457 ordinary paragraph
458
459 _1 indent paragraph one step
460
461 _2 indent paragraph two steps
462
463 _9 indent paragraph nine steps
464
465 }code
466
467 !_ resulting output:
468
469 ordinary paragraph
470
471 _1 indent paragraph one step
472
473 _2 indent paragraph two steps
474
475 _9 indent paragraph nine steps
476
477 !_ markup example:
478 ={ SiSU markup:bullets }
479
480 code{
481
482 _* bullet text
483
484 _1* bullet text, first indent
485
486 _2* bullet text, two step indent
487
488 }code
489
490 !_ resulting output:
491
492 _* bullet text
493
494 _1* bullet text, first indent
495
496 _2* bullet text, two step indent
497
498 Numbered List (not to be confused with headings/titles, (document structure))
499
500 !_ markup example:
501
502 code{
503
504 # numbered list numbered list 1., 2., 3, etc.
505
506 _# numbered list numbered list indented a., b., c., d., etc.
507
508 }code
509
510 2~ Hanging Indents
511 ={ SiSU markup:hanging indents;indented text:hanging }
512
513 !_ markup example:
514
515 code{
516
517 _0_1 first line no indent,
518 rest of paragraph indented one step
519
520 _1_0 first line indented,
521 rest of paragraph no indent
522
523 in each case level may be 0-9
524
525 }code
526
527 !_ resulting output:
528
529 _0_1 first line no indent, rest of paragraph indented one step; first line no indent, rest of paragraph indented one step; first line no indent, rest of paragraph indented one step; first line no indent, rest of paragraph indented one step; first line no indent, rest of paragraph indented one step; first line no indent, rest of paragraph indented one step; first line no indent, rest of paragraph indented one step; first line no indent, rest of paragraph indented one step; first line no indent, rest of paragraph indented one step;
530
531 A regular paragraph.
532
533 _1_0 first line indented, rest of paragraph no indent first line indented, rest of paragraph no indent first line indented, rest of paragraph no indent first line indented, rest of paragraph no indent first line indented, rest of paragraph no indent first line indented, rest of paragraph no indent first line indented, rest of paragraph no indent first line indented, rest of paragraph no indent first line indented, rest of paragraph no indent first line indented, rest of paragraph no indent first line indented, rest of paragraph no indent
534
535 in each case level may be 0-9
536
537 _0_1 *{live-build}* A collection of scripts used to build customized Debian Livesystems. /{live-build}/ was formerly known as live-helper, and even earlier known as live-package.
538
539 _0_1 *{live-build}* \\
540 A collection of scripts used to build customized Debian Livesystems. /{live-build}/ was formerly known as live-helper, and even earlier known as live-package.
541
542 2~ Footnotes / Endnotes
543 ={ SiSU markup:hanging indents;footnotes;endnotes }
544
545 Footnotes and endnotes are marked up at the location where they would be indicated within a text. They are automatically numbered. The output type determines whether footnotes or endnotes will be produced
546
547 !_ markup example:
548
549 code{
550
551 ~{ a footnote or endnote }~
552
553 }code
554
555 !_ resulting output:
556
557 ~{ a footnote or endnote }~
558
559 !_ markup example:
560
561 code{
562
563 normal text~{ self contained endnote marker & endnote in one }~ continues
564
565 }code
566
567 !_ resulting output:
568
569 normal text~{ self contained endnote marker & endnote in one }~ continues
570
571 !_ markup example:
572
573 code{
574
575 normal text ~{* unnumbered asterisk footnote/endnote, insert multiple asterisks if required }~ continues
576
577 normal text ~{** another unnumbered asterisk footnote/endnote }~ continues
578
579 }code
580
581 !_ resulting output:
582
583 normal text ~{* unnumbered asterisk footnote/endnote, insert multiple asterisks if required }~ continues
584
585 normal text ~{** another unnumbered asterisk footnote/endnote }~ continues
586
587 !_ markup example:
588
589 code{
590
591 normal text ~[* editors notes, numbered asterisk footnote/endnote series ]~ continues
592
593 normal text ~[+ editors notes, numbered plus symbol footnote/endnote series ]~ continues
594
595 }code
596
597 !_ resulting output:
598
599 normal text ~[* editors notes, numbered asterisk footnote/endnote series ]~ continues
600
601 normal text ~[+ editors notes, numbered plus symbol footnote/endnote series ]~ continues
602
603 !_ Alternative endnote pair notation for footnotes/endnotes:
604
605 code{
606
607 % note the endnote marker "~^"
608
609 normal text~^ continues
610
611 ^~ endnote text following the paragraph in which the marker occurs
612
613 }code
614
615 the standard and pair notation cannot be mixed in the same document
616
617 2~ Links
618 ={ SiSU markup:links (text, images);links:images|text }
619
620 3~ Naked URLs within text, dealing with urls
621
622 urls found within text are marked up automatically. A url within text is automatically hyperlinked to itself and by default decorated with angled braces, unless they are contained within a code block (in which case they are passed as normal text), or escaped by a preceding underscore (in which case the decoration is omitted).
623
624 !_ markup example:
625
626 code{
627
628 normal text http://www.sisudoc.org/ continues
629
630 }code
631
632 !_ resulting output:
633
634 normal text http://www.sisudoc.org/ continues
635
636 An escaped url without decoration
637
638 !_ markup example:
639
640 code{
641
642 normal text _http://www.sisudoc.org/ continues
643
644 deb _http://www.jus.uio.no/sisu/archive unstable main non-free
645
646 }code
647
648 !_ resulting output:
649
650 normal text _http://www.sisudoc.org/ continues
651
652 deb _http://www.jus.uio.no/sisu/archive unstable main non-free
653
654 where a code block is used there is neither decoration nor hyperlinking, code blocks are discussed later in this document
655
656 !_ resulting output:
657
658 code{
659
660 deb http://www.jus.uio.no/sisu/archive unstable main non-free
661 deb-src http://www.jus.uio.no/sisu/archive unstable main non-free
662
663 }code
664
665 3~link_text Linking Text
666 ={ SiSU markup:links (text);links:text }
667
668 To link text or an image to a url the markup is as follows
669
670 !_ markup example:
671
672 code{
673
674 about { SiSU }http://url.org markup
675
676 }code
677
678 !_ resulting output:
679
680 about { SiSU }http://www.sisudoc.org/ markup
681
682 A shortcut notation is available so the url link may also be provided automatically as a footnote
683
684 !_ markup example:
685
686 code{
687
688 about {~^ SiSU }http://url.org markup
689
690 }code
691
692 !_ resulting output:
693
694 about {~^ SiSU }http://www.sisudoc.org/ markup
695
696 Internal document links to a tagged location, including an ocn
697
698 !_ markup example:
699
700 code{
701
702 about { text links }#link_text
703
704 }code
705
706 !_ resulting output:
707
708 about { text links }#link_text
709
710 Shared document collection link
711
712 !_ markup example:
713
714 code{
715
716 about { SiSU book markup examples }:SiSU/examples.html
717
718 }code
719
720 !_ resulting output:
721
722 about { SiSU book markup examples }:SiSU/examples.html
723
724 3~ Linking Images
725 ={ SiSU markup:links (images);links:images }
726
727 !_ markup example:
728
729 code{
730
731 { tux.png 64x80 }image
732
733 % various url linked images
734
735 {tux.png 64x80 "a better way" }http://www.sisudoc.org/
736
737 {GnuDebianLinuxRubyBetterWay.png 100x101 "Way Better - with Gnu/Linux, Debian and Ruby" }http://www.sisudoc.org/
738
739 {~^ ruby_logo.png "Ruby" }http://www.ruby-lang.org/en/
740
741 }code
742
743 !_ resulting output:
744
745 { tux.png 64x80 }image
746
747 {tux.png 64x80 "Gnu/Linux - a better way" }http://www.sisudoc.org/
748
749 {GnuDebianLinuxRubyBetterWay.png 100x101 "Way Better - with Gnu/Linux, Debian and Ruby" }http://www.sisudoc.org/
750
751 {~^ ruby_logo.png "Ruby" }http://www.ruby-lang.org/en/
752
753 !_ linked url footnote shortcut
754
755 code{
756
757 {~^ [text to link] }http://url.org
758
759 % maps to: { [text to link] }http://url.org ~{ http://url.org }~
760
761 % which produces hyper-linked text within a document/paragraph, with an endnote providing the url for the text location used in the hyperlink
762
763 }code
764
765 code{
766
767 text marker *~name
768
769 }code
770
771 note at a heading level the same is automatically achieved by providing names to headings 1, 2 and 3 i.e. 2~[name] and 3~[name] or in the case of auto-heading numbering, without further intervention.
772
773 3~ Link shortcut for multiple versions of a sisu document in the same directory tree
774
775 !_ markup example:
776
777 code{
778
779 !_ /{"Viral Spiral"}/, David Bollier
780
781 { "Viral Spiral", David Bollier [3sS]}viral_spiral.david_bollier.sst
782
783 }code
784
785
786 !_ /{"Viral Spiral"}/, David Bollier
787
788 { "Viral Spiral", David Bollier [3sS]}viral_spiral.david_bollier.sst
789
790 2~ Grouped Text / blocked text
791 ={ SiSU markup:grouped text;grouped text;blocked text;text blocks }
792
793 There are two markup syntaxes for blocked text, using curly braces or using tics
794
795 3~ blocked text curly brace syntax
796 ={ SiSU markup:grouped text;grouped text:curly brace syntax;blocked text:curly brace syntax;text blocks:curly brace syntax }
797
798 at the start of a line on its own use name of block type with an opening curly brace, follow with the content of the block, and close with a closing curly brace and the name of the block type, e.g.
799
800 ``` code
801 code{
802
803 this is a code block
804
805 }code
806 ```
807
808 ``` code
809 poem{
810
811 this here is a poem
812
813 }poem
814 ```
815
816 3~ blocked text tic syntax
817 ={ SiSU markup:grouped text;grouped text:tic syntax;blocked text:tic syntax;text blocks:tic syntax }
818
819 code{
820
821 ``` code
822 this is a code block
823 ```
824
825 ``` poem
826 this here is a poem
827 ```
828
829 }code
830
831 start a line with three backtics, a space followed by the name of the name of block type, follow with the content of the block, and close with three back ticks on a line of their own, e.g.
832
833 3~ Tables
834 ={ SiSU markup:tables;tables }
835
836 Tables may be prepared in two either of two forms
837
838 !_ markup example:
839
840 code{
841
842 table{ c3; 40; 30; 30;
843
844 This is a table
845 this would become column two of row one
846 column three of row one is here
847
848 And here begins another row
849 column two of row two
850 column three of row two, and so on
851
852 }table
853
854 }code
855
856 !_ resulting output:
857
858 table{ c3; 40; 30; 30;
859
860 This is a table
861 this would become column two of row one
862 column three of row one is here
863
864 And here begins another row
865 column two of row two
866 column three of row two, and so on
867
868 }table
869
870 % ={ output:table markup example;SiSU markup output:table (curly brace syntax) }
871
872 a second form may be easier to work with in cases where there is not much information in each column
873
874 *{markup example:}*~{ Table from the Wealth of Networks by Yochai Benkler \\ http://www.jus.uio.no/sisu/the_wealth_of_networks.yochai_benkler }~
875
876 code{
877
878 !_ Table 3.1: Contributors to Wikipedia, January 2001 - June 2005
879
880 {table~h 24; 12; 12; 12; 12; 12; 12;}
881 |Jan. 2001|Jan. 2002|Jan. 2003|Jan. 2004|July 2004|June 2006
882 Contributors* | 10| 472| 2,188| 9,653| 25,011| 48,721
883 Active contributors** | 9| 212| 846| 3,228| 8,442| 16,945
884 Very active contributors*** | 0| 31| 190| 692| 1,639| 3,016
885 No. of English language articles| 25| 16,000| 101,000| 190,000| 320,000| 630,000
886 No. of articles, all languages | 25| 19,000| 138,000| 490,000| 862,000|1,600,000
887
888 * Contributed at least ten times; ** at least 5 times in last month; *** more than 100 times in last month.
889
890 }code
891
892 !_ resulting output:
893
894
895 !_ Table 3.1: Contributors to Wikipedia, January 2001 - June 2005
896
897 {table~h 24; 12; 12; 12; 12; 12; 12;}
898 |Jan. 2001|Jan. 2002|Jan. 2003|Jan. 2004|July 2004|June 2006
899 Contributors* | 10| 472| 2,188| 9,653| 25,011| 48,721
900 Active contributors** | 9| 212| 846| 3,228| 8,442| 16,945
901 Very active contributors*** | 0| 31| 190| 692| 1,639| 3,016
902 No. of English language articles| 25| 16,000| 101,000| 190,000| 320,000| 630,000
903 No. of articles, all languages | 25| 19,000| 138,000| 490,000| 862,000|1,600,000
904
905 * Contributed at least ten times; ** at least 5 times in last month; *** more than 100 times in last month.
906
907 % code{
908
909 % test
910
911 % ~#
912
913 % % unnumbered paragraph (place marker at end of paragraph)
914
915 % -#
916
917 % % unnumbered paragraph, delete when not required (place marker at end of paragraph) [used in dummy headings, eg. for segmented html]
918
919 % % add a comment to text, that will be removed prior to processing (place marker at beginning of line)
920
921 % }code
922
923 3~ Poem
924 ={ SiSU markup:poem;poems }
925
926 !_ basic markup:
927
928 code{
929
930 poem{
931
932 Your poem here
933
934 }poem
935
936 Each verse in a poem is given an object number.
937
938 }code
939
940 !_ markup example:
941
942 code{
943
944 poem{
945
946 `Fury said to a
947 mouse, That he
948 met in the
949 house,
950 "Let us
951 both go to
952 law: I will
953 prosecute
954 YOU. --Come,
955 I'll take no
956 denial; We
957 must have a
958 trial: For
959 really this
960 morning I've
961 nothing
962 to do."
963 Said the
964 mouse to the
965 cur, "Such
966 a trial,
967 dear Sir,
968 With
969 no jury
970 or judge,
971 would be
972 wasting
973 our
974 breath."
975 "I'll be
976 judge, I'll
977 be jury,"
978 Said
979 cunning
980 old Fury:
981 "I'll
982 try the
983 whole
984 cause,
985 and
986 condemn
987 you
988 to
989 death."'
990 }poem
991
992 }code
993
994 !_ resulting output:
995
996 poem{
997
998 `Fury said to a
999 mouse, That he
1000 met in the
1001 house,
1002 "Let us
1003 both go to
1004 law: I will
1005 prosecute
1006 YOU. --Come,
1007 I'll take no
1008 denial; We
1009 must have a
1010 trial: For
1011 really this
1012 morning I've
1013 nothing
1014 to do."
1015 Said the
1016 mouse to the
1017 cur, "Such
1018 a trial,
1019 dear Sir,
1020 With
1021 no jury
1022 or judge,
1023 would be
1024 wasting
1025 our
1026 breath."
1027 "I'll be
1028 judge, I'll
1029 be jury,"
1030 Said
1031 cunning
1032 old Fury:
1033 "I'll
1034 try the
1035 whole
1036 cause,
1037 and
1038 condemn
1039 you
1040 to
1041 death."'
1042 }poem
1043
1044 % ={ output:poem markup example;SiSU markup output:poem (curly brace syntax) }
1045
1046 3~ Group
1047 ={ SiSU markup:group text;group text }
1048
1049 !_ basic markup:
1050
1051 code{
1052
1053 group{
1054
1055 Your grouped text here
1056
1057 }group
1058
1059 A group is treated as an object and given a single object number.
1060
1061 }code
1062
1063 !_ markup example:
1064
1065 code{
1066
1067 group{
1068
1069 `Fury said to a
1070 mouse, That he
1071 met in the
1072 house,
1073 "Let us
1074 both go to
1075 law: I will
1076 prosecute
1077 YOU. --Come,
1078 I'll take no
1079 denial; We
1080 must have a
1081 trial: For
1082 really this
1083 morning I've
1084 nothing
1085 to do."
1086 Said the
1087 mouse to the
1088 cur, "Such
1089 a trial,
1090 dear Sir,
1091 With
1092 no jury
1093 or judge,
1094 would be
1095 wasting
1096 our
1097 breath."
1098 "I'll be
1099 judge, I'll
1100 be jury,"
1101 Said
1102 cunning
1103 old Fury:
1104 "I'll
1105 try the
1106 whole
1107 cause,
1108 and
1109 condemn
1110 you
1111 to
1112 death."'
1113
1114 }group
1115
1116 }code
1117
1118 !_ resulting output:
1119
1120 group{
1121
1122 `Fury said to a
1123 mouse, That he
1124 met in the
1125 house,
1126 "Let us
1127 both go to
1128 law: I will
1129 prosecute
1130 YOU. --Come,
1131 I'll take no
1132 denial; We
1133 must have a
1134 trial: For
1135 really this
1136 morning I've
1137 nothing
1138 to do."
1139 Said the
1140 mouse to the
1141 cur, "Such
1142 a trial,
1143 dear Sir,
1144 With
1145 no jury
1146 or judge,
1147 would be
1148 wasting
1149 our
1150 breath."
1151 "I'll be
1152 judge, I'll
1153 be jury,"
1154 Said
1155 cunning
1156 old Fury:
1157 "I'll
1158 try the
1159 whole
1160 cause,
1161 and
1162 condemn
1163 you
1164 to
1165 death."'
1166
1167 }group
1168 ={ output:group block markup example;SiSU markup output:group block (curly brace syntax) }
1169
1170 3~ Code
1171 ={ SiSU markup:code block;code block }
1172
1173 Code tags #{ code{ ... }code }# (used as with other group tags described above) are used to escape regular sisu markup, and have been used extensively within this document to provide examples of SiSU markup. You cannot however use code tags to escape code tags. They are however used in the same way as group or poem tags.
1174
1175 A code-block is treated as an object and given a single object number. [an option to number each line of code may be considered at some later time]
1176
1177 !_ use of code tags instead of poem compared, resulting output:
1178
1179 code{
1180
1181 `Fury said to a
1182 mouse, That he
1183 met in the
1184 house,
1185 "Let us
1186 both go to
1187 law: I will
1188 prosecute
1189 YOU. --Come,
1190 I'll take no
1191 denial; We
1192 must have a
1193 trial: For
1194 really this
1195 morning I've
1196 nothing
1197 to do."
1198 Said the
1199 mouse to the
1200 cur, "Such
1201 a trial,
1202 dear Sir,
1203 With
1204 no jury
1205 or judge,
1206 would be
1207 wasting
1208 our
1209 breath."
1210 "I'll be
1211 judge, I'll
1212 be jury,"
1213 Said
1214 cunning
1215 old Fury:
1216 "I'll
1217 try the
1218 whole
1219 cause,
1220 and
1221 condemn
1222 you
1223 to
1224 death."'
1225
1226 }code
1227
1228 From SiSU 2.7.7 on you can number codeblocks by placing a hash after the opening code tag #{ code{# }# as demonstrated here:
1229
1230 code{#
1231
1232 `Fury said to a
1233 mouse, That he
1234 met in the
1235 house,
1236 "Let us
1237 both go to
1238 law: I will
1239 prosecute
1240 YOU. --Come,
1241 I'll take no
1242 denial; We
1243 must have a
1244 trial: For
1245 really this
1246 morning I've
1247 nothing
1248 to do."
1249 Said the
1250 mouse to the
1251 cur, "Such
1252 a trial,
1253 dear Sir,
1254 With
1255 no jury
1256 or judge,
1257 would be
1258 wasting
1259 our
1260 breath."
1261 "I'll be
1262 judge, I'll
1263 be jury,"
1264 Said
1265 cunning
1266 old Fury:
1267 "I'll
1268 try the
1269 whole
1270 cause,
1271 and
1272 condemn
1273 you
1274 to
1275 death."'
1276
1277 }code
1278 ={ output:code markup example;SiSU markup output:code block (curly brace syntax);code block:curly brace syntax }
1279
1280 2~ Additional breaks - linebreaks within objects, column and page-breaks
1281 ={ SiSU markup:breaks (page and line);breaks }
1282
1283 3~ line-breaks
1284 ={ SiSU markup:line break;line break }
1285
1286 To break a line within a "paragraph object", two backslashes \\\\ \\ with a space before and a space or newline after them \\ may be used.
1287
1288 code{
1289
1290 To break a line within a "paragraph object",
1291 two backslashes \\ with a space before
1292 and a space or newline after them \\
1293 may be used.
1294
1295 }code
1296
1297 The html break br enclosed in angle brackets (though undocumented) is available in versions prior to 3.0.13 and 2.9.7 (it remains available for the time being, but is depreciated).
1298
1299 To draw a dividing line dividing paragraphs, see the section on page breaks.
1300
1301 3~ page breaks
1302 ={ SiSU markup:page break;page break }
1303
1304 Page breaks are only relevant and honored in some output formats. A page break or a new page may be inserted manually using the following markup on a line on its own:
1305
1306 page new =\\= breaks the page, starts a new page.
1307
1308 page break -\\- breaks a column, starts a new column, if using columns, else breaks the page, starts a new page.
1309
1310 page break line across page -..- draws a dividing line, dividing paragraphs
1311
1312 page break:
1313
1314 code{
1315
1316 -\\-
1317
1318 }code
1319
1320 page (break) new:
1321
1322 code{
1323
1324 =\\=
1325
1326 }code
1327
1328 page (break) line across page (dividing paragraphs):
1329
1330 code{
1331
1332 -..-
1333
1334 }code
1335
1336 2~ Bibliography / References
1337 ={ SiSU markup:references|bibliography|citations;references }
1338
1339 There are three ways to prepare a bibliography using sisu (which are mutually exclusive): (i) manually preparing and marking up as regular text in sisu a list of references, this is treated as a regular document segment (and placed before endnotes if any); (ii) preparing a bibliography, marking a heading level 1~!biblio (note the exclamation mark) and preparing a bibliography using various metadata tags including for author: title: year: a list of which is provided below, or; (iii) as an assistance in preparing a bibliography, marking a heading level 1~!biblio and tagging citations within footnotes for inclusion, identifying citations and having a parser attempt to extract them and build a bibliography of the citations provided.
1340
1341 For the heading/section sequence: endnotes, bibliography then book index to occur, the name biblio or bibliography must be given to the bibliography section, like so:
1342
1343 code{
1344
1345 1~!biblio
1346
1347 }code
1348
1349 3~ a markup tagged metadata bibliography section
1350
1351 Here instead of writing your full citations directly in footnotes, each time you have new material to cite, you add it to your bibliography section (if it has not been added yet) providing the information you need against an available list of tags (provided below).
1352
1353 The required tags are au: ti: and year: ~{for which you may alternatively use the full form author: title: and year: }~ an short quick example might be as follows:
1354
1355 code{
1356
1357 1~!biblio
1358
1359 au: von Hippel, E.
1360 ti: Perspective: User Toolkits for Innovation
1361 lng: (language)
1362 jo: Journal of Product Innovation Management
1363 vo: 18
1364 ed: (editor)
1365 yr: 2001
1366 note:
1367 sn: Hippel, /{User Toolkits}/ (2001)
1368 id: vHippel_2001
1369 % form:
1370
1371 au: Benkler, Yochai
1372 ti: The Wealth of Networks
1373 st: How Social Production Transforms Markets and Freedom
1374 lng: (language)
1375 pb: Harvard University Press
1376 edn: (edition)
1377 yr: 2006
1378 pl: U.S.
1379 url: http://cyber.law.harvard.edu/wealth_of_networks/Main_Page
1380 note:
1381 sn: Benkler, /{Wealth of Networks}/ (2006)
1382 id: Benkler2006
1383
1384 au: Quixote, Don; Panza, Sancho
1385 ti: Taming Windmills, Keeping True
1386 jo: Imaginary Journal
1387 yr: 1605
1388 url: https://en.wikipedia.org/wiki/Don_Quixote
1389 note: made up to provide an example of author markup for an article with two authors
1390 sn: Quixote & Panza, /{Taming Windmills}/ (1605)
1391 id: quixote1605
1392
1393 }code
1394
1395 Note that the section name !biblio (or !bibliography) is required for the bibliography to be treated specially as such, and placed after the auto-generated endnote section.
1396
1397 Using this method, work goes into preparing the bibliography, the tags author or editor, year and title are required and will be used to sort the bibliography that is placed under the Bibliography section
1398
1399 The metadata tags may include shortname (sn:) and id, if provided, which are used for substitution within text. Every time the given id is found within the text it will be replaced by the given short title of the work (it is for this reason the short title has sisu markup to italicize the title), it should work with any page numbers to be added, the short title should be one that can easily be used to look up the full description in the bibliography.
1400
1401 code{
1402
1403 The following footnote~{ quixote1605, pp 1000 - 1001, also Benkler2006 p 1. }~
1404
1405 }code
1406
1407 would be presented as:
1408
1409 Quixote and Panza, /{Taming Windmills}/ (1605), pp 1000 - 1001 also, Benkler, /{Wealth of Networks}/, (2006) p 1 or rather~{ Quixote and Panza, /{Taming Windmills}/ (1605), pp 1000 - 1001 also, Benkler, /{Wealth of Networks}/ (2006), p 1 }~
1410
1411 code{
1412
1413 au: author Surname, FirstNames (if multiple semi-colon separator)
1414 (required unless editor to be used instead)
1415 ti: title (required)
1416 st: subtitle
1417 jo: journal
1418 vo: volume
1419 ed: editor (required if author not provided)
1420 tr: translator
1421 src: source (generic field where others are not appropriate)
1422 in: in (like src)
1423 pl: place/location (state, country)
1424 pb: publisher
1425 edn: edition
1426 yr: year (yyyy or yyyy-mm or yyyy-mm-dd) (required)
1427 pg: pages
1428 url: http://url
1429 note: note
1430 id: create_short_identifier e.g. authorSurnameYear
1431 (used in substitutions: when found within text will be
1432 replaced by the short name provided)
1433 sn: short name e.g. Author, /{short title}/, Year
1434 (used in substitutions: when an id is found within text
1435 the short name will be used to replace it)
1436
1437 }code
1438
1439 3~ Tagging citations for inclusion in the Bibliography
1440
1441 Here whenever you make a citation that you wish be included in the bibliography, you tag the citation as such using special delimiters (which are subsequently removed from the final text produced by sisu)
1442
1443 Here you would write something like the following, either in regular text or a footnote
1444
1445 code{
1446
1447 See .: Quixote, Don; Panza, Sancho /{Taming Windmills, Keeping True}/ (1605) :.
1448
1449 }code
1450
1451 SiSU will parse for a number of patterns within the delimiters to try make out the authors, title, date etc. and from that create a Bibliography. This is more limited than the previously described method of preparing a tagged bibliography, and using an id within text to identify the work, which also lends itself to greater consistency.
1452
1453 2~ Glossary
1454 ={ SiSU markup:glossary|Glossary }
1455
1456 Using the section name 1~!glossary results in the Glossary being treated specially as such, and placed after the auto-generated endnote section (before the bibliography/list of references if there is one).
1457
1458 The Glossary is ordinary text marked up in a manner deemed suitable for that purpose. e.g. with the term in bold, possibly with a hanging indent.
1459
1460 code{
1461
1462 1~!glossary
1463
1464 _0_1 *{GPL}* An abbreviation that stands for "General Purpose License." ...
1465
1466 _0_1 [provide your list of terms and definitions]
1467
1468 }code
1469
1470 In the given example the first line is not indented subsequent lines are by one level, and the term to be defined is in bold text.
1471
1472 2~ Book index
1473 ={ SiSU markup:book index;book index }
1474
1475 To make an index append to paragraph the book index term relates to it, using an equal sign and curly braces.
1476
1477 Currently two levels are provided, a main term and if needed a sub-term. Sub-terms are separated from the main term by a colon.
1478
1479 code{
1480
1481 Paragraph containing main term and sub-term.
1482 ={Main term:sub-term}
1483
1484 }code
1485
1486 The index syntax starts on a new line, but there should not be an empty line between paragraph and index markup.
1487
1488 The structure of the resulting index would be:
1489
1490 code{
1491
1492 Main term, 1
1493 sub-term, 1
1494
1495 }code
1496
1497 Several terms may relate to a paragraph, they are separated by a semicolon. If the term refers to more than one paragraph, indicate the number of paragraphs.
1498
1499 code{
1500
1501 Paragraph containing main term, second term and sub-term.
1502 ={first term; second term: sub-term}
1503
1504 }code
1505
1506 The structure of the resulting index would be:
1507
1508 code{
1509
1510 First term, 1,
1511 Second term, 1,
1512 sub-term, 1
1513
1514 }code
1515
1516 If multiple sub-terms appear under one paragraph, they are separated under the main term heading from each other by a pipe symbol.
1517
1518 code{
1519
1520 Paragraph containing main term, second term and sub-term.
1521 ={Main term:
1522 sub-term+2|second sub-term;
1523 Another term
1524 }
1525
1526 A paragraph that continues discussion of the first sub-term
1527
1528 }code
1529
1530 The plus one in the example provided indicates the first sub-term spans one additional paragraph. The logical structure of the resulting index would be:
1531
1532 code{
1533
1534 Main term, 1,
1535 sub-term, 1-3,
1536 second sub-term, 1,
1537 Another term, 1
1538
1539 }code
1540
1541 1~ Composite documents markup
1542 ={ SiSU markup:composite documents;composite documents }
1543
1544 It is possible to build a document by creating a master document that requires other documents. The documents required may be complete documents that could be generated independently, or they could be markup snippets, prepared so as to be easily available to be placed within another text. If the calling document is a master document (built from other documents), it should be named with the suffix *{.ssm}* Within this document you would provide information on the other documents that should be included within the text. These may be other documents that would be processed in a regular way, or markup bits prepared only for inclusion within a master document *{.sst}* regular markup file, or *{.ssi}* (insert/information) A secondary file of the composite document is built prior to processing with the same prefix and the suffix *{._sst}*
1545
1546 basic markup for importing a document into a master document
1547
1548 code{
1549
1550 << filename1.sst
1551
1552 << filename2.ssi
1553
1554 }code
1555
1556 The form described above should be relied on. Within the Vim editor it results in the text thus linked becoming hyperlinked to the document it is calling in which is convenient for editing.
1557
1558 1~ Substitutions
1559 ={ SiSU markup:substitutions;substitutions }
1560
1561 !_ markup example:
1562
1563 code{
1564
1565 The current Debian is ${debian_stable} the next debian will be ${debian_testing}
1566
1567 Configure substitution in _sisu/sisu_document_make
1568
1569 @make:
1570 :substitute: /${debian_stable}/,'*{Wheezy}*' /${debian_testing}/,'*{Jessie}*'
1571
1572 }code
1573
1574 !_ resulting output:
1575
1576 The current Debian is ${debian_stable} the next debian will be ${debian_testing}
1577
1578 Configure substitution in _sisu/sisu_document_make