documentation update !bibliography & !glossary
[software/sisu] / man / man1 / sisu.1
1 .TH "sisu" "1" "2014-02-05" "7.1.0" "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 (which are mutually
2372 exclusive): (i) manually preparing and marking up as regular text in sisu a
2373 list of references, this is treated as a regular document segment (and placed
2374 before endnotes if any); (ii) preparing a bibliography, marking a heading level
2375 1~!biblio (note the exclamation mark) and preparing a bibliography using
2376 various metadata tags including for author: title: year: a list of which is
2377 provided below, or; (iii) as an assistance in preparing a bibliography, marking
2378 a heading level 1~!biblio and tagging citations within footnotes for inclusion,
2379 identifying citations and having a parser attempt to extract them and build a
2380 bibliography of the citations provided.
2381
2382 .BR
2383 For the heading/section sequence: endnotes, bibliography then book index to
2384 occur, the name biblio or bibliography must be given to the bibliography
2385 section, like so:
2386 .nf
2387 1~!biblio~ [Note: heading marker::required title missing]
2388 .fi
2389
2390 .SH A MARKUP TAGGED METADATA BIBLIOGRAPHY SECTION
2391
2392
2393 .BR
2394 Here instead of writing your full citations directly in footnotes, each time
2395 you have new material to cite, you add it to your bibliography section (if it
2396 has not been added yet) providing the information you need against an available
2397 list of tags (provided below).
2398
2399 .BR
2400 The required tags are au: ti: and year: [^10] an short quick example might be
2401 as follows:
2402 .nf
2403 1~!biblio~ [Note: heading marker::required title missing]
2404
2405 au: von Hippel, E.
2406 ti: Perspective: User Toolkits for Innovation
2407 lng: (language)
2408 jo: Journal of Product Innovation Management
2409 vo: 18
2410 ed: (editor)
2411 yr: 2001
2412 note:
2413 sn: Hippel, /{User Toolkits}/ (2001)
2414 id: vHippel_2001
2415 % form:
2416
2417 au: Benkler, Yochai
2418 ti: The Wealth of Networks
2419 st: How Social Production Transforms Markets and Freedom
2420 lng: (language)
2421 pb: Harvard University Press
2422 edn: (edition)
2423 yr: 2006
2424 pl: U.S.
2425 url: http://cyber.law.harvard.edu/wealth_of_networks/Main_Page
2426 note:
2427 sn: Benkler, /{Wealth of Networks}/ (2006)
2428 id: Benkler2006
2429
2430 au: Quixote, Don; Panza, Sancho
2431 ti: Taming Windmills, Keeping True
2432 jo: Imaginary Journal
2433 yr: 1605
2434 url: https://en.wikipedia.org/wiki/Don_Quixote
2435 note: made up to provide an example of author markup for an article with two authors
2436 sn: Quixote & Panza, /{Taming Windmills}/ (1605)
2437 id: quixote1605
2438 .fi
2439
2440
2441 .BR
2442 Note that the section name !biblio (or !bibliography) is required for the
2443 bibliography to be treated specially as such, and placed after the
2444 auto-generated endnote section.
2445
2446 .BR
2447 Using this method, work goes into preparing the bibliography, the tags author
2448 or editor, year and title are required and will be used to sort the
2449 bibliography that is placed under the Bibliography section
2450
2451 .BR
2452 The metadata tags may include shortname (sn:) and id, if provided, which are
2453 used for substitution within text. Every time the given id is found within the
2454 text it will be replaced by the given short title of the work (it is for this
2455 reason the short title has sisu markup to italicize the title), it should work
2456 with any page numbers to be added, the short title should be one that can
2457 easily be used to look up the full description in the bibliography.
2458 .nf
2459 The following footnote~{ quixote1605, pp 1000 - 1001, also Benkler2006 p 1. }~
2460 .fi
2461
2462
2463 .BR
2464 would be presented as:
2465
2466 .BR
2467 Quixote and Panza,
2468 .I Taming Windmills
2469 (1605), pp 1000 - 1001 also, Benkler,
2470 .I Wealth of Networks,
2471 (2006) p 1 or rather[^11]
2472 .nf
2473 au: author Surname, FirstNames (if multiple semi-colon separator)
2474 (required unless editor to be used instead)
2475 ti: title (required)
2476 st: subtitle
2477 jo: journal
2478 vo: volume
2479 ed: editor (required if author not provided)
2480 tr: translator
2481 src: source (generic field where others are not appropriate)
2482 in: in (like src)
2483 pl: place/location (state, country)
2484 pb: publisher
2485 edn: edition
2486 yr: year (yyyy or yyyy-mm or yyyy-mm-dd) (required)
2487 pg: pages
2488 url: http://url
2489 note: note
2490 id: create_short_identifier e.g. authorSurnameYear
2491 (used in substitutions: when found within text will be
2492 replaced by the short name provided)
2493 sn: short name e.g. Author, /{short title}/, Year
2494 (used in substitutions: when an id is found within text
2495 the short name will be used to replace it)
2496 .fi
2497
2498 .SH TAGGING CITATIONS FOR INCLUSION IN THE BIBLIOGRAPHY
2499
2500
2501 .BR
2502 Here whenever you make a citation that you wish be included in the
2503 bibliography, you tag the citation as such using special delimiters (which are
2504 subsequently removed from the final text produced by sisu)
2505
2506 .BR
2507 Here you would write something like the following, either in regular text or a
2508 footnote
2509 .nf
2510 See .: Quixote, Don; Panza, Sancho /{Taming Windmills, Keeping True}/ (1605) :.
2511 .fi
2512
2513
2514 .BR
2515
2516 .B SiSU
2517 will parse for a number of patterns within the delimiters to try make out the
2518 authors, title, date etc. and from that create a Bibliography. This is more
2519 limited than the previously described method of preparing a tagged
2520 bibliography, and using an id within text to identify the work, which also
2521 lends itself to greater consistency.
2522 .SH GLOSSARY
2523
2524
2525 .BR
2526 Using the section name 1~!glossary results in the Glossary being treated
2527 specially as such, and placed after the auto-generated endnote section (before
2528 the bibliography/list of references if there is one).
2529
2530 .BR
2531 The Glossary is ordinary text marked up in a manner deemed suitable for that
2532 purpose. e.g. with the term in bold, possibly with a hanging indent.
2533 .nf
2534 1~!glossary~ [Note: heading marker::required title missing]
2535
2536 _0_1 *{GPL}* An abbreviation that stands for "General Purpose License." ...
2537
2538 _0_1 [provide your list of terms and definitions]
2539 .fi
2540
2541
2542 .BR
2543 In the given example the first line is not indented subsequent lines are by one
2544 level, and the term to be defined is in bold text.
2545 .SH BOOK INDEX
2546
2547
2548 .BR
2549 To make an index append to paragraph the book index term relates to it, using
2550 an equal sign and curly braces.
2551
2552 .BR
2553 Currently two levels are provided, a main term and if needed a sub-term.
2554 Sub-terms are separated from the main term by a colon.
2555 .nf
2556 Paragraph containing main term and sub-term.
2557 ={Main term:sub-term}
2558 .fi
2559
2560
2561 .BR
2562 The index syntax starts on a new line, but there should not be an empty line
2563 between paragraph and index markup.
2564
2565 .BR
2566 The structure of the resulting index would be:
2567 .nf
2568 Main term, 1
2569 sub-term, 1
2570 .fi
2571
2572
2573 .BR
2574 Several terms may relate to a paragraph, they are separated by a semicolon. If
2575 the term refers to more than one paragraph, indicate the number of paragraphs.
2576 .nf
2577 Paragraph containing main term, second term and sub-term.
2578 ={first term; second term: sub-term}
2579 .fi
2580
2581
2582 .BR
2583 The structure of the resulting index would be:
2584 .nf
2585 First term, 1,
2586 Second term, 1,
2587 sub-term, 1
2588 .fi
2589
2590
2591 .BR
2592 If multiple sub-terms appear under one paragraph, they are separated under the
2593 main term heading from each other by a pipe symbol.
2594 .nf
2595 Paragraph containing main term, second term and sub-term.
2596 ={Main term:
2597 sub-term+2|second sub-term;
2598 Another term
2599 }
2600
2601 A paragraph that continues discussion of the first sub-term
2602 .fi
2603
2604
2605 .BR
2606 The plus one in the example provided indicates the first sub-term spans one
2607 additional paragraph. The logical structure of the resulting index would be:
2608 .nf
2609 Main term, 1,
2610 sub-term, 1-3,
2611 second sub-term, 1,
2612 Another term, 1
2613 .fi
2614
2615 .SH COMPOSITE DOCUMENTS MARKUP
2616
2617
2618 .BR
2619 It is possible to build a document by creating a master document that requires
2620 other documents. The documents required may be complete documents that could be
2621 generated independently, or they could be markup snippets, prepared so as to be
2622 easily available to be placed within another text. If the calling document is a
2623 master document (built from other documents), it should be named with the
2624 suffix
2625 .B .ssm
2626 Within this document you would provide information on the other documents that
2627 should be included within the text. These may be other documents that would be
2628 processed in a regular way, or markup bits prepared only for inclusion within a
2629 master document
2630 .B .sst
2631 regular markup file, or
2632 .B .ssi
2633 (insert/information) A secondary file of the composite document is built prior
2634 to processing with the same prefix and the suffix
2635 .B ._sst
2636
2637 .BR
2638 basic markup for importing a document into a master document
2639 .nf
2640 << filename1.sst
2641
2642 << filename2.ssi
2643 .fi
2644
2645
2646 .BR
2647 The form described above should be relied on. Within the
2648 .I Vim
2649 editor it results in the text thus linked becoming hyperlinked to the document
2650 it is calling in which is convenient for editing.
2651 .SH SUBSTITUTIONS
2652
2653
2654 .BR
2655
2656 .B markup example:
2657 .nf
2658 The current Debian is ${debian_stable} the next debian will be ${debian_testing}
2659
2660 Configure substitution in _sisu/sisu_document_make
2661
2662 @make:
2663 :substitute: /${debian_stable}/,'*{Wheezy}*' /${debian_testing}/,'*{Jessie}*'
2664 .fi
2665
2666
2667 .BR
2668
2669 .B resulting output:
2670
2671 .BR
2672 The current
2673 .B Debian
2674 is
2675 .B Jessie
2676 the next debian will be
2677 .B Stretch
2678
2679 .BR
2680 Configure substitution in _sisu/sisu_document_make
2681 .SH SISU FILETYPES
2682
2683
2684 .BR
2685
2686 .B SiSU
2687 has
2688 .I plaintext
2689 and binary filetypes, and can process either type of document.
2690 .SH .SST .SSM .SSI MARKED UP PLAIN TEXT
2691
2692 .TP
2693 .B SiSU
2694 documents are prepared as plain-text (utf-8) files with
2695 .B SiSU
2696 markup. They may make reference to and contain images (for example), which are
2697 stored in the directory beneath them _sisu/image. 〔b¤SiSU
2698 .I plaintext
2699 markup files are of three types that may be distinguished by the file extension
2700 used: regular text .sst; master documents, composite documents that incorporate
2701 other text, which can be any regular text or text insert; and inserts the
2702 contents of which are like regular text except these are marked .ssi and are
2703 not processed.
2704
2705 .BR
2706
2707 .B SiSU
2708 processing can be done directly against a sisu documents; which may be located
2709 locally or on a remote server for which a url is provided.
2710
2711 .BR
2712
2713 .B SiSU
2714 source markup can be shared with the command:
2715
2716 .BR
2717 sisu -s [filename]
2718 .SH SISU TEXT - REGULAR FILES (.SST)
2719
2720
2721 .BR
2722 The most common form of document in
2723 .B SiSU,
2724 see the section on
2725 .B SiSU
2726 markup.
2727 .SH SISU MASTER FILES (.SSM)
2728
2729
2730 .BR
2731 Composite documents which incorporate other
2732 .B SiSU
2733 documents which may be either regular
2734 .B SiSU
2735 text .sst which may be generated independently, or inserts prepared solely for
2736 the purpose of being incorporated into one or more master documents.
2737
2738 .BR
2739 The mechanism by which master files incorporate other documents is described as
2740 one of the headings under under
2741 .B SiSU
2742 markup in the
2743 .B SiSU
2744 manual.
2745
2746 .BR
2747 Note: Master documents may be prepared in a similar way to regular documents,
2748 and processing will occur normally if a .sst file is renamed .ssm without
2749 requiring any other documents; the .ssm marker flags that the document may
2750 contain other documents.
2751
2752 .BR
2753 Note: a secondary file of the composite document is built prior to processing
2754 with the same prefix and the suffix ._sst [^12]
2755 .SH SISU INSERT FILES (.SSI)
2756
2757
2758 .BR
2759 Inserts are documents prepared solely for the purpose of being incorporated
2760 into one or more master documents. They resemble regular
2761 .B SiSU
2762 text files (.sst). Since sisu -5.5.0 (6.1.0) .ssi files can like .ssm files
2763 include other .sst or .ssm files. .ssi files cannot be called by the sisu
2764 processor directly and can only be incorporated in other documents. Making a
2765 file a .ssi file is a quick and convenient way of breaking up a document that
2766 is to be included in a master document, and flagging that the file to be
2767 incorporated .ssi is not intended that the file should be processed on its own.
2768 .SH SISUPOD, ZIPPED BINARY CONTAINER (SISUPOD.ZIP, .SSP)
2769
2770
2771 .BR
2772 A sisupod is a zipped
2773 .B SiSU
2774 text file or set of
2775 .B SiSU
2776 text files and any associated images that they contain (this will be extended
2777 to include sound and multimedia-files)
2778 .TP
2779 .B SiSU
2780 .I plaintext
2781 files rely on a recognised directory structure to find contents such as images
2782 associated with documents, but all images for example for all documents
2783 contained in a directory are located in the sub-directory _sisu/image. Without
2784 the ability to create a sisupod it can be inconvenient to manually identify all
2785 other files associated with a document. A sisupod automatically bundles all
2786 associated files with the document that is turned into a pod.
2787
2788 .BR
2789 The structure of the sisupod is such that it may for example contain a single
2790 document and its associated images; a master document and its associated
2791 documents and anything else; or the zipped contents of a whole directory of
2792 prepared
2793 .B SiSU
2794 documents.
2795
2796 .BR
2797 The command to create a sisupod is:
2798
2799 .BR
2800 sisu -S [filename]
2801
2802 .BR
2803 Alternatively, make a pod of the contents of a whole directory:
2804
2805 .BR
2806 sisu -S
2807
2808 .BR
2809
2810 .B SiSU
2811 processing can be done directly against a sisupod; which may be located locally
2812 or on a remote server for which a url is provided.
2813
2814 .BR
2815 <http://www.sisudoc.org/sisu/sisu_commands>
2816
2817 .BR
2818 <http://www.sisudoc.org/sisu/sisu_manual>
2819 .SH CONFIGURATION
2820
2821 .SH CONFIGURATION FILES
2822
2823 .SH CONFIG.YML
2824
2825
2826 .BR
2827
2828 .B SiSU
2829 configration parameters are adjusted in the configuration file, which can be
2830 used to override the defaults set. This includes such things as which directory
2831 interim processing should be done in and where the generated output should be
2832 placed.
2833
2834 .BR
2835 The
2836 .B SiSU
2837 configuration file is a yaml file, which means indentation is significant.
2838
2839 .BR
2840
2841 .B SiSU
2842 resource configuration is determined by looking at the following files if they
2843 exist:
2844
2845 .BR
2846 ./_sisu/v7/sisurc.yml
2847
2848 .BR
2849 ./_sisu/sisurc.yml
2850
2851 .BR
2852 ~/.sisu/v7/sisurc.yml
2853
2854 .BR
2855 ~/.sisu/sisurc.yml
2856
2857 .BR
2858 /etc/sisu/v7/sisurc.yml
2859
2860 .BR
2861 /etc/sisu/sisurc.yml
2862
2863 .BR
2864 The search is in the order listed, and the first one found is used.
2865
2866 .BR
2867 In the absence of instructions in any of these it falls back to the internal
2868 program defaults.
2869
2870 .BR
2871 Configuration determines the output and processing directories and the database
2872 access details.
2873
2874 .BR
2875 If
2876 .B SiSU
2877 is installed a sample sisurc.yml may be found in /etc/sisu/sisurc.yml
2878 .SH SISU_DOCUMENT_MAKE
2879
2880
2881 .BR
2882 Most sisu document headers relate to metadata, the exception is the @make:
2883 header which provides processing related information. The default contents of
2884 the @make header may be set by placing them in a file sisu_document_make.
2885
2886 .BR
2887 The search order is as for resource configuration:
2888
2889 .BR
2890 ./_sisu/v7/sisu_document_make
2891
2892 .BR
2893 ./_sisu/sisu_document_make
2894
2895 .BR
2896 ~/.sisu/v7/sisu_document_make
2897
2898 .BR
2899 ~/.sisu/sisu_document_make
2900
2901 .BR
2902 /etc/sisu/v7/sisu_document_make
2903
2904 .BR
2905 /etc/sisu/sisu_document_make
2906
2907 .BR
2908 A sample sisu_document_make can be found in the _sisu/ directory under along
2909 with the provided sisu markup samples.
2910 .SH CSS - CASCADING STYLE SHEETS (FOR HTML, XHTML AND XML)
2911
2912
2913 .BR
2914 CSS files to modify the appearance of
2915 .B SiSU
2916 html,
2917 .I XHTML
2918 or
2919 .I XML
2920 may be placed in the configuration directory: ./_sisu/css ; ~/.sisu/css or;
2921 /etc/sisu/css and these will be copied to the output directories with the
2922 command sisu -CC.
2923
2924 .BR
2925 The basic CSS file for html output is html. css, placing a file of that name in
2926 directory _sisu/css or equivalent will result in the default file of that name
2927 being overwritten.
2928
2929 .BR
2930
2931 .I HTML:
2932 html. css
2933
2934 .BR
2935
2936 .I XML
2937 DOM: dom.css
2938
2939 .BR
2940
2941 .I XML
2942 SAX: sax.css
2943
2944 .BR
2945
2946 .I XHTML:
2947 xhtml. css
2948
2949 .BR
2950 The default homepage may use homepage.css or html. css
2951
2952 .BR
2953 Under consideration is to permit the placement of a CSS file with a different
2954 name in directory _sisu/css directory or equivalent.[^13]
2955 .SH ORGANISING CONTENT - DIRECTORY STRUCTURE AND MAPPING
2956
2957
2958 .BR
2959
2960 .B SiSU
2961 v3 has new options for the source directory tree, and output directory
2962 structures of which there are 3 alternatives.
2963 .SH DOCUMENT SOURCE DIRECTORY
2964
2965
2966 .BR
2967 The document source directory is the directory in which sisu processing
2968 commands are given. It contains the sisu source files (.sst .ssm .ssi), or (for
2969 sisu v3 may contain) subdirectories with language codes which contain the sisu
2970 source files, so all English files would go in subdirectory en/, French in fr/,
2971 Spanish in es/ and so on. ISO 639-1 codes are used (as varied by po4a). A list
2972 of available languages (and possible sub-directory names) can be obtained with
2973 the command "sisu --help lang" The list of languages is limited to langagues
2974 supported by XeTeX polyglosia.
2975 .SH GENERAL DIRECTORIES
2976
2977 .nf
2978 ./subject_name/
2979
2980 % files stored at this level e.g. sisu_manual.sst or
2981 % for sisu v3 may be under language sub-directories
2982 % e.g.
2983
2984 ./subject_name/en
2985
2986 ./subject_name/fr
2987
2988 ./subject_name/es
2989
2990 ./subject_name/_sisu
2991
2992 ./subject_name/_sisu/css
2993
2994 ./subject_name/_sisu/image
2995 .fi
2996
2997 .SH DOCUMENT OUTPUT DIRECTORY STRUCTURES
2998
2999 .SH OUTPUT DIRECTORY ROOT
3000
3001
3002 .BR
3003 The output directory root can be set in the sisurc.yml file. Under the root,
3004 subdirectories are made for each directory in which a document set resides. If
3005 you have a directory named poems or conventions, that directory will be created
3006 under the output directory root and the output for all documents contained in
3007 the directory of a particular name will be generated to subdirectories beneath
3008 that directory (poem or conventions). A document will be placed in a
3009 subdirectory of the same name as the document with the filetype identifier
3010 stripped (.sst .ssm)
3011
3012 .BR
3013 The last part of a directory path, representing the sub-directory in which a
3014 document set resides, is the directory name that will be used for the output
3015 directory. This has implications for the organisation of document collections
3016 as it could make sense to place documents of a particular subject, or type
3017 within a directory identifying them. This grouping as suggested could be by
3018 subject (sales_law, english_literature); or just as conveniently by some other
3019 classification (X University). The mapping means it is also possible to place
3020 in the same output directory documents that are for organisational purposes
3021 kept separately, for example documents on a given subject of two different
3022 institutions may be kept in two different directories of the same name, under a
3023 directory named after each institution, and these would be output to the same
3024 output directory. Skins could be associated with each institution on a
3025 directory basis and resulting documents will take on the appropriate different
3026 appearance.
3027 .SH ALTERNATIVE OUTPUT STRUCTURES
3028
3029
3030 .BR
3031 There are 3 possibile output structures described as being, by language, by
3032 filetype or by filename, the selection is made in sisurc.yml
3033 .nf
3034 #% output_dir_structure_by: language; filetype; or filename
3035 output_dir_structure_by: language #(language & filetype, preferred?)
3036 #output_dir_structure_by: filetype
3037 #output_dir_structure_by: filename #(default, closest to original v1 & v2)
3038 .fi
3039
3040 .SH BY LANGUAGE
3041
3042
3043 .BR
3044 The by language directory structure places output files
3045
3046 .BR
3047 The by language directory structure separates output files by language code
3048 (all files of a given language), and within the language directory by filetype.
3049
3050 .BR
3051 Its selection is configured in sisurc.yml
3052
3053 .BR
3054 output_dir_structure_by: language
3055 .nf
3056 |-- en
3057 |-- epub
3058 |-- hashes
3059 |-- html
3060 | |-- viral_spiral.david_bollier
3061 | |-- manifest
3062 | |-- qrcode
3063 | |-- odt
3064 | |-- pdf
3065 | |-- sitemaps
3066 | |-- txt
3067 | |-- xhtml
3068 | `-- xml
3069 |-- po4a
3070 | `-- live-manual
3071 | |-- po
3072 | |-- fr
3073 | `-- pot
3074 `-- _sisu
3075 |-- css
3076 |-- image
3077 |-- image_sys -> ../../_sisu/image_sys
3078 `-- xml
3079 |-- rnc
3080 |-- rng
3081 `-- xsd
3082 .fi
3083
3084
3085 .BR
3086 #by: language subject_dir/en/manifest/filename.html
3087 .SH BY FILETYPE
3088
3089
3090 .BR
3091 The by filetype directory structure separates output files by filetype, all
3092 html files in one directory pdfs in another and so on. Filenames are given a
3093 language extension.
3094
3095 .BR
3096 Its selection is configured in sisurc.yml
3097
3098 .BR
3099 output_dir_structure_by: filetype
3100 .nf
3101 |-- epub
3102 |-- hashes
3103 |-- html
3104 |-- viral_spiral.david_bollier
3105 |-- manifest
3106 |-- qrcode
3107 |-- odt
3108 |-- pdf
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 |-- txt
3124 |-- xhtml
3125 `-- xml
3126 .fi
3127
3128
3129 .BR
3130 #by: filetype subject_dir/html/filename/manifest.en.html
3131 .SH BY FILENAME
3132
3133
3134 .BR
3135 The by filename directory structure places most output of a particular file
3136 (the different filetypes) in a common directory.
3137
3138 .BR
3139 Its selection is configured in sisurc.yml
3140
3141 .BR
3142 output_dir_structure_by: filename
3143 .nf
3144 |-- epub
3145 |-- po4a
3146 |-- live-manual
3147 | |-- po
3148 | |-- fr
3149 | `-- pot
3150 |-- _sisu
3151 | |-- css
3152 | |-- image
3153 | |-- image_sys -> ../../_sisu/image_sys
3154 | `-- xml
3155 | |-- rnc
3156 | |-- rng
3157 | `-- xsd
3158 |-- sitemaps
3159 |-- src
3160 |-- pod
3161 `-- viral_spiral.david_bollier
3162 .fi
3163
3164
3165 .BR
3166 #by: filename subject_dir/filename/manifest.en.html
3167 .SH REMOTE DIRECTORIES
3168
3169 .nf
3170 ./subject_name/
3171
3172 % containing sub_directories named after the generated files from which they are made
3173
3174 ./subject_name/src
3175
3176 % contains shared source files text and binary e.g. sisu_manual.sst and sisu_manual.sst.zip
3177
3178 ./subject_name/_sisu
3179
3180 % configuration file e.g. sisurc.yml
3181
3182 ./subject_name/_sisu/skin
3183
3184 % skins in various skin directories doc, dir, site, yml
3185
3186 ./subject_name/_sisu/css
3187
3188 ./subject_name/_sisu/image
3189
3190 % images for documents contained in this directory
3191
3192 ./subject_name/_sisu/mm
3193 .fi
3194
3195 .SH SISUPOD
3196
3197 .nf
3198 ./sisupod/
3199
3200 % files stored at this level e.g. sisu_manual.sst
3201
3202 ./sisupod/_sisu
3203
3204 % configuration file e.g. sisurc.yml
3205
3206 ./sisupod/_sisu/skin
3207
3208 % skins in various skin directories doc, dir, site, yml
3209
3210 ./sisupod/_sisu/css
3211
3212 ./sisupod/_sisu/image
3213
3214 % images for documents contained in this directory
3215
3216 ./sisupod/_sisu/mm
3217 .fi
3218
3219 .SH HOMEPAGES
3220
3221
3222 .BR
3223
3224 .B SiSU
3225 is about the ability to auto-generate documents. Home pages are regarded as
3226 custom built items, and are not created by
3227 .B SiSU.
3228 More accurately,
3229 .B SiSU
3230 has a default home page, which will not be appropriate for use with other
3231 sites, and the means to provide your own home page instead in one of two ways
3232 as part of a site's configuration, these being:
3233
3234 .BR
3235 1. through placing your home page and other custom built documents in the
3236 subdirectory _sisu/home/ (this probably being the easier and more convenient
3237 option)
3238
3239 .BR
3240 2. through providing what you want as the home page in a skin,
3241
3242 .BR
3243 Document sets are contained in directories, usually organised by site or
3244 subject. Each directory can/should have its own homepage. See the section on
3245 directory structure and organisation of content.
3246 .SH HOME PAGE AND OTHER CUSTOM BUILT PAGES IN A SUB-DIRECTORY
3247
3248
3249 .BR
3250 Custom built pages, including the home page index.html may be placed within the
3251 configuration directory _sisu/home/ in any of the locations that is searched
3252 for the configuration directory, namely ./_sisu ; ~/_sisu ; /etc/sisu From
3253 there they are copied to the root of the output directory with the command:
3254
3255 .BR
3256 sisu -CC
3257 .SH MARKUP AND OUTPUT EXAMPLES
3258
3259 .SH MARKUP EXAMPLES
3260
3261
3262 .BR
3263 Current markup examples and document output samples are provided off
3264 <http://sisudoc.org> or <http://www.jus.uio.no/sisu> and in the sisu
3265 -markup-sample package available off <http://git.sisudoc.org>
3266
3267 .BR
3268 For some documents hardly any markup at all is required at all, other than a
3269 header, and an indication that the levels to be taken into account by the
3270 program in generating its output are.
3271 .SH SISU MARKUP SAMPLES
3272
3273
3274 .BR
3275 A few additional sample books prepared as sisu markup samples, output formats
3276 to be generated using
3277 .B SiSU
3278 are contained in a separate package sisu -markup-samples. sisu -markup-samples
3279 contains books (prepared using sisu markup), that were released by their
3280 authors various licenses mostly different Creative Commons licences that do not
3281 permit inclusion in the
3282 .B Debian
3283 Project as they have requirements that do not meet the
3284 .B Debian
3285 Free Software Guidelines for various reasons, most commonly that they require
3286 that the original substantive text remain unchanged, and sometimes that the
3287 works be used only non-commercially.
3288
3289 .BR
3290
3291 .I Accelerando,
3292 Charles Stross (2005)
3293 accelerando.charles_stross.sst
3294
3295 .BR
3296
3297 .I Alice's Adventures in Wonderland,
3298 Lewis Carroll (1865)
3299 alices_adventures_in_wonderland.lewis_carroll.sst
3300
3301 .BR
3302
3303 .I CONTENT,
3304 Cory Doctorow (2008)
3305 content.cory_doctorow.sst
3306
3307 .BR
3308
3309 .I Democratizing Innovation,
3310 Eric von Hippel (2005)
3311 democratizing_innovation.eric_von_hippel.sst
3312
3313 .BR
3314
3315 .I Down and Out in the Magic Kingdom,
3316 Cory Doctorow (2003)
3317 down_and_out_in_the_magic_kingdom.cory_doctorow.sst
3318
3319 .BR
3320
3321 .I For the Win,
3322 Cory Doctorow (2010)
3323 for_the_win.cory_doctorow.sst
3324
3325 .BR
3326
3327 .I Free as in Freedom - Richard Stallman's Crusade for Free Software,
3328 Sam Williams (2002)
3329 free_as_in_freedom.richard_stallman_crusade_for_free_software.sam_williams.sst
3330
3331 .BR
3332
3333 .I Free as in Freedom 2.0 - Richard Stallman and the Free Software Revolution,
3334 Sam Williams (2002), Richard M. Stallman (2010)
3335 free_as_in_freedom_2.richard_stallman_and_the_free_software_revolution.sam_williams.richard_stallman.sst
3336
3337 .BR
3338
3339 .I Free Culture - How Big Media Uses Technology and the Law to Lock Down
3340 Culture and Control Creativity,
3341 Lawrence Lessig (2004)
3342 free_culture.lawrence_lessig.sst
3343
3344 .BR
3345
3346 .I Free For All - How Linux and the Free Software Movement Undercut the High
3347 Tech Titans,
3348 Peter Wayner (2002)
3349 free_for_all.peter_wayner.sst
3350
3351 .BR
3352
3353 .I GNU GENERAL PUBLIC LICENSE v2,
3354 Free Software Foundation (1991)
3355 gpl2.fsf.sst
3356
3357 .BR
3358
3359 .I GNU GENERAL PUBLIC LICENSE v3,
3360 Free Software Foundation (2007)
3361 gpl3.fsf.sst
3362
3363 .BR
3364
3365 .I Gulliver's Travels,
3366 Jonathan Swift (1726 / 1735)
3367 gullivers_travels.jonathan_swift.sst
3368
3369 .BR
3370
3371 .I Little Brother,
3372 Cory Doctorow (2008)
3373 little_brother.cory_doctorow.sst
3374
3375 .BR
3376
3377 .I The Cathederal and the Bazaar,
3378 Eric Raymond (2000)
3379 the_cathedral_and_the_bazaar.eric_s_raymond.sst
3380
3381 .BR
3382
3383 .I The Public Domain - Enclosing the Commons of the Mind,
3384 James Boyle (2008)
3385 the_public_domain.james_boyle.sst
3386
3387 .BR
3388
3389 .I The Wealth of Networks - How Social Production Transforms Markets and
3390 Freedom,
3391 Yochai Benkler (2006)
3392 the_wealth_of_networks.yochai_benkler.sst
3393
3394 .BR
3395
3396 .I Through the Looking Glass,
3397 Lewis Carroll (1871)
3398 through_the_looking_glass.lewis_carroll.sst
3399
3400 .BR
3401
3402 .I Two Bits - The Cultural Significance of Free Software,
3403 Christopher Kelty (2008)
3404 two_bits.christopher_kelty.sst
3405
3406 .BR
3407
3408 .I UN Contracts for International Sale of Goods,
3409 UN (1980)
3410 un_contracts_international_sale_of_goods_convention_1980.sst
3411
3412 .BR
3413
3414 .I Viral Spiral,
3415 David Bollier (2008)
3416 viral_spiral.david_bollier.sst
3417 .SH SISU SEARCH - INTRODUCTION
3418
3419
3420 .BR
3421
3422 .B SiSU
3423 output can easily and conveniently be indexed by a number of standalone
3424 indexing tools, such as Lucene, Hyperestraier.
3425
3426 .BR
3427 Because the document structure of sites created is clearly defined, and the
3428 text
3429 .I object citation system
3430 is available hypothetically at least, for all forms of output, it is possible
3431 to search the sql database, and either read results from that database, or map
3432 the results to the html or other output, which has richer text markup.
3433
3434 .BR
3435
3436 .B SiSU
3437 can populate a relational sql type database with documents at an object level,
3438 including objects numbers that are shared across different output types. Making
3439 a document corpus searchable with that degree of granularity. Basically, your
3440 match criteria is met by these documents and at these locations within each
3441 document, which can be viewed within the database directly or in various output
3442 formats.
3443 .SH SQL
3444
3445 .SH POPULATING SQL TYPE DATABASES
3446
3447
3448 .BR
3449
3450 .B SiSU
3451 feeds sisu markupd documents into sql type databases
3452 .I PostgreSQL
3453 [^14] and/or
3454 .I SQLite
3455 [^15] database together with information related to document structure.
3456
3457 .BR
3458 This is one of the more interesting output forms, as all the structural data of
3459 the documents are retained (though can be ignored by the user of the database
3460 should they so choose). All site texts/documents are (currently) streamed to
3461 four tables:
3462
3463 .BR
3464 * one containing semantic (and other) headers, including, title, author,
3465 subject, (the
3466 .I Dublin Core.
3467 ..);
3468
3469 .BR
3470 * another the substantive texts by individual "paragraph" (or object) - along
3471 with structural information, each paragraph being identifiable by its
3472 paragraph number (if it has one which almost all of them do), and the
3473 substantive text of each paragraph quite naturally being searchable (both in
3474 formatted and clean text versions for searching); and
3475
3476 .BR
3477 * a third containing endnotes cross-referenced back to the paragraph from
3478 which they are referenced (both in formatted and clean text versions for
3479 searching).
3480
3481 .BR
3482 * a fourth table with a one to one relation with the headers table contains
3483 full text versions of output, eg. pdf, html, xml, and
3484 .I ascii.
3485
3486 .BR
3487 There is of course the possibility to add further structures.
3488
3489 .BR
3490 At this level
3491 .B SiSU
3492 loads a relational database with documents chunked into objects, their smallest
3493 logical structurally constituent parts, as text objects, with their object
3494 citation number and all other structural information needed to construct the
3495 document. Text is stored (at this text object level) with and without
3496 elementary markup tagging, the stripped version being so as to facilitate ease
3497 of searching.
3498
3499 .BR
3500 Being able to search a relational database at an object level with the
3501 .B SiSU
3502 citation system is an effective way of locating content generated by
3503 .B SiSU.
3504 As individual text objects of a document stored (and indexed) together with
3505 object numbers, and all versions of the document have the same numbering,
3506 complex searches can be tailored to return just the locations of the search
3507 results relevant for all available output formats, with live links to the
3508 precise locations in the database or in html/xml documents; or, the structural
3509 information provided makes it possible to search the full contents of the
3510 database and have headings in which search content appears, or to search only
3511 headings etc. (as the
3512 .I Dublin Core
3513 is incorporated it is easy to make use of that as well).
3514 .SH POSTGRESQL
3515
3516 .SH NAME
3517
3518
3519 .BR
3520
3521 .B SiSU
3522 - Structured information, Serialized Units - a document publishing system,
3523 postgresql dependency package
3524 .SH DESCRIPTION
3525
3526
3527 .BR
3528 Information related to using postgresql with sisu (and related to the
3529 sisu_postgresql dependency package, which is a dummy package to install
3530 dependencies needed for
3531 .B SiSU
3532 to populate a postgresql database, this being part of
3533 .B SiSU
3534 - man sisu) .
3535 .SH SYNOPSIS
3536
3537
3538 .BR
3539 sisu -D [instruction] [filename/wildcard if required]
3540
3541 .BR
3542 sisu -D --pg --[instruction] [filename/wildcard if required]
3543 .SH COMMANDS
3544
3545
3546 .BR
3547 Mappings to two databases are provided by default, postgresql and sqlite, the
3548 same commands are used within sisu to construct and populate databases however
3549 -d (lowercase) denotes sqlite and -D (uppercase) denotes postgresql,
3550 alternatively --sqlite or --pgsql may be used
3551
3552 .BR
3553
3554 .B -D or --pgsql
3555 may be used interchangeably.
3556 .SH CREATE AND DESTROY DATABASE
3557
3558 .TP
3559 .B --pgsql --createall
3560 initial step, creates required relations (tables, indexes) in existing
3561 (postgresql) database (a database should be created manually and given the same
3562 name as working directory, as requested) (rb.dbi)
3563 .TP
3564 .B sisu -D --createdb
3565 creates database where no database existed before
3566 .TP
3567 .B sisu -D --create
3568 creates database tables where no database tables existed before
3569 .TP
3570 .B sisu -D --Dropall
3571 destroys database (including all its content)! kills data and drops tables,
3572 indexes and database associated with a given directory (and directories of the
3573 same name).
3574 .TP
3575 .B sisu -D --recreate
3576 destroys existing database and builds a new empty database structure
3577 .SH IMPORT AND REMOVE DOCUMENTS
3578
3579 .TP
3580 .B sisu -D --import -v [filename/wildcard]
3581 populates database with the contents of the file. Imports documents(s)
3582 specified to a postgresql database (at an object level).
3583 .TP
3584 .B sisu -D --update -v [filename/wildcard]
3585 updates file contents in database
3586 .TP
3587 .B sisu -D --remove -v [filename/wildcard]
3588 removes specified document from postgresql database.
3589 .SH SQLITE
3590
3591 .SH NAME
3592
3593
3594 .BR
3595
3596 .B SiSU
3597 - Structured information, Serialized Units - a document publishing system.
3598 .SH DESCRIPTION
3599
3600
3601 .BR
3602 Information related to using sqlite with sisu (and related to the sisu_sqlite
3603 dependency package, which is a dummy package to install dependencies needed for
3604 .B SiSU
3605 to populate an sqlite database, this being part of
3606 .B SiSU
3607 - man sisu) .
3608 .SH SYNOPSIS
3609
3610
3611 .BR
3612 sisu -d [instruction] [filename/wildcard if required]
3613
3614 .BR
3615 sisu -d --(sqlite|pg) --[instruction] [filename/wildcard if required]
3616 .SH COMMANDS
3617
3618
3619 .BR
3620 Mappings to two databases are provided by default, postgresql and sqlite, the
3621 same commands are used within sisu to construct and populate databases however
3622 -d (lowercase) denotes sqlite and -D (uppercase) denotes postgresql,
3623 alternatively --sqlite or --pgsql may be used
3624
3625 .BR
3626
3627 .B -d or --sqlite
3628 may be used interchangeably.
3629 .SH CREATE AND DESTROY DATABASE
3630
3631 .TP
3632 .B --sqlite --createall
3633 initial step, creates required relations (tables, indexes) in existing (sqlite)
3634 database (a database should be created manually and given the same name as
3635 working directory, as requested) (rb.dbi)
3636 .TP
3637 .B sisu -d --createdb
3638 creates database where no database existed before
3639 .TP
3640 .B sisu -d --create
3641 creates database tables where no database tables existed before
3642 .TP
3643 .B sisu -d --dropall
3644 destroys database (including all its content)! kills data and drops tables,
3645 indexes and database associated with a given directory (and directories of the
3646 same name).
3647 .TP
3648 .B sisu -d --recreate
3649 destroys existing database and builds a new empty database structure
3650 .SH IMPORT AND REMOVE DOCUMENTS
3651
3652 .TP
3653 .B sisu -d --import -v [filename/wildcard]
3654 populates database with the contents of the file. Imports documents(s)
3655 specified to an sqlite database (at an object level).
3656 .TP
3657 .B sisu -d --update -v [filename/wildcard]
3658 updates file contents in database
3659 .TP
3660 .B sisu -d --remove -v [filename/wildcard]
3661 removes specified document from sqlite database.
3662 .SH CGI SEARCH FORM
3663
3664 .SH SETUP SEARCH FORM
3665
3666
3667 .BR
3668 You will need a web server, httpd with cgi enabled, and a postgresql database
3669 to which you are able to create databases.
3670
3671 .BR
3672 Setup postgresql, make sure you are able to create and write to the database,
3673 e.g.:
3674 .nf
3675 sudo su postgres
3676 createuser -d -a ralph
3677 .fi
3678
3679
3680 .BR
3681 You then need to create the database that sisu will use, for sisu manual in the
3682 directory manual/en for example, (when you try to populate a database that does
3683 not exist sisu prompts as to whether it exists):
3684 .nf
3685 createdb SiSUv6a_manual
3686 .fi
3687
3688
3689 .BR
3690
3691 .B SiSU
3692 is then able to create the required tables that allow you to populate the
3693 database with documents in the directory for which it has been created:
3694 .nf
3695 sisu --pg --createall -v
3696 .fi
3697
3698
3699 .BR
3700 You can then start to populate the database, in this example with a single
3701 document:
3702 .nf
3703 sisu --pg --update -v en/sisu_manual.ssm
3704 .fi
3705
3706
3707 .BR
3708 To create a sample search form, from within the same directory run:
3709 .nf
3710 sisu --sample-search-form --db-pg
3711 .fi
3712
3713
3714 .BR
3715 and copy the resulting cgi form to your cgi-bin directory
3716
3717 .BR
3718 A sample setup for nginx is provided that assumes data will be stored under
3719 /srv/www and cgi scripts under /srv/cgi
3720 .SH SEARCH - DATABASE FRONTEND SAMPLE, UTILISING DATABASE AND SISU FEATURES,
3721 INCLUDING OBJECT CITATION NUMBERING (BACKEND CURRENTLY POSTGRESQL)
3722
3723
3724 .BR
3725 Sample search frontend <http://search.sisudoc.org> [^16] A small database and
3726 sample query front-end (search from) that makes use of the citation system, .I
3727 object citation numbering
3728 to demonstrates functionality.[^17]
3729
3730 .BR
3731
3732 .B SiSU
3733 can provide information on which documents are matched and at what locations
3734 within each document the matches are found. These results are relevant across
3735 all outputs using
3736 .I object citation numbering,
3737 which includes html,
3738 .I XML,
3739 .I EPUB,
3740 .I LaTeX,
3741 .I PDF
3742 and indeed the
3743 .I SQL
3744 database. You can then refer to one of the other outputs or in the
3745 .I SQL
3746 database expand the text within the matched objects (paragraphs) in the
3747 documents matched.
3748
3749 .BR
3750 Note you may set results either for documents matched and object number
3751 locations within each matched document meeting the search criteria; or display
3752 the names of the documents matched along with the objects (paragraphs) that
3753 meet the search criteria.[^18]
3754 .TP
3755 .B sisu -F --webserv-webrick
3756 builds a cgi web search frontend for the database created
3757
3758 .BR
3759 The following is feedback on the setup on a machine provided by the help
3760 command:
3761
3762 .BR
3763 sisu --help sql
3764 .nf
3765 Postgresql
3766 user: ralph
3767 current db set: SiSU_sisu
3768 port: 5432
3769 dbi connect: DBI:Pg:database=SiSU_sisu;port=5432
3770
3771 sqlite
3772 current db set: /home/ralph/sisu_www/sisu/sisu_sqlite.db
3773 dbi connect DBI:SQLite:/home/ralph/sisu_www/sisu/sisu_sqlite.db
3774 .fi
3775
3776
3777 .BR
3778 Note on databases built
3779
3780 .BR
3781 By default, [unless otherwise specified] databases are built on a directory
3782 basis, from collections of documents within that directory. The name of the
3783 directory you choose to work from is used as the database name, i.e. if you are
3784 working in a directory called /home/ralph/ebook the database SiSU_ebook is
3785 used. [otherwise a manual mapping for the collection is necessary]
3786 .SH SEARCH FORM
3787
3788 .TP
3789 .B sisu -F
3790 generates a sample search form, which must be copied to the web-server cgi
3791 directory
3792 .TP
3793 .B sisu -F --webserv-webrick
3794 generates a sample search form for use with the webrick server, which must be
3795 copied to the web-server cgi directory
3796 .TP
3797 .B sisu -W
3798 starts the webrick server which should be available wherever sisu is properly
3799 installed
3800
3801 .BR
3802 The generated search form must be copied manually to the webserver directory as
3803 instructed
3804 .SH SISU_WEBRICK
3805
3806 .SH NAME
3807
3808
3809 .BR
3810
3811 .B SiSU
3812 - Structured information, Serialized Units - a document publishing system
3813 .SH SYNOPSIS
3814
3815
3816 .BR
3817 sisu_webrick [port]
3818
3819 .BR
3820 or
3821
3822 .BR
3823 sisu -W [port]
3824 .SH DESCRIPTION
3825
3826
3827 .BR
3828 sisu_webrick is part of
3829 .B SiSU
3830 (man sisu) sisu_webrick starts
3831 .B Ruby
3832 ' s Webrick web-server and points it to the directories to which
3833 .B SiSU
3834 output is written, providing a list of these directories (assuming
3835 .B SiSU
3836 is in use and they exist).
3837
3838 .BR
3839 The default port for sisu_webrick is set to 8081, this may be modified in the
3840 yaml file: ~/.sisu/sisurc.yml a sample of which is provided as
3841 /etc/sisu/sisurc.yml (or in the equivalent directory on your system).
3842 .SH SUMMARY OF MAN PAGE
3843
3844
3845 .BR
3846 sisu_webrick, may be started on it's own with the command: sisu_webrick [port]
3847 or using the sisu command with the -W flag: sisu -W [port]
3848
3849 .BR
3850 where no port is given and settings are unchanged the default port is 8081
3851 .SH DOCUMENT PROCESSING COMMAND FLAGS
3852
3853
3854 .BR
3855 sisu -W [port] starts
3856 .B Ruby
3857 Webrick web-server, serving
3858 .B SiSU
3859 output directories, on the port provided, or if no port is provided and the
3860 defaults have not been changed in ~/.sisu/sisurc.yaml then on port 8081
3861 .SH SUMMARY OF FEATURES
3862
3863
3864 .BR
3865 * sparse/minimal markup (clean utf-8 source texts). Documents are prepared in a
3866 single
3867 .I UTF-8
3868 file using a minimalistic mnemonic syntax. Typical literature, documents like
3869 "War and Peace" require almost no markup, and most of the headers are optional.
3870
3871 .BR
3872 * markup is easily readable/parsable by the human eye, (basic markup is simpler
3873 and more sparse than the most basic
3874 .I HTML
3875 ) , [this may also be converted to
3876 .I XML
3877 representations of the same input/source document].
3878
3879 .BR
3880 * markup defines document structure (this may be done once in a header
3881 pattern-match description, or for heading levels individually); basic text
3882 attributes (bold, italics, underscore, strike-through etc.) as required; and
3883 semantic information related to the document (header information, extended
3884 beyond the Dublin core and easily further extended as required); the headers
3885 may also contain processing instructions.
3886 .B SiSU
3887 markup is primarily an abstraction of document structure and document metadata
3888 to permit taking advantage of the basic strengths of existing alternative
3889 practical standard ways of representing documents [be that browser viewing,
3890 paper publication, sql search etc.] (html, epub, xml, odf, latex, pdf, sql)
3891
3892 .BR
3893 * for output produces reasonably elegant output of established industry and
3894 institutionally accepted open standard formats.[3] takes advantage of the
3895 different strengths of various standard formats for representing documents,
3896 amongst the output formats currently supported are:
3897
3898 .BR
3899 *
3900 .I HTML
3901 - both as a single scrollable text and a segmented document
3902
3903 .BR
3904 *
3905 .I XHTML
3906
3907 .BR
3908 *
3909 .I EPUB
3910
3911 .BR
3912 *
3913 .I XML
3914 - both in sax and dom style xml structures for further development as required
3915
3916 .BR
3917 *
3918 .I ODT
3919 - Open Document Format text, the iso standard for document storage
3920
3921 .BR
3922 *
3923 .I LaTeX
3924 - used to generate pdf
3925
3926 .BR
3927 *
3928 .I PDF
3929 (via
3930 .I LaTeX
3931 )
3932
3933 .BR
3934 *
3935 .I SQL
3936 - population of an sql database (
3937 .I PostgreSQL
3938 or
3939 .I SQLite
3940 ) , (at the same object level that is used to cite text within a document)
3941
3942 .BR
3943 Also produces: concordance files; document content certificates (md5 or sha256
3944 digests of headings, paragraphs, images etc.) and html manifests (and sitemaps
3945 of content). (b) takes advantage of the strengths implicit in these very
3946 different output types, (e.g. PDFs produced using typesetting of
3947 .I LaTeX,
3948 databases populated with documents at an individual object/paragraph level,
3949 making possible
3950 .I granular search
3951 (and related possibilities))
3952
3953 .BR
3954 * ensuring content can be cited in a meaningful way regardless of selected
3955 output format. Online publishing (and publishing in multiple document formats)
3956 lacks a useful way of citing text internally within documents (important to
3957 academics generally and to lawyers) as page numbers are meaningless across
3958 browsers and formats. sisu seeks to provide a common way of pinpoint the text
3959 within a document, (which can be utilized for citation and by search engines).
3960 The outputs share a common numbering system that is meaningful (to man and
3961 machine) across all digital outputs whether paper, screen, or database
3962 oriented, (pdf,
3963 .I HTML,
3964 .I EPUB,
3965 xml, sqlite, postgresql) , this numbering system can be used to reference
3966 content.
3967
3968 .BR
3969 * Granular search within documents.
3970 .I SQL
3971 databases are populated at an object level (roughly headings, paragraphs,
3972 verse, tables) and become searchable with that degree of granularity, the
3973 output information provides the object/paragraph numbers which are relevant
3974 across all generated outputs; it is also possible to look at just the matching
3975 paragraphs of the documents in the database; [output indexing also work well
3976 with search indexing tools like hyperestraier].
3977
3978 .BR
3979 * long term maintainability of document collections in a world of changing
3980 formats, having a very sparsely marked-up source document base. there is a
3981 considerable degree of future-proofing, output representations are
3982 "upgradeable", and new document formats may be added. e.g. addition of odf
3983 (open document text) module in 2006, epub in 2009 and in future html5 output
3984 sometime in future, without modification of existing prepared texts
3985
3986 .BR
3987 *
3988 .I SQL
3989 search aside, documents are generated as required and static once generated.
3990
3991 .BR
3992 * documents produced are static files, and may be batch processed, this needs
3993 to be done only once but may be repeated for various reasons as desired
3994 (updated content, addition of new output formats, updated technology document
3995 presentations/representations)
3996
3997 .BR
3998 * document source (
3999 .I plaintext
4000 utf-8) if shared on the net may be used as input and processed locally to
4001 produce the different document outputs
4002
4003 .BR
4004 * document source may be bundled together (automatically) with associated
4005 documents (multiple language versions or master document with inclusions) and
4006 images and sent as a zip file called a sisupod, if shared on the net these too
4007 may be processed locally to produce the desired document outputs
4008
4009 .BR
4010 * generated document outputs may automatically be posted to remote sites.
4011
4012 .BR
4013 * for basic document generation, the only software dependency is
4014 .B Ruby,
4015 and a few standard Unix tools (this covers
4016 .I plaintext,
4017 .I HTML,
4018 .I EPUB,
4019 .I XML,
4020 .I ODF,
4021 .I LaTeX
4022 ) . To use a database you of course need that, and to convert the
4023 .I LaTeX
4024 generated to pdf, a latex processor like tetex or texlive.
4025
4026 .BR
4027 * as a developers tool it is flexible and extensible
4028
4029 .BR
4030 Syntax highlighting for
4031 .B SiSU
4032 markup is available for a number of text editors.
4033
4034 .BR
4035
4036 .B SiSU
4037 is less about document layout than about finding a way with little markup to be
4038 able to construct an abstract representation of a document that makes it
4039 possible to produce multiple representations of it which may be rather
4040 different from each other and used for different purposes, whether layout and
4041 publishing, or search of content
4042
4043 .BR
4044 i.e. to be able to take advantage from this minimal preparation starting point
4045 of some of the strengths of rather different established ways of representing
4046 documents for different purposes, whether for search (relational database, or
4047 indexed flat files generated for that purpose whether of complete documents, or
4048 say of files made up of objects), online viewing (e.g. html, xml, pdf) , or
4049 paper publication (e.g. pdf) ...
4050
4051 .BR
4052 the solution arrived at is by extracting structural information about the
4053 document (about headings within the document) and by tracking objects (which
4054 are serialized and also given hash values) in the manner described. It makes
4055 possible representations that are quite different from those offered at
4056 present. For example objects could be saved individually and identified by
4057 their hashes, with an index of how the objects relate to each other to form a
4058 document.
4059 .TP
4060 .BI *1.
4061 square brackets
4062
4063 .BR
4064 .TP
4065 .BI *2.
4066 square brackets
4067
4068 .BR
4069 .TP
4070 .BI +1.
4071 square brackets
4072
4073 .BR
4074 .TP
4075 .BI 1.
4076 <http://www.jus.uio.no/sisu/man/>
4077
4078 .BR
4079 .TP
4080 .BI 2.
4081 <http://www.jus.uio.no/sisu/man/sisu.1.html>
4082
4083 .BR
4084 .TP
4085 .BI 3.
4086 From sometime after SiSU 0.58 it should be possible to describe SiSU markup
4087 using SiSU, which though not an original design goal is useful.
4088
4089 .BR
4090 .TP
4091 .BI 4.
4092 files should be prepared using UTF-8 character encoding
4093
4094 .BR
4095 .TP
4096 .BI 5.
4097 a footnote or endnote
4098
4099 .BR
4100 .TP
4101 .BI 6.
4102 self contained endnote marker & endnote in one
4103
4104 .BR
4105 .TP
4106 .BI *.
4107 unnumbered asterisk footnote/endnote, insert multiple asterisks if required
4108
4109 .BR
4110 .TP
4111 .BI **.
4112 another unnumbered asterisk footnote/endnote
4113
4114 .BR
4115 .TP
4116 .BI *3.
4117 editors notes, numbered asterisk footnote/endnote series
4118
4119 .BR
4120 .TP
4121 .BI +2.
4122 editors notes, numbered plus symbol footnote/endnote series
4123
4124 .BR
4125 .TP
4126 .BI 7.
4127 <http://www.sisudoc.org/>
4128
4129 .BR
4130 .TP
4131 .BI 8.
4132 <http://www.ruby-lang.org/en/>
4133
4134 .BR
4135 .TP
4136 .BI 9.
4137 Table from the Wealth of Networks by Yochai Benkler
4138 <http://www.jus.uio.no/sisu/the_wealth_of_networks.yochai_benkler>
4139
4140 .BR
4141 .TP
4142 .BI 10.
4143 for which you may alternatively use the full form author: title: and year:
4144
4145 .BR
4146 .TP
4147 .BI 11.
4148 Quixote and Panza, Taming Windmills (1605), pp 1000 - 1001 also, Benkler, Wealth of Networks (2006), p 1
4149
4150 .BR
4151 .TP
4152 .BI 12.
4153 \.ssc (for composite) is under consideration but \._sst makes clear that this
4154 is not a regular file to be worked on, and thus less likely that people will
4155 have "accidents", working on a \.ssc file that is overwritten by subsequent
4156 processing. It may be however that when the resulting file is shared \.ssc is an
4157 appropriate suffix to use.
4158
4159 .BR
4160 .TP
4161 .BI 13.
4162 SiSU has worked this way in the past, though this was dropped as it was
4163 thought the complexity outweighed the flexibility, however, the balance was
4164 rather fine and this behaviour could be reinstated.
4165
4166 .BR
4167 .TP
4168 .BI 14.
4169 <http://www.postgresql.org/> <http://advocacy.postgresql.org/>
4170 <http://en.wikipedia.org/wiki/Postgresql>
4171
4172 .BR
4173 .TP
4174 .BI 15.
4175 <http://www.hwaci.com/sw/sqlite/> <http://en.wikipedia.org/wiki/Sqlite>
4176
4177 .BR
4178 .TP
4179 .BI 16.
4180 <http://search.sisudoc.org>
4181
4182 .BR
4183 .TP
4184 .BI 17.
4185 (which could be extended further with current back-end). As regards scaling
4186 of the database, it is as scalable as the database (here Postgresql) and
4187 hardware allow.
4188
4189 .BR
4190 .TP
4191 .BI 18.
4192 of this feature when demonstrated to an IBM software innovations evaluator
4193 in 2004 he said to paraphrase: this could be of interest to us. We have large
4194 document management systems, you can search hundreds of thousands of documents
4195 and we can tell you which documents meet your search criteria, but there is no
4196 way we can tell you without opening each document where within each your
4197 matches are found.
4198
4199 .BR
4200
4201 .TP
4202 .SH SEE ALSO
4203 sisu(1),
4204 sisu-epub(1),
4205 sisu-harvest(1),
4206 sisu-html(1),
4207 sisu-odf(1),
4208 sisu-pdf(1),
4209 sisu-pg(1),
4210 sisu-sqlite(1),
4211 sisu-txt(1).
4212 sisu_vim(7)
4213 .TP
4214 .SH HOMEPAGE
4215 More information about SiSU can be found at <http://www.sisudoc.org/> or <http://www.jus.uio.no/sisu/>
4216 .TP
4217 .SH SOURCE
4218 <http://git.sisudoc.org/>
4219 .TP
4220 .SH AUTHOR
4221 SiSU is written by Ralph Amissah <ralph@amissah.com>