Copyright (C) Ralph Amissah 2007, part of SiSU documentation;
ebook, epublishing, electronic book, electronic publishing, electronic document, electronic citation, data structure, citation systems, search
SiSU ‹<text:a xlink:type='simple' xlink:href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</text:a>› (this copy)
2002-08-28
2011-02-07
sisu_markup.sst
SHA256(sisu_markup.sst)= d0fbb19d8cacd7d1919de4be558ec4dae3e0f2fcfe12d63ca148da872c5a66c1
SHA256(skin_sisu_manual.rb)= 689f79b53be3d51460af31dc82d6cbab4a253079db263cd715c8254a6af60eb8
Generated by: SiSU 2.8.2 of 2011w10/5 (2011-03-11)
ruby 1.8.7 (2008-08-11 patchlevel 72) [i486-linux]
Sun Mar 20 23:45:57 +0100 2011
1
?
SiSU - Markup,
2
?
SiSU Markup
3
markup
1. Introduction to SiSU Markup1 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.
4
1.1
1.1 Summary
5
SiSU source documents are plaintext (UTF-8)2 files should be prepared using UTF-8 character encoding
6
All paragraphs are separated by an empty line.
7
Markup is comprised of:
8
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)
9
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:
10
heading levels defines document structure
11
text basic attributes, italics, bold etc.
12
grouped text (objects), which are to be treated differently, such as code blocks or poems.
13
footnotes/endnotes
14
linked text and images
15
paragraph actions, such as indent, bulleted, numbered-lists, etc.
16
Some interactive help on markup is available, by typing sisu and selecting markup or sisu --help markup
17
To check the markup in a file:
18
sisu --identify [filename].sst
19
For brief descriptive summary of markup history
20
sisu --query-history
21
or if for a particular version:
22
sisu --query-0.38
23
1.2
1.2 Markup Examples
24
1.2.1
1.2.1 Online
25
Online markup examples are available together with the respective outputs produced from <
26
There is of course this document, which provides a cursory overview of sisu markup and the respective output produced: <
27
an alternative presentation of markup syntax: /usr/share/doc/sisu/on_markup.txt.gz
28
1.2.2
1.2.2 Installed
29
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
30
headers
2. Markup of Headers
31
Headers contain either: semantic meta-data about a document, which can be used by any output module of the program, or; processing instructions.
32
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:
33
% this would be a comment
34
2.1
2.1 Sample Header
35
This current document is loaded by a master document that has a header similar to this one:
36
% SiSU master 2.0
37
2.2
2.2 Available Headers
38
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
39
@indentifier: information or instructions
40
where the "identifier" is a tag recognised by the program, and the "information" or "instructions" belong to the tag/indentifier specified
41
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.
42
This is a sample header
43
% SiSU 2.0 [declared file-type identifier with markup version]
44
@title: [title text] [this header is the only one that is mandatory]
45
@creator:
46
@date:
47
@rights:
48
@classify:
49
@links: { SiSU }http://www.sisudoc.org
50
@make:
51
@original:
52
@notes:
53
3
3. Markup of Substantive Text
54
heading_levels
3.1 Heading Levels
55
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)
56
:A~ [heading text] Top level heading [this usually has similar content to the title @title: ] NOTE: the heading levels described here are in 0.38 notation, see heading
57
:B~ [heading text] Second level heading [this is a heading level divider]
58
:C~ [heading text] Third level heading [this is a heading level divider]
59
1~ [heading text] 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
60
2~ [heading text] 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.
61
3~ [heading text] 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
62
1~filename level 1 heading,
63
3.2
3.2 Font Attributes
64
markup example:
65
normal text, *{emphasis}*, !{bold text}!, /{italics}/, _{underscore}_, "{citation}",
66
resulting output:
67
normal text, emphasis , bold text , italics , underscore , citation , superscript , subscript , inserted text , strikethrough, monospace
68
normal text
69
emphasis [note: can be configured to be represented by bold, italics or underscore]
70
bold text
71
italics
72
underscore
73
citation
74
superscript
75
subscript
76
inserted text
77
strikethrough
78
monospace
79
3.3
3.3 Indentation and bullets
80
markup example:
81
ordinary paragraph
82
resulting output:
83
ordinary paragraph
84
indent paragraph one step
85
indent paragraph two steps
86
indent paragraph nine steps
87
markup example:
88
_* bullet text
89
resulting output:
90
bullet text
91
bullet text, first indent
92
bullet text, two step indent
93
Numbered List (not to be confused with headings/titles, (document structure))
94
markup example:
95
# numbered list numbered list 1., 2., 3, etc.
96
3.4
3.4 Footnotes / Endnotes
97
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
98
markup example:
99
~{ a footnote or endnote }~
100
resulting output:
101
3 a footnote or endnote
102
markup example:
103
normal text~{ self contained endnote marker & endnote in one }~ continues
104
resulting output:
105
normal text4 self contained endnote marker & endnote in one
106
markup example:
107
normal text ~{* unnumbered asterisk footnote/endnote, insert multiple asterisks if required }~ continues
108
resulting output:
109
normal text * unnumbered asterisk footnote/endnote, insert multiple asterisks if required
110
normal text ** another unnumbered asterisk footnote/endnote
111
markup example:
112
normal text ~[* editors notes, numbered asterisk footnote/endnote series ]~ continues
113
resulting output:
114
normal text *1 editors notes, numbered asterisk footnote/endnote series
115
normal text +1 editors notes, numbered asterisk footnote/endnote series
116
Alternative endnote pair notation for footnotes/endnotes:
117
% note the endnote marker "~^"
118
the standard and pair notation cannot be mixed in the same document
119
3.5
3.5 Links
120
3.5.1
3.5.1 Naked URLs within text, dealing with urls
121
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).
122
markup example:
123
normal text http://www.sisudoc.org/ continues
124
resulting output:
125
normal text <
126
An escaped url without decoration
127
markup example:
128
normal text _http://www.sisudoc.org/ continues
129
resulting output:
130
normal text <
131
deb <
132
where a code block is used there is neither decoration nor hyperlinking, code blocks are discussed later in this document
133
resulting output:
134
deb http://www.jus.uio.no/sisu/archive unstable main non-free
135
link_text
3.5.2 Linking Text
136
To link text or an image to a url the markup is as follows
137
markup example:
138
about { SiSU }http://url.org markup
139
resulting output:
140
about
141
A shortcut notation is available so the url link may also be provided automatically as a footnote
142
markup example:
143
about {~^ SiSU }http://url.org markup
144
resulting output:
145
about 5 <
146
Internal document links to a tagged location, including an ocn
147
markup example:
148
about { text links }#link_text
149
resulting output:
150
about
151
Shared document collection link
152
markup example:
153
about { SiSU book markup examples }:SiSU/examples.html
154
resulting output:
155
about SiSU book markup examples
156
3.5.3
3.5.3 Linking Images
157
markup example:
158
{ tux.png 64x80 }image
159
resulting output:
160
161
162
163
6 <
164
linked url footnote shortcut
165
{~^ [text to link] }http://url.org
166
text marker
167
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.
168
3.6
3.6 Grouped Text
169
3.6.1
3.6.1 Tables
170
Tables may be prepared in two either of two forms
171
markup example:
172
table{ c3; 40; 30; 30;
173
resulting output:
174
This is a table┆this would become column two of row one┆column three of row one is here』And here begins another row┆column two of row two┆column three of row two, and so on』
175
a second form may be easier to work with in cases where there is not much information in each column
176
markup example: 7 Table from the Wealth of Networks by Yochai Benkler
177
!_ Table 3.1: Contributors to Wikipedia, January 2001 - June 2005
178
resulting output:
179
Table 3.1: Contributors to Wikipedia, January 2001 - June 2005
180
┆Jan. 2001┆Jan. 2002┆Jan. 2003┆Jan. 2004┆July 2004┆June 2006』Contributors*┆10┆472┆2,188┆9,653┆25,011┆48,721』Active contributors**┆9┆212┆846┆3,228┆8,442┆16,945』Very active contributors***┆0┆31┆190┆692┆1,639┆3,016』No. of English language articles┆25┆16,000┆101,000┆190,000┆320,000┆630,000』No. of articles, all languages┆25┆19,000┆138,000┆490,000┆862,000┆1,600,000』
181
* Contributed at least ten times; ** at least 5 times in last month; *** more than 100 times in last month.
182
3.6.2
3.6.2 Poem
183
basic markup:
184
poem{
185
markup example:
186
poem{
187
resulting output:
188
`Fury said to a
189
3.6.3
3.6.3 Group
190
basic markup:
191
group{
192
markup example:
193
group{
194
resulting output:
195
`Fury said to a
196
3.6.4
3.6.4 Code
197
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.
198
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]
199
use of code tags instead of poem compared, resulting output:
200
`Fury said to a
201
From SiSU 2.7.7 on you can number codeblocks by placing a hash after the opening code tag code{# as demonstrated here:
202
1 ┆ `Fury said to a
203
3.7
3.7 Book index
204
To make an index append to paragraph the book index term relates to it, using an equal sign and curly braces.
205
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.
206
Paragraph containing main term and sub-term.
207
The index syntax starts on a new line, but there should not be an empty line between paragraph and index markup.
208
The structure of the resulting index would be:
209
Main term, 1
210
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.
211
Paragraph containing main term, second term and sub-term.
212
The structure of the resulting index would be:
213
First term, 1,
214
If multiple sub-terms appear under one paragraph, they are separated under the main term heading from each other by a pipe symbol.
215
Paragraph containing main term, second term and sub-term.
216
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:
217
Main term, 1,
218
4
4. Composite documents markup
219
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
220
basic markup for importing a document into a master document
221
_<_< filename1.sst
222
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. Alternative markup for importation of documents under consideration, and occasionally supported have been.
223
_<_< filename.ssi
224
Markup Syntax History
225
5
5. Notes related to Files-types and Markup Syntax
226
2.0 introduced new headers and is therefore incompatible with 1.0 though otherwise the same with the addition of a couple of tags (i.e. a superset)
227
0.38 is substantially current for version 1.0
228
depreciated 0.16 supported, though file names were changed at 0.37
229
sisu --query=[sisu version [0.38] or 'history]
230
provides a short history of changes to SiSU markup
231
SiSU 2.0 (2010-03-06:09/6) same as 1.0, apart from the changing of headers and the addition of a monospace tag related headers now grouped, e.g.
232
@title:
233
see document markup samples, and sisu --help headers
234
the monospace tag takes the form of a hash '#'
235
#{ this enclosed text would be monospaced }#
236
1.0 (2009-12-19:50/6) same as 0.69
237
0.69 (2008-09-16:37/2) (same as 1.0) and as previous (0.57) with the addition of book index tags
238
/^={.+?}$/
239
e.g. appended to a paragraph, on a new-line (without a blank line in between) logical structure produced assuming this is the first text "object"
240
={GNU/Linux community distribution:Debian+2|Fedora|Gentoo;Free Software Foundation+5}
241
Free Software Foundation, 1-6
242
0.66 (2008-02-24:07/7) same as previous, adds semantic tags, [experimental and not-used]
243
/[:;]{.+?}[:;][a-z+]/
244
0.57 (2007w34/4) SiSU 0.57 is the same as 0.42 with the introduction of some a shortcut to use the headers @title and @creator in the first heading [expanded using the contents of the headers @title: and @author:]
245
:A~ @title by @author
246
0.52 (2007w14/6) declared document type identifier at start of text/document:
247
SiSU 0.52
248
or, backward compatible using the comment marker:
249
% SiSU 0.38
250
variations include 'SiSU (text|master|insert) [version]' and 'sisu-[version]'
251
0.51 (2007w13/6) skins changed (simplified), markup unchanged
252
0.42 (2006w27/4) * (asterisk) type endnotes, used e.g. in relation to author
253
SiSU 0.42 is the same as 0.38 with the introduction of some additional endnote types,
254
Introduces some variations on endnotes, in particular the use of the asterisk
255
~{* for example for describing an author }~ and ~{** for describing a second author }~
256
* for example for describing an author
257
** for describing a second author
258
and
259
~[* my note ]~ or ~[+ another note ]~
260
which numerically increments an asterisk and plus respectively
261
*1 my note +1 another note
262
0.38 (2006w15/7) introduced new/alternative notation for headers, e.g. @title: (instead of 0~title), and accompanying document structure markup, :A,:B,:C,1,2,3 (maps to previous 1,2,3,4,5,6)
263
SiSU 0.38 introduced alternative experimental header and heading/structure markers,
264
@headername: and headers :A~ :B~ :C~ 1~ 2~ 3~
265
as the equivalent of:
266
0~headername and headers 1~ 2~ 3~ 4~ 5~ 6~
267
The internal document markup of SiSU 0.16 remains valid and standard Though note that SiSU 0.37 introduced a new file naming convention
268
SiSU has in effect two sets of levels to be considered, using 0.38 notation A-C headings/levels, pre-ordinary paragraphs /pre-substantive text, and 1-3 headings/levels, levels which are followed by ordinary text. This may be conceptualised as levels A,B,C, 1,2,3, and using such letter number notation, in effect: A must exist, optional B and C may follow in sequence (not strict) 1 must exist, optional 2 and 3 may follow in sequence i.e. there are two independent heading level sequences A,B,C and 1,2,3 (using the 0.16 standard notation 1,2,3 and 4,5,6) on the positive side: the 0.38 A,B,C,1,2,3 alternative makes explicit an aspect of structuring documents in SiSU that is not otherwise obvious to the newcomer (though it appears more complicated, is more in your face and likely to be understood fairly quickly); the substantive text follows levels 1,2,3 and it is 'nice' to do most work in those levels
269
0.37 (2006w09/7) introduced new file naming convention, .sst (text), .ssm (master), .ssi (insert), markup syntax unchanged
270
SiSU 0.37 introduced new file naming convention, using the file extensions .sst .ssm and .ssi to replace .s1 .s2 .s3 .r1 .r2 .r3 and .si
271
this is captured by the following file 'rename' instruction:
272
rename 's/\.s[123]$/\.sst/' *.s{1,2,3}
273
The internal document markup remains unchanged, from SiSU 0.16
274
0.35 (2005w52/3) sisupod, zipped content file introduced
275
0.23 (2005w36/2) utf-8 for markup file
276
0.22 (2005w35/3) image dimensions may be omitted if rmagick is available to be relied upon
277
0.20.4 (2005w33/4) header 0~links
278
0.16 (2005w25/2) substantial changes introduced to make markup cleaner, header 0~title type, and headings [1-6]~ introduced, also percentage sign (%) at start of a text line as comment marker
279
SiSU 0.16 (0.15 development branch) introduced the use of
280
the header 0~ and headings/structure 1~ 2~ 3~ 4~ 5~ 6~
281
in place of the 0.1 header, heading/structure notation
282
SiSU 0.1 headers and headings structure represented by header 0{~ and headings/structure 1{ 2{ 3{ 4{~ 5{ 6{
283
Endnotes
284
Endnotes