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