6ea499b231c60d835da07dfca47a9b9e7f983ba4
[software/sisu] / man / man1 / sisu.1
1 .TH "sisu" "1" "2014-02-05" "6.2.3" "SiSU"
2 .br
3 .SH NAME
4 .br
5 sisu \- documents: markup, structuring, publishing in multiple standard formats, and search
6 .br
7 .SH SYNOPSIS
8 .br
9 sisu [\-short\-options|\-\-long\-options] [filename/wildcard]
10
11 .br
12 sisu [\-abCcDdeFGghIikLMmNnoPpQqRrSsTtUuVvWwXxYyZ_0\-9] [filename/wildcard]
13
14 .br
15 sisu \-\-txt \-\-html \-\-epub \-\-odt \-\-pdf \-\-wordmap \-\-sqlite \-\-manpage \-\-texinfo \-\-sisupod \-\-source \-\-qrcode [filename/wildcard]
16
17 .br
18 sisu [\-Ddcv] [instruction] [filename/wildcard]
19
20 .br
21 sisu \-\-pg (\-\-createdb|update [filename/wildcard]|\-\-dropall)
22
23 .br
24 sisu [operations]
25
26 .br
27 sisu [\-CcFLSVvW]
28
29 .br
30 sisu (\-\-configure|\-\-webrick|\-\-sample\-search\-form)
31 .SH SISU - MANUAL,
32 RALPH AMISSAH
33
34 .SH WHAT IS SISU?
35
36 .SH INTRODUCTION - WHAT IS SISU?
37
38
39 .BR
40
41 .B SiSU
42 is a lightweight markup based document creation and publishing framework that
43 is controlled from the command line. Prepare documents for
44 .B SiSU
45 using your text editor of choice, then use
46 .B SiSU
47 to generate various output document formats.
48
49 .BR
50 From a single lightly prepared document (plain-text
51 .I UTF-8
52 ) sisu custom builds several standard output formats which share a common (text
53 object) numbering system for citation of content within a document (that also
54 has implications for search). The sisu engine works with an abstraction of the
55 document's structure and content from which it is possible to generate
56 different forms of representation of the document.
57 .B SiSU
58 produces: plain-text,
59 .I HTML,
60 .I XHTML,
61 .I XML,
62 .I EPUB,
63 .I ODF:
64 .I ODT
65 (Opendocument),
66 .I LaTeX,
67 .I PDF,
68 and populates an
69 .I SQL
70 database (
71 .I PostgreSQL
72 or
73 .I SQLite
74 ) with text objects, roughly, paragraph sized chunks so that document searches
75 are done at this level of granularity.
76
77 .BR
78 Outputs share a common citation numbering system, associated with text objects
79 and any semantic meta-data provided about the document.
80
81 .BR
82
83 .B SiSU
84 also provides concordance files, document content certificates and manifests of
85 generated output. Book indexes may be made.
86
87 .BR
88 Some document markup samples are provided in the package sisu -markup-samples.
89 Homepages:
90
91 * <http://www.sisudoc.org/>
92
93 * <http://www.jus.uio.no/sisu>
94
95
96 .SH COMMANDS SUMMARY
97
98 .SH DESCRIPTION
99
100
101 .BR
102
103 .B SiSU
104 is a document publishing system, that from a simple single marked-up document,
105 produces multiple output formats including:
106 .I plaintext,
107 .I HTML,
108 .I XHTML,
109 .I XML,
110 .I EPUB,
111 .I ODT
112 (
113 .I OpenDocument
114 (
115 .I ODF
116 ) text),
117 .I LaTeX,
118 .I PDF,
119 info, and
120 .I SQL
121 (
122 .I PostgreSQL
123 and
124 .I SQLite
125 ) , which share text object numbers ("object citation numbering") and the same
126 document structure information. For more see: <http://sisudoc.org> or
127 <http://www.jus.uio.no/sisu>
128 .SH DOCUMENT PROCESSING COMMAND FLAGS
129
130 .TP
131 .B -[0-9] [filename/wildcard]
132 see --act
133 .TP
134 .B --ao [filename/wildcard/url]
135 assumed for most other flags, creates new intermediate files for processing
136 (abstract objects, document abstraction) that is used in all subsequent
137 processing of other output. This step is assumed for most processing flags. To
138 skip it see -n. Alias -m.
139 .TP
140 .B --act[s0-9] [filename/wildcard]
141 --act0 to --act9 configurable shortcuts for multiple flags, -0 to -9 synonyms,
142 configure in sisurc.yml; sisu default action on a specified file where no flag
143 is provided is --act0; --act or --acts for information on current actions
144 ascribed to --act0 to --act9
145 .TP
146 .B --asciidoc [filename/wildcard]
147 asciidoc, smart text (not available)
148 .TP
149 .B -b [filename/wildcard]
150 see --xhtml
151 .TP
152 .B --by-*
153 see --output-by-*
154 .TP
155 .B -C
156 configure/initialise shared output directory files initialize shared output
157 directory (config files such as css and dtd files are not updated if they
158 already exist unless modifier is used). -C --init-site configure/initialise
159 site more extensive than -C on its own, shared output directory files/force
160 update, existing shared output config files such as css and dtd files are
161 updated if this modifier is used.
162 .TP
163 .B -c [filename/wildcard]
164 see --color-toggle
165 .TP
166 .B --color
167 see --color-on
168 .TP
169 .B --color-off
170 turn off color in output to terminal
171 .TP
172 .B --color-on
173 turn on color in output to terminal
174 .TP
175 .B --color-toggle [filename/wildcard]
176 screen toggle ansi screen colour on or off depending on default set (unless -c
177 flag is used: if sisurc colour default is set to 'true', output to screen will
178 be with colour, if sisurc colour default is set to 'false' or is undefined
179 screen output will be without colour). Alias -c
180 .TP
181 .B --configure
182 configure/initialise shared output directory files initialize shared output
183 directory (config files such as css and dtd files are not updated if they
184 already exist unless modifier is used). The equivalent of: -C --init-site
185 configure/initialise site, more extensive than -C on its own, shared output
186 directory files/force update, existing shared output config files such as css
187 and dtd files are updated if -CC is used.
188 .TP
189 .B --concordance [filename/wildcard]
190 produces concordance (wordmap) a rudimentary index of all the words in a
191 document. (Concordance files are not generated for documents of over 260,000
192 words unless this limit is increased in the file sisurc.yml). Alias -w
193 .TP
194 .B -d [filename/wildcard/url]
195 see --docbook
196 .TP
197 .B --dal [filename/wildcard/url]
198 (abstract objects, document abstraction renamed abstract objects in sisu5) see
199 --ao
200 .TP
201 .B --delete [filename/wildcard]
202 see --zap
203 .TP
204 .B --digests [filename/wildcard/url]
205 document digest or document content certificate ( DCC ) as sha digest tree of
206 the document: the digest for the document, and digests for each object
207 contained within the document (together with information on software versions
208 that produced it) (digest.txt). --digests -V for verbose digest output to
209 screen.
210 .TP
211 .B --docbook [filename/wildcard/url]
212 docbook xml
213 .TP
214 .B --dom [filename/wildcard/url]
215 see --xml-dom
216 .TP
217 .B --dump[=directory_path] [filename/wildcard]
218 places output in directory specified, if none is specified in the current
219 directory (pwd). Unlike using default settings
220 .I HTML
221 files have embedded css. Compare --redirect
222 .TP
223 .B -e [filename/wildcard]
224 see --epub
225 .TP
226 .B --epub [filename/wildcard]
227 produces an epub document, [sisu version >=2 ] (filename.epub). Alias -e
228 .TP
229 .B --errors-as-warnings
230 override stop processing on error. Alias --no-stop
231 .TP
232 .B --exc-*
233 exclude output feature, overrides configuration settings --exc-numbering, see
234 --exc-ocn; --exc-ocn, (exclude "object citation numbering", (switches off
235 object citation numbers), affects html (seg, scroll), epub, xhtml, xml, pdf) ;
236 --exc-toc, (exclude table of contents, affects html (scroll), epub, pdf) ;
237 --exc-links-to-manifest, --exc-manifest-links, (exclude links to manifest,
238 affects html (seg, scroll)); --exc-search-form, (exclude search form, affects
239 html (seg, scroll), manifest); --exc-minitoc, (exclude mini table of contents,
240 affects html (seg), concordance, manifest); --exc-manifest-minitoc, (exclude
241 mini table of contents, affects manifest); --exc-html-minitoc, (exclude mini
242 table of contents, affects html (seg), concordance); --exc-html-navigation,
243 (exclude navigation, affects html (seg)); --exc-html-navigation-bar, (exclude
244 navigation bar, affects html (seg)); --exc-html-search-form, (exclude search
245 form, affects html (seg, scroll)); --exc-html-right-pane, (exclude right
246 pane/column, affects html (seg, scroll)); --exc-html-top-band, (exclude top
247 band, affects html (seg, scroll), concordance (minitoc forced on to provide seg
248 navigation)); --exc-segsubtoc (exclude sub table of contents, affects html
249 (seg), epub) ; see also --inc-*
250 .TP
251 .B -F [--webserv=webrick]
252 see --sample-search-form
253 .TP
254 .B -f [optional string part of filename]
255 see --find
256 .TP
257 .B --fictionbook [filename/wildcard/url]
258 fictionbook xml (not available)
259 .TP
260 .B --find [optional string part of filename]
261 see --glob
262 .TP
263 .B -G [optional string part of filename]
264 see --glob
265 .TP
266 .B -g [filename/wildcard]
267 see --git
268 .TP
269 .B --git [filename/wildcard]
270 produces or updates markup source file structure in a git repo (experimental
271 and subject to change). Alias -g
272 .TP
273 .B --glob [optional string part of filename]
274 without match string, glob all .sst .ssm files in directory (including language
275 subdirectories). With match string, find files that match given string in
276 directory (including language subdirectories). Alias -G, -f, --find
277 .TP
278 .B -h [filename/wildcard]
279 see --html
280 .TP
281 .B --harvest *.ss[tm]
282 makes two lists of sisu output based on the sisu markup documents in a
283 directory: list of author and authors works (year and titles), and; list by
284 topic with titles and author. Makes use of header metadata fields (author,
285 title, date, topic_register). Can be used with maintenance (-M) and remote
286 placement (-R) flags.
287 .TP
288 .B --html [filename/wildcard]
289 produces html output, in two forms (i) segmented text with table of contents
290 (toc.html and index.html) and (ii) the document in a single file (scroll.html).
291 Alias -h
292 .TP
293 .B --html-scroll [filename/wildcard]
294 produces html output, the document in a single file (scroll.html) only. Compare
295 --html-seg and --html
296 .TP
297 .B --html-seg [filename/wildcard]
298 produces html output, segmented text with table of contents (toc.html and
299 index.html). Compare --html-scroll and --html
300 .TP
301 .B --html-strict [filename/wildcard]
302 produces html with --strict option. see --strict
303 .TP
304 .B -I [filename/wildcard]
305 see --texinfo
306 .TP
307 .B -i [filename/wildcard]
308 see --manpage
309 .TP
310 .B --i18n-*
311 these flags affect output by filetype and filename): --i18n-mono
312 (--monolingual) output filenames without language code for default language
313 ('en' or as set); --i18n-multi (--multilingual) language code provided as part
314 of the output filename, this is the default. Where output is in one language
315 only the language code may not be desired. see also --output-by-*
316 .TP
317 .B --inc-*
318 include output feature, overrides configuration settings, (usually the default
319 if none set), has precedence over --exc-* (exclude output feature). Some detail
320 provided under --exc-*, see --exc-*
321 .TP
322 .B -j [filename/wildcard]
323 copies images associated with a file for use by html, xhtml & xml outputs
324 (automatically invoked by --dump & redirect).
325 .TP
326 .B -k
327 see --color-off
328 .TP
329 .B --keep-processing-files [filename/wildcard/url]
330 see --maintenance
331 .TP
332 .B -M [filename/wildcard/url]
333 see --maintenance
334 .TP
335 .B -m [filename/wildcard/url]
336 see --dal (document abstraction level/layer)
337 .TP
338 .B --machine [filename/wildcard/url]
339 see --dal (document abstraction level/layer)
340 .TP
341 .B --maintenance [filename/wildcard/url]
342 maintenance mode, interim processing files are preserved and their locations
343 indicated. (also see -V). Aliases -M and --keep-processing-files.
344 .TP
345 .B --manifest [filename/wildcard]
346 produces an html summary of output generated (hyperlinked to content) and
347 document specific metadata (sisu_manifest.html). This step is assumed for most
348 processing flags.
349 .TP
350 .B --manpage [filename/wildcard]
351 produces man page of file, not suitable for all outputs. Alias -i
352 .TP
353 .B --markdown [filename/wildcard/url]
354 markdown smart text (not available)
355 .TP
356 .B --monolingual
357 see --i18n-*
358 .TP
359 .B --multilingual
360 see --i18n-*
361 .TP
362 .B -N [filename/wildcard/url]
363 see --digests
364 .TP
365 .B -n [filename/wildcard/url]
366 skip the creation of intermediate processing files (document abstraction) if
367 they already exist, this skips the equivalent of -m which is otherwise assumed
368 by most processing flags.
369 .TP
370 .B --no-*
371 see --exc-*
372 .TP
373 .B --no-stop
374 override stop processing on error. Alias --erros-as-warnings
375 .TP
376 .B --numbering
377 turn on "object citation numbers". See --inc-ocn and --exc-ocn
378 .TP
379 .B -o [filename/wildcard/url]
380 see --odt
381 .TP
382 .B --ocn
383 "object citation numbers". See --inc-ocn and --exc-ocn
384 .TP
385 .B --odf [filename/wildcard/url]
386 see --odt
387 .TP
388 .B --odt [filename/wildcard/url]
389 output basic document in opendocument file format (opendocument.odt). Alias -o
390 .TP
391 .B --output-by-*
392 select output directory structure from 3 alternatives: --output-by-language,
393 (language directory (based on language code) with filetype (html, epub, pdf
394 etc.) subdirectories); --output-by-filetype, (filetype directories with
395 language code as part of filename); --output-by-filename, (filename directories
396 with language code as part of filename). This is configurable. Alias --by-*
397 .TP
398 .B -P [language_directory/filename language_directory]
399 see --po4a
400 .TP
401 .B -p [filename/wildcard]
402 see --pdf
403 .TP
404 .B --papersize-(a4|a5|b5|letter|legal)
405 in conjunction with --pdf set pdf papersize, overriding any configuration
406 settings, to set more than one papersize repeat the option --pdf --papersize-a4
407 --papersize-letter. See also --papersize=*
408
409 .BR
410
411 .B --papersize=a4,a5,b5,letter,legal
412 in conjunction with --pdf set pdf papersize, overriding any configuration
413 settings, to set more than one papersize list after the equal sign with a comma
414 separator --papersize=a4,letter. See also --papersize-*
415 .TP
416 .B --pdf [filename/wildcard]
417 produces
418 .I LaTeX
419 pdf (portrait.pdf & landscape.pdf). Orientation and papersize may be set on the
420 command-line. Default paper size is set in config file, or document header, or
421 provided with additional command line parameter, e.g. --papersize-a4 preset
422 sizes include: 'A4', U.S. 'letter' and 'legal' and book sizes 'A5' and 'B5'
423 (system defaults to A4), and; --landscape or --portrait, so: e.g. "sisu
424 --pdf-a4 --pdf-letter --landscape --verbose [filename/wildcard]" or "sisu --pdf
425 --landscape --a4 --letter --verbose [filename/wildcard]". --pdf defaults to
426 both landscape & portrait output, and a4 if no other papersizes are configured.
427 Related options --pdf-landscape --pdf-portrait --pdf-papersize-*
428 --pdf-papersize=[list]. Alias -p
429 .TP
430 .B --pdf-l [filename/wildcard]
431 See --pdf-landscape
432 .TP
433 .B --pdf-landscape [filename/wildcard]
434 sets orientation, produces
435 .I LaTeX
436 pdf landscape.pdf. Default paper size is set in config file, or document
437 header, or provided with additional command line parameter, e.g. --papersize-a4
438 preset sizes include: 'A4', U.S. 'letter' and 'legal' and book sizes 'A5' and
439 'B5' (system defaults to A4). Related options --pdf --pdf-portrait. See also
440 --papersize-* or --papersize=[list]. Alias --pdf-l or in conjunction with --pdf
441 --landscape
442 .TP
443 .B --pdf-p [filename/wildcard]
444 See --pdf-portrait
445 .TP
446 .B --pdf-portrait [filename/wildcard]
447 sets orientation, produces
448 .I LaTeX
449 pdf portrait.pdf.pdf. Default paper size is set in config file, or document
450 header, or provided with additional command line parameter, e.g. --papersize-a4
451 preset sizes include: 'A4', U.S. 'letter' and 'legal' and book sizes 'A5' and
452 'B5' (system defaults to A4). Related options --pdf --pdf-landscape. See also
453 --papersize-* or --papersize=[list]. Alias --pdf-p or in conjunction with --pdf
454 --portrait
455 .TP
456 .B --pg-[instruction] [filename]
457 database
458 .I PostgreSQL
459 ( --pgsql may be used instead) possible instructions, include: --pg-createdb;
460 --pg-create; --pg-dropall; --pg-import [filename]; --pg-update [filename];
461 --pg-remove [filename]; see database section below.
462 .TP
463 .B --po [language_directory/filename language_directory]
464 see --po4a
465 .TP
466 .B --po4a [language_directory/filename language_directory]
467 produces .pot and po files for the file in the languages specified by the
468 language directory.
469 .B SiSU
470 markup is placed in subdirectories named with the language code, e.g. en/ fr/
471 es/. The sisu config file must set the output directory structure to
472 multilingual. v3, experimental
473 .TP
474 .B -Q [filename/wildcard]
475 see --qrcode
476 .TP
477 .B -q [filename/wildcard]
478 see --quiet
479 .TP
480 .B --qrcode [filename/wildcard]
481 generate QR code image of metadata (used in manifest).
482 .TP
483 .B --quiet [filename/wildcard]
484 quiet less output to screen.
485 .TP
486 .B -R [filename/wildcard]
487 see --rsync
488 .TP
489 .B -r [filename/wildcard]
490 see --scp
491 .TP
492 .B --redirect[=directory_path] [filename/wildcard]
493 places output in subdirectory under specified directory, subdirectory uses the
494 filename (without the suffix). If no output directory is specified places the
495 subdirectory under the current directory (pwd). Unlike using default settings
496 .I HTML
497 files have embedded css. Compare --dump
498 .TP
499 .B --rst [filename/wildcard/url]
500 ReST (rST restructured text) smart text (not available)
501 .TP
502 .B --rsync [filename/wildcard]
503 copies sisu output files to remote host using rsync. This requires that
504 sisurc.yml has been provided with information on hostname and username, and
505 that you have your "keys" and ssh agent in place. Note the behavior of rsync
506 different if -R is used with other flags from if used alone. Alone the rsync
507 --delete parameter is sent, useful for cleaning the remote directory (when -R
508 is used together with other flags, it is not). Also see --scp. Alias -R
509 .TP
510 .B -S
511 see --sisupod
512 .TP
513 .B -S [filename/wildcard]
514 see --sisupod
515 .TP
516 .B -s [filename/wildcard]
517 see --source
518 .TP
519 .B --sample-search-form [--db-(pg|sqlite)]
520 generate examples of (naive) cgi search form for
521 .I SQLite
522 or PgSQL depends on your already having used sisu to populate an
523 .I SQLite
524 or PgSQL database, (the
525 .I SQLite
526 version scans the output directories for existing sisu_sqlite databases, so it
527 is first necessary to create them, before generating the search form) see
528 --sqlite & --pg and the database section below. Optional additional parameters:
529 --db-user='www-data'. The samples are dumped in the present work directory
530 which must be writable, (with screen instructions given that they be copied to
531 the cgi-bin directory). Alias -F
532 .TP
533 .B --sax [filename/wildcard/url]
534 see --xml-sax
535 .TP
536 .B --scp [filename/wildcard]
537 copies sisu output files to remote host using scp. This requires that
538 sisurc.yml has been provided with information on hostname and username, and
539 that you have your "keys" and ssh agent in place. Also see --rsync. Alias -r
540 .TP
541 .B --sha256
542 set hash digest where used to sha256
543 .TP
544 .B --sha512
545 set hash digest where used to sha512
546 .TP
547 .B --sqlite-[instruction] [filename]
548 database type set to
549 .I SQLite,
550 this produces one of two possible databases, without additional database
551 related instructions it produces a discreet
552 .I SQLite
553 file for the document processed; with additional instructions it produces a
554 common
555 .I SQLite
556 database of all processed documents that (come from the same document
557 preparation directory and as a result) share the same output directory base
558 path (possible instructions include: --sqlite-createdb; --sqlite-create;
559 --sqlite-dropall; --sqlite-import [filename]; --sqlite-update [filename];
560 --sqlite-remove [filename]); see database section below.
561 .TP
562 .B --sisupod
563 produces a sisupod a zipped sisu directory of markup files including sisu
564 markup source files and the directories local configuration file, images and
565 skins. Note: this only includes the configuration files or skins contained in
566 ./_sisu not those in ~/.sisu -S [filename/wildcard] option. Note: (this option
567 is tested only with zsh). Alias -S
568 .TP
569 .B --sisupod [filename/wildcard]
570 produces a zipped file of the prepared document specified along with associated
571 images, by default named sisupod.zip they may alternatively be named with the
572 filename extension .ssp This provides a quick way of gathering the relevant
573 parts of a sisu document which can then for example be emailed. A sisupod
574 includes sisu markup source file, (along with associated documents if a master
575 file, or available in multilingual versions), together with related images and
576 skin.
577 .B SiSU
578 commands can be run directly against a sisupod contained in a local directory,
579 or provided as a url on a remote site. As there is a security issue with skins
580 provided by other users, they are not applied unless the flag --trust or
581 --trusted is added to the command instruction, it is recommended that file that
582 are not your own are treated as untrusted. The directory structure of the
583 unzipped file is understood by sisu, and sisu commands can be run within it.
584 Note: if you wish to send multiple files, it quickly becomes more space
585 efficient to zip the sisu markup directory, rather than the individual files
586 for sending). See the -S option without [filename/wildcard]. Alias -S
587 .TP
588 .B --source [filename/wildcard]
589 copies sisu markup file to output directory. Alias -s
590 .TP
591 .B --strict
592 together with --html, produces more w3c compliant html, for example not having
593 purely numeric identifiers for text, the location object url#33 becomes url#o33
594 .TP
595 .B -T [filename/wildcard (*.termsheet.rb)]
596 standard form document builder, preprocessing feature
597 .TP
598 .B -t [filename/wildcard]
599 see --txt
600 .TP
601 .B --texinfo [filename/wildcard]
602 produces texinfo and info file, (view with pinfo). Alias -I
603 .TP
604 .B --textile [filename/wildcard/url]
605 textile smart text (not available)
606 .TP
607 .B --txt [filename/wildcard]
608 produces
609 .I plaintext
610 with Unix linefeeds and without markup, (object numbers are omitted), has
611 footnotes at end of each paragraph that contains them [ -A for equivalent dos
612 (linefeed) output file] [see -e for endnotes]. (Options include: --endnotes for
613 endnotes --footnotes for footnotes at the end of each paragraph --unix for unix
614 linefeed (default) --msdos for msdos linefeed). Alias -t
615 .TP
616 .B --txt-asciidoc [filename/wildcard]
617 see --asciidoc
618 .TP
619 .B --txt-markdown [filename/wildcard]
620 see --markdown
621 .TP
622 .B --txt-rst [filename/wildcard]
623 see --rst
624 .TP
625 .B --txt-textile [filename/wildcard]
626 see --textile
627 .TP
628 .B -U [filename/wildcard]
629 see --urls
630 .TP
631 .B -u [filename/wildcard]
632 provides url mapping of output files for the flags requested for processing,
633 also see -U
634 .TP
635 .B --urls [filename/wildcard]
636 prints url output list/map for the available processing flags options and
637 resulting files that could be requested, (can be used to get a list of
638 processing options in relation to a file, together with information on the
639 output that would be produced), -u provides url output mapping for those flags
640 requested for processing. The default assumes sisu_webrick is running and
641 provides webrick url mappings where appropriate, but these can be switched to
642 file system paths in sisurc.yml. Alias -U
643 .TP
644 .B -V
645 on its own, provides
646 .B SiSU
647 version and environment information (sisu --help env)
648 .TP
649 .B -V [filename/wildcard]
650 even more verbose than the -v flag.
651 .TP
652 .B -v
653 on its own, provides
654 .B SiSU
655 version information
656 .TP
657 .B -v [filename/wildcard]
658 see --verbose
659 .TP
660 .B --verbose [filename/wildcard]
661 provides verbose output of what is being generated, where output is placed (and
662 error messages if any), as with -u flag provides a url mapping of files created
663 for each of the processing flag requests. Alias -v
664 .TP
665 .B --very-verbose [filename/wildcard]
666 provides more verbose output of what is being generated. See --verbose. Alias
667 -V
668 .TP
669 .B --version
670 sisu version
671 .TP
672 .B -W
673 see --webrick
674 .TP
675 .B -w [filename/wildcard]
676 see --concordance
677 .TP
678 .B --webrick
679 starts ruby' s webrick webserver points at sisu output directories, the default
680 port is set to 8081 and can be changed in the resource configuration files.
681 [tip: the webrick server requires link suffixes, so html output should be
682 created using the -h option rather than -H ; also, note -F webrick ]. Alias -W
683 .TP
684 .B --wordmap [filename/wildcard]
685 see --concordance
686 .TP
687 .B --xhtml [filename/wildcard]
688 produces xhtml/
689 .I XML
690 output for browser viewing (sax parsing). Alias -b
691 .TP
692 .B --xml-dom [filename/wildcard]
693 produces
694 .I XML
695 output with deep document structure, in the nature of dom. Alias -X
696 .TP
697 .B --xml-sax [filename/wildcard]
698 produces
699 .I XML
700 output shallow structure (sax parsing). Alias -x
701 .TP
702 .B -X [filename/wildcard]
703 see --xml-dom
704 .TP
705 .B -x [filename/wildcard]
706 see --xml-sax
707 .TP
708 .B -Y [filename/wildcard]
709 produces a short sitemap entry for the document, based on html output and the
710 sisu_manifest. --sitemaps generates/updates the sitemap index of existing
711 sitemaps. (Experimental, [g,y,m announcement this week])
712 .TP
713 .B -y [filename/wildcard]
714 see --manifest
715 .TP
716 .B -Z [filename/wildcard]
717 see --zap
718 .TP
719 .B --zap [filename/wildcard]
720 Zap, if used with other processing flags deletes output files of the type about
721 to be processed, prior to processing. If -Z is used as the lone processing
722 related flag (or in conjunction with a combination of -[mMvVq]), will remove
723 the related document output directory. Alias -Z
724 .SH COMMAND LINE MODIFIERS
725
726 .TP
727 .B --no-ocn
728 [with --html --pdf or --epub] switches off
729 .I object citation numbering.
730 Produce output without identifying numbers in margins of html or
731 .I LaTeX
732 /pdf output.
733 .TP
734 .B --no-annotate
735 strips output text of editor endnotes[^*1] denoted by asterisk or dagger/plus
736 sign
737 .TP
738 .B --no-asterisk
739 strips output text of editor endnotes[^*2] denoted by asterisk sign
740 .TP
741 .B --no-dagger
742 strips output text of editor endnotes[^+1] denoted by dagger/plus sign
743 .SH DATABASE COMMANDS
744
745
746 .BR
747
748 .B dbi - database interface
749
750 .BR
751
752 .B --pg or --pgsql
753 set for
754 .I PostgreSQL
755 .B --sqlite
756 default set for
757 .I SQLite
758 -d is modifiable with --db=[database type (PgSQL or
759 .I SQLite
760 ) ]
761 .TP
762 .B --pg -v --createall
763 initial step, creates required relations (tables, indexes) in existing
764 .I PostgreSQL
765 database (a database should be created manually and given the same name as
766 working directory, as requested) (rb.dbi) [ -dv --createall
767 .I SQLite
768 equivalent] it may be necessary to run sisu -Dv --createdb initially NOTE: at
769 the present time for
770 .I PostgreSQL
771 it may be necessary to manually create the database. The command would be
772 'createdb [database name]' where database name would be SiSU_[present working
773 directory name (without path)]. Please use only alphanumerics and underscores.
774 .TP
775 .B --pg -v --import
776 [filename/wildcard] imports data specified to
777 .I PostgreSQL
778 db (rb.dbi) [ -dv --import
779 .I SQLite
780 equivalent]
781 .TP
782 .B --pg -v --update
783 [filename/wildcard] updates/imports specified data to
784 .I PostgreSQL
785 db (rb.dbi) [ -dv --update
786 .I SQLite
787 equivalent]
788 .TP
789 .B --pg --remove
790 [filename/wildcard] removes specified data to
791 .I PostgreSQL
792 db (rb.dbi) [ -d --remove
793 .I SQLite
794 equivalent]
795 .TP
796 .B --pg --dropall
797 kills data" and drops (
798 .I PostgreSQL
799 or
800 .I SQLite
801 ) db, tables & indexes [ -d --dropall
802 .I SQLite
803 equivalent]
804
805 .BR
806 The -v is for verbose output.
807 .SH COMMAND LINE WITH FLAGS - BATCH PROCESSING
808
809
810 .BR
811 In the data directory run sisu -mh filename or wildcard eg. "sisu -h cisg.sst"
812 or "sisu -h *.{sst,ssm}" to produce html version of all documents.
813
814 .BR
815 Running sisu (alone without any flags, filenames or wildcards) brings up the
816 interactive help, as does any sisu command that is not recognised. Enter to
817 escape.
818 .SH HELP
819
820 .SH SISU MANUAL
821
822
823 .BR
824 The most up to date information on sisu should be contained in the sisu_manual,
825 available at:
826
827 .BR
828 <http://sisudoc.org/sisu/sisu_manual/>
829
830 .BR
831 The manual can be generated from source, found respectively, either within the
832 .B SiSU
833 tarball or installed locally at:
834
835 .BR
836 ./data/doc/sisu/markup-samples/sisu_manual
837
838 .BR
839 /usr/share/doc/sisu/markup-samples/sisu_manual
840
841 .BR
842 move to the respective directory and type e.g.:
843
844 .BR
845 sisu sisu_manual.ssm
846 .SH SISU MAN PAGES
847
848
849 .BR
850 If
851 .B SiSU
852 is installed on your system usual man commands should be available, try:
853
854 .BR
855 man sisu
856
857 .BR
858 Most
859 .B SiSU
860 man pages are generated directly from sisu documents that are used to prepare
861 the sisu manual, the sources files for which are located within the
862 .B SiSU
863 tarball at:
864
865 .BR
866 ./data/doc/sisu/markup-samples/sisu_manual
867
868 .BR
869 Once installed, directory equivalent to:
870
871 .BR
872 /usr/share/doc/sisu/markup-samples/sisu_manual
873
874 .BR
875 Available man pages are converted back to html using man2html:
876
877 .BR
878 /usr/share/doc/sisu/html/
879
880 .BR
881 ./data/doc/sisu/html
882
883 .BR
884 An online version of the sisu man page is available here:
885
886 .BR
887 * various sisu man pages <http://www.jus.uio.no/sisu/man/> [^1]
888
889 .BR
890 * sisu.1 <http://www.jus.uio.no/sisu/man/sisu.1.html> [^2]
891 .SH SISU BUILT-IN INTERACTIVE HELP, [DISCONTINUED]
892
893
894 .BR
895 This fell out of date and has been discontinued.
896 .SH INTRODUCTION TO SISU MARKUP[^3]
897
898 .SH SUMMARY
899
900
901 .BR
902
903 .B SiSU
904 source documents are
905 .I plaintext
906 (
907 .I UTF-8
908 )[^4] files
909
910 .BR
911 All paragraphs are separated by an empty line.
912
913 .BR
914 Markup is comprised of:
915
916 .BR
917 * at the top of a document, the document header made up of semantic meta-data
918 about the document and if desired additional processing instructions (such an
919 instruction to automatically number headings from a particular level down)
920
921 .BR
922 * followed by the prepared substantive text of which the most important single
923 characteristic is the markup of different heading levels, which define the
924 primary outline of the document structure. Markup of substantive text includes:
925
926 .BR
927 * heading levels defines document structure
928
929 .BR
930 * text basic attributes, italics, bold etc.
931
932 .BR
933 * grouped text (objects), which are to be treated differently, such as code
934 blocks or poems.
935
936 .BR
937 * footnotes/endnotes
938
939 .BR
940 * linked text and images
941
942 .BR
943 * paragraph actions, such as indent, bulleted, numbered-lists, etc.
944 .SH MARKUP RULES, DOCUMENT STRUCTURE AND METADATA REQUIREMENTS
945
946
947 .BR
948 minimal content/structure requirement:
949
950 .BR
951 [metadata]
952 .nf
953 A~ (level A [title])
954
955 1~ (at least one level 1 [segment/(chapter)])
956 .fi
957
958
959 .BR
960 structure rules (document heirarchy, heading levels):
961
962 .BR
963 there are two sets of heading levels ABCD (title & parts if any) and 123
964 (segment & subsegments if any)
965
966 .BR
967 sisu has the fllowing levels:
968 .nf
969 A~ [title] .
970 required (== 1) followed by B~ or 1~
971 B~ [part] *
972 followed by C~ or 1~
973 C~ [subpart] *
974 followed by D~ or 1~
975 D~ [subsubpart] *
976 followed by 1~
977 1~ [segment (chapter)] +
978 required (>= 1) followed by text or 2~
979 text *
980 followed by more text or 1~, 2~
981 or relevant part *()
982 2~ [subsegment] *
983 followed by text or 3~
984 text *
985 followed by more text or 1~, 2~ or 3~
986 or relevant part, see *()
987 3~ [subsubsegment] *
988 followed by text
989 text *
990 followed by more text or 1~, 2~ or 3~ or relevant part, see *()
991
992 *(B~ if none other used;
993 if C~ is last used: C~ or B~;
994 if D~ is used: D~, C~ or B~)
995 .fi
996
997 .nf
998 * level A~ is the tile and is mandatory
999 * there can only be one level A~
1000 * heading levels BCD, are optional and there may be several of each
1001 (where all three are used corresponding to e.g. Book Part Section)
1002 * sublevels that are used must follow each other sequentially
1003 (alphabetically),
1004 * heading levels A~ B~ C~ D~ are followed by other heading levels rather
1005 than substantive text
1006 which may be the subsequent sequential (alphabetic) heading part level
1007 or a heading (segment) level 1~
1008 * there must be at least one heading (segment) level 1~
1009 (the level on which the text is segmented, in a book would correspond
1010 to the Chapter level)
1011 * additional heading levels 1~ 2~ 3~ are optional and there may be several
1012 of each
1013 * heading levels 1~ 2~ 3~ are followed by text (which may be followed by
1014 the same heading level)
1015 and/or the next lower numeric heading level (followed by text)
1016 or indeed return to the relevant part level
1017 (as a corollary to the rules above substantive text/ content
1018 must be preceded by a level 1~ (2~ or 3~) heading)
1019 .fi
1020
1021 .SH MARKUP EXAMPLES
1022
1023 .SH ONLINE
1024
1025
1026 .BR
1027 Online markup examples are available together with the respective outputs
1028 produced from <http://www.jus.uio.no/sisu/SiSU/examples.html> or from
1029 <http://www.jus.uio.no/sisu/sisu_examples/>
1030
1031 .BR
1032 There is of course this document, which provides a cursory overview of sisu
1033 markup and the respective output produced:
1034 <http://www.jus.uio.no/sisu/sisu_markup/>
1035
1036 .BR
1037 an alternative presentation of markup syntax:
1038 /usr/share/doc/sisu/on_markup.txt.gz
1039 .SH INSTALLED
1040
1041
1042 .BR
1043 With
1044 .B SiSU
1045 installed sample skins may be found in: /usr/share/doc/sisu/markup-samples (or
1046 equivalent directory) and if sisu -markup-samples is installed also under:
1047 /usr/share/doc/sisu/markup-samples-non-free
1048 .SH MARKUP OF HEADERS
1049
1050
1051 .BR
1052 Headers contain either: semantic meta-data about a document, which can be used
1053 by any output module of the program, or; processing instructions.
1054
1055 .BR
1056 Note: the first line of a document may include information on the markup
1057 version used in the form of a comment. Comments are a percentage mark at the
1058 start of a paragraph (and as the first character in a line of text) followed by
1059 a space and the comment:
1060 .nf
1061 % this would be a comment
1062 .fi
1063
1064 .SH SAMPLE HEADER
1065
1066
1067 .BR
1068 This current document is loaded by a master document that has a header similar
1069 to this one:
1070 .nf
1071 % SiSU master 4.0
1072
1073 @title: SiSU
1074 :subtitle: Manual
1075
1076 @creator:
1077 :author: Amissah, Ralph
1078
1079 @publisher: [publisher name]
1080
1081 @rights: Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL 3
1082
1083 @classify:
1084 :topic_register: SiSU:manual;electronic documents:SiSU:manual
1085 :subject: ebook, epublishing, electronic book, electronic publishing,
1086 electronic document, electronic citation, data structure,
1087 citation systems, search
1088
1089 % used_by: manual
1090
1091 @date:
1092 :published: 2008-05-22
1093 :created: 2002-08-28
1094 :issued: 2002-08-28
1095 :available: 2002-08-28
1096 :modified: 2010-03-03
1097
1098 @make:
1099 :num_top: 1
1100 :breaks: new=C; break=1
1101 :bold: /Gnu|Debian|Ruby|SiSU/
1102 :home_button_text: {SiSU}http://sisudoc.org; {git}http://git.sisudoc.org
1103 :footer: {SiSU}http://sisudoc.org; {git}http://git.sisudoc.org
1104 :manpage: name=sisu - documents: markup, structuring, publishing in multiple standard formats, and search;
1105 synopsis=sisu [-abcDdeFhIiMmNnopqRrSsTtUuVvwXxYyZz0-9] [filename/wildcard ]
1106 . sisu [-Ddcv] [instruction]
1107 . sisu [-CcFLSVvW]
1108
1109 @links:
1110 { SiSU Homepage }http://www.sisudoc.org/
1111 { SiSU Manual }http://www.sisudoc.org/sisu/sisu_manual/
1112 { Book Samples & Markup Examples }http://www.jus.uio.no/sisu/SiSU/examples.html
1113 { SiSU Download }http://www.jus.uio.no/sisu/SiSU/download.html
1114 { SiSU Changelog }http://www.jus.uio.no/sisu/SiSU/changelog.html
1115 { SiSU Git repo }http://git.sisudoc.org/gitweb/?p=code/sisu.git;a=summary
1116 { SiSU List Archives }http://lists.sisudoc.org/pipermail/sisu/
1117 { SiSU @ Debian }http://packages.qa.debian.org/s/sisu.html
1118 { SiSU Project @ Debian }http://qa.debian.org/developer.php?login=sisu@lists.sisudoc.org
1119 { SiSU @ Wikipedia }http://en.wikipedia.org/wiki/SiSU
1120 .fi
1121
1122 .SH AVAILABLE HEADERS
1123
1124
1125 .BR
1126 Header tags appear at the beginning of a document and provide meta information
1127 on the document (such as the
1128 .I Dublin Core
1129 ) , or information as to how the document as a whole is to be processed. All
1130 header instructions take the form @headername: or on the next line and indented
1131 by once space :subheadername: All
1132 .I Dublin Core
1133 meta tags are available
1134
1135 .BR
1136
1137 .B @identifier:
1138 information or instructions
1139
1140 .BR
1141 where the "identifier" is a tag recognised by the program, and the
1142 "information" or "instructions" belong to the tag/identifier specified
1143
1144 .BR
1145 Note: a header where used should only be used once; all headers apart from
1146 @title: are optional; the @structure: header is used to describe document
1147 structure, and can be useful to know.
1148
1149 .BR
1150 This is a sample header
1151 .nf
1152 % SiSU 2.0 [declared file-type identifier with markup version]
1153 .fi
1154
1155 .nf
1156 @title: [title text] [this header is the only one that is mandatory]
1157 :subtitle: [subtitle if any]
1158 :language: English
1159 .fi
1160
1161 .nf
1162 @creator:
1163 :author: [Lastname, First names]
1164 :illustrator: [Lastname, First names]
1165 :translator: [Lastname, First names]
1166 :prepared_by: [Lastname, First names]
1167 .fi
1168
1169 .nf
1170 @date:
1171 :published: [year or yyyy-mm-dd]
1172 :created: [year or yyyy-mm-dd]
1173 :issued: [year or yyyy-mm-dd]
1174 :available: [year or yyyy-mm-dd]
1175 :modified: [year or yyyy-mm-dd]
1176 :valid: [year or yyyy-mm-dd]
1177 :added_to_site: [year or yyyy-mm-dd]
1178 :translated: [year or yyyy-mm-dd]
1179 .fi
1180
1181 .nf
1182 @rights:
1183 :copyright: Copyright (C) [Year and Holder]
1184 :license: [Use License granted]
1185 :text: [Year and Holder]
1186 :translation: [Name, Year]
1187 :illustrations: [Name, Year]
1188 .fi
1189
1190 .nf
1191 @classify:
1192 :topic_register: SiSU:markup sample:book;book:novel:fantasy
1193 :type:
1194 :subject:
1195 :description:
1196 :keywords:
1197 :abstract:
1198 :loc: [Library of Congress classification]
1199 :dewey: [Dewey classification
1200 .fi
1201
1202 .nf
1203 @identify:
1204 :isbn: [ISBN]
1205 :oclc:
1206 .fi
1207
1208 .nf
1209 @links: { SiSU }http://www.sisudoc.org
1210 { FSF }http://www.fsf.org
1211 .fi
1212
1213 .nf
1214 @make:
1215 :num_top: 1
1216 :headings: [text to match for each level
1217 (e.g. PART; Chapter; Section; Article; or another: none; BOOK|FIRST|SECOND; none; CHAPTER;)
1218 :breaks: new=:C; break=1
1219 :promo: sisu, ruby, sisu_search_libre, open_society
1220 :bold: [regular expression of words/phrases to be made bold]
1221 :italics: [regular expression of words/phrases to italicise]
1222 :home_button_text: {SiSU}http://sisudoc.org; {git}http://git.sisudoc.org
1223 :footer: {SiSU}http://sisudoc.org; {git}http://git.sisudoc.org
1224 .fi
1225
1226 .nf
1227 @original:
1228 :language: [language]
1229 .fi
1230
1231 .nf
1232 @notes:
1233 :comment:
1234 :prefix: [prefix is placed just after table of contents]
1235 .fi
1236
1237 .SH MARKUP OF SUBSTANTIVE TEXT
1238
1239 .SH HEADING LEVELS
1240
1241
1242 .BR
1243 Heading levels are :A~ ,:B~ ,:C~ ,1~ ,2~ ,3~ ... :A - :C being part / section
1244 headings, followed by other heading levels, and 1 -6 being headings followed by
1245 substantive text or sub-headings. :A~ usually the title :A~? conditional level
1246 1 heading (used where a stand-alone document may be imported into another)
1247
1248 .BR
1249
1250 .B :A~ [heading text]
1251 Top level heading [this usually has similar content to the title @title: ]
1252 NOTE: the heading levels described here are in 0.38 notation, see heading
1253
1254 .BR
1255
1256 .B :B~ [heading text]
1257 Second level heading [this is a heading level divider]
1258
1259 .BR
1260
1261 .B :C~ [heading text]
1262 Third level heading [this is a heading level divider]
1263
1264 .BR
1265
1266 .B 1~ [heading text]
1267 Top level heading preceding substantive text of document or sub-heading 2, the
1268 heading level that would normally be marked 1. or 2. or 3. etc. in a document,
1269 and the level on which sisu by default would break html output into named
1270 segments, names are provided automatically if none are given (a number),
1271 otherwise takes the form 1~my_filename_for_this_segment
1272
1273 .BR
1274
1275 .B 2~ [heading text]
1276 Second level heading preceding substantive text of document or sub-heading 3 ,
1277 the heading level that would normally be marked 1.1 or 1.2 or 1.3 or 2.1 etc.
1278 in a document.
1279
1280 .BR
1281
1282 .B 3~ [heading text]
1283 Third level heading preceding substantive text of document, that would normally
1284 be marked 1.1.1 or 1.1.2 or 1.2.1 or 2.1.1 etc. in a document
1285 .nf
1286 1~filename level 1 heading,
1287
1288 % the primary division such as Chapter that is followed by substantive text, and may be further subdivided (this is the level on which by default html segments are made)
1289 .fi
1290
1291 .SH FONT ATTRIBUTES
1292
1293
1294 .BR
1295
1296 .B markup example:
1297 .nf
1298 normal text, *{emphasis}*, !{bold text}!, /{italics}/, _{underscore}_, "{citation}",
1299 ^{superscript}^, ,{subscript},, +{inserted text}+, -{strikethrough}-, #{monospace}#
1300
1301 normal text
1302
1303 *{emphasis}* [note: can be configured to be represented by bold, italics or underscore]
1304
1305 !{bold text}!
1306
1307 /{italics}/
1308
1309 _{underscore}_
1310
1311 "{citation}"
1312
1313 ^{superscript}^
1314
1315 ,{subscript},
1316
1317 +{inserted text}+
1318
1319 -{strikethrough}-
1320
1321 #{monospace}#
1322 .fi
1323
1324
1325 .BR
1326
1327 .B resulting output:
1328
1329 .BR
1330 normal text,
1331 .B emphasis,
1332 .B bold text
1333 ,
1334 .I italics,
1335 .I underscore,
1336 "citation", ^superscript^, [subscript], ++inserted text++, --strikethrough--,
1337 monospace
1338
1339 .BR
1340 normal text
1341
1342 .BR
1343
1344 .B emphasis
1345 [note: can be configured to be represented by bold, italics or underscore]
1346
1347 .BR
1348
1349 .B bold text
1350
1351 .BR
1352
1353 .I italics
1354
1355 .BR
1356 .I underscore
1357
1358 .BR
1359 "citation"
1360
1361 .BR
1362 ^superscript^
1363
1364 .BR
1365 [subscript]
1366
1367 .BR
1368 ++inserted text++
1369
1370 .BR
1371 --strikethrough--
1372
1373 .BR
1374 monospace
1375 .SH INDENTATION AND BULLETS
1376
1377
1378 .BR
1379
1380 .B markup example:
1381 .nf
1382 ordinary paragraph
1383
1384 _1 indent paragraph one step
1385
1386 _2 indent paragraph two steps
1387
1388 _9 indent paragraph nine steps
1389 .fi
1390
1391
1392 .BR
1393
1394 .B resulting output:
1395
1396 .BR
1397 ordinary paragraph
1398
1399 .BR
1400 indent paragraph one step
1401
1402 .BR
1403 indent paragraph two steps
1404
1405 .BR
1406 indent paragraph nine steps
1407
1408 .BR
1409
1410 .B markup example:
1411 .nf
1412 _* bullet text
1413
1414 _1* bullet text, first indent
1415
1416 _2* bullet text, two step indent
1417 .fi
1418
1419
1420 .BR
1421
1422 .B resulting output:
1423
1424 .BR
1425 * bullet text
1426
1427 .BR
1428 * bullet text, first indent
1429
1430 .BR
1431 * bullet text, two step indent
1432
1433 .BR
1434 Numbered List (not to be confused with headings/titles, (document structure))
1435
1436 .BR
1437
1438 .B markup example:
1439 .nf
1440 # numbered list numbered list 1., 2., 3, etc.
1441
1442 _# numbered list numbered list indented a., b., c., d., etc.
1443 .fi
1444
1445 .SH HANGING INDENTS
1446
1447
1448 .BR
1449
1450 .B markup example:
1451 .nf
1452 _0_1 first line no indent,
1453 rest of paragraph indented one step
1454
1455 _1_0 first line indented,
1456 rest of paragraph no indent
1457
1458 in each case level may be 0-9
1459 .fi
1460
1461
1462 .BR
1463
1464 .B resulting output:
1465
1466 .BR
1467 first line no indent, rest of paragraph indented one step; first line no
1468 indent, rest of paragraph indented one step; first line no indent, rest of
1469 paragraph indented one step; first line no indent, rest of paragraph indented
1470 one step; first line no indent, rest of paragraph indented one step; first
1471 line no indent, rest of paragraph indented one step; first line no indent,
1472 rest of paragraph indented one step; first line no indent, rest of paragraph
1473 indented one step; first line no indent, rest of paragraph indented one step;
1474
1475 .BR
1476 A regular paragraph.
1477
1478 .BR
1479 first line indented, rest of paragraph no indent first line indented, rest of
1480 paragraph no indent first line indented, rest of paragraph no indent first line
1481 indented, rest of paragraph no indent first line indented, rest of paragraph no
1482 indent first line indented, rest of paragraph no indent first line indented,
1483 rest of paragraph no indent first line indented, rest of paragraph no indent
1484 first line indented, rest of paragraph no indent first line indented, rest of
1485 paragraph no indent first line indented, rest of paragraph no indent
1486
1487 .BR
1488 in each case level may be 0-9
1489
1490 .BR
1491
1492 .B live-build
1493 A collection of scripts used to build customized
1494 .B Debian
1495 Livesystems.
1496 .I live-build
1497 was formerly known as live-helper, and even earlier known as live-package.
1498
1499 .BR
1500
1501 .B live-build
1502
1503 A collection of scripts used to build customized
1504 .B Debian
1505 Livesystems.
1506 .I live-build
1507 was formerly known as live-helper, and even earlier known as live-package.
1508 .SH FOOTNOTES / ENDNOTES
1509
1510
1511 .BR
1512 Footnotes and endnotes are marked up at the location where they would be
1513 indicated within a text. They are automatically numbered. The output type
1514 determines whether footnotes or endnotes will be produced
1515
1516 .BR
1517
1518 .B markup example:
1519 .nf
1520 ~{ a footnote or endnote }~
1521 .fi
1522
1523
1524 .BR
1525
1526 .B resulting output:
1527
1528 .BR
1529 [^5]
1530
1531 .BR
1532
1533 .B markup example:
1534 .nf
1535 normal text~{ self contained endnote marker & endnote in one }~ continues
1536 .fi
1537
1538
1539 .BR
1540
1541 .B resulting output:
1542
1543 .BR
1544 normal text[^6] continues
1545
1546 .BR
1547
1548 .B markup example:
1549 .nf
1550 normal text ~{* unnumbered asterisk footnote/endnote, insert multiple asterisks if required }~ continues
1551
1552 normal text ~{** another unnumbered asterisk footnote/endnote }~ continues
1553 .fi
1554
1555
1556 .BR
1557
1558 .B resulting output:
1559
1560 .BR
1561 normal text [^*] continues
1562
1563 .BR
1564 normal text [^**] continues
1565
1566 .BR
1567
1568 .B markup example:
1569 .nf
1570 normal text ~[* editors notes, numbered asterisk footnote/endnote series ]~ continues
1571
1572 normal text ~[+ editors notes, numbered plus symbol footnote/endnote series ]~ continues
1573 .fi
1574
1575
1576 .BR
1577
1578 .B resulting output:
1579
1580 .BR
1581 normal text [^*3] continues
1582
1583 .BR
1584 normal text [^+2] continues
1585
1586 .BR
1587
1588 .B Alternative endnote pair notation for footnotes/endnotes:
1589 .nf
1590 % note the endnote marker "~^"
1591
1592 normal text~^ continues
1593
1594 ^~ endnote text following the paragraph in which the marker occurs
1595 .fi
1596
1597
1598 .BR
1599 the standard and pair notation cannot be mixed in the same document
1600 .SH LINKS
1601
1602 .SH NAKED URLS WITHIN TEXT, DEALING WITH URLS
1603
1604
1605 .BR
1606 urls found within text are marked up automatically. A url within text is
1607 automatically hyperlinked to itself and by default decorated with angled
1608 braces, unless they are contained within a code block (in which case they are
1609 passed as normal text), or escaped by a preceding underscore (in which case the
1610 decoration is omitted).
1611
1612 .BR
1613
1614 .B markup example:
1615 .nf
1616 normal text http://www.sisudoc.org/ continues
1617 .fi
1618
1619
1620 .BR
1621
1622 .B resulting output:
1623
1624 .BR
1625 normal text <http://www.sisudoc.org/> continues
1626
1627 .BR
1628 An escaped url without decoration
1629
1630 .BR
1631
1632 .B markup example:
1633 .nf
1634 normal text _http://www.sisudoc.org/ continues
1635
1636 deb _http://www.jus.uio.no/sisu/archive unstable main non-free
1637 .fi
1638
1639
1640 .BR
1641
1642 .B resulting output:
1643
1644 .BR
1645 normal text <_http://www.sisudoc.org/> continues
1646
1647 .BR
1648 deb <_http://www.jus.uio.no/sisu/archive> unstable main non-free
1649
1650 .BR
1651 where a code block is used there is neither decoration nor hyperlinking, code
1652 blocks are discussed later in this document
1653
1654 .BR
1655
1656 .B resulting output:
1657 .nf
1658 deb http://www.jus.uio.no/sisu/archive unstable main non-free
1659 deb-src http://www.jus.uio.no/sisu/archive unstable main non-free
1660 .fi
1661
1662 .SH LINKING TEXT
1663
1664
1665 .BR
1666 To link text or an image to a url the markup is as follows
1667
1668 .BR
1669
1670 .B markup example:
1671 .nf
1672 about { SiSU }http://url.org markup
1673 .fi
1674
1675
1676 .BR
1677
1678 .B resulting output:
1679
1680 .BR
1681 aboutSiSU <http://www.sisudoc.org/> markup
1682
1683 .BR
1684 A shortcut notation is available so the url link may also be provided
1685 automatically as a footnote
1686
1687 .BR
1688
1689 .B markup example:
1690 .nf
1691 about {~^ SiSU }http://url.org markup
1692 .fi
1693
1694
1695 .BR
1696
1697 .B resulting output:
1698
1699 .BR
1700 aboutSiSU <http://www.sisudoc.org/> [^7] markup
1701
1702 .BR
1703 Internal document links to a tagged location, including an ocn
1704
1705 .BR
1706
1707 .B markup example:
1708 .nf
1709 about { text links }#link_text
1710 .fi
1711
1712
1713 .BR
1714
1715 .B resulting output:
1716
1717 .BR
1718 about ⌠text links⌡⌈link_text⌋
1719
1720 .BR
1721 Shared document collection link
1722
1723 .BR
1724
1725 .B markup example:
1726 .nf
1727 about { SiSU book markup examples }:SiSU/examples.html
1728 .fi
1729
1730
1731 .BR
1732
1733 .B resulting output:
1734
1735 .BR
1736 about ⌠
1737 .B SiSU
1738 book markup examples⌡⌈:SiSU/examples.html⌋
1739 .SH LINKING IMAGES
1740
1741
1742 .BR
1743
1744 .B markup example:
1745 .nf
1746 { tux.png 64x80 }image
1747
1748 % various url linked images
1749
1750 {tux.png 64x80 "a better way" }http://www.sisudoc.org/
1751
1752 {GnuDebianLinuxRubyBetterWay.png 100x101 "Way Better - with Gnu/Linux, Debian and Ruby" }http://www.sisudoc.org/
1753
1754 {~^ ruby_logo.png "Ruby" }http://www.ruby-lang.org/en/
1755 .fi
1756
1757
1758 .BR
1759
1760 .B resulting output:
1761
1762 .BR
1763 [ tux.png ]
1764
1765 .BR
1766 tux.png 64x80 "Gnu/Linux - a better way" <http://www.sisudoc.org/>
1767
1768 .BR
1769 GnuDebianLinuxRubyBetterWay.png 100x101 "Way Better - with Gnu/Linux, Debian
1770 and Ruby" <http://www.sisudoc.org/>
1771
1772 .BR
1773 ruby_logo.png 70x90 "Ruby" <http://www.ruby-lang.org/en/> [^8]
1774
1775 .BR
1776
1777 .B linked url footnote shortcut
1778 .nf
1779 {~^ [text to link] }http://url.org
1780
1781 % maps to: { [text to link] }http://url.org ~{ http://url.org }~
1782
1783 % which produces hyper-linked text within a document/paragraph, with an endnote providing the url for the text location used in the hyperlink
1784 .fi
1785
1786 .nf
1787 text marker *~name
1788 .fi
1789
1790
1791 .BR
1792 note at a heading level the same is automatically achieved by providing names
1793 to headings 1, 2 and 3 i.e. 2~[name] and 3~[name] or in the case of
1794 auto-heading numbering, without further intervention.
1795 .SH LINK SHORTCUT FOR MULTIPLE VERSIONS OF A SISU DOCUMENT IN THE SAME DIRECTORY
1796 TREE
1797
1798
1799 .BR
1800
1801 .B markup example:
1802 .nf
1803 !_ /{"Viral Spiral"}/, David Bollier
1804
1805 { "Viral Spiral", David Bollier [3sS]}viral_spiral.david_bollier.sst
1806 .fi
1807
1808
1809 .BR
1810
1811 .B
1812 .I "Viral Spiral",
1813 David Bollier
1814 "Viral Spiral", David Bollier <http://corundum/sisu_manual/en/manifest/viral_spiral.david_bollier.html>
1815 document manifest <http://corundum/sisu_manual/en/manifest/viral_spiral.david_bollier.html>
1816 ⌠html, segmented text⌡「http://corundum/sisu_manual/en/html/viral_spiral.david_bollier.html」
1817 ⌠html, scroll, document in one⌡「http://corundum/sisu_manual/en/html/viral_spiral.david_bollier.html」
1818 ⌠epub⌡「http://corundum/sisu_manual/en/epub/viral_spiral.david_bollier.epub」
1819 ⌠pdf, landscape⌡「http://corundum/sisu_manual/en/pdf/viral_spiral.david_bollier.pdf」
1820 ⌠pdf, portrait⌡「http://corundum/sisu_manual/en/pdf/viral_spiral.david_bollier.pdf」
1821 ⌠odf: odt, open document text⌡「http://corundum/sisu_manual/en/odt/viral_spiral.david_bollier.odt」
1822 ⌠xhtml scroll⌡「http://corundum/sisu_manual/en/xhtml/viral_spiral.david_bollier.xhtml」
1823 ⌠xml, sax⌡「http://corundum/sisu_manual/en/xml/viral_spiral.david_bollier.xml」
1824 ⌠xml, dom⌡「http://corundum/sisu_manual/en/xml/viral_spiral.david_bollier.xml」
1825 ⌠concordance⌡「http://corundum/sisu_manual/en/html/viral_spiral.david_bollier.html」
1826 ⌠dcc, document content certificate (digests)⌡「http://corundum/sisu_manual/en/digest/viral_spiral.david_bollier.txt」
1827 ⌠markup source text⌡「http://corundum/sisu_manual/en/src/viral_spiral.david_bollier.sst」
1828 ⌠markup source (zipped) pod⌡「http://corundum/sisu_manual/en/pod/viral_spiral.david_bollier.sst.zip」
1829
1830 .SH GROUPED TEXT / BLOCKED TEXT
1831
1832
1833 .BR
1834 There are two markup syntaxes for blocked text, using curly braces or using
1835 tics
1836 .SH BLOCKED TEXT CURLY BRACE SYNTAX
1837
1838
1839 .BR
1840 at the start of a line on its own use name of block type with an opening curly
1841 brace, follow with the content of the block, and close with a closing curly
1842 brace and the name of the block type, e.g.
1843 .nf
1844 code{
1845
1846 this is a code block
1847
1848 }code
1849 .fi
1850
1851 .nf
1852
1853 poem{
1854
1855 this here is a poem
1856
1857 }poem
1858 .fi
1859
1860 .SH BLOCKED TEXT TIC SYNTAX
1861
1862 .nf
1863 ``` code
1864 this is a code block
1865
1866 ```
1867
1868 ``` poem
1869 this here is a poem
1870
1871 ```
1872 .fi
1873
1874
1875 .BR
1876 start a line with three backtics, a space followed by the name of the name of
1877 block type, follow with the content of the block, and close with three back
1878 ticks on a line of their own, e.g.
1879 .SH TABLES
1880
1881
1882 .BR
1883 Tables may be prepared in two either of two forms
1884
1885 .BR
1886
1887 .B markup example:
1888 .nf
1889 table{ c3; 40; 30; 30;
1890
1891 This is a table
1892 this would become column two of row one
1893 column three of row one is here
1894
1895 And here begins another row
1896 column two of row two
1897 column three of row two, and so on
1898
1899 }table
1900 .fi
1901
1902
1903 .BR
1904
1905 .B resulting output:
1906 This is a table|this would become column two of row one|column three of row one is here』And here begins another row|column two of row two|column three of row two, and so on』
1907
1908
1909 .BR
1910 a second form may be easier to work with in cases where there is not much
1911 information in each column
1912
1913 .BR
1914
1915 .B markup example:
1916 [^9]
1917 .nf
1918 !_ Table 3.1: Contributors to Wikipedia, January 2001 - June 2005
1919
1920 {table~h 24; 12; 12; 12; 12; 12; 12;}
1921 |Jan. 2001|Jan. 2002|Jan. 2003|Jan. 2004|July 2004|June 2006
1922 Contributors* | 10| 472| 2,188| 9,653| 25,011| 48,721
1923 Active contributors** | 9| 212| 846| 3,228| 8,442| 16,945
1924 Very active contributors*** | 0| 31| 190| 692| 1,639| 3,016
1925 No. of English language articles| 25| 16,000| 101,000| 190,000| 320,000| 630,000
1926 No. of articles, all languages | 25| 19,000| 138,000| 490,000| 862,000|1,600,000
1927
1928 * Contributed at least ten times; ** at least 5 times in last month; *** more than 100 times in last month.
1929 .fi
1930
1931
1932 .BR
1933
1934 .B resulting output:
1935
1936 .BR
1937
1938 .B Table 3.1: Contributors to Wikipedia, January 2001 - June 2005
1939 |Jan. 2001|Jan. 2002|Jan. 2003|Jan. 2004|July 2004|June 2006』Contributors*|10|472|2,188|9,653|25,011|48,721』Active contributors**|9|212|846|3,228|8,442|16,945』Very active contributors***|0|31|190|692|1,639|3,016』No. of English language articles|25|16,000|101,000|190,000|320,000|630,000』No. of articles, all languages|25|19,000|138,000|490,000|862,000|1,600,000』
1940
1941
1942 .BR
1943 * Contributed at least ten times; ** at least 5 times in last month; *** more
1944 than 100 times in last month.
1945 .SH POEM
1946
1947
1948 .BR
1949
1950 .B basic markup:
1951 .nf
1952 poem{
1953
1954 Your poem here
1955
1956 }poem
1957
1958 Each verse in a poem is given an object number.
1959 .fi
1960
1961
1962 .BR
1963
1964 .B markup example:
1965 .nf
1966 poem{
1967
1968 `Fury said to a
1969 mouse, That he
1970 met in the
1971 house,
1972 "Let us
1973 both go to
1974 law: I will
1975 prosecute
1976 YOU. --Come,
1977 I'll take no
1978 denial; We
1979 must have a
1980 trial: For
1981 really this
1982 morning I've
1983 nothing
1984 to do."
1985 Said the
1986 mouse to the
1987 cur, "Such
1988 a trial,
1989 dear Sir,
1990 With
1991 no jury
1992 or judge,
1993 would be
1994 wasting
1995 our
1996 breath."
1997 "I'll be
1998 judge, I'll
1999 be jury,"
2000 Said
2001 cunning
2002 old Fury:
2003 "I'll
2004 try the
2005 whole
2006 cause,
2007 and
2008 condemn
2009 you
2010 to
2011 death."'
2012
2013 }poem
2014 .fi
2015
2016
2017 .BR
2018
2019 .B resulting output:
2020 `Fury said to a
2021 mouse, That he
2022 met in the
2023 house,
2024 "Let us
2025 both go to
2026 law: I will
2027 prosecute
2028 YOU. --Come,
2029 I'll take no
2030 denial; We
2031 must have a
2032 trial: For
2033 really this
2034 morning I've
2035 nothing
2036 to do."
2037 Said the
2038 mouse to the
2039 cur, "Such
2040 a trial,
2041 dear Sir,
2042 With
2043 no jury
2044 or judge,
2045 would be
2046 wasting
2047 our
2048 breath."
2049 "I'll be
2050 judge, I'll
2051 be jury,"
2052 Said
2053 cunning
2054 old Fury:
2055 "I'll
2056 try the
2057 whole
2058 cause,
2059 and
2060 condemn
2061 you
2062 to
2063 death."'
2064
2065
2066 .SH GROUP
2067
2068
2069 .BR
2070
2071 .B basic markup:
2072 .nf
2073 group{
2074
2075 Your grouped text here
2076
2077 }group
2078
2079 A group is treated as an object and given a single object number.
2080 .fi
2081
2082
2083 .BR
2084
2085 .B markup example:
2086 .nf
2087 group{
2088
2089 `Fury said to a
2090 mouse, That he
2091 met in the
2092 house,
2093 "Let us
2094 both go to
2095 law: I will
2096 prosecute
2097 YOU. --Come,
2098 I'll take no
2099 denial; We
2100 must have a
2101 trial: For
2102 really this
2103 morning I've
2104 nothing
2105 to do."
2106 Said the
2107 mouse to the
2108 cur, "Such
2109 a trial,
2110 dear Sir,
2111 With
2112 no jury
2113 or judge,
2114 would be
2115 wasting
2116 our
2117 breath."
2118 "I'll be
2119 judge, I'll
2120 be jury,"
2121 Said
2122 cunning
2123 old Fury:
2124 "I'll
2125 try the
2126 whole
2127 cause,
2128 and
2129 condemn
2130 you
2131 to
2132 death."'
2133
2134 }group
2135 .fi
2136
2137
2138 .BR
2139
2140 .B resulting output:
2141 `Fury said to a
2142 mouse, That he
2143 met in the
2144 house,
2145 "Let us
2146 both go to
2147 law: I will
2148 prosecute
2149 YOU. --Come,
2150 I'll take no
2151 denial; We
2152 must have a
2153 trial: For
2154 really this
2155 morning I've
2156 nothing
2157 to do."
2158 Said the
2159 mouse to the
2160 cur, "Such
2161 a trial,
2162 dear Sir,
2163 With
2164 no jury
2165 or judge,
2166 would be
2167 wasting
2168 our
2169 breath."
2170 "I'll be
2171 judge, I'll
2172 be jury,"
2173 Said
2174 cunning
2175 old Fury:
2176 "I'll
2177 try the
2178 whole
2179 cause,
2180 and
2181 condemn
2182 you
2183 to
2184 death."'
2185
2186
2187 .SH CODE
2188
2189
2190 .BR
2191 Code tags code{ ... }code (used as with other group tags described above) are
2192 used to escape regular sisu markup, and have been used extensively within this
2193 document to provide examples of
2194 .B SiSU
2195 markup. You cannot however use code tags to escape code tags. They are however
2196 used in the same way as group or poem tags.
2197
2198 .BR
2199 A code-block is treated as an object and given a single object number. [an
2200 option to number each line of code may be considered at some later time]
2201
2202 .BR
2203
2204 .B use of code tags instead of poem compared, resulting output:
2205 .nf
2206 `Fury said to a
2207 mouse, That he
2208 met in the
2209 house,
2210 "Let us
2211 both go to
2212 law: I will
2213 prosecute
2214 YOU. --Come,
2215 I'll take no
2216 denial; We
2217 must have a
2218 trial: For
2219 really this
2220 morning I've
2221 nothing
2222 to do."
2223 Said the
2224 mouse to the
2225 cur, "Such
2226 a trial,
2227 dear Sir,
2228 With
2229 no jury
2230 or judge,
2231 would be
2232 wasting
2233 our
2234 breath."
2235 "I'll be
2236 judge, I'll
2237 be jury,"
2238 Said
2239 cunning
2240 old Fury:
2241 "I'll
2242 try the
2243 whole
2244 cause,
2245 and
2246 condemn
2247 you
2248 to
2249 death."'
2250 .fi
2251
2252
2253 .BR
2254 From
2255 .B SiSU
2256 2.7.7 on you can number codeblocks by placing a hash after the opening code tag
2257 code{# as demonstrated here:
2258 .nf
2259 1 | `Fury said to a
2260 2 | mouse, That he
2261 3 | met in the
2262 4 | house,
2263 5 | "Let us
2264 6 | both go to
2265 7 | law: I will
2266 8 | prosecute
2267 9 | YOU. --Come,
2268 10 | I'll take no
2269 11 | denial; We
2270 12 | must have a
2271 13 | trial: For
2272 14 | really this
2273 15 | morning I've
2274 16 | nothing
2275 17 | to do."
2276 18 | Said the
2277 19 | mouse to the
2278 20 | cur, "Such
2279 21 | a trial,
2280 22 | dear Sir,
2281 23 | With
2282 24 | no jury
2283 25 | or judge,
2284 26 | would be
2285 27 | wasting
2286 28 | our
2287 29 | breath."
2288 30 | "I'll be
2289 31 | judge, I'll
2290 32 | be jury,"
2291 33 | Said
2292 34 | cunning
2293 35 | old Fury:
2294 36 | "I'll
2295 37 | try the
2296 38 | whole
2297 39 | cause,
2298 40 | and
2299 41 | condemn
2300 42 | you
2301 43 | to
2302 44 | death."'
2303 .fi
2304
2305 .SH ADDITIONAL BREAKS - LINEBREAKS WITHIN OBJECTS, COLUMN AND PAGE-BREAKS
2306
2307 .SH LINE-BREAKS
2308
2309
2310 .BR
2311 To break a line within a "paragraph object", two backslashes \e\e
2312 with a space before and a space or newline after them
2313 may be used.
2314 .nf
2315 To break a line within a "paragraph object",
2316 two backslashes \e\e with a space before
2317 and a space or newline after them \e\e
2318 may be used.
2319 .fi
2320
2321
2322 .BR
2323 The html break br enclosed in angle brackets (though undocumented) is available
2324 in versions prior to 3.0.13 and 2.9.7 (it remains available for the time being,
2325 but is depreciated).
2326
2327 .BR
2328 To draw a dividing line dividing paragraphs, see the section on page breaks.
2329 .SH PAGE BREAKS
2330
2331
2332 .BR
2333 Page breaks are only relevant and honored in some output formats. A page break
2334 or a new page may be inserted manually using the following markup on a line on
2335 its own:
2336
2337 .BR
2338 page new =\e= breaks the page, starts a new page.
2339
2340 .BR
2341 page break -\- breaks a column, starts a new column, if using columns, else
2342 breaks the page, starts a new page.
2343
2344 .BR
2345 page break line across page -..- draws a dividing line, dividing paragraphs
2346
2347 .BR
2348 page break:
2349 .nf
2350 -\e\e-
2351 .fi
2352
2353
2354 .BR
2355 page (break) new:
2356 .nf
2357 =\e\e=
2358 .fi
2359
2360
2361 .BR
2362 page (break) line across page (dividing paragraphs):
2363 .nf
2364 -..-
2365 .fi
2366
2367 .SH BIBLIOGRAPHY / REFERENCES
2368
2369
2370 .BR
2371 There are three ways to prepare a bibliography using sisu: (i) manually
2372 preparing and marking up as regular text in sisu a list of references; (ii)
2373 (tagging citations for inclusion) using a restricted form for citations and
2374 marking them up to identify them as such (which sisu then parses and attempts
2375 to build a bibliography from), or; (iii) preparing a bibliography, using
2376 metadata tags for author: title: year: and the like, including an id: and
2377 shortname: the id can be inserted in footnotes in place of the citation, and it
2378 will be substituted there by the short title for the work.
2379
2380 .BR
2381 For the heading/section sequence: endnotes, bibliography then book index to
2382 occur, the name biblio or bibliography must be given to the bibliography
2383 section, like so:
2384 .nf
2385 1~biblio Bibliography
2386 .fi
2387
2388 .SH A MARKUP TAGGED METADATA BIBLIOGRAPHY SECTION
2389
2390
2391 .BR
2392 Here instead of writing your full citations directly in footnotes, each time
2393 you have new material to cite, you add it to your bibliography section (if it
2394 has not been added yet) providing the information you need against an available
2395 list of tags. At the time of writing, for articles: au|author; ti|title;
2396 lng|language; jo|journal; vo|volume; edr|editor; yr|year; pst|publisher_state;
2397 url; note; sn|shortname; id; and
2398 for books: au|author; ti|title; st|subtitle; lng|language; pb|publisher;
2399 edn|edition; yr|year; pst|publisher_state; url; note; sn|shortname; id.
2400
2401 .BR
2402 The required tags are au: ti: and year: [^10] an short quick example might be
2403 as follows:
2404 .nf
2405 1~biblio Bibliography
2406
2407 au: von Hippel, E.
2408 ti: Perspective: User Toolkits for Innovation
2409 lng: (language)
2410 jo: Journal of Product Innovation Management
2411 vo: 18
2412 edr: (editor)
2413 yr: 2001
2414 note:
2415 sn: Hippel, /{User Toolkits}/ (2001)
2416 id: vHippel_2001
2417 % form:
2418
2419 au: Benkler, Yochai
2420 ti: The Wealth of Networks
2421 st: How Social Production Transforms Markets and Freedom
2422 lng: (language)
2423 pb: Harvard University Press
2424 edn: (edition)
2425 yr: 2006
2426 pst: U.S.
2427 url: http://cyber.law.harvard.edu/wealth_of_networks/Main_Page
2428 note:
2429 sn: Benkler, /{Wealth of Networks}/ (2006)
2430 id: Benkler2006
2431
2432 au: Quixote, Don; Panza, Sancho
2433 ti: Taming Windmills, Keeping True
2434 jo: Imaginary Journal
2435 yr: 1605
2436 url: https://en.wikipedia.org/wiki/Don_Quixote
2437 note: made up to provide an example of author markup for an article with two authors
2438 sn: Quixote and Panza, /{Taming Windmills}/ (1605)
2439 id: quixote1605
2440 .fi
2441
2442
2443 .BR
2444 Note that the section name biblio (or bibliography) is required for the
2445 bibliography to be recognized as such, parsed correctly, and placed after the
2446 auto-generated endnote section.
2447
2448 .BR
2449 Using this method, work goes into preparing the bibliography, which will be
2450 automatically sorted by surname and presented, under the References or
2451 Bibliography section using the format for books:
2452
2453 .BR
2454 number, author (firstname & initials, surname), fulltitle, publisher, year,
2455 url (if any)
2456
2457 .BR
2458 and for articles:
2459
2460 .BR
2461 number, author (firstname & initials, surname), title, journal, volume, year,
2462 url (if any)
2463
2464 .BR
2465 The metadata tags may include shortname and id, if provided, every time the
2466 given id is found within the text it will be replaced by the given short title
2467 of the work (it is for this reason the short title has sisu markup to italicize
2468 the title), it should work with any page numbers to be added, the short title
2469 should be one that can easily be used to look up the full description in the
2470 bibliography.
2471 .nf
2472 The following footnote~{ quixote1605, pp 1000 - 1001, also Benkler2006 p 1. }~
2473 .fi
2474
2475
2476 .BR
2477 would be presented as:
2478
2479 .BR
2480 Quixote and Panza,
2481 .I Taming Windmills
2482 (1605), pp 1000 - 1001 also, Benkler,
2483 .I Wealth of Networks,
2484 (2006) p 1 or rather[^11]
2485 .SH TAGGING CITATIONS FOR INCLUSION IN THE BIBLIOGRAPHY
2486
2487
2488 .BR
2489 Here whenever you make a citation that you wish be included in the
2490 bibliography, you tag the citation as such using special delimiters (which are
2491 subsequently removed from the final text produced by sisu)
2492
2493 .BR
2494 Here you would write something like the following, either in regular text or a
2495 footnote
2496 .nf
2497 See .: Quixote, Don; Panza, Sancho /{Taming Windmills, Keeping True}/ (1605) :.
2498 .fi
2499
2500
2501 .BR
2502
2503 .B SiSU
2504 will parse for a number of patterns within the delimiters to try make out the
2505 authors, title, date etc. and from that create a Bibliography. This is more
2506 limited than the previously described method of preparing a tagged
2507 bibliography, and using an id within text to identify the work, which also
2508 lends itself to greater consistency.
2509 .SH BOOK INDEX
2510
2511
2512 .BR
2513 To make an index append to paragraph the book index term relates to it, using
2514 an equal sign and curly braces.
2515
2516 .BR
2517 Currently two levels are provided, a main term and if needed a sub-term.
2518 Sub-terms are separated from the main term by a colon.
2519 .nf
2520 Paragraph containing main term and sub-term.
2521 ={Main term:sub-term}
2522 .fi
2523
2524
2525 .BR
2526 The index syntax starts on a new line, but there should not be an empty line
2527 between paragraph and index markup.
2528
2529 .BR
2530 The structure of the resulting index would be:
2531 .nf
2532 Main term, 1
2533 sub-term, 1
2534 .fi
2535
2536
2537 .BR
2538 Several terms may relate to a paragraph, they are separated by a semicolon. If
2539 the term refers to more than one paragraph, indicate the number of paragraphs.
2540 .nf
2541 Paragraph containing main term, second term and sub-term.
2542 ={first term; second term: sub-term}
2543 .fi
2544
2545
2546 .BR
2547 The structure of the resulting index would be:
2548 .nf
2549 First term, 1,
2550 Second term, 1,
2551 sub-term, 1
2552 .fi
2553
2554
2555 .BR
2556 If multiple sub-terms appear under one paragraph, they are separated under the
2557 main term heading from each other by a pipe symbol.
2558 .nf
2559 Paragraph containing main term, second term and sub-term.
2560 ={Main term:
2561 sub-term+2|second sub-term;
2562 Another term
2563 }
2564
2565 A paragraph that continues discussion of the first sub-term
2566 .fi
2567
2568
2569 .BR
2570 The plus one in the example provided indicates the first sub-term spans one
2571 additional paragraph. The logical structure of the resulting index would be:
2572 .nf
2573 Main term, 1,
2574 sub-term, 1-3,
2575 second sub-term, 1,
2576 Another term, 1
2577 .fi
2578
2579 .SH COMPOSITE DOCUMENTS MARKUP
2580
2581
2582 .BR
2583 It is possible to build a document by creating a master document that requires
2584 other documents. The documents required may be complete documents that could be
2585 generated independently, or they could be markup snippets, prepared so as to be
2586 easily available to be placed within another text. If the calling document is a
2587 master document (built from other documents), it should be named with the
2588 suffix
2589 .B .ssm
2590 Within this document you would provide information on the other documents that
2591 should be included within the text. These may be other documents that would be
2592 processed in a regular way, or markup bits prepared only for inclusion within a
2593 master document
2594 .B .sst
2595 regular markup file, or
2596 .B .ssi
2597 (insert/information) A secondary file of the composite document is built prior
2598 to processing with the same prefix and the suffix
2599 .B ._sst
2600
2601 .BR
2602 basic markup for importing a document into a master document
2603 .nf
2604 << filename1.sst
2605
2606 << filename2.ssi
2607 .fi
2608
2609
2610 .BR
2611 The form described above should be relied on. Within the
2612 .I Vim
2613 editor it results in the text thus linked becoming hyperlinked to the document
2614 it is calling in which is convenient for editing.
2615 .SH SUBSTITUTIONS
2616
2617
2618 .BR
2619
2620 .B markup example:
2621 .nf
2622 The current Debian is ${debian_stable} the next debian will be ${debian_testing}
2623
2624 Configure substitution in _sisu/sisu_document_make
2625
2626 @make:
2627 :substitute: /${debian_stable}/,'*{Wheezy}*' /${debian_testing}/,'*{Jessie}*'
2628 .fi
2629
2630
2631 .BR
2632
2633 .B resulting output:
2634
2635 .BR
2636 The current
2637 .B Debian
2638 is
2639 .B Jessie
2640 the next debian will be
2641 .B Stretch
2642
2643 .BR
2644 Configure substitution in _sisu/sisu_document_make
2645 .SH SISU FILETYPES
2646
2647
2648 .BR
2649
2650 .B SiSU
2651 has
2652 .I plaintext
2653 and binary filetypes, and can process either type of document.
2654 .SH .SST .SSM .SSI MARKED UP PLAIN TEXT
2655
2656 .TP
2657 .B SiSU
2658 documents are prepared as plain-text (utf-8) files with
2659 .B SiSU
2660 markup. They may make reference to and contain images (for example), which are
2661 stored in the directory beneath them _sisu/image. 〔b¤SiSU
2662 .I plaintext
2663 markup files are of three types that may be distinguished by the file extension
2664 used: regular text .sst; master documents, composite documents that incorporate
2665 other text, which can be any regular text or text insert; and inserts the
2666 contents of which are like regular text except these are marked .ssi and are
2667 not processed.
2668
2669 .BR
2670
2671 .B SiSU
2672 processing can be done directly against a sisu documents; which may be located
2673 locally or on a remote server for which a url is provided.
2674
2675 .BR
2676
2677 .B SiSU
2678 source markup can be shared with the command:
2679
2680 .BR
2681 sisu -s [filename]
2682 .SH SISU TEXT - REGULAR FILES (.SST)
2683
2684
2685 .BR
2686 The most common form of document in
2687 .B SiSU,
2688 see the section on
2689 .B SiSU
2690 markup.
2691 .SH SISU MASTER FILES (.SSM)
2692
2693
2694 .BR
2695 Composite documents which incorporate other
2696 .B SiSU
2697 documents which may be either regular
2698 .B SiSU
2699 text .sst which may be generated independently, or inserts prepared solely for
2700 the purpose of being incorporated into one or more master documents.
2701
2702 .BR
2703 The mechanism by which master files incorporate other documents is described as
2704 one of the headings under under
2705 .B SiSU
2706 markup in the
2707 .B SiSU
2708 manual.
2709
2710 .BR
2711 Note: Master documents may be prepared in a similar way to regular documents,
2712 and processing will occur normally if a .sst file is renamed .ssm without
2713 requiring any other documents; the .ssm marker flags that the document may
2714 contain other documents.
2715
2716 .BR
2717 Note: a secondary file of the composite document is built prior to processing
2718 with the same prefix and the suffix ._sst [^12]
2719 .SH SISU INSERT FILES (.SSI)
2720
2721
2722 .BR
2723 Inserts are documents prepared solely for the purpose of being incorporated
2724 into one or more master documents. They resemble regular
2725 .B SiSU
2726 text files (.sst). Since sisu -5.5.0 (6.1.0) .ssi files can like .ssm files
2727 include other .sst or .ssm files. .ssi files cannot be called by the sisu
2728 processor directly and can only be incorporated in other documents. Making a
2729 file a .ssi file is a quick and convenient way of breaking up a document that
2730 is to be included in a master document, and flagging that the file to be
2731 incorporated .ssi is not intended that the file should be processed on its own.
2732 .SH SISUPOD, ZIPPED BINARY CONTAINER (SISUPOD.ZIP, .SSP)
2733
2734
2735 .BR
2736 A sisupod is a zipped
2737 .B SiSU
2738 text file or set of
2739 .B SiSU
2740 text files and any associated images that they contain (this will be extended
2741 to include sound and multimedia-files)
2742 .TP
2743 .B SiSU
2744 .I plaintext
2745 files rely on a recognised directory structure to find contents such as images
2746 associated with documents, but all images for example for all documents
2747 contained in a directory are located in the sub-directory _sisu/image. Without
2748 the ability to create a sisupod it can be inconvenient to manually identify all
2749 other files associated with a document. A sisupod automatically bundles all
2750 associated files with the document that is turned into a pod.
2751
2752 .BR
2753 The structure of the sisupod is such that it may for example contain a single
2754 document and its associated images; a master document and its associated
2755 documents and anything else; or the zipped contents of a whole directory of
2756 prepared
2757 .B SiSU
2758 documents.
2759
2760 .BR
2761 The command to create a sisupod is:
2762
2763 .BR
2764 sisu -S [filename]
2765
2766 .BR
2767 Alternatively, make a pod of the contents of a whole directory:
2768
2769 .BR
2770 sisu -S
2771
2772 .BR
2773
2774 .B SiSU
2775 processing can be done directly against a sisupod; which may be located locally
2776 or on a remote server for which a url is provided.
2777
2778 .BR
2779 <http://www.sisudoc.org/sisu/sisu_commands>
2780
2781 .BR
2782 <http://www.sisudoc.org/sisu/sisu_manual>
2783 .SH CONFIGURATION
2784
2785 .SH CONFIGURATION FILES
2786
2787 .SH CONFIG.YML
2788
2789
2790 .BR
2791
2792 .B SiSU
2793 configration parameters are adjusted in the configuration file, which can be
2794 used to override the defaults set. This includes such things as which directory
2795 interim processing should be done in and where the generated output should be
2796 placed.
2797
2798 .BR
2799 The
2800 .B SiSU
2801 configuration file is a yaml file, which means indentation is significant.
2802
2803 .BR
2804
2805 .B SiSU
2806 resource configuration is determined by looking at the following files if they
2807 exist:
2808
2809 .BR
2810 ./_sisu/v7/sisurc.yml
2811
2812 .BR
2813 ./_sisu/sisurc.yml
2814
2815 .BR
2816 ~/.sisu/v7/sisurc.yml
2817
2818 .BR
2819 ~/.sisu/sisurc.yml
2820
2821 .BR
2822 /etc/sisu/v7/sisurc.yml
2823
2824 .BR
2825 /etc/sisu/sisurc.yml
2826
2827 .BR
2828 The search is in the order listed, and the first one found is used.
2829
2830 .BR
2831 In the absence of instructions in any of these it falls back to the internal
2832 program defaults.
2833
2834 .BR
2835 Configuration determines the output and processing directories and the database
2836 access details.
2837
2838 .BR
2839 If
2840 .B SiSU
2841 is installed a sample sisurc.yml may be found in /etc/sisu/sisurc.yml
2842 .SH SISU_DOCUMENT_MAKE
2843
2844
2845 .BR
2846 Most sisu document headers relate to metadata, the exception is the @make:
2847 header which provides processing related information. The default contents of
2848 the @make header may be set by placing them in a file sisu_document_make.
2849
2850 .BR
2851 The search order is as for resource configuration:
2852
2853 .BR
2854 ./_sisu/v7/sisu_document_make
2855
2856 .BR
2857 ./_sisu/sisu_document_make
2858
2859 .BR
2860 ~/.sisu/v7/sisu_document_make
2861
2862 .BR
2863 ~/.sisu/sisu_document_make
2864
2865 .BR
2866 /etc/sisu/v7/sisu_document_make
2867
2868 .BR
2869 /etc/sisu/sisu_document_make
2870
2871 .BR
2872 A sample sisu_document_make can be found in the _sisu/ directory under along
2873 with the provided sisu markup samples.
2874 .SH CSS - CASCADING STYLE SHEETS (FOR HTML, XHTML AND XML)
2875
2876
2877 .BR
2878 CSS files to modify the appearance of
2879 .B SiSU
2880 html,
2881 .I XHTML
2882 or
2883 .I XML
2884 may be placed in the configuration directory: ./_sisu/css ; ~/.sisu/css or;
2885 /etc/sisu/css and these will be copied to the output directories with the
2886 command sisu -CC.
2887
2888 .BR
2889 The basic CSS file for html output is html. css, placing a file of that name in
2890 directory _sisu/css or equivalent will result in the default file of that name
2891 being overwritten.
2892
2893 .BR
2894
2895 .I HTML:
2896 html. css
2897
2898 .BR
2899
2900 .I XML
2901 DOM: dom.css
2902
2903 .BR
2904
2905 .I XML
2906 SAX: sax.css
2907
2908 .BR
2909
2910 .I XHTML:
2911 xhtml. css
2912
2913 .BR
2914 The default homepage may use homepage.css or html. css
2915
2916 .BR
2917 Under consideration is to permit the placement of a CSS file with a different
2918 name in directory _sisu/css directory or equivalent.[^13]
2919 .SH ORGANISING CONTENT - DIRECTORY STRUCTURE AND MAPPING
2920
2921
2922 .BR
2923
2924 .B SiSU
2925 v3 has new options for the source directory tree, and output directory
2926 structures of which there are 3 alternatives.
2927 .SH DOCUMENT SOURCE DIRECTORY
2928
2929
2930 .BR
2931 The document source directory is the directory in which sisu processing
2932 commands are given. It contains the sisu source files (.sst .ssm .ssi), or (for
2933 sisu v3 may contain) subdirectories with language codes which contain the sisu
2934 source files, so all English files would go in subdirectory en/, French in fr/,
2935 Spanish in es/ and so on. ISO 639-1 codes are used (as varied by po4a). A list
2936 of available languages (and possible sub-directory names) can be obtained with
2937 the command "sisu --help lang" The list of languages is limited to langagues
2938 supported by XeTeX polyglosia.
2939 .SH GENERAL DIRECTORIES
2940
2941 .nf
2942 ./subject_name/
2943
2944 % files stored at this level e.g. sisu_manual.sst or
2945 % for sisu v3 may be under language sub-directories
2946 % e.g.
2947
2948 ./subject_name/en
2949
2950 ./subject_name/fr
2951
2952 ./subject_name/es
2953
2954 ./subject_name/_sisu
2955
2956 ./subject_name/_sisu/css
2957
2958 ./subject_name/_sisu/image
2959 .fi
2960
2961 .SH DOCUMENT OUTPUT DIRECTORY STRUCTURES
2962
2963 .SH OUTPUT DIRECTORY ROOT
2964
2965
2966 .BR
2967 The output directory root can be set in the sisurc.yml file. Under the root,
2968 subdirectories are made for each directory in which a document set resides. If
2969 you have a directory named poems or conventions, that directory will be created
2970 under the output directory root and the output for all documents contained in
2971 the directory of a particular name will be generated to subdirectories beneath
2972 that directory (poem or conventions). A document will be placed in a
2973 subdirectory of the same name as the document with the filetype identifier
2974 stripped (.sst .ssm)
2975
2976 .BR
2977 The last part of a directory path, representing the sub-directory in which a
2978 document set resides, is the directory name that will be used for the output
2979 directory. This has implications for the organisation of document collections
2980 as it could make sense to place documents of a particular subject, or type
2981 within a directory identifying them. This grouping as suggested could be by
2982 subject (sales_law, english_literature); or just as conveniently by some other
2983 classification (X University). The mapping means it is also possible to place
2984 in the same output directory documents that are for organisational purposes
2985 kept separately, for example documents on a given subject of two different
2986 institutions may be kept in two different directories of the same name, under a
2987 directory named after each institution, and these would be output to the same
2988 output directory. Skins could be associated with each institution on a
2989 directory basis and resulting documents will take on the appropriate different
2990 appearance.
2991 .SH ALTERNATIVE OUTPUT STRUCTURES
2992
2993
2994 .BR
2995 There are 3 possibile output structures described as being, by language, by
2996 filetype or by filename, the selection is made in sisurc.yml
2997 .nf
2998 #% output_dir_structure_by: language; filetype; or filename
2999 output_dir_structure_by: language #(language & filetype, preferred?)
3000 #output_dir_structure_by: filetype
3001 #output_dir_structure_by: filename #(default, closest to original v1 & v2)
3002 .fi
3003
3004 .SH BY LANGUAGE
3005
3006
3007 .BR
3008 The by language directory structure places output files
3009
3010 .BR
3011 The by language directory structure separates output files by language code
3012 (all files of a given language), and within the language directory by filetype.
3013
3014 .BR
3015 Its selection is configured in sisurc.yml
3016
3017 .BR
3018 output_dir_structure_by: language
3019 .nf
3020 |-- en
3021 |-- epub
3022 |-- hashes
3023 |-- html
3024 | |-- viral_spiral.david_bollier
3025 | |-- manifest
3026 | |-- qrcode
3027 | |-- odt
3028 | |-- pdf
3029 | |-- sitemaps
3030 | |-- txt
3031 | |-- xhtml
3032 | `-- xml
3033 |-- po4a
3034 | `-- live-manual
3035 | |-- po
3036 | |-- fr
3037 | `-- pot
3038 `-- _sisu
3039 |-- css
3040 |-- image
3041 |-- image_sys -> ../../_sisu/image_sys
3042 `-- xml
3043 |-- rnc
3044 |-- rng
3045 `-- xsd
3046 .fi
3047
3048
3049 .BR
3050 #by: language subject_dir/en/manifest/filename.html
3051 .SH BY FILETYPE
3052
3053
3054 .BR
3055 The by filetype directory structure separates output files by filetype, all
3056 html files in one directory pdfs in another and so on. Filenames are given a
3057 language extension.
3058
3059 .BR
3060 Its selection is configured in sisurc.yml
3061
3062 .BR
3063 output_dir_structure_by: filetype
3064 .nf
3065 |-- epub
3066 |-- hashes
3067 |-- html
3068 |-- viral_spiral.david_bollier
3069 |-- manifest
3070 |-- qrcode
3071 |-- odt
3072 |-- pdf
3073 |-- po4a
3074 |-- live-manual
3075 | |-- po
3076 | |-- fr
3077 | `-- pot
3078 |-- _sisu
3079 | |-- css
3080 | |-- image
3081 | |-- image_sys -> ../../_sisu/image_sys
3082 | `-- xml
3083 | |-- rnc
3084 | |-- rng
3085 | `-- xsd
3086 |-- sitemaps
3087 |-- txt
3088 |-- xhtml
3089 `-- xml
3090 .fi
3091
3092
3093 .BR
3094 #by: filetype subject_dir/html/filename/manifest.en.html
3095 .SH BY FILENAME
3096
3097
3098 .BR
3099 The by filename directory structure places most output of a particular file
3100 (the different filetypes) in a common directory.
3101
3102 .BR
3103 Its selection is configured in sisurc.yml
3104
3105 .BR
3106 output_dir_structure_by: filename
3107 .nf
3108 |-- epub
3109 |-- po4a
3110 |-- live-manual
3111 | |-- po
3112 | |-- fr
3113 | `-- pot
3114 |-- _sisu
3115 | |-- css
3116 | |-- image
3117 | |-- image_sys -> ../../_sisu/image_sys
3118 | `-- xml
3119 | |-- rnc
3120 | |-- rng
3121 | `-- xsd
3122 |-- sitemaps
3123 |-- src
3124 |-- pod
3125 `-- viral_spiral.david_bollier
3126 .fi
3127
3128
3129 .BR
3130 #by: filename subject_dir/filename/manifest.en.html
3131 .SH REMOTE DIRECTORIES
3132
3133 .nf
3134 ./subject_name/
3135
3136 % containing sub_directories named after the generated files from which they are made
3137
3138 ./subject_name/src
3139
3140 % contains shared source files text and binary e.g. sisu_manual.sst and sisu_manual.sst.zip
3141
3142 ./subject_name/_sisu
3143
3144 % configuration file e.g. sisurc.yml
3145
3146 ./subject_name/_sisu/skin
3147
3148 % skins in various skin directories doc, dir, site, yml
3149
3150 ./subject_name/_sisu/css
3151
3152 ./subject_name/_sisu/image
3153
3154 % images for documents contained in this directory
3155
3156 ./subject_name/_sisu/mm
3157 .fi
3158
3159 .SH SISUPOD
3160
3161 .nf
3162 ./sisupod/
3163
3164 % files stored at this level e.g. sisu_manual.sst
3165
3166 ./sisupod/_sisu
3167
3168 % configuration file e.g. sisurc.yml
3169
3170 ./sisupod/_sisu/skin
3171
3172 % skins in various skin directories doc, dir, site, yml
3173
3174 ./sisupod/_sisu/css
3175
3176 ./sisupod/_sisu/image
3177
3178 % images for documents contained in this directory
3179
3180 ./sisupod/_sisu/mm
3181 .fi
3182
3183 .SH HOMEPAGES
3184
3185
3186 .BR
3187
3188 .B SiSU
3189 is about the ability to auto-generate documents. Home pages are regarded as
3190 custom built items, and are not created by
3191 .B SiSU.
3192 More accurately,
3193 .B SiSU
3194 has a default home page, which will not be appropriate for use with other
3195 sites, and the means to provide your own home page instead in one of two ways
3196 as part of a site's configuration, these being:
3197
3198 .BR
3199 1. through placing your home page and other custom built documents in the
3200 subdirectory _sisu/home/ (this probably being the easier and more convenient
3201 option)
3202
3203 .BR
3204 2. through providing what you want as the home page in a skin,
3205
3206 .BR
3207 Document sets are contained in directories, usually organised by site or
3208 subject. Each directory can/should have its own homepage. See the section on
3209 directory structure and organisation of content.
3210 .SH HOME PAGE AND OTHER CUSTOM BUILT PAGES IN A SUB-DIRECTORY
3211
3212
3213 .BR
3214 Custom built pages, including the home page index.html may be placed within the
3215 configuration directory _sisu/home/ in any of the locations that is searched
3216 for the configuration directory, namely ./_sisu ; ~/_sisu ; /etc/sisu From
3217 there they are copied to the root of the output directory with the command:
3218
3219 .BR
3220 sisu -CC
3221 .SH MARKUP AND OUTPUT EXAMPLES
3222
3223 .SH MARKUP EXAMPLES
3224
3225
3226 .BR
3227 Current markup examples and document output samples are provided off
3228 <http://sisudoc.org> or <http://www.jus.uio.no/sisu> and in the sisu
3229 -markup-sample package available off <http://git.sisudoc.org>
3230
3231 .BR
3232 For some documents hardly any markup at all is required at all, other than a
3233 header, and an indication that the levels to be taken into account by the
3234 program in generating its output are.
3235 .SH SISU MARKUP SAMPLES
3236
3237
3238 .BR
3239 A few additional sample books prepared as sisu markup samples, output formats
3240 to be generated using
3241 .B SiSU
3242 are contained in a separate package sisu -markup-samples. sisu -markup-samples
3243 contains books (prepared using sisu markup), that were released by their
3244 authors various licenses mostly different Creative Commons licences that do not
3245 permit inclusion in the
3246 .B Debian
3247 Project as they have requirements that do not meet the
3248 .B Debian
3249 Free Software Guidelines for various reasons, most commonly that they require
3250 that the original substantive text remain unchanged, and sometimes that the
3251 works be used only non-commercially.
3252
3253 .BR
3254
3255 .I Accelerando,
3256 Charles Stross (2005)
3257 accelerando.charles_stross.sst
3258
3259 .BR
3260
3261 .I Alice's Adventures in Wonderland,
3262 Lewis Carroll (1865)
3263 alices_adventures_in_wonderland.lewis_carroll.sst
3264
3265 .BR
3266
3267 .I CONTENT,
3268 Cory Doctorow (2008)
3269 content.cory_doctorow.sst
3270
3271 .BR
3272
3273 .I Democratizing Innovation,
3274 Eric von Hippel (2005)
3275 democratizing_innovation.eric_von_hippel.sst
3276
3277 .BR
3278
3279 .I Down and Out in the Magic Kingdom,
3280 Cory Doctorow (2003)
3281 down_and_out_in_the_magic_kingdom.cory_doctorow.sst
3282
3283 .BR
3284
3285 .I For the Win,
3286 Cory Doctorow (2010)
3287 for_the_win.cory_doctorow.sst
3288
3289 .BR
3290
3291 .I Free as in Freedom - Richard Stallman's Crusade for Free Software,
3292 Sam Williams (2002)
3293 free_as_in_freedom.richard_stallman_crusade_for_free_software.sam_williams.sst
3294
3295 .BR
3296
3297 .I Free as in Freedom 2.0 - Richard Stallman and the Free Software Revolution,
3298 Sam Williams (2002), Richard M. Stallman (2010)
3299 free_as_in_freedom_2.richard_stallman_and_the_free_software_revolution.sam_williams.richard_stallman.sst
3300
3301 .BR
3302
3303 .I Free Culture - How Big Media Uses Technology and the Law to Lock Down
3304 Culture and Control Creativity,
3305 Lawrence Lessig (2004)
3306 free_culture.lawrence_lessig.sst
3307
3308 .BR
3309
3310 .I Free For All - How Linux and the Free Software Movement Undercut the High
3311 Tech Titans,
3312 Peter Wayner (2002)
3313 free_for_all.peter_wayner.sst
3314
3315 .BR
3316
3317 .I GNU GENERAL PUBLIC LICENSE v2,
3318 Free Software Foundation (1991)
3319 gpl2.fsf.sst
3320
3321 .BR
3322
3323 .I GNU GENERAL PUBLIC LICENSE v3,
3324 Free Software Foundation (2007)
3325 gpl3.fsf.sst
3326
3327 .BR
3328
3329 .I Gulliver's Travels,
3330 Jonathan Swift (1726 / 1735)
3331 gullivers_travels.jonathan_swift.sst
3332
3333 .BR
3334
3335 .I Little Brother,
3336 Cory Doctorow (2008)
3337 little_brother.cory_doctorow.sst
3338
3339 .BR
3340
3341 .I The Cathederal and the Bazaar,
3342 Eric Raymond (2000)
3343 the_cathedral_and_the_bazaar.eric_s_raymond.sst
3344
3345 .BR
3346
3347 .I The Public Domain - Enclosing the Commons of the Mind,
3348 James Boyle (2008)
3349 the_public_domain.james_boyle.sst
3350
3351 .BR
3352
3353 .I The Wealth of Networks - How Social Production Transforms Markets and
3354 Freedom,
3355 Yochai Benkler (2006)
3356 the_wealth_of_networks.yochai_benkler.sst
3357
3358 .BR
3359
3360 .I Through the Looking Glass,
3361 Lewis Carroll (1871)
3362 through_the_looking_glass.lewis_carroll.sst
3363
3364 .BR
3365
3366 .I Two Bits - The Cultural Significance of Free Software,
3367 Christopher Kelty (2008)
3368 two_bits.christopher_kelty.sst
3369
3370 .BR
3371
3372 .I UN Contracts for International Sale of Goods,
3373 UN (1980)
3374 un_contracts_international_sale_of_goods_convention_1980.sst
3375
3376 .BR
3377
3378 .I Viral Spiral,
3379 David Bollier (2008)
3380 viral_spiral.david_bollier.sst
3381 .SH SISU SEARCH - INTRODUCTION
3382
3383
3384 .BR
3385
3386 .B SiSU
3387 output can easily and conveniently be indexed by a number of standalone
3388 indexing tools, such as Lucene, Hyperestraier.
3389
3390 .BR
3391 Because the document structure of sites created is clearly defined, and the
3392 text
3393 .I object citation system
3394 is available hypothetically at least, for all forms of output, it is possible
3395 to search the sql database, and either read results from that database, or map
3396 the results to the html or other output, which has richer text markup.
3397
3398 .BR
3399
3400 .B SiSU
3401 can populate a relational sql type database with documents at an object level,
3402 including objects numbers that are shared across different output types. Making
3403 a document corpus searchable with that degree of granularity. Basically, your
3404 match criteria is met by these documents and at these locations within each
3405 document, which can be viewed within the database directly or in various output
3406 formats.
3407 .SH SQL
3408
3409 .SH POPULATING SQL TYPE DATABASES
3410
3411
3412 .BR
3413
3414 .B SiSU
3415 feeds sisu markupd documents into sql type databases
3416 .I PostgreSQL
3417 [^14] and/or
3418 .I SQLite
3419 [^15] database together with information related to document structure.
3420
3421 .BR
3422 This is one of the more interesting output forms, as all the structural data of
3423 the documents are retained (though can be ignored by the user of the database
3424 should they so choose). All site texts/documents are (currently) streamed to
3425 four tables:
3426
3427 .BR
3428 * one containing semantic (and other) headers, including, title, author,
3429 subject, (the
3430 .I Dublin Core.
3431 ..);
3432
3433 .BR
3434 * another the substantive texts by individual "paragraph" (or object) - along
3435 with structural information, each paragraph being identifiable by its
3436 paragraph number (if it has one which almost all of them do), and the
3437 substantive text of each paragraph quite naturally being searchable (both in
3438 formatted and clean text versions for searching); and
3439
3440 .BR
3441 * a third containing endnotes cross-referenced back to the paragraph from
3442 which they are referenced (both in formatted and clean text versions for
3443 searching).
3444
3445 .BR
3446 * a fourth table with a one to one relation with the headers table contains
3447 full text versions of output, eg. pdf, html, xml, and
3448 .I ascii.
3449
3450 .BR
3451 There is of course the possibility to add further structures.
3452
3453 .BR
3454 At this level
3455 .B SiSU
3456 loads a relational database with documents chunked into objects, their smallest
3457 logical structurally constituent parts, as text objects, with their object
3458 citation number and all other structural information needed to construct the
3459 document. Text is stored (at this text object level) with and without
3460 elementary markup tagging, the stripped version being so as to facilitate ease
3461 of searching.
3462
3463 .BR
3464 Being able to search a relational database at an object level with the
3465 .B SiSU
3466 citation system is an effective way of locating content generated by
3467 .B SiSU.
3468 As individual text objects of a document stored (and indexed) together with
3469 object numbers, and all versions of the document have the same numbering,
3470 complex searches can be tailored to return just the locations of the search
3471 results relevant for all available output formats, with live links to the
3472 precise locations in the database or in html/xml documents; or, the structural
3473 information provided makes it possible to search the full contents of the
3474 database and have headings in which search content appears, or to search only
3475 headings etc. (as the
3476 .I Dublin Core
3477 is incorporated it is easy to make use of that as well).
3478 .SH POSTGRESQL
3479
3480 .SH NAME
3481
3482
3483 .BR
3484
3485 .B SiSU
3486 - Structured information, Serialized Units - a document publishing system,
3487 postgresql dependency package
3488 .SH DESCRIPTION
3489
3490
3491 .BR
3492 Information related to using postgresql with sisu (and related to the
3493 sisu_postgresql dependency package, which is a dummy package to install
3494 dependencies needed for
3495 .B SiSU
3496 to populate a postgresql database, this being part of
3497 .B SiSU
3498 - man sisu) .
3499 .SH SYNOPSIS
3500
3501
3502 .BR
3503 sisu -D [instruction] [filename/wildcard if required]
3504
3505 .BR
3506 sisu -D --pg --[instruction] [filename/wildcard if required]
3507 .SH COMMANDS
3508
3509
3510 .BR
3511 Mappings to two databases are provided by default, postgresql and sqlite, the
3512 same commands are used within sisu to construct and populate databases however
3513 -d (lowercase) denotes sqlite and -D (uppercase) denotes postgresql,
3514 alternatively --sqlite or --pgsql may be used
3515
3516 .BR
3517
3518 .B -D or --pgsql
3519 may be used interchangeably.
3520 .SH CREATE AND DESTROY DATABASE
3521
3522 .TP
3523 .B --pgsql --createall
3524 initial step, creates required relations (tables, indexes) in existing
3525 (postgresql) database (a database should be created manually and given the same
3526 name as working directory, as requested) (rb.dbi)
3527 .TP
3528 .B sisu -D --createdb
3529 creates database where no database existed before
3530 .TP
3531 .B sisu -D --create
3532 creates database tables where no database tables existed before
3533 .TP
3534 .B sisu -D --Dropall
3535 destroys database (including all its content)! kills data and drops tables,
3536 indexes and database associated with a given directory (and directories of the
3537 same name).
3538 .TP
3539 .B sisu -D --recreate
3540 destroys existing database and builds a new empty database structure
3541 .SH IMPORT AND REMOVE DOCUMENTS
3542
3543 .TP
3544 .B sisu -D --import -v [filename/wildcard]
3545 populates database with the contents of the file. Imports documents(s)
3546 specified to a postgresql database (at an object level).
3547 .TP
3548 .B sisu -D --update -v [filename/wildcard]
3549 updates file contents in database
3550 .TP
3551 .B sisu -D --remove -v [filename/wildcard]
3552 removes specified document from postgresql database.
3553 .SH SQLITE
3554
3555 .SH NAME
3556
3557
3558 .BR
3559
3560 .B SiSU
3561 - Structured information, Serialized Units - a document publishing system.
3562 .SH DESCRIPTION
3563
3564
3565 .BR
3566 Information related to using sqlite with sisu (and related to the sisu_sqlite
3567 dependency package, which is a dummy package to install dependencies needed for
3568 .B SiSU
3569 to populate an sqlite database, this being part of
3570 .B SiSU
3571 - man sisu) .
3572 .SH SYNOPSIS
3573
3574
3575 .BR
3576 sisu -d [instruction] [filename/wildcard if required]
3577
3578 .BR
3579 sisu -d --(sqlite|pg) --[instruction] [filename/wildcard if required]
3580 .SH COMMANDS
3581
3582
3583 .BR
3584 Mappings to two databases are provided by default, postgresql and sqlite, the
3585 same commands are used within sisu to construct and populate databases however
3586 -d (lowercase) denotes sqlite and -D (uppercase) denotes postgresql,
3587 alternatively --sqlite or --pgsql may be used
3588
3589 .BR
3590
3591 .B -d or --sqlite
3592 may be used interchangeably.
3593 .SH CREATE AND DESTROY DATABASE
3594
3595 .TP
3596 .B --sqlite --createall
3597 initial step, creates required relations (tables, indexes) in existing (sqlite)
3598 database (a database should be created manually and given the same name as
3599 working directory, as requested) (rb.dbi)
3600 .TP
3601 .B sisu -d --createdb
3602 creates database where no database existed before
3603 .TP
3604 .B sisu -d --create
3605 creates database tables where no database tables existed before
3606 .TP
3607 .B sisu -d --dropall
3608 destroys database (including all its content)! kills data and drops tables,
3609 indexes and database associated with a given directory (and directories of the
3610 same name).
3611 .TP
3612 .B sisu -d --recreate
3613 destroys existing database and builds a new empty database structure
3614 .SH IMPORT AND REMOVE DOCUMENTS
3615
3616 .TP
3617 .B sisu -d --import -v [filename/wildcard]
3618 populates database with the contents of the file. Imports documents(s)
3619 specified to an sqlite database (at an object level).
3620 .TP
3621 .B sisu -d --update -v [filename/wildcard]
3622 updates file contents in database
3623 .TP
3624 .B sisu -d --remove -v [filename/wildcard]
3625 removes specified document from sqlite database.
3626 .SH CGI SEARCH FORM
3627
3628 .SH SETUP SEARCH FORM
3629
3630
3631 .BR
3632 You will need a web server, httpd with cgi enabled, and a postgresql database
3633 to which you are able to create databases.
3634
3635 .BR
3636 Setup postgresql, make sure you are able to create and write to the database,
3637 e.g.:
3638 .nf
3639 sudo su postgres
3640 createuser -d -a ralph
3641 .fi
3642
3643
3644 .BR
3645 You then need to create the database that sisu will use, for sisu manual in the
3646 directory manual/en for example, (when you try to populate a database that does
3647 not exist sisu prompts as to whether it exists):
3648 .nf
3649 createdb SiSUv6a_manual
3650 .fi
3651
3652
3653 .BR
3654
3655 .B SiSU
3656 is then able to create the required tables that allow you to populate the
3657 database with documents in the directory for which it has been created:
3658 .nf
3659 sisu --pg --createall -v
3660 .fi
3661
3662
3663 .BR
3664 You can then start to populate the database, in this example with a single
3665 document:
3666 .nf
3667 sisu --pg --update -v en/sisu_manual.ssm
3668 .fi
3669
3670
3671 .BR
3672 To create a sample search form, from within the same directory run:
3673 .nf
3674 sisu --sample-search-form --db-pg
3675 .fi
3676
3677
3678 .BR
3679 and copy the resulting cgi form to your cgi-bin directory
3680
3681 .BR
3682 A sample setup for nginx is provided that assumes data will be stored under
3683 /srv/www and cgi scripts under /srv/cgi
3684 .SH SEARCH - DATABASE FRONTEND SAMPLE, UTILISING DATABASE AND SISU FEATURES,
3685 INCLUDING OBJECT CITATION NUMBERING (BACKEND CURRENTLY POSTGRESQL)
3686
3687
3688 .BR
3689 Sample search frontend <http://search.sisudoc.org> [^16] A small database and
3690 sample query front-end (search from) that makes use of the citation system, .I
3691 object citation numbering
3692 to demonstrates functionality.[^17]
3693
3694 .BR
3695
3696 .B SiSU
3697 can provide information on which documents are matched and at what locations
3698 within each document the matches are found. These results are relevant across
3699 all outputs using
3700 .I object citation numbering,
3701 which includes html,
3702 .I XML,
3703 .I EPUB,
3704 .I LaTeX,
3705 .I PDF
3706 and indeed the
3707 .I SQL
3708 database. You can then refer to one of the other outputs or in the
3709 .I SQL
3710 database expand the text within the matched objects (paragraphs) in the
3711 documents matched.
3712
3713 .BR
3714 Note you may set results either for documents matched and object number
3715 locations within each matched document meeting the search criteria; or display
3716 the names of the documents matched along with the objects (paragraphs) that
3717 meet the search criteria.[^18]
3718 .TP
3719 .B sisu -F --webserv-webrick
3720 builds a cgi web search frontend for the database created
3721
3722 .BR
3723 The following is feedback on the setup on a machine provided by the help
3724 command:
3725
3726 .BR
3727 sisu --help sql
3728 .nf
3729 Postgresql
3730 user: ralph
3731 current db set: SiSU_sisu
3732 port: 5432
3733 dbi connect: DBI:Pg:database=SiSU_sisu;port=5432
3734
3735 sqlite
3736 current db set: /home/ralph/sisu_www/sisu/sisu_sqlite.db
3737 dbi connect DBI:SQLite:/home/ralph/sisu_www/sisu/sisu_sqlite.db
3738 .fi
3739
3740
3741 .BR
3742 Note on databases built
3743
3744 .BR
3745 By default, [unless otherwise specified] databases are built on a directory
3746 basis, from collections of documents within that directory. The name of the
3747 directory you choose to work from is used as the database name, i.e. if you are
3748 working in a directory called /home/ralph/ebook the database SiSU_ebook is
3749 used. [otherwise a manual mapping for the collection is necessary]
3750 .SH SEARCH FORM
3751
3752 .TP
3753 .B sisu -F
3754 generates a sample search form, which must be copied to the web-server cgi
3755 directory
3756 .TP
3757 .B sisu -F --webserv-webrick
3758 generates a sample search form for use with the webrick server, which must be
3759 copied to the web-server cgi directory
3760 .TP
3761 .B sisu -W
3762 starts the webrick server which should be available wherever sisu is properly
3763 installed
3764
3765 .BR
3766 The generated search form must be copied manually to the webserver directory as
3767 instructed
3768 .SH SISU_WEBRICK
3769
3770 .SH NAME
3771
3772
3773 .BR
3774
3775 .B SiSU
3776 - Structured information, Serialized Units - a document publishing system
3777 .SH SYNOPSIS
3778
3779
3780 .BR
3781 sisu_webrick [port]
3782
3783 .BR
3784 or
3785
3786 .BR
3787 sisu -W [port]
3788 .SH DESCRIPTION
3789
3790
3791 .BR
3792 sisu_webrick is part of
3793 .B SiSU
3794 (man sisu) sisu_webrick starts
3795 .B Ruby
3796 ' s Webrick web-server and points it to the directories to which
3797 .B SiSU
3798 output is written, providing a list of these directories (assuming
3799 .B SiSU
3800 is in use and they exist).
3801
3802 .BR
3803 The default port for sisu_webrick is set to 8081, this may be modified in the
3804 yaml file: ~/.sisu/sisurc.yml a sample of which is provided as
3805 /etc/sisu/sisurc.yml (or in the equivalent directory on your system).
3806 .SH SUMMARY OF MAN PAGE
3807
3808
3809 .BR
3810 sisu_webrick, may be started on it's own with the command: sisu_webrick [port]
3811 or using the sisu command with the -W flag: sisu -W [port]
3812
3813 .BR
3814 where no port is given and settings are unchanged the default port is 8081
3815 .SH DOCUMENT PROCESSING COMMAND FLAGS
3816
3817
3818 .BR
3819 sisu -W [port] starts
3820 .B Ruby
3821 Webrick web-server, serving
3822 .B SiSU
3823 output directories, on the port provided, or if no port is provided and the
3824 defaults have not been changed in ~/.sisu/sisurc.yaml then on port 8081
3825 .SH SUMMARY OF FEATURES
3826
3827
3828 .BR
3829 * sparse/minimal markup (clean utf-8 source texts). Documents are prepared in a
3830 single
3831 .I UTF-8
3832 file using a minimalistic mnemonic syntax. Typical literature, documents like
3833 "War and Peace" require almost no markup, and most of the headers are optional.
3834
3835 .BR
3836 * markup is easily readable/parsable by the human eye, (basic markup is simpler
3837 and more sparse than the most basic
3838 .I HTML
3839 ) , [this may also be converted to
3840 .I XML
3841 representations of the same input/source document].
3842
3843 .BR
3844 * markup defines document structure (this may be done once in a header
3845 pattern-match description, or for heading levels individually); basic text
3846 attributes (bold, italics, underscore, strike-through etc.) as required; and
3847 semantic information related to the document (header information, extended
3848 beyond the Dublin core and easily further extended as required); the headers
3849 may also contain processing instructions.
3850 .B SiSU
3851 markup is primarily an abstraction of document structure and document metadata
3852 to permit taking advantage of the basic strengths of existing alternative
3853 practical standard ways of representing documents [be that browser viewing,
3854 paper publication, sql search etc.] (html, epub, xml, odf, latex, pdf, sql)
3855
3856 .BR
3857 * for output produces reasonably elegant output of established industry and
3858 institutionally accepted open standard formats.[3] takes advantage of the
3859 different strengths of various standard formats for representing documents,
3860 amongst the output formats currently supported are:
3861
3862 .BR
3863 *
3864 .I HTML
3865 - both as a single scrollable text and a segmented document
3866
3867 .BR
3868 *
3869 .I XHTML
3870
3871 .BR
3872 *
3873 .I EPUB
3874
3875 .BR
3876 *
3877 .I XML
3878 - both in sax and dom style xml structures for further development as required
3879
3880 .BR
3881 *
3882 .I ODT
3883 - Open Document Format text, the iso standard for document storage
3884
3885 .BR
3886 *
3887 .I LaTeX
3888 - used to generate pdf
3889
3890 .BR
3891 *
3892 .I PDF
3893 (via
3894 .I LaTeX
3895 )
3896
3897 .BR
3898 *
3899 .I SQL
3900 - population of an sql database (
3901 .I PostgreSQL
3902 or
3903 .I SQLite
3904 ) , (at the same object level that is used to cite text within a document)
3905
3906 .BR
3907 Also produces: concordance files; document content certificates (md5 or sha256
3908 digests of headings, paragraphs, images etc.) and html manifests (and sitemaps
3909 of content). (b) takes advantage of the strengths implicit in these very
3910 different output types, (e.g. PDFs produced using typesetting of
3911 .I LaTeX,
3912 databases populated with documents at an individual object/paragraph level,
3913 making possible
3914 .I granular search
3915 (and related possibilities))
3916
3917 .BR
3918 * ensuring content can be cited in a meaningful way regardless of selected
3919 output format. Online publishing (and publishing in multiple document formats)
3920 lacks a useful way of citing text internally within documents (important to
3921 academics generally and to lawyers) as page numbers are meaningless across
3922 browsers and formats. sisu seeks to provide a common way of pinpoint the text
3923 within a document, (which can be utilized for citation and by search engines).
3924 The outputs share a common numbering system that is meaningful (to man and
3925 machine) across all digital outputs whether paper, screen, or database
3926 oriented, (pdf,
3927 .I HTML,
3928 .I EPUB,
3929 xml, sqlite, postgresql) , this numbering system can be used to reference
3930 content.
3931
3932 .BR
3933 * Granular search within documents.
3934 .I SQL
3935 databases are populated at an object level (roughly headings, paragraphs,
3936 verse, tables) and become searchable with that degree of granularity, the
3937 output information provides the object/paragraph numbers which are relevant
3938 across all generated outputs; it is also possible to look at just the matching
3939 paragraphs of the documents in the database; [output indexing also work well
3940 with search indexing tools like hyperestraier].
3941
3942 .BR
3943 * long term maintainability of document collections in a world of changing
3944 formats, having a very sparsely marked-up source document base. there is a
3945 considerable degree of future-proofing, output representations are
3946 "upgradeable", and new document formats may be added. e.g. addition of odf
3947 (open document text) module in 2006, epub in 2009 and in future html5 output
3948 sometime in future, without modification of existing prepared texts
3949
3950 .BR
3951 *
3952 .I SQL
3953 search aside, documents are generated as required and static once generated.
3954
3955 .BR
3956 * documents produced are static files, and may be batch processed, this needs
3957 to be done only once but may be repeated for various reasons as desired
3958 (updated content, addition of new output formats, updated technology document
3959 presentations/representations)
3960
3961 .BR
3962 * document source (
3963 .I plaintext
3964 utf-8) if shared on the net may be used as input and processed locally to
3965 produce the different document outputs
3966
3967 .BR
3968 * document source may be bundled together (automatically) with associated
3969 documents (multiple language versions or master document with inclusions) and
3970 images and sent as a zip file called a sisupod, if shared on the net these too
3971 may be processed locally to produce the desired document outputs
3972
3973 .BR
3974 * generated document outputs may automatically be posted to remote sites.
3975
3976 .BR
3977 * for basic document generation, the only software dependency is
3978 .B Ruby,
3979 and a few standard Unix tools (this covers
3980 .I plaintext,
3981 .I HTML,
3982 .I EPUB,
3983 .I XML,
3984 .I ODF,
3985 .I LaTeX
3986 ) . To use a database you of course need that, and to convert the
3987 .I LaTeX
3988 generated to pdf, a latex processor like tetex or texlive.
3989
3990 .BR
3991 * as a developers tool it is flexible and extensible
3992
3993 .BR
3994 Syntax highlighting for
3995 .B SiSU
3996 markup is available for a number of text editors.
3997
3998 .BR
3999
4000 .B SiSU
4001 is less about document layout than about finding a way with little markup to be
4002 able to construct an abstract representation of a document that makes it
4003 possible to produce multiple representations of it which may be rather
4004 different from each other and used for different purposes, whether layout and
4005 publishing, or search of content
4006
4007 .BR
4008 i.e. to be able to take advantage from this minimal preparation starting point
4009 of some of the strengths of rather different established ways of representing
4010 documents for different purposes, whether for search (relational database, or
4011 indexed flat files generated for that purpose whether of complete documents, or
4012 say of files made up of objects), online viewing (e.g. html, xml, pdf) , or
4013 paper publication (e.g. pdf) ...
4014
4015 .BR
4016 the solution arrived at is by extracting structural information about the
4017 document (about headings within the document) and by tracking objects (which
4018 are serialized and also given hash values) in the manner described. It makes
4019 possible representations that are quite different from those offered at
4020 present. For example objects could be saved individually and identified by
4021 their hashes, with an index of how the objects relate to each other to form a
4022 document.
4023 .TP
4024 .BI *1.
4025 square brackets
4026
4027 .BR
4028 .TP
4029 .BI *2.
4030 square brackets
4031
4032 .BR
4033 .TP
4034 .BI +1.
4035 square brackets
4036
4037 .BR
4038 .TP
4039 .BI 1.
4040 <http://www.jus.uio.no/sisu/man/>
4041
4042 .BR
4043 .TP
4044 .BI 2.
4045 <http://www.jus.uio.no/sisu/man/sisu.1.html>
4046
4047 .BR
4048 .TP
4049 .BI 3.
4050 From sometime after SiSU 0.58 it should be possible to describe SiSU markup
4051 using SiSU, which though not an original design goal is useful.
4052
4053 .BR
4054 .TP
4055 .BI 4.
4056 files should be prepared using UTF-8 character encoding
4057
4058 .BR
4059 .TP
4060 .BI 5.
4061 a footnote or endnote
4062
4063 .BR
4064 .TP
4065 .BI 6.
4066 self contained endnote marker & endnote in one
4067
4068 .BR
4069 .TP
4070 .BI *.
4071 unnumbered asterisk footnote/endnote, insert multiple asterisks if required
4072
4073 .BR
4074 .TP
4075 .BI **.
4076 another unnumbered asterisk footnote/endnote
4077
4078 .BR
4079 .TP
4080 .BI *3.
4081 editors notes, numbered asterisk footnote/endnote series
4082
4083 .BR
4084 .TP
4085 .BI +2.
4086 editors notes, numbered plus symbol footnote/endnote series
4087
4088 .BR
4089 .TP
4090 .BI 7.
4091 <http://www.sisudoc.org/>
4092
4093 .BR
4094 .TP
4095 .BI 8.
4096 <http://www.ruby-lang.org/en/>
4097
4098 .BR
4099 .TP
4100 .BI 9.
4101 Table from the Wealth of Networks by Yochai Benkler
4102 <http://www.jus.uio.no/sisu/the_wealth_of_networks.yochai_benkler>
4103
4104 .BR
4105 .TP
4106 .BI 10.
4107 for which you may alternatively use the full form author: title: and year:
4108
4109 .BR
4110 .TP
4111 .BI 11.
4112 Quixote and Panza, Taming Windmills (1605), pp 1000 - 1001 also, Benkler, Wealth of Networks (2006), p 1
4113
4114 .BR
4115 .TP
4116 .BI 12.
4117 \.ssc (for composite) is under consideration but \._sst makes clear that this
4118 is not a regular file to be worked on, and thus less likely that people will
4119 have "accidents", working on a \.ssc file that is overwritten by subsequent
4120 processing. It may be however that when the resulting file is shared \.ssc is an
4121 appropriate suffix to use.
4122
4123 .BR
4124 .TP
4125 .BI 13.
4126 SiSU has worked this way in the past, though this was dropped as it was
4127 thought the complexity outweighed the flexibility, however, the balance was
4128 rather fine and this behaviour could be reinstated.
4129
4130 .BR
4131 .TP
4132 .BI 14.
4133 <http://www.postgresql.org/> <http://advocacy.postgresql.org/>
4134 <http://en.wikipedia.org/wiki/Postgresql>
4135
4136 .BR
4137 .TP
4138 .BI 15.
4139 <http://www.hwaci.com/sw/sqlite/> <http://en.wikipedia.org/wiki/Sqlite>
4140
4141 .BR
4142 .TP
4143 .BI 16.
4144 <http://search.sisudoc.org>
4145
4146 .BR
4147 .TP
4148 .BI 17.
4149 (which could be extended further with current back-end). As regards scaling
4150 of the database, it is as scalable as the database (here Postgresql) and
4151 hardware allow.
4152
4153 .BR
4154 .TP
4155 .BI 18.
4156 of this feature when demonstrated to an IBM software innovations evaluator
4157 in 2004 he said to paraphrase: this could be of interest to us. We have large
4158 document management systems, you can search hundreds of thousands of documents
4159 and we can tell you which documents meet your search criteria, but there is no
4160 way we can tell you without opening each document where within each your
4161 matches are found.
4162
4163 .BR
4164
4165 .TP
4166 .SH SEE ALSO
4167 sisu(1),
4168 sisu-epub(1),
4169 sisu-harvest(1),
4170 sisu-html(1),
4171 sisu-odf(1),
4172 sisu-pdf(1),
4173 sisu-pg(1),
4174 sisu-sqlite(1),
4175 sisu-txt(1).
4176 sisu_vim(7)
4177 .TP
4178 .SH HOMEPAGE
4179 More information about SiSU can be found at <http://www.sisudoc.org/> or <http://www.jus.uio.no/sisu/>
4180 .TP
4181 .SH SOURCE
4182 <http://git.sisudoc.org/>
4183 .TP
4184 .SH AUTHOR
4185 SiSU is written by Ralph Amissah <ralph@amissah.com>