Removing useless whitespaces from upstream files at EOL.
[software/sisu] / data / doc / sisu / v1 / html / sisu.1.html
1 <!-- manual page source format generated by PolyglotMan v3.2, -->
2 <!-- available at http://polyglotman.sourceforge.net/ -->
3
4 <html>
5 <head>
6 <title>"sisu"("1") manual page</title>
7 </head>
8 <body bgcolor='white'>
9 <a href='#toc'>Table of Contents</a><p>
10
11 <h2><a name='sect0' href='#toc0'>Name</a></h2>
12 sisu - documents: markup, structuring, publishing in multiple standard
13 formats, and search
14 <h2><a name='sect1' href='#toc1'>Synopsis</a></h2>
15 sisu [-abcDdFHhIiMmNnopqRrSsTtUuVvwXxYyZz0-9]
16 [filename/wildcard ] sisu [-Ddcv] [instruction] sisu [-CcFLSVvW] SISU -
17 MANUAL, RALPH AMISSAH
18 <p> WHAT IS SISU?
19 <p> 1. INTRODUCTION - WHAT IS SISU?
20
21 <p> <b>SiSU</b> is a framework for document structuring, publishing (in
22 multiple open standard formats) and search, comprising of: (a) a lightweight
23 document structure and presentation markup syntax; and (b) an accompanying
24 engine for generating standard document format outputs from documents prepared
25 in sisu markup syntax, which is able to produce multiple standard outputs
26 (including the population of sql databases) that (can) share a common numbering
27 system for the citation of text within a document. <p> <b>SiSU</b> is
28 developed under an open source, software libre license (GPL3). Its use case for
29 development is to cope with medium to large document sets with evolving markup
30 related technologies, which should be prepared once, and for which you want
31 multiple output formats that can be updated and a common mechanism for
32 cross-output-format citation, and search. <p> <b>SiSU</b> both defines a
33 markup syntax and provides an engine that produces open standards format
34 outputs from documents prepared with <b>SiSU</b> markup. From a single lightly
35 prepared document sisu custom builds several standard output formats which
36 share a common (text object) numbering system for citation of content within a
37 document (that also has implications for search). The sisu engine works with an
38 abstraction of the document&rsquo;s structure and content from which it is
39 possible to generate different forms of representation of the document.
40 Significantly <b>SiSU</b> markup is more sparse than html and outputs which
41 include html, LaTeX, landscape and portrait pdfs, Open Document Format (ODF),
42 all of which can be added to and updated. <b>SiSU</b> is also able to populate
43 SQL type databases at an object level, which means that searches can be made
44 with that degree of granularity. <p> Source document preparation and output
45 generation is a two step process: (i) document source is prepared, that is,
46 marked up in sisu markup syntax and (ii) the desired output subsequently
47 generated by running the sisu engine against document source. Output
48 representations if updated (in the sisu engine) can be generated by re-running
49 the engine against the prepared source. Using <b>SiSU</b> markup applied to a
50 document, <b>SiSU</b> custom builds (to take advantage of the strengths of
51 different ways of representing documents) various standard open output formats
52 including plain text, HTML, XHTML, XML, OpenDocument, LaTeX or PDF files, and
53 populate an SQL database with objects[^1] (equating generally to
54 paragraph-sized chunks) so searches may be performed and matches returned with
55 that degree of granularity ( e.g. your search criteria is met by these
56 documents and at these locations within each document). Document output formats
57 share a common object numbering system for locating content. This is
58 particularly suitable for works (finalized texts as opposed to works that are
59 frequently changed or updated) for which it provides a fixed means of reference
60 of content. <p> In preparing a <b>SiSU</b> document you optionally provide
61 semantic information related to the document in a document header, and in
62 marking up the substantive text provide information on the structure of the
63 document, primarily indicating heading levels and footnotes. You also provide
64 information on basic text attributes where used. The rest is automatic, sisu
65 from this information custom builds[^2] the different forms of output
66 requested. <p> <b>SiSU</b> works with an abstraction of the document based on
67 its structure which is comprised of its structure (or frame)[^3] and the
68 objects[^4] it contains, which enables <b>SiSU</b> to represent the document in
69 many different ways, and to take advantage of the strengths of different ways
70 of presenting documents. The objects are numbered, and these numbers can be
71 used to provide a common base for citing material within a document across the
72 different output format types. This is significant as page numbers are not well
73 suited to the digital age, in web publishing, changing a browser&rsquo;s
74 default font or using a different browser means that text appears on different
75 pages; and in publishing in different formats, html, landscape and portrait pdf
76 etc. again page numbers are of no use to cite text in a manner that is relevant
77 against the different output types. Dealing with documents at an object level
78 together with object numbering also has implications for search. <p> One of
79 the challenges of maintaining documents is to keep them in a format that would
80 allow users to use them without depending on a proprietary software popular at
81 the time. Consider the ease of dealing with legacy proprietary formats today
82 and what guarantee you have that old proprietary formats will remain (or can be
83 read without proprietary software/equipment) in 15 years time, or the way the
84 way in which html has evolved over its relatively short span of existence.
85 <b>SiSU</b> provides the flexibility of outputing documents in multiple
86 non-proprietary open formats including html, pdf[^5] and the ISO standard
87 ODF.[^6] Whilst <b>SiSU</b> relies on software, the markup is uncomplicated and
88 minimalistic which guarantees that future engines can be written to run against
89 it. It is also easily converted to other formats, which means documents
90 prepared in <b>SiSU</b> can be migrated to other document formats. Further
91 security is provided by the fact that the software itself, <b>SiSU</b> is
92 available under GPL3 a licence that guarantees that the source code will always
93 be open, and free as in libre which means that that code base can be used,
94 updated and further developed as required under the terms of its license.
95 Another challenge is to keep up with a moving target. <b>SiSU</b> permits new
96 forms of output to be added as they become important, (Open Document Format
97 text was added in 2006 when it became an ISO standard for office applications
98 and the archival of documents), and existing output to be updated (html has
99 evolved and the related module has been updated repeatedly over the years,
100 presumably when the World Wide Web Consortium (w3c) finalises html 5 which is
101 currently under development, the html module will again be updated allowing all
102 existing documents to be regenerated as html 5). <p> The document formats are
103 written to the file-system and available for indexing by independent indexing
104 tools, whether off the web like Google and Yahoo or on the site like Lucene and
105 Hyperestraier. <p> <b>SiSU</b> also provides other features such as
106 concordance files and document content certificates, and the working against an
107 abstraction of document structure has further possibilities for the research
108 and development of other document representations, the availability of objects
109 is useful for example for topic maps and thesauri, together with the
110 flexibility of <b>SiSU</b> offers great possibilities.
111 <p> <b>SiSU</b> is primarily for published works,
112 which can take advantage of the citation system to reliably reference its
113 documents. <b>SiSU</b> works well in a complementary manner with such collaborative
114 technologies as Wikis, which can take advantage of and be used to discuss
115 the substance of content prepared in <b>SiSU</b>
116 <p> &lt;<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a>
117 &gt;
118 <p> 2.
119 COMMANDS SUMMARY
120 <p> 2.1 SYNOPSIS
121 <p> <b>SiSU</b> - Structured information, Serialized
122 Units - a document publishing system
123 <p> sisu [ &nbsp;-abcDdFHhIiMmNnopqRrSsTtUuVvwXxYyZz0-9
124 &nbsp;] [ &nbsp;filename/ &nbsp;wildcard &nbsp;]
125 <p> sisu [ &nbsp;-Ddcv &nbsp;] [ &nbsp;instruction &nbsp;]
126 <p> sisu [ &nbsp;-CcFLSVvW
127 &nbsp;]
128 <p> Note: commands should be issued from within the directory that contains
129 the marked up files, cd to markup directory.
130 <p> 2.2 DESCRIPTION
131 <p> <b>SiSU</b> <b>SiSU</b>
132 is a document publishing system, that from a simple single marked-up document,
133 produces multiple of output formats including: plaintext, html, LaTeX,
134 pdf, xhtml, XML, info, and SQL (PostgreSQL and SQLite), which share numbered
135 text objects ( structure information. For more see: &lt;<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a>
136 &gt;
137
138 <p> 2.3 DOCUMENT PROCESSING COMMAND FLAGS
139 <p>
140 <dl>
141
142 <dt><b>-a [filename/wildcard]</b> </dt>
143 <dd>produces plaintext
144 with Unix linefeeds and without markup, (object numbers are omitted), has
145 footnotes at end of each paragraph that contains them [ &nbsp;-A &nbsp;for &nbsp;equivalent
146 &nbsp;dos &nbsp;(linefeed) &nbsp;output &nbsp;file] [see &nbsp;-e &nbsp;for (Options include: --endnotes for endnotes
147 --footnotes for footnotes at the end of each paragraph --unix for unix linefeed
148 (default) --msdos for msdos linefeed)
149 <p> </dd>
150
151 <dt><b>-b [filename/wildcard]</b> </dt>
152 <dd>produces xhtml/XML
153 output for browser viewing (sax parsing).
154 <p> </dd>
155
156 <dt><b>-C [--init-site]</b> </dt>
157 <dd>configure/initialise
158 shared output directory files initialize shared output directory (config
159 files such as css and dtd files are not updated if they already exist unless
160 modifier is used). -C --init-site configure/initialise site more extensive than
161 -C on its own, shared output directory files/force update, existing shared
162 output config files such as css and dtd files are updated if this modifier
163 is used.
164 <p> </dd>
165
166 <dt><b>-CC</b> </dt>
167 <dd>configure/initialise shared output directory files initialize
168 shared output directory (config files such as css and dtd files are not
169 updated if they already exist unless modifier is used). The equivalent of:
170 -C --init-site configure/initialise site, more extensive than -C on its own,
171 shared output directory files/force update, existing shared output config
172 files such as css and dtd files are updated if -CC is used.
173 <p> </dd>
174
175 <dt><b>-c [filename/wildcard]</b>
176 </dt>
177 <dd>screen toggle ansi screen colour on or off depending on default set (unless
178 -c flag is used: if sisurc colour default is set to &rsquo;true&rsquo;, output to screen
179 will be with colour, if sisurc colour default is set to &rsquo;false&rsquo; or is undefined
180 screen output will be without colour).
181 <p> </dd>
182
183 <dt><b>-D [instruction] [filename]</b> </dt>
184 <dd>database
185 postgresql ( --pgsql may be used instead) possible instructions, include:
186 --createdb; --create; --dropall; --import [filename]; --update [filename]; --remove
187 [filename]; see database section below.
188 <p> </dd>
189
190 <dt><b>-d [--db-[database &nbsp;type &nbsp;(sqlite|pg)]]
191 --[instruction] [filename]</b> </dt>
192 <dd>database type default set to sqlite, (for which
193 --sqlite may be used instead) or to specify another database --db-[pgsql, &nbsp;sqlite]
194 (however see -D) possible instructions include: --createdb; --create; --dropall;
195 --import [filename]; --update [filename]; --remove [filename]; see database section
196 below.
197 <p> </dd>
198
199 <dt><b>-F [--webserv=webrick]</b> </dt>
200 <dd>generate examples of (naive) cgi search form
201 for sqlite and pgsql depends on your already having used sisu to populate
202 an sqlite and/or pgsql database, (the sqlite version scans the output directories
203 for existing sisu_sqlite databases, so it is first necessary to create
204 them, before generating the search form) see -d -D and the database section
205 below. If the optional parameter --webserv=webrick is passed, the cgi examples
206 created will be set up to use the default port set for use by the webrick
207 server, (otherwise the port is left blank and the system setting used,
208 usually 80). The samples are dumped in the present work directory which
209 must be writable, (with screen instructions given that they be copied to
210 the cgi-bin directory). -Fv (in addition to the above) provides some information
211
212 <p>on setting up hyperestraier for sisu
213 <p> </dd>
214
215 <dt><b>-H [filename/wildcard]</b> </dt>
216 <dd>produces html
217 without link suffixes (.html .pdf etc.) ( an appropriately configured web
218 server. [behaviour &nbsp;switched &nbsp;after &nbsp;0.35 see &nbsp;-h].
219 <p> </dd>
220
221 <dt><b>-h [filename/wildcard]</b> </dt>
222 <dd>produces
223 html (with hardlinks i.e. with name suffixes in links/local urls). html, with
224 internal document links that include the document suffix, i.e. whether it
225 is .html or .pdf (required for browsing directly off a file system, and works
226 with most web servers). [behaviour &nbsp;switched &nbsp;after &nbsp;0.35 &nbsp;see &nbsp;-H].
227 <p> </dd>
228
229 <dt><b>-I [filename/wildcard]</b>
230 </dt>
231 <dd>produces texinfo and info file, (view with pinfo).
232 <p> </dd>
233
234 <dt><b>-i [filename/wildcard]</b>
235 </dt>
236 <dd>produces man page of file, not suitable for all outputs.
237 <p> </dd>
238
239 <dt><b>-L</b> </dt>
240 <dd>prints license
241 information.
242 <p> </dd>
243
244 <dt><b>-M [filename/wildcard/url]</b> </dt>
245 <dd>maintenance mode files created for
246 processing preserved and their locations indicated. (also see -V)
247 <p> </dd>
248
249 <dt><b>-m [filename/wildcard/url]</b>
250 </dt>
251 <dd>assumed for most other flags, creates new intermediate files for processing
252 (document abstraction) that is used in all subsequent processing of other
253 output. This step is assumed for most processing flags. To skip it see -n
254 <p> </dd>
255
256 <dt><b>-N [filename/wildcard/url]</b>
257 </dt>
258 <dd>document digest or document content certificate ( DCC ) as md5 digest tree
259 of the document: the digest for the document, and digests for each object
260 contained within the document (together with information on software versions
261 that produced it) (digest.txt). -NV for verbose digest output to screen.
262 <p> </dd>
263
264 <dt><b>-n
265 [filename/wildcard/url]</b>
266 </dt>
267 <dd>skip the creation of intermediate processing files (document abstraction)
268 if they already exist, this skips the equivalent of -m which is otherwise
269 assumed by most processing flags.
270 <p> </dd>
271
272 <dt><b>-o [filename/wildcard/url]</b> </dt>
273 <dd>output basic
274 document in opendocument file format (opendocument.odt).
275 <p> </dd>
276
277 <dt><b>-p [filename/wildcard]</b>
278 </dt>
279 <dd>produces LaTeX pdf (portrait.pdf &amp; landscape.pdf). Default paper size is set
280 in config file, or document header, or provided with additional command
281 line parameter, e.g. --papersize-a4 preset sizes include: &rsquo;A4&rsquo;, U.S. &rsquo;letter&rsquo; and
282 &rsquo;legal&rsquo; and book sizes &rsquo;A5&rsquo; and &rsquo;B5&rsquo; (system defaults to A4).
283 <p> </dd>
284
285 <dt><b>-q [filename/wildcard]</b>
286 </dt>
287 <dd>quiet less output to screen.
288 <p> </dd>
289
290 <dt><b>-R [filename/wildcard]</b> </dt>
291 <dd>copies sisu output files
292 to remote host using rsync. This requires that sisurc.yml has been provided
293 with information on hostname and username, and that you have your different
294 if -R is used with other flags from if used alone. Alone the rsync --delete
295 parameter is sent, useful for cleaning the remote directory (when -R is
296 used together with other flags, it is not). Also see -r
297 <p> </dd>
298
299 <dt><b>-r [filename/wildcard]</b>
300 </dt>
301 <dd>copies sisu output files to remote host using scp. This requires that sisurc.yml
302 has been provided with information on hostname and username, and that you
303
304 <p>have your
305 <p> </dd>
306
307 <dt><b>-S</b> </dt>
308 <dd>produces a sisupod a zipped sisu directory of markup files
309 including sisu markup source files and the directories local configuration
310 file, images and skins. Note: this only includes the configuration files
311 or skins contained in ./_sisu not those in ~/.sisu -S [filename/wildcard]
312 option. Note: (this<br>
313 option is tested only with zsh).
314 <p> </dd>
315
316 <dt><b>-S [filename/wildcard]</b> </dt>
317 <dd>produces a zipped
318 file of the prepared document specified along with associated images, by
319 default named sisupod.zip they may alternatively be named with the filename
320 extension .ssp This provides a quick way of gathering the relevant parts
321 of a sisu document which can then for example be emailed. A sisupod includes
322 sisu markup source file, (along with associated documents if a master file,
323 or available in multilingual versions), together with related images and
324 skin. <b>SiSU</b> commands can be run directly against a sisupod contained in a
325 local directory, or provided as a url on a remote site. As there is a security
326 issue with skins provided by other users, they are not applied unless the
327 flag --trust or --trusted is added to the command instruction, it is recommended
328 that file that are not your own are treated as untrusted. The directory
329 structure of the unzipped file is understood by sisu, and sisu commands
330 can be run within it. Note: if you wish to send multiple files, it quickly
331 becomes more space efficient to zip the sisu markup directory, rather than
332 the individual files for sending). See the -S option without [filename/wildcard].
333
334 <p> </dd>
335
336 <dt><b>-s [filename/wildcard]</b> </dt>
337 <dd>copies sisu markup file to output directory.
338 <p> </dd>
339
340 <dt><b>-t [filename/wildcard
341 &nbsp;(*.termsheet.rb)]</b> </dt>
342 <dd>standard form document builder, preprocessing feature
343 <p>
344 </dd>
345
346 <dt><b>-U [filename/wildcard]</b> </dt>
347 <dd>prints url output list/map for the available processing
348 flags options and resulting files that could be requested, (can be used
349 to get a list of processing options in relation to a file, together with
350 information on the output that would be produced), -u provides url output
351 mapping for those flags requested for processing. The default assumes sisu_webrick
352 is running and provides webrick url mappings where appropriate, but these
353
354 <p>can be switched to file system paths in sisurc.yml
355 <p> </dd>
356
357 <dt><b>-u [filename/wildcard]</b>
358 </dt>
359 <dd>provides url mapping of output files for the flags requested for processing,
360
361 <p>also see -U
362 <p> </dd>
363
364 <dt><b>-V</b> </dt>
365 <dd>on its own, provides <b>SiSU</b> version and environment information
366 (sisu --help env)
367 <p> </dd>
368
369 <dt><b>-V [filename/wildcard]</b> </dt>
370 <dd>even more verbose than the -v flag.
371 (also see -M)
372 <p> </dd>
373
374 <dt><b>-v</b> </dt>
375 <dd>on its own, provides <b>SiSU</b> version information
376 <p> </dd>
377
378 <dt><b>-v [filename/wildcard]</b>
379 </dt>
380 <dd>provides verbose output of what is being built, where it is being built
381 (and error messages if any), as with -u flag provides a url mapping of files
382 created for each of the processing flag requests. See also -V
383 <p> </dd>
384
385 <dt><b>-W</b> </dt>
386 <dd>starts ruby&rsquo;s
387 webrick webserver points at sisu output directories, the default port is
388 set to 8081 and can be changed in the resource configuration files. [tip:
389 &nbsp;the &nbsp;webrick &nbsp;server &nbsp;requires &nbsp;link &nbsp;suffixes, &nbsp;so &nbsp;html &nbsp;output &nbsp;should &nbsp;be &nbsp;created
390 &nbsp;using &nbsp;the &nbsp;-h &nbsp;option &nbsp;rather &nbsp;than and search -H; &nbsp;also, &nbsp;note &nbsp;-F &nbsp;webrick &nbsp;].
391 <p> </dd>
392
393 <dt><b>-w
394 [filename/wildcard]</b> </dt>
395 <dd>produces concordance (wordmap) a rudimentary index
396 of all the words in a document. (Concordance files are not generated for
397 documents of over 260,000 words unless this limit is increased in the file
398 sisurc.yml)
399 <p> </dd>
400
401 <dt><b>-X [filename/wildcard]</b> </dt>
402 <dd>produces XML output with deep document
403 structure, in the nature of dom.
404 <p> </dd>
405
406 <dt><b>-x [filename/wildcard]</b> </dt>
407 <dd>produces XML output
408 shallow structure (sax parsing).
409 <p> </dd>
410
411 <dt><b>-Y [filename/wildcard]</b> </dt>
412 <dd>produces a short
413 sitemap entry for the document, based on html output and the sisu_manifest.
414 --sitemaps generates/updates the sitemap index of existing sitemaps. (Experimental,
415 [g,y,m &nbsp;announcement &nbsp;this &nbsp;week])
416 <p> </dd>
417
418 <dt><b>-y [filename/wildcard]</b> </dt>
419 <dd>produces an html
420 summary of output generated (hyperlinked to content) and document specific
421 metadata (sisu_manifest.html). This step is assumed for most processing flags.
422
423 <p> </dd>
424
425 <dt><b>-Z [filename/wildcard]</b> </dt>
426 <dd>Zap, if used with other processing flags deletes
427 output files of the type about to be processed, prior to processing. If
428 -Z is used as the lone processing related flag (or in conjunction with a
429 combination of -[mMvVq]), will remove the related document output directory.
430
431 <p> </dd>
432
433 <dt><b>-z [filename/wildcard]</b> </dt>
434 <dd>produces php (zend) [this &nbsp;feature &nbsp;is &nbsp;disabled &nbsp;for
435 &nbsp;the &nbsp;time being]
436 <p> </dd>
437
438 <dt><b>--harvest *.ss[tm]</b> </dt>
439 <dd>makes two lists of sisu output based
440 on the sisu markup documents in a directory: list of author and authors
441 works (year and titles), and; list by topic with titles and author. Makes
442 use of header metadata fields (author, title, date, topic_register). Can
443 be used with maintenance (-M) and remote placement (-R) flags.
444 <p> </dd>
445 </dl>
446 3. COMMAND
447 LINE MODIFIERS
448 <p>
449 <dl>
450
451 <dt><b>--no-ocn</b> </dt>
452 <dd>[with &nbsp;-h &nbsp;-H &nbsp;or &nbsp;-p] switches off object citation numbering.
453 Produce output without identifying numbers in margins of html or LaTeX/pdf
454 output.
455 <p> </dd>
456
457 <dt><b>--no-annotate</b> </dt>
458 <dd>strips output text of editor endnotes[^*1] denoted by
459
460 <p>asterisk or dagger/plus sign
461 <p> </dd>
462
463 <dt><b>--no-asterisk</b> </dt>
464 <dd>strips output text of editor endnotes[^*2]
465
466 <p>denoted by asterisk sign
467 <p> </dd>
468
469 <dt><b>--no-dagger</b> </dt>
470 <dd>strips output text of editor endnotes[^+1]
471
472 <p>denoted by dagger/plus sign
473 <p> </dd>
474 </dl>
475 4. DATABASE COMMANDS
476 <p> dbi - database interface
477
478 <p> -D or --pgsql set for postgresql -d or --sqlite default set for sqlite -d is
479 modifiable with --db=[database &nbsp;type &nbsp;(pgsql &nbsp;or &nbsp;sqlite)]
480 <p>
481 <dl>
482
483 <dt><b>-Dv --createall</b> </dt>
484 <dd>initial
485 step, creates required relations (tables, indexes) in existing postgresql
486 database (a database should be created manually and given the same name
487 as working directory, as requested) (rb.dbi) [ &nbsp;-dv &nbsp;--createall sqlite &nbsp;equivalent]
488 it may be necessary to run sisu -Dv --createdb initially NOTE: at the present
489 time for postgresql it may be necessary to manually create the database.
490 The command would be &rsquo;createdb [database name]&rsquo; where database name would
491 be SiSU_[present &nbsp;working &nbsp;directory &nbsp;name &nbsp;(without &nbsp;path)]. Please use only
492 alphanumerics and underscores.
493 <p> </dd>
494
495 <dt><b>-Dv --import</b> </dt>
496 <dd>[filename/wildcard] imports data
497 specified to postgresql db (rb.dbi) [ &nbsp;-dv &nbsp;--import &nbsp;sqlite &nbsp;equivalent]
498 <p> </dd>
499
500 <dt><b>-Dv --update</b>
501 </dt>
502 <dd>[filename/wildcard] updates/imports specified data to postgresql db (rb.dbi)
503 [ &nbsp;-dv &nbsp;--update &nbsp;sqlite &nbsp;equivalent]
504 <p> </dd>
505
506 <dt><b>-D --remove</b> </dt>
507 <dd>[filename/wildcard] removes specified
508 data to postgresql db (rb.dbi) [ &nbsp;-d &nbsp;--remove &nbsp;sqlite &nbsp;equivalent]
509 <p> </dd>
510
511 <dt><b>-D --dropall</b>
512 </dt>
513 <dd>kills data --dropall &nbsp;sqlite &nbsp;equivalent]
514 <p> The v in e.g. -Dv is for verbose output.
515
516 <p> </dd>
517 </dl>
518 5. SHORTCUTS, SHORTHAND FOR MULTIPLE FLAGS
519 <p>
520 <dl>
521
522 <dt><b>--update [filename/wildcard]</b>
523 </dt>
524 <dd>Checks existing file output and runs the flags required to update this
525 output. This means that if only html and pdf output was requested on previous
526 runs, only the -hp files will be applied, and only these will be generated
527 this time, together with the summary. This can be very convenient, if you
528 offer different outputs of different files, and just want to do the same
529 again.
530 <p> </dd>
531
532 <dt><b>-0 to -5 [filename &nbsp;or &nbsp;wildcard]</b> </dt>
533 <dd>Default shorthand mappings (note that
534 the defaults can be changed/configured in the sisurc.yml file):
535 <p> </dd>
536
537 <dt><b>-0</b> </dt>
538 <dd>-mNhwpAobxXyYv
539 [this &nbsp;is &nbsp;the &nbsp;default &nbsp;action &nbsp;run &nbsp;when &nbsp;no &nbsp;i.e. &nbsp;on &nbsp;&rsquo;sisu &nbsp;[filename]&rsquo;]
540 <p> </dd>
541
542 <dt><b>-1</b> </dt>
543 <dd>-mNHwpy
544
545 <p> </dd>
546
547 <dt><b>-2</b> </dt>
548 <dd>-mNHwpaoy
549 <p> </dd>
550
551 <dt><b>-3</b> </dt>
552 <dd>-mNhwpAobxXyY
553 <p> </dd>
554
555 <dt><b>-4</b> </dt>
556 <dd>-mNhwpAobxXDyY --import
557 <p> </dd>
558
559 <dt><b>-5</b> </dt>
560 <dd>-mNhwpAobxXDyY --update
561
562 <p> add -v for verbose mode and -c for color, e.g. sisu -2vc [filename &nbsp;or
563 <p> consider
564
565 <p>-
566 <p>u for appended url info or -v for verbose output
567 <p> </dd>
568 </dl>
569 5.1 COMMAND LINE WITH FLAGS
570 - BATCH PROCESSING
571 <p> In the data directory run sisu -mh filename or wildcard
572 eg. cisg.sst documents.
573 <p> Running sisu (alone without any flags, filenames
574 or wildcards) brings up the interactive help, as does any sisu command
575 that is not recognised. Enter to escape.
576 <p> 6. HELP
577 <p> 6.1 SISU MANUAL
578 <p> The most
579 up to date information on sisu should be contained in the sisu_manual,
580 available at:
581 <p> &lt;<a href='http://sisudoc.org/sisu/sisu_manual/'>http://sisudoc.org/sisu/sisu_manual/</a>
582 &gt;<br>
583
584 <p> The manual can be generated from source, found respectively, either
585 within the <b>SiSU</b> tarball or installed locally at:
586 <p> ./data/doc/sisu/v1/sisu_markup_samples/sisu_manual/<br>
587
588 <p> /usr/share/doc/sisu/v1/sisu_markup_samples/sisu_manual/<br>
589
590 <p> move to the respective directory and type e.g.:
591 <p> sisu sisu_manual.ssm<br>
592
593 <p> 6.2 SISU MAN PAGES
594 <p> If <b>SiSU</b> is installed on your system usual man commands
595 should be available, try:
596 <p> man sisu<br>
597
598 <p> man sisu_markup<br>
599
600 <p> man sisu_commands<br>
601
602 <p> Most <b>SiSU</b> man pages are generated directly from sisu documents that
603 are used to prepare the sisu manual, the sources files for which are located
604 within the <b>SiSU</b> tarball at:
605 <p> ./data/doc/sisu/v1/sisu_markup_samples/sisu_manual<br>
606
607 <p> Once installed, directory equivalent to:
608 <p> /usr/share/doc/sisu/v1/sisu_markup_samples/sisu_manual/<br>
609
610
611 <p> Available man pages are converted back to html using man2html:
612 <p> /usr/share/doc/sisu/v1/html/<br>
613
614 <p> ./data/doc/sisu/v1/html/<br>
615
616 <p> An online version of the sisu man page is available here:
617 <p> * various
618 sisu man pages &lt;<a href='http://www.jus.uio.no/sisu/man/'>http://www.jus.uio.no/sisu/man/</a>
619 &gt; [^7]
620 <p> * sisu.1 &lt;<a href='http://www.jus.uio.no/sisu/man/sisu.1.html'>http://www.jus.uio.no/sisu/man/sisu.1.html</a>
621 &gt;
622 [^8]
623 <p> 6.3 SISU BUILT-IN INTERACTIVE HELP
624 <p> This is particularly useful for
625 getting the current sisu setup/environment information:
626 <p> sisu --help<br>
627
628 <p> sisu --help [subject]<br>
629
630 <p> sisu --help commands<br>
631
632 <p> sisu --help markup<br>
633
634 <p> sisu --help env [for &nbsp;feedback &nbsp;on &nbsp;the &nbsp;way &nbsp;your &nbsp;system &nbsp;is <br>
635 setup &nbsp;with &nbsp;regard &nbsp;to &nbsp;sisu]<br>
636
637 <p> sisu -V [environment &nbsp;information, &nbsp;same &nbsp;as &nbsp;above &nbsp;command]<br>
638
639 <p> sisu (on its own provides version and some help information)<br>
640
641 <p> Apart from real-time information on your current configuration the <b>SiSU</b>
642 manual and man pages are likely to contain more up-to-date information than
643 the sisu interactive help (for example on commands and markup).
644 <p> NOTE:
645 Running the command sisu (alone without any flags, filenames or wildcards)
646 brings up the interactive help, as does any sisu command that is not recognised.
647 Enter to escape.
648 <p> 6.4 HELP SOURCES
649 <p> For lists of alternative help sources,
650 see:
651 <p> <b>man page</b>
652 <p> man sisu_help_sources<br>
653
654 <p> <b>man2html</b>
655 <p> /usr/share/doc/sisu/v1/html/sisu.1.html<br>
656
657 <p> &lt;<a href='http://sisudoc.org/sisu/sisu_help_sources/index.html'>http://sisudoc.org/sisu/sisu_help_sources/index.html</a>
658 &gt;<br>
659
660 <p> 7. INTRODUCTION TO SISU MARKUP[^9]
661 <p> 7.1 SUMMARY
662 <p> <b>SiSU</b> source documents
663 are plaintext (UTF-8)[^10] files
664 <p> All paragraphs are separated by an empty
665 line.
666 <p> Markup is comprised of:
667 <p> * at the top of a document, the document
668 header made up of semantic meta-data about the document and if desired additional
669 processing instructions (such an instruction to automatically number headings
670 from a particular level down)
671 <p> * followed by the prepared substantive
672 text of which the most important single characteristic is the markup of
673 different heading levels, which define the primary outline of the document
674 structure. Markup of substantive text includes:
675 <p> * heading levels defines
676 document structure<br>
677
678 <p> * text basic attributes, italics, bold etc.<br>
679
680 <p> * grouped text (objects), which are to be treated differently, such
681 as code<br>
682 blocks or poems.<br>
683
684 <p> * footnotes/endnotes<br>
685
686 <p> * linked text and images<br>
687
688 <p> * paragraph actions, such as indent, bulleted, numbered-lists, etc.<br>
689
690 <p> Some interactive help on markup is available, by typing sisu and selecting
691
692 <p>markup or sisu --help markup
693 <p> To check the markup in a file:
694 <p> sisu --identify
695 [filename].sst<br>
696
697 <p> For brief descriptive summary of markup history
698 <p> sisu --query-history<br>
699
700 <p> or if for a particular version:
701 <p> sisu --query-0.38<br>
702
703 <p> 7.2 MARKUP EXAMPLES
704 <p> 7.2.1 ONLINE
705 <p> Online markup examples are available
706 together with the respective outputs produced from &lt;<a href='http://www.jus.uio.no/sisu/SiSU/examples.html'>http://www.jus.uio.no/sisu/SiSU/examples.html</a>
707 &gt;
708 or from &lt;<a href='http://www.jus.uio.no/sisu/sisu_examples/'>http://www.jus.uio.no/sisu/sisu_examples/</a>
709 &gt;
710 <p> There is of course this
711 document, which provides a cursory overview of sisu markup and the respective
712 output produced: &lt;<a href='http://www.jus.uio.no/sisu/sisu_markup/'>http://www.jus.uio.no/sisu/sisu_markup/</a>
713 &gt;
714 <p> Some example marked
715 up files are available as html with syntax highlighting for viewing: &lt;<a href='http://www.jus.uio.no/sisu/sample/syntax'>http://www.jus.uio.no/sisu/sample/syntax</a>
716 &gt;
717
718 <p> an alternative presentation of markup syntax: &lt;<a href='http://www.jus.uio.no/sisu/sample/on_markup.txt'>http://www.jus.uio.no/sisu/sample/on_markup.txt</a>
719 &gt;
720
721 <p> 7.2.2 INSTALLED
722 <p> With <b>SiSU</b> installed sample skins may be found in: /usr/share/doc/sisu/v1/sisu_markup_samples/dfsg
723 (or equivalent directory) and if sisu-markup-samples is installed also under:
724
725 <p>/usr/share/doc/sisu/v1/sisu_markup_samples/non-free
726 <p> 8. MARKUP OF HEADERS
727 <p>
728 Headers contain either: semantic meta-data about a document, which can
729 be used by any output module of the program, or; processing instructions.
730
731 <p> Note: the first line of a document may include information on the markup
732 version used in the form of a comment. Comments are a percentage mark at
733 the start of a paragraph (and as the first character in a line of text)
734 followed by a space and the comment:
735 <p>
736 <p> <br>
737 <pre> % this would be a comment
738 </pre>
739 <p> 8.1 SAMPLE HEADER
740 <p> This current document has a header similar to this
741 one (without the comments):
742 <p>
743 <p> <br>
744 <pre> % SiSU 0.57
745 @title: SiSU
746 @subtitle: Markup
747 @creator: Amissah, Ralph
748 % note formatting rules on author / creator field,
749 @rights: Copyright (C) Ralph Amissah 2007, part of SiSU documentation,
750 License GPL 3
751 @type: information
752 @subject: ebook, epublishing, electronic book, electronic publishing,
753 electronic document, electronic citation, data structure, citation systems,
754 search
755 @topic_register: text markup language; application:text processing;output:html|xml|latex|pdf|sql
756 % note formatting for topic_register topic levels are separated by a
757 colon, a semi-colon separates main topics
758 @date: 2007-09-16
759 % original publication date unless the substantive text is updated/modified,
760 then date of update
761 @date.created: 2002-08-28
762 @date.issued: 2002-08-28
763 @date.available: 2002-08-28
764 @date.modified: 2007-09-16
765 @level: new=C; break=1; num_top=1
766 % comment: in this @level header num_top=1 starts automatic heading numbering
767 at heading level 1 (numbering continues 3 levels down); the new and break
768 instructions are used by the LaTeX/pdf and odf output to determine where
769 to put page breaks (that are not used by html output or say sql database
770 population).
771 @skin: skin_sisu_manual
772 % skins modify the appearance of a document and are placed in a sub-directory
773 under ./_sisu/skin ~/.sisu/skin or /etc/sisu/skin. A skin may affect single
774 documents that request them, all documents in a directory, or be site-wide.
775 (A document is affected by a single skin)
776 @bold: /Gnu|Debian|Ruby|SiSU/
777 @links: { SiSU Manual }http://www.jus.uio.no/sisu/sisu_manual/
778 { Book Samples and Markup Examples }http://www.jus.uio.no/sisu/SiSU/examples.html
779 { SiSU @ Wikipedia }http://en.wikipedia.org/wiki/SiSU
780 { SiSU @ Freshmeat }http://freshmeat.net/projects/sisu/
781 { SiSU @ Ruby Application Archive }http://raa.ruby-lang.org/project/sisu/
782 { SiSU @ Debian }http://packages.qa.debian.org/s/sisu.html
783 { SiSU Download }http://www.jus.uio.no/sisu/SiSU/download.html
784 { SiSU Changelog }http://www.jus.uio.no/sisu/SiSU/changelog.html
785 </pre>
786 <p> 8.2 AVAILABLE HEADERS
787 <p> Header tags appear at the beginning of a document
788 and provide meta information on the document (such as the Dublin Core),
789 or information as to how the document as a whole is to be processed. All
790 header instructions take either the form @headername: or 0~headername. All
791
792 <p>Dublin Core meta tags are available
793 <p> <b>@indentifier:</b> information or instructions
794
795 <p> where the information
796 <p> Note: a header where used should only be used
797 once; all headers apart from @title: are optional; the @structure: header
798 is used to describe document structure, and can be useful to know.
799 <p> This
800
801 <p>is a sample header
802 <p> <b>% SiSU 0.38</b> [declared &nbsp;file-type &nbsp;identifier &nbsp;with &nbsp;markup
803 &nbsp;version]
804 <p>
805 <p> <b>@title:</b> &nbsp;[title &nbsp;text] This is the title of the document and
806 used as such, this header is the only one that is<br>
807 <i>mandatory</i>
808 <p> <b>@subtitle:</b> The Subtitle if any
809 <p> <b>@creator:</b> [or &nbsp;@author:] Name
810
811 <p>of Author
812 <p> <b>@subject:</b> (whatever your subject)
813 <p> <b>@description:</b>
814 <p> <b>@publisher:</b>
815
816 <p> <b>@contributor:</b>
817 <p> <b>@translator:</b> &nbsp;[or &nbsp;@translated_by:]
818 <p> <b>@illustrator:</b> &nbsp;[or
819 &nbsp;@illustrated_by:]
820 <p> <b>@prepared_by:</b> &nbsp;[or &nbsp;@digitized_by:]
821 <p> <b>@date: 2000-08-27</b>
822 [ &nbsp;also &nbsp;@date.created: &nbsp;@date.issued: &nbsp;@date.available: &nbsp;@date.valid: &nbsp;]
823 <p>
824 <p> <b>@type:
825
826 <p>article</b>
827 <p> <b>@format:</b>
828 <p> <b>@identifier:</b>
829 <p> <b>@source:</b>
830 <p> <b>@language:</b> [or &nbsp;@language.document:]
831 [country &nbsp;code &nbsp;for &nbsp;language &nbsp;if &nbsp;available, &nbsp;or &nbsp;language, &nbsp;English, &nbsp;en &nbsp;is &nbsp;the
832 &nbsp;default &nbsp;setting] (en - English, fr - French, de - German, it - Italian, es
833 - Spanish, pt - Portuguese, sv - Swedish, da - Danish, fi - Finnish, no - Norwegian,
834 is - Icelandic, nl - Dutch, et - Estonian, hu - Hungarian, pl - Polish, ro -
835 Romanian, ru - Russian, el - Greek, uk - Ukranian, tr - Turkish, sk - Slovak,
836 sl - Slovenian, hr - Croatian, cs - Czech, bg - Bul garian ) [however, &nbsp;encodings
837 &nbsp;are &nbsp;not &nbsp;available &nbsp;for &nbsp;all &nbsp;of &nbsp;the languages &nbsp;listed.]
838 <p> [@language.original:
839 &nbsp;original &nbsp;language &nbsp;in &nbsp;which &nbsp;the &nbsp;work &nbsp;was published]
840 <p> <b>@papersize:</b> (A4|US_letter|book_B5|book_A5|US_legal)
841
842 <p> <b>@relation:</b>
843 <p> <b>@coverage:</b>
844 <p> <b>@rights:</b> Copyright (c) Name of Right Holder,
845 all rights reserved, or as granted: public domain, copyleft, creative commons
846 variant, etc.
847 <p> <b>@owner:</b>
848 <p> <b>@keywords:</b> text document generation processing
849 management latex pdf structured xml citation [your &nbsp;keywords &nbsp;here, &nbsp;used
850 &nbsp;for &nbsp;example &nbsp;by &nbsp;rss &nbsp;feeds,
851 <p> <b>@abstract:</b> [paper &nbsp;abstract, &nbsp;placed &nbsp;after &nbsp;table
852 &nbsp;of &nbsp;contents]
853 <p> <b>@comment:</b> [...]
854 <p> <b>@catalogue:</b> loc=[Library &nbsp;of &nbsp;Congress &nbsp;classification];
855 dewey=[Dewey rss &nbsp;feeds, isbn=[ISBN]; pg=[Project &nbsp;Gutenberg &nbsp;text &nbsp;number]
856
857 <p> <b>@classify_loc:</b> [Library &nbsp;of &nbsp;Congress &nbsp;classification]
858 <p> <b>@classify_dewey:</b>
859 [Dewey &nbsp;classification]
860 <p> <b>@classify_isbn:</b> [ISBN]
861 <p> <b>@classify_pg:</b> [Project
862 &nbsp;Gutenberg &nbsp;text &nbsp;number]
863 <p> <b>@prefix:</b> [prefix &nbsp;is &nbsp;placed &nbsp;just &nbsp;after &nbsp;table &nbsp;of
864 &nbsp;contents]
865 <p> <b>@prefix_a:</b> [prefix &nbsp;is &nbsp;placed &nbsp;just &nbsp;before &nbsp;table &nbsp;of &nbsp;contents
866 &nbsp;- &nbsp;not
867 <p> <b>@prefix_b:</b>
868 <p> <b>@rcs:</b> $Id: sisu_markup.sst,v 1.2 2007/09/08 17:12:47
869 ralph Exp $ [used &nbsp;by &nbsp;rcs or &nbsp;cvs &nbsp;to &nbsp;embed &nbsp;version &nbsp;(revision &nbsp;control) &nbsp;information
870 &nbsp;into document, &nbsp;rcs &nbsp;or &nbsp;cvs &nbsp;can &nbsp;usefully &nbsp;provide &nbsp;a &nbsp;history &nbsp;of updates &nbsp;to
871 &nbsp;a &nbsp;document &nbsp;]
872 <p> <b>@structure:</b> PART; CHAPTER; SECTION; ARTICLE; none; none;
873 optional, document structure can be defined by words to match or regular
874 expression (the regular expression is assumed to start at the beginning
875 of a line of text i.e. ^) default markers :A~ to :C~ and 1~ to 6~ can be used
876 within text instead, without this header tag, and may be used to supplement
877 the instructions provided in this header tag if provided (@structure: is
878 a synonym for @toc:)
879 <p> <b>@level:</b> newpage=3; breakpage=4 [paragraph &nbsp;level,
880 &nbsp;used &nbsp;by &nbsp;latex &nbsp;to &nbsp;breakpages, &nbsp;the &nbsp;page &nbsp;is &nbsp;optional &nbsp;eg. &nbsp;in &nbsp;newpage]
881 <p> <b>@markup:</b>
882 information on the markup used, e.g. new=1,2,3; break=4; num_top=4 [or is
883 newpage=1,2,3; &nbsp;breakpage=4; &nbsp;num_top=4] newpage and breakpage, heading level,
884 used by LaTeX to breakpages. breakpage: starts on a new page in single column
885 text and on a new column in double column text; newpage: starts on a new
886 page for both single and double column texts. num_top=4 [auto-number &nbsp;document,
887 &nbsp;starting &nbsp;at &nbsp;level &nbsp;4. &nbsp;the a new default &nbsp;is &nbsp;to &nbsp;provide &nbsp;3 &nbsp;levels, &nbsp;as &nbsp;in &nbsp;1 &nbsp;level
888 &nbsp;4, &nbsp;1.1 &nbsp;1.1.1 &nbsp;level &nbsp;6, &nbsp;markup &nbsp;to &nbsp;be &nbsp;merged &nbsp;within &nbsp;level] num_extract [take
889 &nbsp;numbering &nbsp;of &nbsp;headings &nbsp;provided &nbsp;(manually &nbsp;in marked &nbsp;up &nbsp;source &nbsp;document),
890 &nbsp;and &nbsp;use &nbsp;for &nbsp;numbering &nbsp;of segments. &nbsp;Available &nbsp;where &nbsp;a &nbsp;clear &nbsp;numbering &nbsp;structure
891 &nbsp;is provided &nbsp;within &nbsp;document, &nbsp;without &nbsp;the &nbsp;repetition &nbsp;of &nbsp;a &nbsp;number in &nbsp;a &nbsp;header.]
892 [In &nbsp;0.38 &nbsp;notation, &nbsp;you &nbsp;would &nbsp;map &nbsp;to &nbsp;the equivalent &nbsp;levels, &nbsp;the &nbsp;examples
893 &nbsp;provided &nbsp;would &nbsp;map &nbsp;to &nbsp;the following &nbsp;new=A,B,C; &nbsp;break=1; &nbsp;num_top=1 &nbsp;[or &nbsp;newpage=A,B,C;
894 breakpage=1; &nbsp;num_top=1] see headings]
895 <p> <b>@bold:</b> [regular &nbsp;expression &nbsp;of &nbsp;words/phrases
896 &nbsp;to &nbsp;be &nbsp;made &nbsp;bold]
897 <p> <b>@italics:</b> [regular &nbsp;expression &nbsp;of &nbsp;words/phrases &nbsp;to &nbsp;italicise]
898
899 <p> <b>@vocabulary:</b> name of taxonomy/vocabulary/wordlist to use against document
900
901 <p> <b>@skin:</b> skin_doc_[name_of_desired_document_skin] skins change default
902 settings related to the appearance of documents generated, such as the
903 urls of the home site, and the icon/logo for the document or site.
904 <p>
905 <dl>
906
907 <dt><b>@man:
908 8;</b> </dt>
909 <dd>name=sisu - documents: markup, structuring, publishing in multiple standard
910 formats, and search; synopsis=sisu [-abcDdFHhIiMmNnopqRrSsTtUuVvwXxYyZz0-9]
911 [filename/wildcard ] sisu [-Ddcv] [instruction] sisu [-CcFLSVvW] the man
912 page category number (default 1) and special tags used in preparing man
913
914 <p>page headings
915 <p> <b>@links:</b> { <b>SiSU</b> }<a href='http://www.jus.uio.no/sisu/;'>http://www.jus.uio.no/sisu/;</a>
916 { FSF }<a href='http://www.fsf.org'>http://www.fsf.org</a>
917
918
919 <p> <b>@promo:</b> sisu, ruby, search_libre_docs, open_society [places &nbsp;content &nbsp;in
920 &nbsp;right &nbsp;pane &nbsp;in &nbsp;html, &nbsp;makes &nbsp;use &nbsp;of &nbsp;commented &nbsp;out &nbsp;sample &nbsp;in &nbsp;document and &nbsp;promo.yml,
921 &nbsp;commented &nbsp;out &nbsp;sample &nbsp;in &nbsp;document
922 <p> </dd>
923 </dl>
924 9. MARKUP OF SUBSTANTIVE TEXT
925 <p> 9.1 HEADING
926
927 <p>LEVELS
928 <p> Heading levels are :A~ ,:B~ ,:C~ ,1~ ,2~ ,3~ ... :A - :C being part
929 / section headings, followed by other heading levels, and 1 -6 being headings
930 followed by substantive text or sub-headings. :A~ usually the title :A~?
931 conditional level 1 heading (used where a stand-alone document may be imported
932 into another)
933 <p> <b>:A~ [heading &nbsp;text]</b> Top level heading [this &nbsp;usually &nbsp;has
934 &nbsp;similar &nbsp;content &nbsp;to &nbsp;the &nbsp;] NOTE: the heading levels described here are in
935 0.38 notation, see heading
936 <p> <b>:B~ [heading &nbsp;text]</b> Second level heading [this
937 &nbsp;is &nbsp;a &nbsp;heading &nbsp;level &nbsp;divider]
938 <p> <b>:C~ [heading &nbsp;text]</b> Third level heading [this
939 &nbsp;is &nbsp;a &nbsp;heading &nbsp;level &nbsp;divider]
940 <p> <b>1~ [heading &nbsp;text]</b> Top level heading preceding
941 substantive text of document or sub-heading 2, the heading level that would
942 normally be marked 1. or 2. or 3. etc. in a document, and the level on which
943 sisu by default would break html output into named segments, names are
944 provided automatically if none are given (a number), otherwise takes the
945
946 <p>form 1~my_filename_for_this_segment
947 <p> <b>2~ [heading &nbsp;text]</b> Second level heading
948 preceding substantive text of document or sub-heading 3, the heading level
949 that would normally be marked 1.1 or 1.2 or 1.3 or 2.1 etc. in a document.
950 <p>
951 <b>3~ [heading &nbsp;text]</b> Third level heading preceding substantive text of document,
952 that would normally be marked 1.1.1 or 1.1.2 or 1.2.1 or 2.1.1 etc. in a document
953
954 <p>
955 <p> <br>
956 <pre> 1~filename level 1 heading,
957 % the primary division such as Chapter that is followed by substantive
958 text, and may be further subdivided (this is the level on which by default
959 html segments are made)
960 </pre>
961 <p> 9.2 FONT ATTRIBUTES
962 <p> <b>markup example:</b>
963 <p>
964 <p> <br>
965 <pre> normal text !{emphasis}! *{bold text}* _{underscore}_ /{italics}/
966 normal text
967 !{emphasis}!
968 *{bold text}*
969 _{underscore}_
970 /{italics}/
971
972 ^{superscript}^
973 ,{subscript},
974 +{inserted text}+
975 -{strikethrough}-
976 </pre>
977 <p> <b>resulting output:</b>
978 <p> normal text <b>emphasis</b> <b>bold text</b> <i>underscore</i> <i>italics</i>
979 &lt;cite&gt;citation&lt;/cite&gt; ^superscript^ &nbsp;[subscript] &lt;ins&gt;inserted text&lt;/ins&gt; &lt;del&gt;strikethrough&lt;/del&gt;
980
981 <p> normal text
982 <p>
983 <p> <b>bold text</b>
984 <p> <i>underscore</i>
985 <p> <i>italics</i>
986 <p> &lt;cite&gt;citation&lt;/cite&gt;
987 <p>
988 ^superscript^
989 <p> [subscript]
990 <p> &lt;ins&gt;inserted text&lt;/ins&gt;
991 <p> &lt;del&gt;strikethrough&lt;/del&gt;
992
993 <p> 9.3 INDENTATION AND BULLETS
994 <p> <b>markup example:</b>
995 <p>
996 <p> <br>
997 <pre> ordinary paragraph
998 _1 indent paragraph one step
999 _2 indent paragraph two steps
1000 _9 indent paragraph nine steps
1001 </pre>
1002 <p>
1003 <p> <b>resulting output:</b>
1004 <p> ordinary paragraph
1005 <p> indent paragraph one step<br>
1006
1007 <p> indent paragraph two steps<br>
1008
1009 <p> indent paragraph nine steps<br>
1010
1011 <p> <b>markup example:</b>
1012 <p>
1013 <p> <br>
1014 <pre> _* bullet text
1015 _1* bullet text, first indent
1016 _2* bullet text, two step indent
1017 </pre>
1018 <p> <b>resulting output:</b>
1019 <p> * bullet text
1020 <p> * bullet text, first indent<br>
1021
1022 <p> * bullet text, two step indent<br>
1023
1024 <p> Numbered List (not to be confused with headings/titles, (document structure))
1025
1026 <p> <b>markup example:</b>
1027 <p>
1028 <p> <br>
1029 <pre> # numbered list numbered list 1., 2., 3, etc.
1030 _# numbered list numbered list indented a., b., c., d., etc.
1031 </pre>
1032 <p> 9.4 FOOTNOTES / ENDNOTES
1033 <p> Footnotes and endnotes not distinguished in
1034 markup. They are automatically numbered. Depending on the output file format
1035 (html, odf, pdf etc.), the document output selected will have either footnotes
1036 or endnotes.
1037 <p> <b>markup example:</b>
1038 <p>
1039 <p> <br>
1040 <pre> ~{ a footnote or endnote }~
1041 </pre>
1042 <p> <b>resulting output:</b>
1043 <p> [^11]
1044 <p> <b>markup example:</b>
1045 <p>
1046 <p> <br>
1047 <pre> normal text~{ self contained endnote marker &amp; endnote in one }~ continues
1048 </pre>
1049 <p> <b>resulting output:</b>
1050 <p> normal text[^12] continues
1051 <p> <b>markup example:</b>
1052 <p>
1053 <p> <br>
1054 <pre> normal text ~{* unnumbered asterisk footnote/endnote, insert multiple
1055 asterisks if required }~ continues
1056 normal text ~{** another unnumbered asterisk footnote/endnote }~ continues
1057 </pre>
1058 <p> <b>resulting output:</b>
1059 <p> normal text [^*] continues
1060 <p> normal text [^**] continues
1061
1062 <p>
1063 <p> <b>markup example:</b>
1064 <p>
1065 <p> <br>
1066 <pre> normal text ~[* &nbsp;editors &nbsp;notes, &nbsp;numbered &nbsp;asterisk &nbsp;footnote/endnote &nbsp;series
1067 &nbsp;]~ continues
1068 normal text ~[+ &nbsp;editors &nbsp;notes, &nbsp;numbered &nbsp;asterisk &nbsp;footnote/endnote &nbsp;series
1069 &nbsp;]~ continues
1070 </pre>
1071 <p> <b>resulting output:</b>
1072 <p> normal text [^*3] continues
1073 <p> normal text [^+2] continues
1074
1075 <p>
1076 <p> <b>Alternative endnote pair notation for footnotes/endnotes:</b>
1077 <p>
1078 <p> <br>
1079 <pre> % note the endnote marker
1080 normal text~^ continues
1081 ^~ endnote text following the paragraph in which the marker occurs
1082 </pre>
1083 <p> the standard and pair notation cannot be mixed in the same document
1084 <p>
1085
1086 <p>9.5 LINKS
1087 <p> 9.5.1 NAKED URLS WITHIN TEXT, DEALING WITH URLS
1088 <p> urls are found
1089 within text and marked up automatically. A url within text is automatically
1090 hyperlinked to itself and by default decorated with angled braces, unless
1091 they are contained within a code block (in which case they are passed as
1092 normal text), or escaped by a preceding underscore (in which case the decoration
1093 is omitted).
1094 <p> <b>markup example:</b>
1095 <p>
1096 <p> <br>
1097 <pre> normal text http://www.jus.uio.no/sisu continues
1098 </pre>
1099 <p> <b>resulting output:</b>
1100 <p> normal text &lt;<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a>
1101 &gt; continues
1102 <p> An
1103
1104 <p>escaped url without decoration
1105 <p> <b>markup example:</b>
1106 <p>
1107 <p> <br>
1108 <pre> normal text http://www.jus.uio.no/sisu continues
1109 deb http://www.jus.uio.no/sisu/archive unstable main non-free
1110 </pre>
1111 <p> <b>resulting output:</b>
1112 <p> normal text <a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a>
1113 continues
1114 <p> deb
1115
1116 <p><a href='http://www.jus.uio.no/sisu/archive'>http://www.jus.uio.no/sisu/archive</a>
1117 unstable main non-free
1118 <p> where a code block
1119 is used there is neither decoration nor hyperlinking, code blocks are discussed
1120
1121 <p>later in this document
1122 <p> <b>resulting output:</b>
1123 <p>
1124 <p> <br>
1125 <pre> deb http://www.jus.uio.no/sisu/archive unstable main non-free
1126 deb-src http://www.jus.uio.no/sisu/archive unstable main non-free
1127 </pre>
1128 <p> To link text or an image to a url the markup is as follows
1129 <p> <b>markup example:</b>
1130
1131 <p>
1132 <p> <br>
1133 <pre> about { SiSU }http://url.org markup
1134 </pre>
1135 <p> 9.5.2 LINKING TEXT
1136 <p> <b>resulting output:</b>
1137 <p> about SiSU &lt;<a href='http://www.jus.uio.no/sisu/'>http://www.jus.uio.no/sisu/</a>
1138 &gt;
1139
1140 <p>markup
1141 <p> A shortcut notation is available so the url link may also be provided
1142
1143 <p>automatically as a footnote
1144 <p> <b>markup example:</b>
1145 <p>
1146 <p> <br>
1147 <pre> about {~^ SiSU }http://url.org markup
1148 </pre>
1149 <p> <b>resulting output:</b>
1150 <p> about SiSU &lt;<a href='http://www.jus.uio.no/sisu/'>http://www.jus.uio.no/sisu/</a>
1151 &gt; [^13] markup
1152 <p>
1153
1154 <p>9.5.3 LINKING IMAGES
1155 <p> <b>markup example:</b>
1156 <p>
1157 <p> <br>
1158 <pre> { tux.png 64x80 }image
1159 % various url linked images
1160 {tux.png 64x80
1161 {GnuDebianLinuxRubyBetterWay.png 100x101
1162 {~^ ruby_logo.png
1163 </pre>
1164 <p> <b>resulting output:</b>
1165 <p> [ tux.png ]
1166 <p> tux.png 64x80
1167 <p> [ &nbsp;ruby_logo &nbsp;(png &nbsp;missing)
1168 &nbsp;] [^14]
1169 <p> GnuDebianLinuxRubyBetterWay.png 100x101 and Ruby
1170 <p> <b>linked url footnote
1171
1172 <p>shortcut</b>
1173 <p>
1174 <p> <br>
1175 <pre> {~^ &nbsp;[text &nbsp;to &nbsp;link] }http://url.org
1176 % maps to: { &nbsp;[text &nbsp;to &nbsp;link] }http://url.org ~{ http://url.org }~
1177 % which produces hyper-linked text within a document/paragraph, with an
1178 endnote providing the url for the text location used in the hyperlink
1179 </pre>
1180 <p>
1181 <p> <br>
1182 <pre> text marker *~name
1183 </pre>
1184 <p> note at a heading level the same is automatically achieved by providing
1185 names to headings 1, 2 and 3 i.e. 2~[name] and 3~[name] or in the case of
1186 auto-heading numbering, without further intervention.
1187 <p> 9.6 GROUPED TEXT
1188 <p> 9.6.1
1189
1190 <p>TABLES
1191 <p> Tables may be prepared in two either of two forms
1192 <p> <b>markup example:</b>
1193
1194 <p>
1195 <p> <br>
1196 <pre> table{ c3; 40; 30; 30;
1197 This is a table
1198 this would become column two of row one
1199 column three of row one is here
1200 And here begins another row
1201 column two of row two
1202 column three of row two, and so on
1203 }table
1204 </pre>
1205 <p> <b>resulting output:</b>
1206 <p> &nbsp;[table &nbsp;omitted, &nbsp;see &nbsp;other &nbsp;document &nbsp;formats]<br>
1207
1208 <p> a second form may be easier to work with in cases where there is not
1209
1210 <p>much information in each column
1211 <p> <b>markup example:</b> [^15]
1212 <p>
1213 <p> <br>
1214 <pre> !_ Table 3.1: Contributors to Wikipedia, January 2001 - June 2005
1215 {table~h 24; 12; 12; 12; 12; 12; 12;}
1216 |Jan. 2001|Jan. 2002|Jan. 2003|Jan. 2004|July
1217 2004|June 2006
1218 Contributors* | 10| 472| 2,188| 9,653|
1219 25,011| 48,721
1220 Active contributors** | 9| 212| 846| 3,228|
1221 8,442| 16,945
1222 Very active contributors*** | 0| 31| 190| 692|
1223 1,639| 3,016
1224 No. of English language articles| 25| 16,000| 101,000| 190,000|
1225 320,000| 630,000
1226 No. of articles, all languages | 25| 19,000| 138,000| 490,000|
1227 862,000|1,600,000
1228 \* Contributed at least ten times; \** at least 5 times in last month;
1229 \* more than 100 times in last month.
1230 </pre>
1231 <p> <b>resulting output:</b>
1232 <p> <b>Table 3.1: Contributors to Wikipedia, January 2001
1233 - June 2005</b>
1234 <p> &nbsp;[table &nbsp;omitted, &nbsp;see &nbsp;other &nbsp;document &nbsp;formats]<br>
1235
1236 <p> * Contributed at least ten times; ** at least 5 times in last month;
1237 *** more than 100 times in last month.
1238 <p> 9.6.2 POEM
1239 <p> <b>basic markup:</b>
1240 <p>
1241 <p> <br>
1242 <pre> poem{
1243 Your poem here
1244 }poem
1245 Each verse in a poem is given a separate object number.
1246 </pre>
1247 <p> <b>markup example:</b>
1248 <p>
1249 <p> <br>
1250 <pre> poem{
1251 &rsquo;Fury said to a
1252 mouse, That he
1253 met in the
1254 house,
1255
1256 both go to
1257 law: I will
1258 prosecute
1259 YOU. --Come,
1260 I&rsquo;ll take no
1261 denial; We
1262 must have a
1263 trial: For
1264 really this
1265 morning I&rsquo;ve
1266 nothing
1267 to do.
1268 Said the
1269 mouse to the
1270 cur,
1271 a trial,
1272 dear Sir,
1273 With
1274 no jury
1275 or judge,
1276 would be
1277 wasting
1278 our
1279 breath.
1280
1281 judge, I&rsquo;ll
1282 be jury,
1283 Said
1284 cunning
1285 old Fury:
1286
1287 try the
1288 whole
1289 cause,
1290 and
1291 condemn
1292 you
1293 to
1294 death.
1295 }poem
1296 </pre>
1297 <p> <b>resulting output:</b>
1298 <p>
1299 <p> &rsquo;Fury said to a<br>
1300 mouse, That he<br>
1301 met in the<br>
1302 house,<br>
1303 <br>
1304 both go to<br>
1305 law: I will<br>
1306 prosecute<br>
1307 YOU. --Come,<br>
1308 I&rsquo;ll take no<br>
1309 denial; We<br>
1310 must have a<br>
1311 trial: For<br>
1312 really this<br>
1313 morning I&rsquo;ve<br>
1314 nothing<br>
1315 to do.<br>
1316 Said the<br>
1317 mouse to the<br>
1318 cur,<br>
1319 a trial,<br>
1320 dear Sir,<br>
1321 With<br>
1322 no jury<br>
1323 or judge,<br>
1324 would be<br>
1325 wasting<br>
1326 our<br>
1327 breath.<br>
1328 <br>
1329 judge, I&rsquo;ll<br>
1330 be jury,<br>
1331 Said<br>
1332 cunning<br>
1333 old Fury:<br>
1334 <br>
1335 try the<br>
1336 whole<br>
1337 cause,<br>
1338 and<br>
1339 condemn<br>
1340 you<br>
1341 to<br>
1342 death.<br>
1343
1344 <p> 9.6.3 GROUP
1345 <p> <b>basic markup:</b>
1346 <p>
1347 <p> <br>
1348 <pre> group{
1349 Your grouped text here
1350 }group
1351 A group is treated as an object and given a single object number.
1352 </pre>
1353 <p> <b>markup example:</b>
1354 <p>
1355 <p> <br>
1356 <pre> group{
1357 &rsquo;Fury said to a
1358 mouse, That he
1359 met in the
1360 house,
1361
1362 both go to
1363 law: I will
1364 prosecute
1365 YOU. --Come,
1366 I&rsquo;ll take no
1367 denial; We
1368 must have a
1369 trial: For
1370 really this
1371 morning I&rsquo;ve
1372 nothing
1373 to do.
1374 Said the
1375 mouse to the
1376 cur,
1377 a trial,
1378 dear Sir,
1379 With
1380 no jury
1381 or judge,
1382 would be
1383 wasting
1384 our
1385 breath.
1386
1387 judge, I&rsquo;ll
1388 be jury,
1389 Said
1390 cunning
1391 old Fury:
1392
1393 try the
1394 whole
1395 cause,
1396 and
1397 condemn
1398 you
1399 to
1400 death.
1401 }group
1402 </pre>
1403 <p> <b>resulting output:</b>
1404 <p>
1405 <p> &rsquo;Fury said to a<br>
1406 mouse, That he<br>
1407 met in the<br>
1408 house,<br>
1409 <br>
1410 both go to<br>
1411 law: I will<br>
1412 prosecute<br>
1413 YOU. --Come,<br>
1414 I&rsquo;ll take no<br>
1415 denial; We<br>
1416 must have a<br>
1417 trial: For<br>
1418 really this<br>
1419 morning I&rsquo;ve<br>
1420 nothing<br>
1421 to do.<br>
1422 Said the<br>
1423 mouse to the<br>
1424 cur,<br>
1425 a trial,<br>
1426 dear Sir,<br>
1427 With<br>
1428 no jury<br>
1429 or judge,<br>
1430 would be<br>
1431 wasting<br>
1432 our<br>
1433 breath.<br>
1434 <br>
1435 judge, I&rsquo;ll<br>
1436 be jury,<br>
1437 Said<br>
1438 cunning<br>
1439 old Fury:<br>
1440 <br>
1441 try the<br>
1442 whole<br>
1443 cause,<br>
1444 and<br>
1445 condemn<br>
1446 you<br>
1447 to<br>
1448 death.<br>
1449
1450 <p> 9.6.4 CODE
1451 <p> Code tags are used to escape regular sisu markup, and have
1452 been used extensively within this document to provide examples of <b>SiSU</b>
1453 markup. You cannot however use code tags to escape code tags. They are however
1454 used in the same way as group or poem tags.
1455 <p> A code-block is treated as
1456 an object and given a single object number. [an more than 100 times in last
1457 month. option &nbsp;to &nbsp;number &nbsp;each &nbsp;line &nbsp;of &nbsp;code &nbsp;may &nbsp;be &nbsp;considered &nbsp;at more than
1458 100 times in last month. some &nbsp;later &nbsp;time]
1459 <p> <b>use of code tags instead of
1460 poem compared, resulting output:</b>
1461 <p>
1462 <p> <br>
1463 <pre> &rsquo;Fury said to a
1464 mouse, That he
1465 met in the
1466 house,
1467
1468 both go to
1469 law: I will
1470 prosecute
1471 YOU. --Come,
1472 I&rsquo;ll take no
1473 denial; We
1474 must have a
1475 trial: For
1476 really this
1477 morning I&rsquo;ve
1478 nothing
1479 to do.
1480 Said the
1481 mouse to the
1482 cur,
1483 a trial,
1484 dear Sir,
1485 With
1486 no jury
1487 or judge,
1488 would be
1489 wasting
1490 our
1491 breath.
1492
1493 judge, I&rsquo;ll
1494 be jury,
1495 Said
1496 cunning
1497 old Fury:
1498
1499 try the
1500 whole
1501 cause,
1502 and
1503 condemn
1504 you
1505 to
1506 death.
1507 </pre>
1508 <p> 9.7 BOOK INDEX
1509 <p> To make an index append to paragraph the book index term
1510 relates to it, using an equal sign and curly braces.
1511 <p> Currently two levels
1512 are provided, a main term and if needed a sub-term. Sub-terms are separated
1513 from the main term by a colon.
1514 <p>
1515 <p> <br>
1516 <pre> Paragraph containing main term and sub-term.
1517 ={Main term:sub-term}
1518 </pre>
1519 <p> The index syntax starts on a new line, but there should not be an empty
1520 line between paragraph and index markup.
1521 <p> The structure of the resulting
1522 index would be:
1523 <p>
1524 <p> <br>
1525 <pre> Main term, 1
1526 sub-term, 1
1527 </pre>
1528 <p> Several terms may relate to a paragraph, they are separated by a semicolon.
1529 If the term refers to more than one paragraph, indicate the number of paragraphs.
1530
1531 <p>
1532 <p> <br>
1533 <pre> Paragraph containing main term, second term and sub-term.
1534 ={first term; second term: sub-term}
1535 </pre>
1536 <p> The structure of the resulting index would be:
1537 <p>
1538 <p> <br>
1539 <pre> First term, 1,
1540 Second term, 1,
1541 sub-term, 1
1542 </pre>
1543 <p> If multiple sub-terms appear under one paragraph, they are separated under
1544 the main term heading from each other by a pipe symbol.
1545 <p>
1546 <p> <br>
1547 <pre> Paragraph containing main term, second term and sub-term.
1548 ={Main term:sub-term+1|second sub-term
1549 A paragraph that continues discussion of the first sub-term
1550 </pre>
1551 <p> The plus one in the example provided indicates the first sub-term spans
1552 one additional paragraph. The logical structure of the resulting index would
1553 be:
1554 <p>
1555 <p> <br>
1556 <pre> Main term, 1,
1557 sub-term, 1-3,
1558 second sub-term, 1,
1559 </pre>
1560 <p> 10. COMPOSITE DOCUMENTS MARKUP
1561 <p> It is possible to build a document by
1562 creating a master document that requires other documents. The documents
1563 required may be complete documents that could be generated independently,
1564 or they could be markup snippets, prepared so as to be easily available
1565 to be placed within another text. If the calling document is a master document
1566 (built from other documents), it should be named with the suffix <b>.ssm</b> Within
1567 this document you would provide information on the other documents that
1568 should be included within the text. These may be other documents that would
1569 be processed in a regular way, or markup bits prepared only for inclusion
1570 within a master document <b>.sst</b> regular markup file, or <b>.ssi</b> (insert/information)
1571
1572 <p>A secondary file of the composite document is built prior to processing
1573
1574 <p>with the same prefix and the suffix <b>._sst</b>
1575 <p> basic markup for importing a
1576
1577 <p>document into a master document
1578 <p>
1579 <p> <br>
1580 <pre> &lt;&lt; filename1.sst
1581 &lt;&lt; filename2.ssi
1582 </pre>
1583 <p> The form described above should be relied on. Within the Vim editor it
1584 results in the text thus linked becoming hyperlinked to the document it
1585 is calling in which is convenient for editing. Alternative markup for importation
1586 of documents under consideration, and occasionally supported have been.
1587
1588 <p>
1589 <p> <br>
1590 <pre> &lt;&lt; filename.ssi
1591 &lt;&lt;{filename.ssi}
1592 % using textlink alternatives
1593 &lt;&lt; |filename.ssi|@|^|
1594 </pre>
1595 <p> MARKUP SYNTAX HISTORY
1596 <p> 11. NOTES RELATED TO FILES-TYPES AND MARKUP SYNTAX
1597
1598 <p> 0.38 is substantially current, depreciated 0.16 supported, though file
1599
1600 <p>names were changed at 0.37
1601 <p> * sisu --query=[sisu &nbsp;version &nbsp;[0.38] or &rsquo;history]
1602
1603 <p> provides a short history of changes to <b>SiSU</b> markup
1604 <p> <b>0.57</b> (2007w34/4)
1605 <b>SiSU</b> 0.57 is the same as 0.42 with the introduction of some a shortcut to
1606 use the headers @title and @creator in the first heading [expanded &nbsp;using
1607 &nbsp;the &nbsp;and &nbsp;@author:]
1608 <p>
1609 <p> <br>
1610 <pre> :A~ @title by @author
1611 </pre>
1612 <p> <b>0.52</b> (2007w14/6) declared document type identifier at start of text/document:
1613
1614 <p> .B SiSU<br>
1615 0.52
1616 <p> or, backward compatible using the comment marker:
1617 <p> %<br>
1618 <b>SiSU</b> 0.38
1619 <p> variations include &rsquo; <b>SiSU</b> (text|master|insert) [version]&rsquo; and &rsquo;sisu-[version]&rsquo;
1620
1621 <p> <b>0.51</b> (2007w13/6) skins changed (simplified), markup unchanged
1622 <p> <b>0.42</b> (2006w27/4)
1623 * (asterisk) type endnotes, used e.g. in relation to author
1624 <p> <b>SiSU</b> 0.42 is
1625 the same as 0.38 with the introduction of some additional endnote types,
1626
1627 <p> Introduces some variations on endnotes, in particular the use of the
1628
1629 <p>asterisk
1630 <p>
1631 <p> <br>
1632 <pre> ~{* for example for describing an author }~ and ~{** for describing a
1633 second author }~
1634 </pre>
1635 <p> * for example for describing an author
1636 <p> ** for describing a second author
1637
1638 <p> and
1639 <p>
1640 <p> <br>
1641 <pre> ~[* &nbsp;my &nbsp;note &nbsp;]~ or ~[+ &nbsp;another &nbsp;note &nbsp;]~
1642 </pre>
1643 <p> which numerically increments an asterisk and plus respectively
1644 <p> *1 my
1645
1646 <p>note +1 another note
1647 <p> <b>0.38</b> (2006w15/7) introduced new/alternative notation
1648 for headers, e.g. @title: (instead of 0~title), and accompanying document
1649 structure markup, :A,:B,:C,1,2,3 (maps to previous 1,2,3,4,5,6)
1650 <p> <b>SiSU</b>
1651 0.38 introduced alternative experimental header and heading/structure markers,
1652
1653 <p>
1654 <p> <br>
1655 <pre> @headername: and headers :A~ :B~ :C~ 1~ 2~ 3~
1656 </pre>
1657 <p> as the equivalent of:
1658 <p>
1659 <p> <br>
1660 <pre> 0~headername and headers 1~ 2~ 3~ 4~ 5~ 6~
1661 </pre>
1662 <p> The internal document markup of <b>SiSU</b> 0.16 remains valid and standard Though
1663
1664 <p>note that <b>SiSU</b> 0.37 introduced a new file naming convention
1665 <p> <b>SiSU</b> has in
1666 effect two sets of levels to be considered, using 0.38 notation A-C headings/levels,
1667 pre-ordinary paragraphs /pre-substantive text, and 1-3 headings/levels, levels
1668 which are followed by ordinary text. This may be conceptualised as levels
1669 A,B,C, 1,2,3, and using such letter number notation, in effect: A must
1670 exist, optional B and C may follow in sequence (not strict) 1 must exist,
1671 optional 2 and 3 may follow in sequence i.e. there are two independent heading
1672 level sequences A,B,C and 1,2,3 (using the 0.16 standard notation 1,2,3
1673 and 4,5,6) on the positive side: the 0.38 A,B,C,1,2,3 alternative makes
1674 explicit an aspect of structuring documents in <b>SiSU</b> that is not otherwise
1675 obvious to the newcomer (though it appears more complicated, is more in
1676 your face and likely to be understood fairly quickly); the substantive
1677 text follows levels 1,2,3 and it is &rsquo;nice&rsquo; to do most work in those levels
1678
1679 <p> <b>0.37</b> (2006w09/7) introduced new file naming convention, .sst (text), .ssm
1680 (master), .ssi (insert), markup syntax unchanged
1681 <p> <b>SiSU</b> 0.37 introduced new
1682 file naming convention, using the file extensions .sst .ssm and .ssi to replace
1683 .s1 .s2 .s3 .r1 .r2 .r3 and .si<br>
1684
1685 <p> this is captured by the following file &rsquo;rename&rsquo; instruction:
1686 <p>
1687 <p> <br>
1688 <pre> rename &rsquo;s/.s[123]$/.sst/&rsquo; *.s{1,2,3}
1689 rename &rsquo;s/.r[123]$/.ssm/&rsquo; *.r{1,2,3}
1690 rename &rsquo;s/.si$/.ssi/&rsquo; *.si
1691 </pre>
1692 <p> The internal document markup remains unchanged, from <b>SiSU</b> 0.16
1693 <p> <b>0.35</b> (2005w52/3)
1694 sisupod, zipped content file introduced
1695 <p> <b>0.23</b> (2005w36/2) utf-8 for markup
1696
1697 <p>file
1698 <p> <b>0.22</b> (2005w35/3) image dimensions may be omitted if rmagick is available
1699
1700 <p>to be relied upon
1701 <p> <b>0.20.4</b> (2005w33/4) header 0~links
1702 <p> <b>0.16</b> (2005w25/2) substantial
1703 changes introduced to make markup cleaner, header 0~title type, and headings
1704 [1-6]~ introduced, also percentage sign (%) at start of a text line as comment
1705
1706 <p>marker
1707 <p> <b>SiSU</b> 0.16 (0.15 development branch) introduced the use of
1708 <p> the
1709 header 0~ and headings/structure 1~ 2~ 3~ 4~ 5~ 6~
1710 <p> in place of the 0.1
1711 header, heading/structure notation
1712 <p> <b>SiSU</b> 0.1 headers and headings structure
1713 represented by header 0{~ and headings/structure 1{ 2{ 3{ 4{~ 5{ 6{
1714 <p> 12.
1715 SISU FILETYPES
1716 <p> <b>SiSU</b> has plaintext and binary filetypes, and can process
1717 either type of document.
1718 <p> 12.1 .SST .SSM .SSI MARKED UP PLAIN TEXT
1719 <p> <b>SiSU</b> documents
1720 are prepared as plain-text (utf-8) files with <b>SiSU</b> markup. They may make reference
1721 to and contain images (for example), which are stored in the directory
1722 beneath them _sisu/image. <b>SiSU</b> plaintext markup files are of three types
1723 that may be distinguished by the file extension used: regular text .sst;
1724 master documents, composite documents that incorporate other text, which
1725 can be any regular text or text insert; and inserts the contents of which
1726 are like regular text except these are marked .ssi and are not processed.<br>
1727
1728 <p> <b>SiSU</b> processing can be done directly against a sisu documents; which
1729 may be located locally or on a remote server for which a url is provided.
1730
1731 <p> <b>SiSU</b> source markup can be shared with the command:
1732 <p> sisu -s [filename]<br>
1733
1734 <p> 12.1.1 SISU TEXT - REGULAR FILES (.SST)
1735 <p> The most common form of document
1736 in <b>SiSU</b> , see the section on <b>SiSU</b> markup.
1737 <p> &lt;<a href='http://www.jus.uio.no/sisu/sisu_markup'>http://www.jus.uio.no/sisu/sisu_markup</a>
1738 &gt;
1739
1740 <p> &lt;<a href='http://www.jus.uio.no/sisu/sisu_manual'>http://www.jus.uio.no/sisu/sisu_manual</a>
1741 &gt;
1742 <p> 12.1.2 SISU MASTER FILES (.SSM)
1743 <p> Composite
1744 documents which incorporate other <b>SiSU</b> documents which may be either regular
1745 <b>SiSU</b> text .sst which may be generated independently, or inserts prepared
1746 solely for the purpose of being incorporated into one or more master documents.
1747
1748 <p> The mechanism by which master files incorporate other documents is described
1749 as one of the headings under under <b>SiSU</b> markup in the <b>SiSU</b> manual.
1750 <p> Note:
1751 Master documents may be prepared in a similar way to regular documents,
1752 and processing will occur normally if a .sst file is renamed .ssm without
1753 requiring any other documents; the .ssm marker flags that the document may
1754 contain other documents.
1755 <p> Note: a secondary file of the composite document
1756 is built prior to processing with the same prefix and the suffix ._sst [^16]
1757
1758 <p> &lt;<a href='http://www.jus.uio.no/sisu/sisu_markup'>http://www.jus.uio.no/sisu/sisu_markup</a>
1759 &gt;
1760 <p> &lt;<a href='http://www.jus.uio.no/sisu/sisu_manual'>http://www.jus.uio.no/sisu/sisu_manual</a>
1761 &gt;
1762
1763 <p> 12.1.3 SISU INSERT FILES (.SSI)
1764 <p> Inserts are documents prepared solely for
1765 the purpose of being incorporated into one or more master documents. They
1766 resemble regular <b>SiSU</b> text files except they are ignored by the <b>SiSU</b> processor.
1767 Making a file a .ssi file is a quick and convenient way of flagging that
1768 it is not intended that the file should be processed on its own.
1769 <p> 12.2 SISUPOD,
1770 ZIPPED BINARY CONTAINER (SISUPOD.ZIP, .SSP)
1771 <p> A sisupod is a zipped <b>SiSU</b>
1772 text file or set of <b>SiSU</b> text files and any associated images that they
1773 contain (this will be extended to include sound and multimedia-files)
1774 <p>
1775 <b>SiSU</b> plaintext files rely on a recognised directory structure to find contents
1776 such as images associated with documents, but all images for example for
1777 all documents contained in a directory are located in the sub-directory
1778 _sisu/image. Without the ability to create a sisupod it can be inconvenient
1779 to manually identify all other files associated with a document. A sisupod
1780 automatically bundles all associated files with the document that is turned
1781 into a pod.
1782 <p> The structure of the sisupod is such that it may for example
1783 contain a single document and its associated images; a master document
1784 and its associated documents and anything else; or the zipped contents
1785 of a whole directory of prepared <b>SiSU</b> documents.
1786 <p> The command to create
1787 a sisupod is:
1788 <p> sisu -S [filename]<br>
1789
1790 <p> Alternatively, make a pod of the contents of a whole directory:
1791 <p>
1792 sisu -S<br>
1793
1794 <p> <b>SiSU</b> processing can be done directly against a sisupod; which may be
1795 located locally or on a remote server for which a url is provided.
1796 <p> &lt;<a href='http://www.jus.uio.no/sisu/sisu_commands'>http://www.jus.uio.no/sisu/sisu_commands</a>
1797 &gt;
1798
1799 <p> &lt;<a href='http://www.jus.uio.no/sisu/sisu_manual'>http://www.jus.uio.no/sisu/sisu_manual</a>
1800 &gt;
1801 <p> 13. EXPERIMENTAL ALTERNATIVE INPUT
1802 REPRESENTATIONS
1803 <p> 13.1 ALTERNATIVE XML
1804 <p> <b>SiSU</b> offers alternative XML input
1805 representations of documents as a proof of concept, experimental feature.
1806 They are however not strictly maintained, and incomplete and should be
1807 handled with care.
1808 <p> <b>convert from sst to simple xml representations (sax,
1809 dom and node):</b>
1810 <p> sisu --to-sax [filename/wildcard] or sisu --to-sxs [filename/wildcard]<br>
1811
1812 <p> sisu --to-dom [filename/wildcard] or sisu --to-sxd [filename/wildcard]<br>
1813
1814 <p> sisu --to-node [filename/wildcard] or sisu --to-sxn [filename/wildcard]<br>
1815
1816 <p>
1817 <p> <b>convert to sst from any sisu xml representation (sax, dom and node):</b>
1818
1819 <p> sisu --from-xml2sst [filename/wildcard &nbsp;[.sxs.xml,.sxd.xml,sxn.xml]]<br>
1820
1821 <p> or the same:
1822 <p> sisu --from-sxml [filename/wildcard &nbsp;[.sxs.xml,.sxd.xml,sxn.xml]]<br>
1823
1824 <p> 13.1.1 XML SAX REPRESENTATION
1825 <p> To convert from sst to simple xml (sax)
1826 representation:
1827 <p> sisu --to-sax [filename/wildcard] or sisu --to-sxs [filename/wildcard]<br>
1828
1829 <p> To convert from any sisu xml representation back to sst
1830 <p> sisu --from-xml2sst
1831 [filename/wildcard &nbsp;[.sxs.xml,.sxd.xml,sxn.xml]]<br>
1832
1833 <p> or the same:
1834 <p> sisu --from-sxml [filename/wildcard &nbsp;[.sxs.xml,.sxd.xml,sxn.xml]]<br>
1835
1836 <p> 13.1.2 XML DOM REPRESENTATION
1837 <p> To convert from sst to simple xml (dom)
1838 representation:
1839 <p> sisu --to-dom [filename/wildcard] or sisu --to-sxd [filename/wildcard]<br>
1840
1841 <p> To convert from any sisu xml representation back to sst
1842 <p> sisu --from-xml2sst
1843 [filename/wildcard &nbsp;[.sxs.xml,.sxd.xml,sxn.xml]]<br>
1844
1845 <p> or the same:
1846 <p> sisu --from-sxml [filename/wildcard &nbsp;[.sxs.xml,.sxd.xml,sxn.xml]]<br>
1847
1848 <p> 13.1.3 XML NODE REPRESENTATION
1849 <p> To convert from sst to simple xml (node)
1850 representation:
1851 <p> sisu --to-node [filename/wildcard] or sisu --to-sxn [filename/wildcard]<br>
1852
1853 <p> To convert from any sisu xml representation back to sst
1854 <p> sisu --from-xml2sst
1855 [filename/wildcard &nbsp;[.sxs.xml,.sxd.xml,sxn.xml]]<br>
1856
1857 <p> or the same:
1858 <p> sisu --from-sxml [filename/wildcard &nbsp;[.sxs.xml,.sxd.xml,sxn.xml]]<br>
1859
1860 <p> 14. CONFIGURATION
1861 <p> 14.1 DETERMINING THE CURRENT CONFIGURATION
1862 <p> Information
1863 on the current configuration of <b>SiSU</b> should be available with the help
1864 command:
1865 <p> sisu -v<br>
1866
1867 <p> which is an alias for:
1868 <p> sisu --help env<br>
1869
1870 <p> Either of these should be executed from within a directory that contains
1871 sisu markup source documents.
1872 <p> 14.2 CONFIGURATION FILES (CONFIG.YML)
1873 <p> <b>SiSU</b>
1874 configration parameters are adjusted in the configuration file, which can
1875 be used to override the defaults set. This includes such things as which
1876 directory interim processing should be done in and where the generated
1877 output should be placed.
1878 <p> The <b>SiSU</b> configuration file is a yaml file, which
1879 means indentation is significant.
1880 <p> <b>SiSU</b> resource configuration is determined
1881 by looking at the following files if they exist:
1882 <p> ./_sisu/sisurc.yml<br>
1883
1884 <p> ~/.sisu/sisurc.yml<br>
1885
1886 <p> /etc/sisu/sisurc.yml<br>
1887
1888 <p> The search is in the order listed, and the first one found is used.
1889 <p>
1890 In the absence of instructions in any of these it falls back to the internal
1891 program defaults.
1892 <p> Configuration determines the output and processing directories
1893 and the database access details.
1894 <p> If <b>SiSU</b> is installed a sample sisurc.yml
1895
1896 <p>may be found in /etc/sisu/sisurc.yml
1897 <p> 15. SKINS
1898 <p> Skins modify the default
1899 appearance of document output on a document, directory, or site wide basis.
1900 Skins are looked for in the following locations:
1901 <p> ./_sisu/skin<br>
1902
1903 <p> ~/.sisu/skin<br>
1904
1905 <p> /etc/sisu/skin<br>
1906
1907 <p> <b>Within the skin directory</b> are the following the default sub-directories
1908 for document skins:
1909 <p> ./skin/doc<br>
1910
1911 <p> ./skin/dir<br>
1912
1913 <p> ./skin/site<br>
1914
1915 <p> A skin is placed in the appropriate directory and the file named skin_[name].rb
1916
1917 <p> The skin itself is a ruby file which modifies the default appearances
1918 set in the program.
1919 <p> 15.1 DOCUMENT SKIN
1920 <p> Documents take on a document skin,
1921 if the header of the document specifies a skin to be used.
1922 <p>
1923 <p> <br>
1924 <pre> @skin: skin_united_nations
1925 </pre>
1926 <p> 15.2 DIRECTORY SKIN
1927 <p> A directory may be mapped on to a particular skin,
1928 so all documents within that directory take on a particular appearance.
1929 If a skin exists in the skin/dir with the same name as the document directory,
1930 it will automatically be used for each of the documents in that directory,
1931 (except where a document specifies the use of another skin, in the skin/doc
1932 directory).
1933 <p> A personal habit is to place all skins within the doc directory,
1934 and symbolic links as needed from the site, or dir directories as required.
1935
1936 <p> 15.3 SITE SKIN
1937 <p> A site skin, modifies the program default skin.
1938 <p> 15.4 SAMPLE
1939
1940 <p>SKINS
1941 <p> With <b>SiSU</b> installed sample skins may be found in:
1942 <p> /etc/sisu/skin/doc
1943 and<br>
1944 /usr/share/doc/sisu/v1/sisu_markup_samples/dfsg/_sisu/skin/doc<br>
1945
1946 <p> (or equivalent directory) and if sisu-markup-samples is installed also
1947 under:
1948 <p> /usr/share/doc/sisu/v1/sisu_markup_samples/non-free/_sisu/skin/doc<br>
1949
1950 <p> Samples of list.yml and promo.yml (which are used to create the right
1951 column list) may be found in:
1952 <p> /usr/share/doc/sisu/v1/sisu_markup_samples/dfsg/_sisu/skin/yml
1953 (or equivalent<br>
1954 directory)<br>
1955
1956 <p> 16. CSS - CASCADING STYLE SHEETS (FOR HTML, XHTML AND XML)
1957 <p> CSS files
1958 to modify the appearance of <b>SiSU</b> html, XHTML or XML may be placed in the
1959 configuration directory: ./_sisu/css; ~/.sisu/css or; /etc/sisu/css and
1960 these will be copied to the<br>
1961 output directories with the command sisu -CC.
1962 <p> The basic CSS file for html
1963 output is html.css, placing a file of that name in directory _sisu/css or
1964 equivalent will result in the default file of that name being overwritten.
1965
1966 <p> HTML: html.css
1967 <p> XML DOM: dom.css
1968 <p> XML SAX: sax.css
1969 <p> XHTML: xhtml.css
1970 <p>
1971 The default homepage may use homepage.css or html.css
1972 <p> Under consideration
1973 is to permit the placement of a CSS file with a different name in directory
1974 _sisu/css directory or equivalent, and change the default CSS file that
1975 is looked for in a skin.[^17]
1976 <p> 17. ORGANISING CONTENT
1977 <p> 17.1 DIRECTORY STRUCTURE
1978
1979 <p>AND MAPPING
1980 <p> The output directory root can be set in the sisurc.yml file.
1981 Under the root, subdirectories are made for each directory in which a document
1982 set resides. If you have a directory named poems or conventions, that directory
1983 will be created under the output directory root and the output for all
1984 documents contained in the directory of a particular name will be generated
1985 to subdirectories beneath that directory (poem or conventions). A document
1986 will be placed in a subdirectory of the same name as the document with
1987 the filetype identifier stripped (.sst .ssm)
1988 <p> The last part of a directory
1989 path, representing the sub-directory in which a document set resides, is
1990 the directory name that will be used for the output directory. This has
1991 implications for the organisation of document collections as it could make
1992 sense to place documents of a particular subject, or type within a directory
1993 identifying them. This grouping as suggested could be by subject (sales_law,
1994 english_literature); or just as conveniently by some other classification
1995 (X University). The mapping means it is also possible to place in the same
1996 output directory documents that are for organisational purposes kept separately,
1997 for example documents on a given subject of two different institutions
1998 may be kept in two different directories of the same name, under a directory
1999 named after each institution, and these would be output to the same output
2000 directory. Skins could be associated with each institution on a directory
2001 basis and resulting documents will take on the appropriate different appearance.
2002
2003 <p> 17.2 ORGANISING CONTENT
2004 <p> 18. HOMEPAGES
2005 <p> <b>SiSU</b> is about the ability to auto-generate
2006 documents. Home pages are regarded as custom built items, and are not created
2007 by <b>SiSU</b> <b>SiSU</b> has a default home page, which will not be appropriate for
2008 use with other sites, and the means to provide your own home page instead
2009 in one of two ways as part of a site&rsquo;s configuration, these being:
2010 <p> 1. through
2011 placing your home page and other custom built documents in the subdirectory
2012 _sisu/home/ (this probably being the easier and more convenient option)
2013
2014 <p> 2. through providing what you want as the home page in a skin,
2015 <p> Document
2016 sets are contained in directories, usually organised by site or subject.
2017 Each directory can/should have its own homepage. See the section on directory
2018 structure and organisation of content.
2019 <p> 18.1 HOME PAGE AND OTHER CUSTOM BUILT
2020
2021 <p>PAGES IN A SUB-DIRECTORY
2022 <p> Custom built pages, including the home page index.html
2023 may be placed within the configuration directory _sisu/home/ in any of
2024 the locations that is searched for the configuration directory, namely
2025 ./_sisu; ~/_sisu; /etc/sisu From there they are copied to the root of the
2026 output directory with the command:
2027 <p> sisu -CC<br>
2028
2029 <p> 18.2 HOME PAGE WITHIN A SKIN
2030 <p> Skins are described in a separate section,
2031 but basically are a file written in the programming language <b>Ruby</b> that
2032 may be provided to change the defaults that are provided with sisu with
2033 respect to individual documents, a directories contents or for a site.
2034 <p>
2035 If you wish to provide a homepage within a skin the skin should be in
2036 the directory _sisu/skin/dir and have the name of the directory for which
2037 it is to become the home page. Documents in the directory commercial_law
2038 would have the homepage modified in skin_commercial law.rb; or the directory
2039
2040 <p>poems in skin_poems.rb
2041 <p>
2042 <p> <br>
2043 <pre> class Home
2044 def homepage
2045 # place the html content of your homepage here, this will become
2046 index.html
2047 &lt;&lt;HOME &lt;html&gt;
2048 &lt;head&gt;&lt;/head&gt;
2049 &lt;doc&gt;
2050 &lt;p&gt;this is my new homepage.&lt;/p&gt;
2051 &lt;/doc&gt;
2052 &lt;/html&gt;
2053 HOME
2054 end
2055 end
2056 </pre>
2057 <p> 19. MARKUP AND OUTPUT EXAMPLES
2058 <p> 19.1 MARKUP EXAMPLES
2059 <p> Current markup examples
2060 and document output samples are provided at &lt;<a href='http://www.jus.uio.no/sisu/SiSU/examples.html'>http://www.jus.uio.no/sisu/SiSU/examples.html</a>
2061 &gt;
2062
2063 <p> Some markup with syntax highlighting may be found under &lt;<a href='http://www.jus.uio.no/sisu/sample/syntax'>http://www.jus.uio.no/sisu/sample/syntax</a>
2064 &gt;
2065 but is not as up to date.
2066 <p> For some documents hardly any markup at all
2067 is required at all, other than a header, and an indication that the levels
2068 to be taken into account by the program in generating its output are.
2069 <p> 20.
2070 SISU SEARCH - INTRODUCTION
2071 <p> <b>SiSU</b> output can easily and conveniently be
2072 indexed by a number of standalone indexing tools, such as Lucene, Hyperestraier.
2073
2074 <p> Because the document structure of sites created is clearly defined, and
2075 the text object citation system is available hypothetically at least, for
2076 all forms of output, it is possible to search the sql database, and either
2077 read results from that database, or just as simply map the results to the
2078 html output, which has richer text markup.
2079 <p> In addition to this <b>SiSU</b> has
2080 the ability to populate a relational sql type database with documents at
2081 an object level, with objects numbers that are shared across different
2082 output types, which make them searchable with that degree of granularity.
2083 Basically, your match criteria is met by these documents and at these locations
2084 within each document, which can be viewed within the database directly
2085 or in various output formats.
2086 <p> 21. SQL
2087 <p> 21.1 POPULATING SQL TYPE DATABASES
2088
2089 <p> <b>SiSU</b> feeds sisu markupd documents into sql type databases PostgreSQL[^18]
2090 and/or SQLite[^19] database together with information related to document
2091 structure.
2092 <p> This is one of the more interesting output forms, as all the
2093 structural data of the documents are retained (though can be ignored by
2094 the user of the database should they so choose). All site texts/documents
2095 are (currently) streamed to four tables:
2096 <p> * one containing semantic
2097 (and other) headers, including, title, author,<br>
2098 subject, (the Dublin Core...);<br>
2099
2100 <p> * another the substantive texts by individual<br>
2101 along with structural information, each paragraph being identifiable
2102 by its<br>
2103 paragraph number (if it has one which almost all of them do), and the<br>
2104 substantive text of each paragraph quite naturally being searchable
2105 (both in<br>
2106 formatted and clean text versions for searching); and<br>
2107
2108 <p> * a third containing endnotes cross-referenced back to the paragraph
2109 from<br>
2110 which they are referenced (both in formatted and clean text versions
2111 for<br>
2112 searching).<br>
2113
2114 <p> * a fourth table with a one to one relation with the headers table
2115 contains<br>
2116 full text versions of output, eg. pdf, html, xml, and ascii.<br>
2117
2118 <p> There is of course the possibility to add further structures.
2119 <p> At this
2120 level <b>SiSU</b> loads a relational database with documents chunked into objects,
2121 their smallest logical structurally constituent parts, as text objects,
2122 with their object citation number and all other structural information
2123 needed to construct the document. Text is stored (at this text object level)
2124 with and without elementary markup tagging, the stripped version being
2125 so as to facilitate ease of searching.
2126 <p> Being able to search a relational
2127 database at an object level with the <b>SiSU</b> citation system is an effective
2128 way of locating content generated by <b>SiSU</b> object numbers, and all versions
2129 of the document have the same numbering, complex searches can be tailored
2130 to return just the locations of the search results relevant for all available
2131 output formats, with live links to the precise locations in the database
2132 or in html/xml documents; or, the structural information provided makes
2133 it possible to search the full contents of the database and have headings
2134 in which search content appears, or to search only headings etc. (as the
2135 Dublin Core is incorporated it is easy to make use of that as well).
2136 <p> 22.
2137 POSTGRESQL
2138 <p> 22.1 NAME
2139 <p> <b>SiSU</b> - Structured information, Serialized Units
2140 - a document publishing system, postgresql dependency package
2141 <p> 22.2 DESCRIPTION
2142
2143 <p> Information related to using postgresql with sisu (and related to the
2144 sisu_postgresql dependency package, which is a dummy package to install
2145 dependencies needed for <b>SiSU</b> to populate a postgresql database, this being
2146 part of <b>SiSU</b> - man sisu).
2147 <p> 22.3 SYNOPSIS
2148 <p> sisu -D [instruction] [filename/wildcard
2149 &nbsp;if &nbsp;required]<br>
2150
2151 <p> sisu -D --pg --[instruction] [filename/wildcard &nbsp;if &nbsp;required]<br>
2152
2153 <p> 22.4 COMMANDS
2154 <p> Mappings to two databases are provided by default, postgresql
2155 and sqlite, the same commands are used within sisu to construct and populate
2156 databases however -d (lowercase) denotes sqlite and -D (uppercase) denotes
2157 postgresql, alternatively --sqlite or --pgsql may be used
2158 <p> <b>-D or --pgsql</b> may
2159 be used interchangeably.
2160 <p> 22.4.1 CREATE AND DESTROY DATABASE
2161 <p>
2162 <dl>
2163
2164 <dt><b>--pgsql --createall</b>
2165 </dt>
2166 <dd>initial step, creates required relations (tables, indexes) in existing
2167 (postgresql) database (a database should be created manually and given
2168 the same name as working directory, as requested) (rb.dbi)
2169 <p> </dd>
2170
2171 <dt><b>sisu -D --createdb</b>
2172 </dt>
2173 <dd>
2174 <p>creates database where no database existed before
2175 <p> </dd>
2176
2177 <dt><b>sisu -D --create</b> </dt>
2178 <dd>creates
2179
2180 <p>database tables where no database tables existed before
2181 <p> </dd>
2182
2183 <dt><b>sisu -D --Dropall</b>
2184 </dt>
2185 <dd>destroys database (including all its content)! kills data and drops tables,
2186 indexes and database associated with a given directory (and directories
2187 of the same name).
2188 <p> </dd>
2189
2190 <dt><b>sisu -D --recreate</b> </dt>
2191 <dd>destroys existing database and builds
2192
2193 <p>a new empty database structure
2194 <p> </dd>
2195 </dl>
2196 22.4.2 IMPORT AND REMOVE DOCUMENTS
2197 <p>
2198 <dl>
2199
2200 <dt><b>sisu
2201 -D --import -v [filename/wildcard]</b> </dt>
2202 <dd>populates database with the contents of
2203 the file. Imports documents(s) specified to a postgresql database (at an
2204 object level).
2205 <p> </dd>
2206
2207 <dt><b>sisu -D --update -v [filename/wildcard]</b> </dt>
2208 <dd>updates file contents
2209
2210 <p>in database
2211 <p> </dd>
2212
2213 <dt><b>sisu -D --remove -v [filename/wildcard]</b> </dt>
2214 <dd>removes specified document
2215 from postgresql database.
2216 <p> </dd>
2217 </dl>
2218 23. SQLITE
2219 <p> 23.1 NAME
2220 <p> <b>SiSU</b> - Structured information,
2221 Serialized Units - a document publishing system.
2222 <p> 23.2 DESCRIPTION
2223 <p> Information
2224 related to using sqlite with sisu (and related to the sisu_sqlite dependency
2225 package, which is a dummy package to install dependencies needed for <b>SiSU</b>
2226 to populate an sqlite database, this being part of <b>SiSU</b> - man sisu).
2227 <p> 23.3
2228
2229 <p>SYNOPSIS
2230 <p> sisu -d [instruction] [filename/wildcard &nbsp;if &nbsp;required]<br>
2231
2232 <p> sisu -d --(sqlite|pg) --[instruction] [filename/wildcard &nbsp;if <br>
2233 required]<br>
2234
2235 <p> 23.4 COMMANDS
2236 <p> Mappings to two databases are provided by default, postgresql
2237 and sqlite, the same commands are used within sisu to construct and populate
2238 databases however -d (lowercase) denotes sqlite and -D (uppercase) denotes
2239 postgresql, alternatively --sqlite or --pgsql may be used
2240 <p> <b>-d or --sqlite</b> may
2241 be used interchangeably.
2242 <p> 23.4.1 CREATE AND DESTROY DATABASE
2243 <p>
2244 <dl>
2245
2246 <dt><b>--sqlite --createall</b>
2247 </dt>
2248 <dd>initial step, creates required relations (tables, indexes) in existing
2249 (sqlite) database (a database should be created manually and given the
2250 same name as working directory, as requested) (rb.dbi)
2251 <p> </dd>
2252
2253 <dt><b>sisu -d --createdb</b>
2254 </dt>
2255 <dd>
2256 <p>creates database where no database existed before
2257 <p> </dd>
2258
2259 <dt><b>sisu -d --create</b> </dt>
2260 <dd>creates
2261
2262 <p>database tables where no database tables existed before
2263 <p> </dd>
2264
2265 <dt><b>sisu -d --dropall</b>
2266 </dt>
2267 <dd>destroys database (including all its content)! kills data and drops tables,
2268 indexes and database associated with a given directory (and directories
2269 of the same name).
2270 <p> </dd>
2271
2272 <dt><b>sisu -d --recreate</b> </dt>
2273 <dd>destroys existing database and builds
2274
2275 <p>a new empty database structure
2276 <p> </dd>
2277 </dl>
2278 23.4.2 IMPORT AND REMOVE DOCUMENTS
2279 <p>
2280 <dl>
2281
2282 <dt><b>sisu
2283 -d --import -v [filename/wildcard]</b> </dt>
2284 <dd>populates database with the contents of
2285 the file. Imports documents(s) specified to an sqlite database (at an object
2286 level).
2287 <p> </dd>
2288
2289 <dt><b>sisu -d --update -v [filename/wildcard]</b> </dt>
2290 <dd>updates file contents in database
2291
2292 <p> </dd>
2293
2294 <dt><b>sisu -d --remove -v [filename/wildcard]</b> </dt>
2295 <dd>removes specified document from sqlite
2296 database.
2297 <p> </dd>
2298 </dl>
2299 24. INTRODUCTION
2300 <p> 24.1 SEARCH - DATABASE FRONTEND SAMPLE, UTILISING
2301 DATABASE AND SISU FEATURES, INCLUDING OBJECT CITATION NUMBERING (BACKEND
2302 CURRENTLY POSTGRESQL)
2303 <p> Sample search frontend &lt;<a href='http://search.sisudoc.org'>http://search.sisudoc.org</a>
2304 &gt;
2305 [^20] A small database and sample query front-end (search from) that makes
2306 use of the citation system, <i>object</i> citation numbering to demonstrates functionality.[^21]
2307
2308 <p> <b>SiSU</b> can provide information on which documents are matched and at what
2309 locations within each document the matches are found. These results are
2310 relevant across all outputs using object citation numbering, which includes
2311 html, XML, LaTeX, PDF and indeed the SQL database. You can then refer to
2312 one of the other outputs or in the SQL database expand the text within
2313 the matched objects (paragraphs) in the documents matched.
2314 <p> Note you may
2315 set results either for documents matched and object number locations within
2316 each matched document meeting the search criteria; or display the names
2317 of the documents matched along with the objects (paragraphs) that meet
2318 the search criteria.[^22]
2319 <p>
2320 <dl>
2321
2322 <dt><b>sisu -F --webserv-webrick</b> </dt>
2323 <dd>builds a cgi web search
2324
2325 <p>frontend for the database created
2326 <p> The following is feedback on the setup
2327 on a machine provided by the help command:
2328 <p> sisu --help sql<br>
2329
2330 <p>
2331 <p> <br>
2332 <pre> Postgresql
2333 user: ralph
2334 current db set: SiSU_sisu
2335 port: 5432
2336 dbi connect: DBI:Pg:database=SiSU_sisu;port=5432
2337 sqlite
2338 current db set: /home/ralph/sisu_www/sisu/sisu_sqlite.db
2339 dbi connect DBI:SQLite:/home/ralph/sisu_www/sisu/sisu_sqlite.db
2340 </pre>
2341 <p> Note on databases built
2342 <p> By default, [unless &nbsp;otherwise &nbsp;specified] databases
2343 are built on a directory basis, from collections of documents within that
2344 directory. The name of the directory you choose to work from is used as
2345 the database name, i.e. if you are working in a directory called /home/ralph/ebook
2346 the database SiSU_ebook is used. [otherwise &nbsp;a &nbsp;manual &nbsp;mapping &nbsp;for &nbsp;the &nbsp;collection
2347 &nbsp;is
2348 <p> </dd>
2349 </dl>
2350 24.2 SEARCH FORM
2351 <p>
2352 <dl>
2353
2354 <dt><b>sisu -F</b> </dt>
2355 <dd>generates a sample search form, which must
2356
2357 <p>be copied to the web-server cgi directory
2358 <p> </dd>
2359
2360 <dt><b>sisu -F --webserv-webrick</b> </dt>
2361 <dd>generates
2362 a sample search form for use with the webrick server, which must be copied
2363
2364 <p>to the web-server cgi directory
2365 <p> </dd>
2366
2367 <dt><b>sisu -Fv</b> </dt>
2368 <dd>as above, and provides some information
2369
2370 <p>on setting up hyperestraier
2371 <p> </dd>
2372
2373 <dt><b>sisu -W</b> </dt>
2374 <dd>starts the webrick server which should
2375
2376 <p>be available wherever sisu is properly installed
2377 <p> The generated search
2378
2379 <p>form must be copied manually to the webserver directory as instructed
2380 <p>
2381 </dd>
2382 </dl>
2383 25. HYPERESTRAIER
2384 <p> See the documentation for hyperestraier:
2385 <p> &lt;<a href='http://hyperestraier.sourceforge.net/'>http://hyperestraier.sourceforge.net/</a>
2386 &gt;<br>
2387
2388 <p> /usr/share/doc/hyperestraier/index.html<br>
2389
2390 <p> man estcmd<br>
2391
2392 <p> NOTE: the examples that follow assume that sisu output is placed in
2393
2394 <p>the directory /home/ralph/sisu_www
2395 <p> (A) to generate the index within the
2396 webserver directory to be indexed:
2397 <p> estcmd gather -sd [index &nbsp;name] [directory
2398 &nbsp;path &nbsp;to &nbsp;index]<br>
2399
2400 <p> the following are examples that will need to be tailored according to
2401 your needs:
2402 <p> cd /home/ralph/sisu_www<br>
2403
2404 <p> estcmd gather -sd casket /home/ralph/sisu_www<br>
2405
2406 <p> you may use the &rsquo;find&rsquo; command together with &rsquo;egrep&rsquo; to limit indexing to
2407 particular document collection directories within the web server directory:
2408
2409 <p> find /home/ralph/sisu_www -type f | egrep<br>
2410 &rsquo;/home/ralph/sisu_www/sisu/.+?.html$&rsquo; |estcmd gather -sd casket -<br>
2411
2412 <p> Check which directories in the webserver/output directory (~/sisu_www
2413 or elsewhere depending on configuration) you wish to include in the search
2414 index.
2415 <p> As sisu duplicates output in multiple file formats, it it is probably
2416 preferable to limit the estraier index to html output, and as it may also
2417 be desirable to exclude files &rsquo;plain.txt&rsquo;, &rsquo;toc.html&rsquo; and &rsquo;concordance.html&rsquo;, as
2418 these duplicate information held in other html output e.g.
2419 <p> find /home/ralph/sisu_www
2420 -type f | egrep<br>
2421 &rsquo;/sisu_www/(sisu|bookmarks)/.+?.html$&rsquo; | egrep -v<br>
2422 &rsquo;(doc|concordance).html$&rsquo; |estcmd gather -sd casket -<br>
2423
2424 <p> from your current document preparation/markup directory, you would construct
2425 a rune along the following lines:
2426 <p> find /home/ralph/sisu_www -type f
2427 | egrep &rsquo;/home/ralph/sisu_www/([specify <br>
2428 first &nbsp;directory &nbsp;for &nbsp;inclusion]|[specify &nbsp;second &nbsp;directory &nbsp;for <br>
2429 inclusion]|[another &nbsp;directory &nbsp;for &nbsp;inclusion? &nbsp;...])/.+?.html$&rsquo; |<br>
2430 egrep -v &rsquo;(doc|concordance).html$&rsquo; |estcmd gather -sd<br>
2431 /home/ralph/sisu_www/casket -<br>
2432
2433 <p> (B) to set up the search form
2434 <p> (i) copy estseek.cgi to your cgi directory
2435 and set file permissions to 755:
2436 <p> sudo cp -vi /usr/lib/estraier/estseek.cgi
2437 /usr/lib/cgi-bin<br>
2438
2439 <p> sudo chmod -v 755 /usr/lib/cgi-bin/estseek.cgi<br>
2440
2441 <p> sudo cp -v /usr/share/hyperestraier/estseek.* /usr/lib/cgi-bin<br>
2442
2443 <p> [see &nbsp;estraier &nbsp;documentation &nbsp;for &nbsp;paths]<br>
2444
2445 <p> (ii) edit estseek.conf, with attention to the lines starting &rsquo;indexname:&rsquo;
2446 and &rsquo;replace:&rsquo;:
2447 <p> indexname: /home/ralph/sisu_www/casket<br>
2448
2449 <p> replace: ^file:///home/ralph/sisu_www{{!}}<a href='http://localhost'>http://localhost</a>
2450 <br>
2451
2452 <p> replace: /index.html?${{!}}/<br>
2453
2454 <p> (C) to test using webrick, start webrick:
2455 <p> sisu -W<br>
2456
2457 <p> and try open the url: &lt;<a href='http://localhost:8081/cgi-bin/estseek.cgi'>http://localhost:8081/cgi-bin/estseek.cgi</a>
2458 &gt;
2459 <p> 26. SISU_WEBRICK
2460
2461 <p> 26.1 NAME
2462 <p> <b>SiSU</b> - Structured information, Serialized Units - a document
2463
2464 <p>publishing system
2465 <p> 26.2 SYNOPSIS
2466 <p> sisu_webrick [port]
2467 <p> or
2468 <p> sisu -W [port]
2469
2470 <p> 26.3 DESCRIPTION
2471 <p> sisu_webrick is part of <b>SiSU</b> (man sisu) sisu_webrick
2472 starts <b>Ruby</b> &rsquo;s Webrick web-server and points it to the directories to which
2473 <b>SiSU</b> output is written, providing a list of these directories (assuming
2474 <b>SiSU</b> is in use and they exist).
2475 <p> The default port for sisu_webrick is set
2476 to 8081, this may be modified in the yaml file: ~/.sisu/sisurc.yml a sample
2477 of which is provided as /etc/sisu/sisurc.yml (or in the equivalent directory
2478 on your system).
2479 <p> 26.4 SUMMARY OF MAN PAGE
2480 <p> sisu_webrick, may be started
2481 on it&rsquo;s own with the command: sisu_webrick [port] or using the sisu command
2482 with the -W flag: sisu -W [port]
2483 <p> where no port is given and settings are
2484
2485 <p>unchanged the default port is 8081
2486 <p> 26.5 DOCUMENT PROCESSING COMMAND FLAGS
2487
2488 <p> sisu -W [port] starts <b>Ruby</b> Webrick web-server, serving <b>SiSU</b> output directories,
2489 on the port provided, or if no port is provided and the defaults have not
2490
2491 <p>been changed in ~/.sisu/sisurc.yaml then on port 8081
2492 <p> 26.6 FURTHER INFORMATION
2493
2494 <p> For more information on <b>SiSU</b> see: &lt;<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a>
2495 &gt;
2496 <p> or man sisu
2497
2498 <p> 26.7 AUTHOR
2499 <p> Ralph Amissah ralph@amissah.com or ralph.amissah@gmail.com
2500 <p>
2501
2502 <p>26.8 SEE ALSO
2503 <p> <a href='http:~/bin/man2html?sisu:1'>sisu(1)</a>
2504 <br>
2505
2506 <p> <a href='http:~/bin/man2html?sisu_vim:7'>sisu_vim(7)</a>
2507 <br>
2508
2509 <p> <a href='http:~/bin/man2html?sisu:8'>sisu(8)</a>
2510 <br>
2511
2512 <p> 27. REMOTE SOURCE DOCUMENTS
2513 <p> <b>SiSU</b> processing instructions can be run
2514 against remote source documents by providing the url of the documents against
2515 which the processing instructions are to be carried out. The remote <b>SiSU</b>
2516 documents can either be sisu marked up files in plaintext .sst or .ssm or;
2517 zipped sisu files, sisupod.zip or filename.ssp
2518 <p> <b>.sst / .ssm - sisu text files</b>
2519
2520 <p> <b>SiSU</b> can be run against source text files on a remote machine, provide
2521 the processing instruction and the url. The source file and any associated
2522 parts (such as images) will be downloaded and generated locally.
2523 <p>
2524 <p> <br>
2525 <pre> sisu -3 http://[provide &nbsp;url &nbsp;to &nbsp;valid &nbsp;.sst &nbsp;or &nbsp;.ssm &nbsp;file]
2526 </pre>
2527 <p> Any of the source documents in the sisu examples page can be used in
2528 this way, see &lt;<a href='http://www.jus.uio.no/sisu/SiSU/examples.html'>http://www.jus.uio.no/sisu/SiSU/examples.html</a>
2529 &gt; and use the url
2530 for the desired document.
2531 <p> NOTE: to set up a remote machine to serve <b>SiSU</b>
2532 documents in this way, images should be in the directory relative to the
2533
2534 <p>document source ../_sisu/image
2535 <p> <b>sisupod - zipped sisu files</b>
2536 <p> A sisupod is
2537 the zipped content of a sisu marked up text or texts and any other associated
2538 parts to the document such as images.
2539 <p> <b>SiSU</b> can be run against a sisupod
2540 on a (local or) remote machine, provide the processing instruction and
2541 the url, the sisupod will be downloaded and the documents it contains generated
2542 locally.
2543 <p>
2544 <p> <br>
2545 <pre> sisu -3 http://[provide &nbsp;url &nbsp;to &nbsp;valid &nbsp;sisupod.zip &nbsp;or &nbsp;.ssp &nbsp;file]
2546 </pre>
2547 <p> Any of the source documents in the sisu examples page can be used in
2548 this way, see &lt;<a href='http://www.jus.uio.no/sisu/SiSU/examples.html'>http://www.jus.uio.no/sisu/SiSU/examples.html</a>
2549 &gt; and use the url
2550 for the desired document.
2551 <p> REMOTE DOCUMENT OUTPUT
2552 <p> 28. REMOTE OUTPUT
2553 <p>
2554 Once properly configured <b>SiSU</b> output can be automatically posted once generated
2555 to a designated remote machine using either rsync, or scp.
2556 <p> In order to
2557 do this some ssh authentication agent and keychain or similar tool will
2558 need to be configured. Once that is done the placement on a remote host
2559 can be done seamlessly with the -r (for scp) or -R (for rsync) flag, which
2560 may be used in conjunction with other processing flags, e.g.
2561 <p>
2562 <p> <br>
2563 <pre> sisu -3R sisu_remote.sst
2564 </pre>
2565 <p> 28.1 COMMANDS
2566 <p>
2567 <dl>
2568
2569 <dt><b>-R [filename/wildcard]</b> </dt>
2570 <dd>copies sisu output files to remote
2571 host using rsync. This requires that sisurc.yml has been provided with information
2572 on hostname and username, and that you have your different if -R is used
2573 with other flags from if used alone. Alone the rsync --delete parameter is
2574 sent, useful for cleaning the remote directory (when -R is used together
2575 with other flags, it is not). Also see -r
2576 <p> </dd>
2577
2578 <dt><b>-r [filename/wildcard]</b> </dt>
2579 <dd>copies sisu
2580 output files to remote host using scp. This requires that sisurc.yml has
2581 been provided with information on hostname and username, and that you have
2582
2583 <p>your
2584 <p> </dd>
2585 </dl>
2586 28.2 CONFIGURATION
2587 <p> [expand &nbsp;on &nbsp;the &nbsp;setting &nbsp;up &nbsp;of &nbsp;an &nbsp;ssh-agent &nbsp;/ &nbsp;keychain]
2588
2589 <p> 29. REMOTE SERVERS
2590 <p> As <b>SiSU</b> is generally operated using the command line,
2591 and works within a Unix type environment, <b>SiSU</b> the program and all documents
2592 can just as easily be on a remote server, to which you are logged on using
2593 a terminal, and commands and operations would be pretty much the same as
2594 they would be on your local machine.
2595 <p> 30. QUICKSTART - GETTING STARTED HOWTO
2596
2597 <p> 30.1 INSTALLATION
2598 <p> Installation is currently most straightforward and
2599 tested on the <b>Debian</b> platform, as there are packages for the installation
2600 of sisu and all requirements for what it does.
2601 <p> 30.1.1 DEBIAN INSTALLATION
2602
2603 <p> <b>SiSU</b> is available directly from the <b>Debian</b> Sid and testing archives (and
2604 possibly Ubuntu), assuming your /etc/apt/sources.list is set accordingly:
2605
2606 <p>
2607 <p> <br>
2608 <pre> aptitude update
2609 aptitude install sisu-complete
2610 </pre>
2611 <p> The following /etc/apt/sources.list setting permits the download of additional
2612 markup samples:
2613 <p>
2614 <p> <br>
2615 <pre> #/etc/apt/sources.list
2616 deb http://ftp.fi.debian.org/debian/ unstable main non-free contrib
2617 deb-src http://ftp.fi.debian.org/debian/ unstable main non-free contrib
2618 d
2619 </pre>
2620 <p> The aptitude commands become:
2621 <p>
2622 <p> <br>
2623 <pre> aptitude update
2624 aptitude install sisu-complete sisu-markup-samples
2625 </pre>
2626 <p> If there are newer versions of <b>SiSU</b> upstream of the <b>Debian</b> archives,
2627
2628 <p>they will be available by adding the following to your /etc/apt/sources.list
2629
2630 <p>
2631 <p> <br>
2632 <pre> #/etc/apt/sources.list
2633 deb http://www.jus.uio.no/sisu/archive unstable main non-free
2634 deb-src http://www.jus.uio.no/sisu/archive unstable main non-free
2635 </pre>
2636 <p> repeat the aptitude commands
2637 <p>
2638 <p> <br>
2639 <pre> aptitude update
2640 aptitude install sisu-complete sisu-markup-samples
2641 </pre>
2642 <p> Note however that it is not necessary to install sisu-complete if not
2643 all components of sisu are to be used. Installing just the package sisu
2644 will provide basic functionality.
2645 <p> 30.1.2 RPM INSTALLATION
2646 <p> RPMs are provided
2647 though untested, they are prepared by running alien against the source
2648 package, and against the debs.
2649 <p> They may be downloaded from:
2650 <p> &lt;<a href='http://www.jus.uio.no/sisu/SiSU/download.html#rpm'>http://www.jus.uio.no/sisu/SiSU/download.html#rpm</a>
2651 &gt;<br>
2652
2653 <p> as root type:
2654 <p> rpm -i [rpm &nbsp;package &nbsp;name]<br>
2655
2656 <p> 30.1.3 INSTALLATION FROM SOURCE
2657 <p> To install <b>SiSU</b> from source check information
2658 at:
2659 <p> &lt;<a href='http://www.jus.uio.no/sisu/SiSU/download.html#current'>http://www.jus.uio.no/sisu/SiSU/download.html#current</a>
2660 &gt;<br>
2661
2662 <p> * download the source package
2663 <p> * Unpack the source
2664 <p> Two alternative
2665 modes of installation from source are provided, setup.rb (by Minero Aoki)
2666 and a rant(by Stefan Lang) built install file, in either case: the first
2667 steps are the same, download and unpack the source file:
2668 <p> For basic use
2669 <b>SiSU</b> is only dependent on the programming language in which it is written
2670 <b>Ruby</b> , and <b>SiSU</b> will be able to generate html, various XMLs, including
2671 ODF (and will also produce LaTeX). Dependencies required for further actions,
2672 though it relies on the installation of additional dependencies which the
2673 source tarball does not take care of, for things like using a database
2674 (postgresql or sqlite)[^23] or converting LaTeX to pdf.
2675 <p> <b>setup.rb</b>
2676 <p> This
2677 is a standard ruby installer, using setup.rb is a three step process. In
2678 the root directory of the unpacked <b>SiSU</b> as root type:
2679 <p>
2680 <p> <br>
2681 <pre> ruby setup.rb config
2682 ruby setup.rb setup
2683 #[and &nbsp;as &nbsp;root:]
2684 ruby setup.rb install
2685 </pre>
2686 <p> further information on setup.rb is available from:
2687 <p> &lt;<a href='http://i.loveruby.net/en/projects/setup/'>http://i.loveruby.net/en/projects/setup/</a>
2688 &gt;<br>
2689
2690 <p> &lt;<a href='http://i.loveruby.net/en/projects/setup/doc/usage.html'>http://i.loveruby.net/en/projects/setup/doc/usage.html</a>
2691 &gt;<br>
2692
2693 <p> <b></b>
2694 <p> The root directory of the unpacked <b>SiSU</b> as root type:
2695 <p> ruby install
2696 base<br>
2697
2698 <p> or for a more complete installation:
2699 <p> ruby install<br>
2700
2701 <p> or
2702 <p> ruby install base<br>
2703
2704 <p> This makes use of Rant (by Stefan Lang) and the provided Rantfile. It
2705 has been configured to do post installation setup setup configuration and
2706 generation of first test file. Note however, that additional external package
2707 dependencies, such as tetex-extra are not taken care of for you.
2708 <p> Further
2709
2710 <p>information on
2711 <p> &lt;<a href='http://make.rubyforge.org/'>http://make.rubyforge.org/</a>
2712 &gt;<br>
2713
2714 <p> &lt;<a href='http://rubyforge.org/frs/?group_id=615'>http://rubyforge.org/frs/?group_id=615</a>
2715 &gt;<br>
2716
2717 <p> For a list of alternative actions you may type:
2718 <p> ruby install help<br>
2719
2720 <p> ruby install -T<br>
2721
2722 <p> 30.2 TESTING SISU, GENERATING OUTPUT
2723 <p> To check which version of sisu
2724 is installed:
2725 <p> sisu -v
2726 <p> Depending on your mode of installation one or
2727 a number of markup sample files may be found either in the directory:
2728 <p>
2729
2730 <p> or
2731 <p>
2732 <p> change directory to the appropriate one:
2733 <p> cd /usr/share/doc/sisu/v1/sisu_markup_samples/dfsg
2734
2735 <p> 30.2.1 BASIC TEXT, PLAINTEXT, HTML, XML, ODF
2736 <p> Having moved to the directory
2737 that contains the markup samples (see instructions above if necessary),
2738
2739 <p>choose a file and run sisu against it
2740 <p> sisu -NhwoabxXyv free_as_in_freedom.rms_and_free_software.sam_williams.sst
2741
2742 <p> this will generate html including a concordance file, opendocument text
2743 format, plaintext, XHTML and various forms of XML, and OpenDocument text
2744
2745 <p> 30.2.2 LATEX / PDF
2746 <p> Assuming a LaTeX engine such as tetex or texlive is
2747 installed with the required modules (done automatically on selection of
2748 sisu-pdf in <b>Debian</b> )
2749 <p> Having moved to the directory that contains the markup
2750 samples (see instructions above if necessary), choose a file and run sisu
2751
2752 <p>against it
2753 <p> sisu -pv free_as_in_freedom.rms_and_free_software.sam_williams.sst
2754
2755 <p> sisu -3 free_as_in_freedom.rms_and_free_software.sam_williams.sst
2756 <p> should
2757 generate most available output formats: html including a concordance file,
2758 opendocument text format, plaintext, XHTML and various forms of XML, and
2759
2760 <p>OpenDocument text and pdf
2761 <p> 30.2.3 RELATIONAL DATABASE - POSTGRESQL, SQLITE
2762
2763 <p> Relational databases need some setting up - you must have permission to
2764 create the database and write to it when you run sisu.
2765 <p> Assuming you have
2766
2767 <p>the database installed and the requisite permissions
2768 <p> sisu --sqlite --recreate
2769
2770 <p> sisu --sqlite -v --import free_as_in_freedom.rms_and_free_software.sam_williams.sst
2771
2772 <p> sisu --pgsql --recreate
2773 <p> sisu --pgsql -v --import free_as_in_freedom.rms_and_free_software.sam_williams.sst
2774
2775 <p> 30.3 GETTING HELP
2776 <p> 30.3.1 THE MAN PAGES
2777 <p> Type:
2778 <p> man sisu<br>
2779
2780 <p> The man pages are also available online, though not always kept as up
2781 to date as within the package itself:
2782 <p> * sisu.1 &lt;<a href='http://www.jus.uio.no/sisu/man/sisu.1'>http://www.jus.uio.no/sisu/man/sisu.1</a>
2783 &gt;
2784 [^24]
2785 <p> * sisu.8 &lt;<a href='http://www.jus.uio.no/sisu/man/sisu.8'>http://www.jus.uio.no/sisu/man/sisu.8</a>
2786 &gt; [^25]
2787 <p> * man directory
2788 &lt;<a href='http://www.jus.uio.no/sisu/man'>http://www.jus.uio.no/sisu/man</a>
2789 &gt; [^26]
2790 <p> 30.3.2 BUILT IN HELP
2791 <p> sisu --help
2792 <p> sisu
2793
2794 <p>-
2795 <p>-
2796 <p>help --env
2797 <p> sisu --help --commands
2798 <p> sisu --help --markup
2799 <p> 30.3.3 THE HOME PAGE
2800 <p>
2801 &lt;<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a>
2802 &gt;
2803 <p> &lt;<a href='http://www.jus.uio.no/sisu/SiSU'>http://www.jus.uio.no/sisu/SiSU</a>
2804 &gt;
2805 <p> 30.4 MARKUP SAMPLES
2806
2807 <p> A number of markup samples (along with output) are available off:
2808 <p> &lt;<a href='http://www.jus.uio.no/sisu/SiSU/examples.html'>http://www.jus.uio.no/sisu/SiSU/examples.html</a>
2809 &gt;
2810
2811 <p> Additional markup samples are packaged separately in the file:
2812 <p> <b>*</b>
2813 <p>
2814 On <b>Debian</b> they are available in non-free[^27] to include them it is necessary
2815 to include non-free in your /etc/apt/source.list or obtain them from the
2816 sisu home site.
2817 <p> 31. EDITOR FILES, SYNTAX HIGHLIGHTING
2818 <p> The directory:
2819
2820 <p> ./data/sisu/v1/conf/editor-syntax-etc/<br>
2821
2822 <p> /usr/share/sisu/conf/editor-syntax-etc<br>
2823
2824 <p> contains rudimentary sisu syntax highlighting files for:
2825 <p> * (g)vim
2826 &lt;<a href='http://www.vim.org'>http://www.vim.org</a>
2827 &gt;
2828 <p> package: sisu-vim<br>
2829
2830 <p> status: largely done
2831 <p> there is a vim syntax highlighting and folds
2832 component<br>
2833
2834 <p> * gedit &lt;<a href='http://www.gnome.org/projects/gedit'>http://www.gnome.org/projects/gedit</a>
2835 &gt;
2836 <p> * gobby &lt;<a href='http://gobby.0x539.de/'>http://gobby.0x539.de/</a>
2837 &gt;
2838
2839 <p> file: sisu.lang<br>
2840
2841 <p> place in:
2842 <p> /usr/share/gtksourceview-1.0/language-specs<br>
2843
2844 <p> or
2845 <p> ~/.gnome2/gtksourceview-1.0/language-specs<br>
2846
2847 <p> status: very basic syntax highlighting<br>
2848
2849 <p> comments: this editor features display line wrap and is used by Goby!<br>
2850
2851 <p> * nano &lt;<a href='http://www.nano-editor.org'>http://www.nano-editor.org</a>
2852 &gt;
2853 <p> file: nanorc<br>
2854
2855 <p> save as:
2856 <p> ~/.nanorc<br>
2857
2858 <p> status: basic syntax highlighting<br>
2859
2860 <p> comments: assumes dark background; no display line-wrap; does line
2861 breaks<br>
2862
2863 <p> * diakonos (an editor written in ruby) &lt;<a href='http://purepistos.net/diakonos'>http://purepistos.net/diakonos</a>
2864 &gt;
2865
2866 <p> file: diakonos.conf
2867 <p> save as:
2868 <p> ~/.diakonos/diakonos.conf<br>
2869
2870 <p> includes:
2871 <p> status: basic syntax highlighting<br>
2872
2873 <p> comments: assumes dark background; no display line-wrap
2874 <p> * kate &amp; kwrite
2875 &lt;<a href='http://kate.kde.org'>http://kate.kde.org</a>
2876 &gt;
2877 <p> file: sisu.xml<br>
2878
2879 <p> place in:<br>
2880
2881 <p> /usr/share/apps/katepart/syntax<br>
2882
2883 <p> or<br>
2884
2885 <p> ~/.kde/share/apps/katepart/syntax<br>
2886
2887 <p> [settings::configure &nbsp;kate::{highlighting,filetypes}]<br>
2888
2889 <p> [tools::highlighting::{markup,scripts}:: &nbsp;.B &nbsp;SiSU &nbsp;]<br>
2890
2891 <p> * nedit &lt;<a href='http://www.nedit.org'>http://www.nedit.org</a>
2892 &gt;
2893 <p> file: sisu_nedit.pats<br>
2894
2895 <p> nedit -import sisu_nedit.pats<br>
2896
2897 <p> status: a very clumsy first attempt [not &nbsp;really &nbsp;done]<br>
2898
2899 <p> comments: this editor features display line wrap<br>
2900
2901 <p> * emacs &lt;<a href='http://www.gnu.org/software/emacs/emacs.html'>http://www.gnu.org/software/emacs/emacs.html</a>
2902 &gt;
2903 <p> files: sisu-mode.el<br>
2904
2905 <p> to file ~/.emacs add the following 2 lines:<br>
2906
2907 <p> (add-to-list &rsquo;load-path<br>
2908
2909 <p> (require &rsquo;sisu-mode.el)<br>
2910
2911 <p> [not &nbsp;done &nbsp;/ &nbsp;not &nbsp;yet &nbsp;included]<br>
2912
2913 <p> * vim &amp; gvim &lt;<a href='http://www.vim.org'>http://www.vim.org</a>
2914 &gt;
2915 <p> files:<br>
2916
2917 <p> package is the most comprehensive sisu syntax highlighting and editor<br>
2918 environment provided to date (is for vim/ gvim, and is separate from
2919 the<br>
2920 contents of this directory)<br>
2921
2922 <p> status: this includes: syntax highlighting; vim folds; some error
2923 checking<br>
2924
2925 <p> comments: this editor features display line wrap<br>
2926
2927 <p> NOTE:
2928 <p> [ &nbsp;.B &nbsp;SiSU &nbsp;parses &nbsp;files &nbsp;with &nbsp;long &nbsp;lines &nbsp;or &nbsp;line &nbsp;breaks, but, &nbsp;display
2929 &nbsp;linewrap &nbsp;(without &nbsp;line-breaks) &nbsp;is &nbsp;a &nbsp;convenient editor &nbsp;feature &nbsp;to &nbsp;have &nbsp;for
2930 &nbsp;sisu &nbsp;markup]
2931 <p> 32. HOW DOES SISU WORK?
2932 <p> <b>SiSU</b> markup is fairly minimalistic,
2933 it consists of: a (largely optional) document header, made up of information
2934 about the document (such as when it was published, who authored it, and
2935 granting what rights) and any processing instructions; and markup within
2936 the substantive text of the document, which is related to document structure
2937 and typeface. <b>SiSU</b> must be able to discern the structure of a document,
2938 (text headings and their levels in relation to each other), either from
2939 information provided in the document header or from markup within the text
2940 (or from a combination of both). Processing is done against an abstraction
2941 of the document comprising of information on the document&rsquo;s structure and
2942 its objects,[2] which the program serializes (providing the object numbers)
2943 and which are assigned hash sum values based on their content. This abstraction
2944 of information about document structure, objects, (and hash sums), provides
2945 considerable flexibility in representing documents different ways and for
2946 different purposes (e.g. search, document layout, publishing, content certification,
2947 concordance etc.), and makes it possible to take advantage of some of the
2948 strengths of established ways of representing documents, (or indeed to
2949 create new ones).
2950 <p> 33. SUMMARY OF FEATURES
2951 <p> * sparse/minimal markup (clean
2952 utf-8 source texts). Documents are prepared in a single UTF-8 file using a
2953 minimalistic mnemonic syntax. Typical literature, documents like headers
2954 are optional.
2955 <p> * markup is easily readable/parsable by the human eye, (basic
2956 markup is simpler and more sparse than the most basic HTML), [this &nbsp;may
2957 &nbsp;also &nbsp;be &nbsp;converted &nbsp;to &nbsp;XML &nbsp;representations &nbsp;of &nbsp;the &nbsp;same &nbsp;input/source &nbsp;document].
2958
2959 <p> * markup defines document structure (this may be done once in a header
2960 pattern-match description, or for heading levels individually); basic text
2961 attributes (bold, italics, underscore, strike-through etc.) as required;
2962 and semantic information related to the document (header information, extended
2963 beyond the Dublin core and easily further extended as required); the headers
2964 may also contain processing instructions. <b>SiSU</b> markup is primarily an abstraction
2965 of document structure and document metadata to permit taking advantage
2966 of the basic strengths of existing alternative practical standard ways
2967 of representing documents [be &nbsp;that &nbsp;paper &nbsp;publication, &nbsp;sql &nbsp;search &nbsp;etc.] (html,
2968 xml, odf, latex, pdf, sql)
2969 <p> * for output produces reasonably elegant output
2970 of established industry and institutionally accepted open standard formats.[3]
2971 takes advantage of the different strengths of various standard formats
2972 for representing documents, amongst the output formats currently supported
2973 are:
2974 <p> * html - both as a single scrollable text and a segmented document<br>
2975
2976 <p> * xhtml<br>
2977
2978 <p> * XML - both in sax and dom style xml structures for further development
2979 as<br>
2980 required<br>
2981
2982 <p> * ODF - open document format, the iso standard for document storage<br>
2983
2984 <p> * LaTeX - used to generate pdf<br>
2985
2986 <p> * pdf (via LaTeX)<br>
2987
2988 <p> * sql - population of an sql database, (at the same object level that
2989 is<br>
2990 used to cite text within a document)<br>
2991
2992 <p> Also produces: concordance files; document content certificates (md5
2993 or sha256 digests of headings, paragraphs, images etc.) and html manifests
2994 (and sitemaps of content). (b) takes advantage of the strengths implicit
2995 in these very different output types, (e.g. PDFs produced using typesetting
2996 of LaTeX, databases populated with documents at an individual object/paragraph
2997 level, making possible granular search (and related possibilities))
2998 <p> *
2999 ensuring content can be cited in a meaningful way regardless of selected
3000 output format. Online publishing (and publishing in multiple document formats)
3001 lacks a useful way of citing text internally within documents (important
3002 to academics generally and to lawyers) as page numbers are meaningless
3003 across browsers and formats. sisu seeks to provide a common way of pinpoint
3004 the text within a document, (which can be utilized for citation and by
3005 search engines). The outputs share a common numbering system that is meaningful
3006 (to man and machine) across all digital outputs whether paper, screen,
3007 or database oriented, (pdf, HTML, xml, sqlite, postgresql), this numbering
3008 system can be used to reference content.
3009 <p> * Granular search within documents.
3010 SQL databases are populated at an object level (roughly headings, paragraphs,
3011 verse, tables) and become searchable with that degree of granularity, the
3012 output information provides the object/paragraph numbers which are relevant
3013 across all generated outputs; it is also possible to look at just the matching
3014 paragraphs of the documents in the database; [output &nbsp;indexing &nbsp;also &nbsp;work
3015 &nbsp;well &nbsp;with &nbsp;search &nbsp;indexing tools &nbsp;like &nbsp;hyperestraier].
3016 <p> * long term maintainability
3017 of document collections in a world of changing formats, having a very sparsely
3018 marked-up source document base. there is a considerable degree of future-proofing,
3019 output representations are upgradeable (open document text) module in 2006
3020 and in future html5 output sometime in future, without modification of
3021
3022 <p>existing prepared texts
3023 <p> * SQL search aside, documents are generated as
3024 required and static once generated.
3025 <p> * documents produced are static files,
3026 and may be batch processed, this needs to be done only once but may be
3027 repeated for various reasons as desired (updated content, addition of new
3028 output formats, updated technology document presentations/representations)
3029
3030 <p> * document source (plaintext utf-8) if shared on the net may be used as
3031
3032 <p>input and processed locally to produce the different document outputs
3033 <p>
3034 * document source may be bundled together (automatically) with associated
3035 documents (multiple language versions or master document with inclusions)
3036 and images and sent as a zip file called a sisupod, if shared on the net
3037
3038 <p>these too may be processed locally to produce the desired document outputs
3039
3040 <p> * generated document outputs may automatically be posted to remote sites.
3041
3042 <p> * for basic document generation, the only software dependency is <b>Ruby</b>
3043 , and a few standard Unix tools (this covers plaintext, HTML, XML, ODF,
3044 LaTeX). To use a database you of course need that, and to convert the LaTeX
3045 generated to pdf, a latex processor like tetex or texlive.
3046 <p> * as a developers
3047
3048 <p>tool it is flexible and extensible
3049 <p> Syntax highlighting for <b>SiSU</b> markup
3050 is available for a number of text editors.
3051 <p> <b>SiSU</b> is less about document
3052 layout than about finding a way with little markup to be able to construct
3053 an abstract representation of a document that makes it possible to produce
3054 multiple representations of it which may be rather different from each
3055 other and used for different purposes, whether layout and publishing, or
3056
3057 <p>search of content
3058 <p> i.e. to be able to take advantage from this minimal preparation
3059 starting point of some of the strengths of rather different established
3060 ways of representing documents for different purposes, whether for search
3061 (relational database, or indexed flat files generated for that purpose
3062 whether of complete documents, or say of files made up of objects), online
3063 viewing (e.g. html, xml, pdf), or paper publication (e.g. pdf)...
3064 <p> the solution
3065 arrived at is by extracting structural information about the document (about
3066 headings within the document) and by tracking objects (which are serialized
3067 and also given hash values) in the manner described. It makes possible representations
3068 that are quite different from those offered at present. For example objects
3069 could be saved individually and identified by their hashes, with an index
3070 of how the objects relate to each other to form a document.
3071 <p> 34. HELP SOURCES
3072
3073 <p> For a summary of alternative ways to get help on <b>SiSU</b> try one of the
3074 following:
3075 <p> <b>man page</b>
3076 <p> man sisu_help<br>
3077
3078 <p> <b>man2html</b>
3079 <p> &lt;<a href='http://www.jus.uio.no/sisu/man/sisu_help.1.html'>http://www.jus.uio.no/sisu/man/sisu_help.1.html</a>
3080 &gt;<br>
3081
3082 <p> <b>sisu generated output - links to html</b>
3083 <p> &lt;<a href='http://sisudoc.org/sisu/sisu_help/index.html'>http://sisudoc.org/sisu/sisu_help/index.html</a>
3084 &gt;<br>
3085
3086 <p> <b>help sources lists</b>
3087 <p> Alternative sources for this help sources page
3088 listed here:
3089 <p> man sisu_help_sources<br>
3090
3091 <p> &lt;<a href='http://sisudoc.org/sisu/sisu_help_sources/index.html'>http://sisudoc.org/sisu/sisu_help_sources/index.html</a>
3092 &gt;<br>
3093
3094 <p> 34.1 MAN PAGES
3095 <p> 34.1.1 MAN
3096 <p> man sisu<br>
3097
3098 <p> man 7 sisu_complete<br>
3099
3100 <p> man 7 sisu_pdf<br>
3101
3102 <p> man 7 sisu_postgresql<br>
3103
3104 <p> man 7 sisu_sqlite<br>
3105
3106 <p> man sisu_termsheet<br>
3107
3108 <p> man sisu_webrick<br>
3109
3110 <p> 34.2 SISU GENERATED OUTPUT - LINKS TO HTML
3111 <p> Note <b>SiSU</b> documentation is
3112 prepared in <b>SiSU</b> and output is available in multiple formats including
3113 amongst others html, pdf, and odf which may be also be accessed via the
3114 html pages[^28]
3115 <p> 34.2.1 WWW.SISUDOC.ORG
3116 <p> &lt;<a href='http://sisudoc.org/sisu/sisu_manual/index.html'>http://sisudoc.org/sisu/sisu_manual/index.html</a>
3117 &gt;
3118
3119 <p> &lt;<a href='http://sisudoc.org/sisu/sisu_manual/index.html'>http://sisudoc.org/sisu/sisu_manual/index.html</a>
3120 &gt;<br>
3121
3122 <p> &lt;<a href='http://sisudoc.org/sisu/sisu_commands/index.html'>http://sisudoc.org/sisu/sisu_commands/index.html</a>
3123 &gt;<br>
3124
3125 <p> &lt;<a href='http://sisudoc.org/sisu/sisu_complete/index.html'>http://sisudoc.org/sisu/sisu_complete/index.html</a>
3126 &gt;<br>
3127
3128 <p> &lt;<a href='http://sisudoc.org/sisu/sisu_configuration/index.html'>http://sisudoc.org/sisu/sisu_configuration/index.html</a>
3129 &gt;<br>
3130
3131 <p> &lt;<a href='http://sisudoc.org/sisu/sisu_description/index.html'>http://sisudoc.org/sisu/sisu_description/index.html</a>
3132 &gt;<br>
3133
3134 <p> &lt;<a href='http://sisudoc.org/sisu/sisu_examples/index.html'>http://sisudoc.org/sisu/sisu_examples/index.html</a>
3135 &gt;<br>
3136
3137 <p> &lt;<a href='http://sisudoc.org/sisu/sisu_faq/index.html'>http://sisudoc.org/sisu/sisu_faq/index.html</a>
3138 &gt;<br>
3139
3140 <p> &lt;<a href='http://sisudoc.org/sisu/sisu_filetypes/index.html'>http://sisudoc.org/sisu/sisu_filetypes/index.html</a>
3141 &gt;<br>
3142
3143 <p> &lt;<a href='http://sisudoc.org/sisu/sisu_help/index.html'>http://sisudoc.org/sisu/sisu_help/index.html</a>
3144 &gt;<br>
3145
3146 <p> &lt;<a href='http://sisudoc.org/sisu/sisu_help_sources/index.html'>http://sisudoc.org/sisu/sisu_help_sources/index.html</a>
3147 &gt;<br>
3148
3149 <p> &lt;<a href='http://sisudoc.org/sisu/sisu_howto/index.html'>http://sisudoc.org/sisu/sisu_howto/index.html</a>
3150 &gt;<br>
3151
3152 <p> &lt;<a href='http://sisudoc.org/sisu/sisu_introduction/index.html'>http://sisudoc.org/sisu/sisu_introduction/index.html</a>
3153 &gt;<br>
3154
3155 <p> &lt;<a href='http://sisudoc.org/sisu/sisu_manual/index.html'>http://sisudoc.org/sisu/sisu_manual/index.html</a>
3156 &gt;<br>
3157
3158 <p> &lt;<a href='http://sisudoc.org/sisu/sisu_markup/index.html'>http://sisudoc.org/sisu/sisu_markup/index.html</a>
3159 &gt;<br>
3160
3161 <p> &lt;<a href='http://sisudoc.org/sisu/sisu_output_overview/index.html'>http://sisudoc.org/sisu/sisu_output_overview/index.html</a>
3162 &gt;<br>
3163
3164 <p> &lt;<a href='http://sisudoc.org/sisu/sisu_pdf/index.html'>http://sisudoc.org/sisu/sisu_pdf/index.html</a>
3165 &gt;<br>
3166
3167 <p> &lt;<a href='http://sisudoc.org/sisu/sisu_postgresql/index.html'>http://sisudoc.org/sisu/sisu_postgresql/index.html</a>
3168 &gt;<br>
3169
3170 <p> &lt;<a href='http://sisudoc.org/sisu/sisu_quickstart/index.html'>http://sisudoc.org/sisu/sisu_quickstart/index.html</a>
3171 &gt;<br>
3172
3173 <p> &lt;<a href='http://sisudoc.org/sisu/sisu_remote/index.html'>http://sisudoc.org/sisu/sisu_remote/index.html</a>
3174 &gt;<br>
3175
3176 <p> &lt;<a href='http://sisudoc.org/sisu/sisu_search/index.html'>http://sisudoc.org/sisu/sisu_search/index.html</a>
3177 &gt;<br>
3178
3179 <p> &lt;<a href='http://sisudoc.org/sisu/sisu_skin/index.html'>http://sisudoc.org/sisu/sisu_skin/index.html</a>
3180 &gt;<br>
3181
3182 <p> &lt;<a href='http://sisudoc.org/sisu/sisu_sqlite/index.html'>http://sisudoc.org/sisu/sisu_sqlite/index.html</a>
3183 &gt;<br>
3184
3185 <p> &lt;<a href='http://sisudoc.org/sisu/sisu_syntax_highlighting/index.html'>http://sisudoc.org/sisu/sisu_syntax_highlighting/index.html</a>
3186 &gt;<br>
3187
3188 <p> &lt;<a href='http://sisudoc.org/sisu/sisu_vim/index.html'>http://sisudoc.org/sisu/sisu_vim/index.html</a>
3189 &gt;<br>
3190
3191 <p> &lt;<a href='http://sisudoc.org/sisu/sisu_webrick/index.html'>http://sisudoc.org/sisu/sisu_webrick/index.html</a>
3192 &gt;<br>
3193
3194 <p> 34.3 MAN2HTML
3195 <p> 34.3.1 LOCALLY INSTALLED
3196 <p> &lt;file:///usr/share/doc/sisu/v1/html/sisu.1.html&gt;
3197
3198 <p> &lt;file:///usr/share/doc/sisu/v1/html/sisu_help.1.html&gt;
3199 <p> &lt;file:///usr/share/doc/sisu/v1/html/sisu_help_sources.1.html&gt;
3200
3201 <p> /usr/share/doc/sisu/v1/html/sisu.1.html<br>
3202
3203 <p> /usr/share/doc/sisu/v1/html/sisu_pdf.7.html<br>
3204
3205 <p> /usr/share/doc/sisu/v1/html/sisu_postgresql.7.html<br>
3206
3207 <p> /usr/share/doc/sisu/v1/html/sisu_sqlite.7.html<br>
3208
3209 <p> /usr/share/doc/sisu/v1/html/sisu_webrick.1.html<br>
3210
3211 <p> 34.3.2 WWW.JUS.UIO.NO/SISU
3212 <p> &lt;<a href='http://www.jus.uio.no/sisu/man/sisu.1.html'>http://www.jus.uio.no/sisu/man/sisu.1.html</a>
3213 &gt;
3214 <p> &lt;<a href='http://www.jus.uio.no/sisu/man/sisu.1.html'>http://www.jus.uio.no/sisu/man/sisu.1.html</a>
3215 &gt;<br>
3216
3217 <p> &lt;<a href='http://www.jus.uio.no/sisu/man/sisu_complete.7.html'>http://www.jus.uio.no/sisu/man/sisu_complete.7.html</a>
3218 &gt;<br>
3219
3220 <p> &lt;<a href='http://www.jus.uio.no/sisu/man/sisu_pdf.7.html'>http://www.jus.uio.no/sisu/man/sisu_pdf.7.html</a>
3221 &gt;<br>
3222
3223 <p> &lt;<a href='http://www.jus.uio.no/sisu/man/sisu_postgresql.7.html'>http://www.jus.uio.no/sisu/man/sisu_postgresql.7.html</a>
3224 &gt;<br>
3225
3226 <p> &lt;<a href='http://www.jus.uio.no/sisu/man/sisu_sqlite.7.html'>http://www.jus.uio.no/sisu/man/sisu_sqlite.7.html</a>
3227 &gt;<br>
3228
3229 <p> &lt;<a href='http://www.jus.uio.no/sisu/man/sisu_webrick.1.html'>http://www.jus.uio.no/sisu/man/sisu_webrick.1.html</a>
3230 &gt;<br>
3231
3232 <p> DOCUMENT INFORMATION (METADATA)
3233 <p> METADATA
3234 <p> Document Manifest @ &lt;<a href='http://sisudoc.org/sisu_manual/sisu/sisu_manifest.html'>http://sisudoc.org/sisu_manual/sisu/sisu_manifest.html</a>
3235 &gt;
3236
3237 <p> <b>Dublin Core</b> (DC)
3238 <p> <i>DC</i> tags included with this document are provided here.
3239
3240 <p> Title: <i>SiSU</i> - Manual
3241 <p> Creator: <i>Ralph</i> Amissah
3242 <p> Rights: <i>Copyright</i> (C) Ralph
3243 Amissah 2008, part of SiSU documentation, License GPL 3
3244 <p> Type: <i>information</i>
3245
3246 <p> Date created: <i>2002-08-28</i>
3247 <p> Date issued: <i>2002-08-28</i>
3248 <p> Date available: <i>2002-08-28</i>
3249
3250 <p> Date modified: <i>2008-12-16</i>
3251 <p> Date: <i>2008-12-16</i>
3252 <p>
3253 <p> <b>Version Information</b>
3254 <p> Sourcefile:
3255
3256 <p><i>sisu.ssm.sst</i>
3257 <p> Filetype: <i>SiSU</i> text insert 0.67
3258 <p> Sourcefile Digest, MD5(sisu.ssm.sst)=
3259
3260 <p><i>96d1e268b43e0430a2720e67a5876e5e</i>
3261 <p> Skin_Digest: MD5(skin_sisu_manual.rb)=
3262
3263 <p><i>072b2584bedea82ea8a416587b9fa244</i>
3264 <p> <b>Generated</b>
3265 <p> Document (metaverse) last
3266 generated: <i>Tue</i> Dec 16 00:16:50 -0500 2008
3267 <p> Generated by: <i>SiSU</i> <i>0.70.2</i> of 2008w50/2
3268 (2008-12-16)
3269 <p> Ruby version: <i>ruby</i> 1.8.7 (2008-08-11 patchlevel 72) &nbsp;[i486-linux]
3270
3271 <p>
3272 <ol>
3273 <b>.</b><li>objects include: headings, paragraphs, verse, tables, images, but not
3274 footnotes/endnotes which are numbered separately and tied to the object
3275 from which they are referenced. </li><b>.</b><li>i.e. the html, pdf, odf outputs are each built
3276 individually and optimised for that form of presentation, rather than for
3277 example the html being a saved version of the odf, or the pdf being a saved
3278 version of the html. </li><b>.</b><li>the different heading levels </li><b>.</b><li>units of text, primarily
3279 paragraphs and headings, also any tables, poems, code-blocks </li><b>.</b><li>Specification
3280 submitted by Adobe to ISO to become a full open ISO specification &lt;<a href='http://www.linux-watch.com/news/NS7542722606.html'>http://www.linux-watch.com/news/NS7542722606.html</a>
3281 &gt;
3282 </li><b>.</b><li>ISO/IEC 26300:2006 </dd>
3283
3284 <dt><b>*1.</b> </dt>
3285 <dd>square brackets </dd>
3286
3287 <dt><b>*2.</b> </dt>
3288 <dd>square brackets </dd>
3289
3290 <dt><b>+1.</b> </dt>
3291 <dd>square brackets
3292 </li><b>.</b><li>&lt;<a href='http://www.jus.uio.no/sisu/man/'>http://www.jus.uio.no/sisu/man/</a>
3293 &gt; </li><b>.</b><li>&lt;<a href='http://www.jus.uio.no/sisu/man/sisu.1.html'>http://www.jus.uio.no/sisu/man/sisu.1.html</a>
3294 &gt; </li><b>.</b><li>From
3295 sometime after SiSU 0.58 it should be possible to describe SiSU markup using
3296 SiSU, which though not an original design goal is useful. </li><b>.</b><li>files should be
3297 prepared using UTF-8 character encoding </li><b>.</b><li>a footnote or endnote </li><b>.</b><li>self contained
3298 endnote marker &amp; endnote in one </dd>
3299
3300 <dt><b>*.</b> </dt>
3301 <dd>unnumbered asterisk footnote/endnote,
3302 insert multiple asterisks if required </dd>
3303
3304 <dt><b>**.</b> </dt>
3305 <dd>another unnumbered asterisk footnote/endnote
3306 </dd>
3307
3308 <dt><b>*3.</b> </dt>
3309 <dd>editors notes, numbered asterisk footnote/endnote series </dd>
3310
3311 <dt><b>+2.</b> </dt>
3312 <dd>editors
3313 notes, numbered asterisk footnote/endnote series </li><b>.</b><li>&lt;<a href='http://www.jus.uio.no/sisu/'>http://www.jus.uio.no/sisu/</a>
3314 &gt;
3315 </li><b>.</b><li>&lt;<a href='http://www.ruby-lang.org/en/'>http://www.ruby-lang.org/en/</a>
3316 &gt; </li><b>.</b><li>Table from the Wealth of Networks by Yochai Benkler
3317 &lt;<a href='http://www.jus.uio.no/sisu/the_wealth_of_networks.yochai_benkler'>http://www.jus.uio.no/sisu/the_wealth_of_networks.yochai_benkler</a>
3318 &gt; </li><b>.</b><li>.ssc (for composite)
3319 is under consideration but ._sst makes clear that this is not a regular
3320 file to be worked on, and thus less likely that people will have processing.
3321 It may be however that when the resulting file is shared .ssc is an appropriate
3322 suffix to use. </li><b>.</b><li>.B SiSU has worked this way in the past, though this was dropped
3323 as it was thought the complexity outweighed the flexibility, however, the
3324 balance was rather fine and this behaviour could be reinstated. </li><b>.</b><li>&lt;<a href='http://www.postgresql.org/'>http://www.postgresql.org/</a>
3325 &gt;
3326 &lt;<a href='http://advocacy.postgresql.org/'>http://advocacy.postgresql.org/</a>
3327 &gt; &lt;<a href='http://en.wikipedia.org/wiki/Postgresql'>http://en.wikipedia.org/wiki/Postgresql</a>
3328 &gt; </li><b>.</b><li>&lt;<a href='http://www.hwaci.com/sw/sqlite/'>http://www.hwaci.com/sw/sqlite/</a>
3329 &gt;
3330 &lt;<a href='http://en.wikipedia.org/wiki/Sqlite'>http://en.wikipedia.org/wiki/Sqlite</a>
3331 &gt; </li><b>.</b><li>&lt;<a href='http://search.sisudoc.org'>http://search.sisudoc.org</a>
3332 &gt; </li><b>.</b><li>(which could
3333 be extended further with current back-end). As regards scaling of the database,
3334 it is as scalable as the database (here Postgresql) and hardware allow.
3335 </li><b>.</b><li>of this feature when demonstrated to an IBM software innovations evaluator
3336 in 2004 he said to paraphrase: this could be of interest to us. We have
3337 large document management systems, you can search hundreds of thousands
3338 of documents and we can tell you which documents meet your search criteria,
3339 but there is no way we can tell you without opening each document where
3340 within each your matches are found. </li><b>.</b><li>There is nothing to stop MySQL support
3341 being added in future. </li><b>.</b><li>&lt;<a href='http://www.jus.uio.no/sisu/man/sisu.1'>http://www.jus.uio.no/sisu/man/sisu.1</a>
3342 &gt; </li><b>.</b><li>&lt;<a href='http://www.jus.uio.no/sisu/man/sisu.8'>http://www.jus.uio.no/sisu/man/sisu.8</a>
3343 &gt;
3344 </li><b>.</b><li>&lt;<a href='http://www.jus.uio.no/sisu/man'>http://www.jus.uio.no/sisu/man</a>