Merge tag 'sisu_5.6.0' into debian/sid
[software/sisu] / README
1 SISU - README
2 =============
3
4 INTRODUCTION
5 ************
6
7 INTRODUCTION - WHAT IS SISU?
8 ----------------------------
9
10 *SiSU* is a lightweight markup based document creation and publishing framework
11 that is controlled from the command line. Prepare documents for *SiSU* using
12 your text editor of choice, then use *SiSU* to generate various output document
13 formats.
14
15 From a single lightly prepared document (plain-text /UTF-8/) sisu custom builds
16 several standard output formats which share a common (text object) numbering
17 system for citation of content within a document (that also has implications
18 for search). The sisu engine works with an abstraction of the document's
19 structure and content from which it is possible to generate different forms of
20 representation of the document. *SiSU* produces: plain-text, /HTML/, /XHTML/,
21 /XML/, /EPUB/, /ODF/: /ODT/ (Opendocument), /LaTeX/, /PDF/, and populates an
22 /SQL/ database (/PostgreSQL/ or /SQLite/) with text objects, roughly, paragraph
23 sized chunks so that document searches are done at this level of granularity.
24
25 Outputs share a common citation numbering system, associated with text objects
26 and any semantic meta-data provided about the document.
27
28 *SiSU* also provides concordance files, document content certificates and
29 manifests of generated output. Book indexes may be made.
30
31 Some document markup samples are provided in the package sisu -markup-samples.
32
33 Homepages:
34 * <http://www.sisudoc.org/>
35 * <http://www.jus.uio.no/sisu>
36
37 INSTALL OR RUN WITHOUT INSTALLATION
38 ***********************************
39
40 SOURCE TARBALL
41 --------------
42
43 RUN OFF SOURCE PACKAGE DIRECTORY TREE (WITHOUT INSTALLING)
44 ..........................................................
45
46 1. Download the latest source
47
48 2. Unpack the source
49
50 Provided you have *Ruby*, *SiSU* can be run without installation straight from
51 the source package directory tree. Run ruby against the full path to bin/sisu
52 (in the unzipped source package directory tree)
53
54 Note however, that additional external package dependencies, such as texlive
55 (for pdfs), sqlite3 or postgresql (for search) should you desire to use them
56 are not taken care of for you.
57
58 GEM INSTALL (WITH RAKE)
59 .......................
60
61 Gem install, you need to:
62
63 (i) create the gemspec; (ii) build the gem (from the gemspec); (iii) install
64 the gem
65
66 Provided you have ruby & rake, this can be done with the single command:
67
68 rake gem_create_build_install # (to build and install sisu v5 & sisu v6,
69 alias gemcbi)
70
71 separate gems are made/installed for sisu v5 & sisu v6 contained in source:
72
73 rake gem_create_build_install_stable # (to build and install sisu v5, alias
74 gem5cbi)
75
76 rake gem_create_build_install_unstable # (to build and install sisu v6, alias
77 gem6cbi)
78
79 for individual steps (create, build, install) see rake options, rake -T to
80 specify sisu version for sisu installed via gem
81
82 gem search sisu
83
84 sisu _5.6.0_ --version
85
86 sisu _6.2.1_ --version
87
88 to uninstall sisu installed via gem
89
90 sudo gem uninstall --verbose sisu
91
92 For a list of alternative actions you may type:
93
94 rake help
95
96 rake -T
97
98 Rake: <http://rake.rubyforge.org/> <http://rubyforge.org/frs/?group_id=50>
99
100 Rant: <http://make.rubyforge.org/> <http://rubyforge.org/frs/?group_id=615>
101
102 INSTALLATION WITH SETUP.RB
103 ..........................
104
105 It should also be possible to install sisu using setup.rb
106
107 this is a three step process, in the root directory of the unpacked *SiSU* as
108 root type:
109
110 ruby setup.rb config
111 ruby setup.rb setup
112 #[as root:]
113 ruby setup.rb install
114
115 further information:
116 <http://i.loveruby.net/en/projects/setup/>
117 <http://i.loveruby.net/en/projects/setup/doc/usage.html>
118
119 ruby setup.rb config && ruby setup.rb setup && sudo ruby setup.rb install
120
121 UNIX/LINUX DISTRIBUTION
122 -----------------------
123
124 A distribution install should take care of the dependencies of sisu for
125 producing various outputs.
126
127 DEBIAN
128 ......
129
130 *SiSU* is available off the *Debian* archives. It should necessary only to run
131 as root, Using apt-get:
132
133 apt-get update
134
135 apt get install sisu-complete
136
137 (all sisu dependencies should be taken care of)
138
139 If there are newer versions of *SiSU* upstream, they will be available by
140 adding the following to your sources list /etc/apt/sources.list
141
142 #/etc/apt/sources.list
143
144 deb http://www.jus.uio.no/sisu/archive unstable main non-free
145 deb-src http://www.jus.uio.no/sisu/archive unstable main non-free
146
147 The non-free section is for sisu markup samples provided, which contain
148 authored works the substantive text of which cannot be changed, and which as a
149 result do not meet the debian free software guidelines.
150
151 *SiSU* is developed on *Debian*, and packages are available for *Debian* that
152 take care of the dependencies encountered on installation.
153
154 The package is divided into the following components:
155
156 *sisu*, the base code, (the main package on which the others depend), without
157 any dependencies other than ruby (and for convenience the ruby webrick web
158 server), this generates a number of types of output on its own, other
159 packages provide additional functionality, and have their dependencies
160
161 *sisu-complete*, a dummy package that installs the whole of greater sisu as
162 described below, apart from sisu -examples
163
164 *sisu-pdf*, dependencies used by sisu to produce pdf from /LaTeX/ generated
165
166 *sisu-postgresql*, dependencies used by sisu to populate postgresql database
167 (further configuration is necessary)
168
169 *sisu-sqlite*, dependencies used by sisu to populate sqlite database
170
171 *sisu-markup-samples*, sisu markup samples and other miscellany (under
172 *Debian* Free Software Guidelines non-free)
173
174 *SiSU* is available off Debian Unstable and Testing [link:
175 <http://packages.debian.org/cgi-bin/search_packages.pl?searchon=names&subword=1&version=all&release=all&keywords=sisu>]
176 [^1] install it using apt-get, aptitude or alternative *Debian* install tools.
177
178 DEPENDENCIES
179 ------------
180
181 Here is a list of sisu' s current dependencies,[^2] which depend on such
182 factors as whether you want to generate pdf, whether you will be using *SiSU*
183 with or without a database, ...). sisu_markup-samples may also be of interest.
184
185 Package: sisu
186 Depends: ruby | ruby-interpreter, openssl, rsync, unzip, zip
187 Recommends: sisu-pdf, sisu-sqlite, sisu-postgresql, imagemagick |
188 graphicsmagick, keychain, openssh-client | lsh-client, po4a, qrencode, rake,
189 ruby-rmagick, tidy, tree, vim-addon-manager
190 Suggests: lv, calibre, pinfo, poedit, texinfo, trang
191
192 Package: sisu-complete
193 Depends: ruby | ruby-interpreter, sisu (= ${source:Version}), sisu-pdf (=
194 ${source:Version}), sisu-postgresql (= ${source:Version}), sisu-sqlite (=
195 ${source:Version})
196 Description-en: installs all SiSU related packages
197
198 Package: sisu-pdf
199 Depends: ruby | ruby-interpreter, sisu (= ${source:Version}),
200 texlive-latex-base, texlive-fonts-recommended, texlive-generic-recommended,
201 texlive-latex-recommended, texlive-latex-extra, texlive-math-extra,
202 texlive-xetex, fonts-liberation, lmodern, latex-cjk-all, texlive-lang-cjk
203 Suggests: evince | pdf-viewer
204
205 Package: sisu-postgresql
206 Depends: ruby | ruby-interpreter, sisu (= ${source:Version}), postgresql,
207 ruby-dbd-pg, ruby-dbi, ruby-fcgi
208 Suggests: postgresql-contrib
209
210 Package: sisu-sqlite
211 Depends: ruby | ruby-interpreter, sisu (= ${source:Version}), sqlite3,
212 ruby-sqlite3, ruby-dbd-sqlite3, ruby-dbi, ruby-fcgi
213
214 Package: sisu-markup-samples
215 Depends: sisu
216
217 COMMANDS
218 ********
219
220 COMMANDS SUMMARY
221 ----------------
222
223 DESCRIPTION
224 ...........
225
226 *SiSU* is a document publishing system, that from a simple single marked-up
227 document, produces multiple output formats including: /plaintext/, /HTML/,
228 /XHTML/, /XML/, /EPUB/, /ODT/ (/OpenDocument/ (/ODF/) text), /LaTeX/, /PDF/,
229 info, and /SQL/ (/PostgreSQL/ and /SQLite/) , which share text object numbers
230 ("object citation numbering") and the same document structure information. For
231 more see: <http://sisudoc.org> or <http://www.jus.uio.no/sisu>
232
233 DOCUMENT PROCESSING COMMAND FLAGS
234 .................................
235
236 *-[0-9] [filename/wildcard]*
237 see --act
238
239 *--ao [filename/wildcard/url]*
240 assumed for most other flags, creates new intermediate files for processing
241 (abstract objects, document abstraction) that is used in all subsequent
242 processing of other output. This step is assumed for most processing flags. To
243 skip it see -n. Alias -m.
244
245 *--act[0-9] [filename/wildcard]*
246 --act0 to --act9 configurable shortcuts for multiple flags, -0 to -9 synonyms,
247 configure in sisurc.yml, sisu default action on a specified file where no flag
248 is provided is --act0, current default setting for --act0 is --digest --qrcode
249 --text --html --epub --concordance --pdf --odf --docbook --xhtml --xml-sax
250 --xml-dom --sqlite --manifest --verbose
251
252 *--asciitext [filename/wildcard]*
253 asciitext, smart text (not available)
254
255 *-b [filename/wildcard]*
256 see --xhtml
257
258 *--by-**
259 see --output-by-*
260
261 *-C*
262 configure/initialise shared output directory files initialize shared output
263 directory (config files such as css and dtd files are not updated if they
264 already exist unless modifier is used). -C --init-site configure/initialise
265 site more extensive than -C on its own, shared output directory files/force
266 update, existing shared output config files such as css and dtd files are
267 updated if this modifier is used.
268
269 *-c [filename/wildcard]*
270 see --color-toggle
271
272 *--color*
273 see --color-on
274
275 *--color-off*
276 turn off color in output to terminal
277
278 *--color-on*
279 turn on color in output to terminal
280
281 *--color-toggle [filename/wildcard]*
282 screen toggle ansi screen colour on or off depending on default set (unless -c
283 flag is used: if sisurc colour default is set to 'true', output to screen will
284 be with colour, if sisurc colour default is set to 'false' or is undefined
285 screen output will be without colour). Alias -c
286
287 *--configure*
288 configure/initialise shared output directory files initialize shared output
289 directory (config files such as css and dtd files are not updated if they
290 already exist unless modifier is used). The equivalent of: -C --init-site
291 configure/initialise site, more extensive than -C on its own, shared output
292 directory files/force update, existing shared output config files such as css
293 and dtd files are updated if -CC is used.
294
295 *--concordance [filename/wildcard]*
296 produces concordance (wordmap) a rudimentary index of all the words in a
297 document. (Concordance files are not generated for documents of over 260,000
298 words unless this limit is increased in the file sisurc.yml). Alias -w
299
300 *-d [filename/wildcard/url]*
301 see --docbook
302
303 *--dal [filename/wildcard/url]*
304 (abstract objects, document abstraction renamed abstract objects in sisu5) see
305 --ao
306
307 *--delete [filename/wildcard]*
308 see --zap
309
310 *--digests [filename/wildcard/url]*
311 document digest or document content certificate ( DCC ) as sha digest tree of
312 the document: the digest for the document, and digests for each object
313 contained within the document (together with information on software versions
314 that produced it) (digest.txt). --digests -V for verbose digest output to
315 screen.
316
317 *--docbook [filename/wildcard/url]*
318 docbook xml
319
320 *--dom [filename/wildcard/url]*
321 see --xml-dom
322
323 *--dump[=directory_path] [filename/wildcard]*
324 places output in directory specified, if none is specified in the current
325 directory (pwd). Unlike using default settings /HTML/ files have embedded css.
326 Compare --redirect
327
328 *-e [filename/wildcard]*
329 see --epub
330
331 *--epub [filename/wildcard]*
332 produces an epub document, [sisu version >=2 ] (filename.epub). Alias -e
333
334 *--exc-**
335 exclude output feature, overrides configuration settings --exc-numbering, see
336 --exc-ocn; --exc-ocn, (exclude "object citation numbering", (switches off
337 object citation numbers), affects html (seg, scroll), epub, xhtml, xml, pdf) ;
338 --exc-toc, (exclude table of contents, affects html (scroll), epub, pdf) ;
339 --exc-links-to-manifest, --exc-manifest-links, (exclude links to manifest,
340 affects html (seg, scroll)); --exc-search-form, (exclude search form, affects
341 html (seg, scroll), manifest); --exc-minitoc, (exclude mini table of contents,
342 affects html (seg), concordance, manifest); --exc-manifest-minitoc, (exclude
343 mini table of contents, affects manifest); --exc-html-minitoc, (exclude mini
344 table of contents, affects html (seg), concordance); --exc-html-navigation,
345 (exclude navigation, affects html (seg)); --exc-html-navigation-bar, (exclude
346 navigation bar, affects html (seg)); --exc-html-search-form, (exclude search
347 form, affects html (seg, scroll)); --exc-html-right-pane, (exclude right
348 pane/column, affects html (seg, scroll)); --exc-html-top-band, (exclude top
349 band, affects html (seg, scroll), concordance (minitoc forced on to provide seg
350 navigation)); --exc-segsubtoc (exclude sub table of contents, affects html
351 (seg), epub) ; see also --inc-*
352
353 *-F [--webserv=webrick]*
354 see --sample-search-form
355
356 *-f [optional string part of filename]*
357 see --find
358
359 *--fictionbook [filename/wildcard/url]*
360 fictionbook xml (not available)
361
362 *--find [optional string part of filename]*
363 without match string, glob all .sst .ssm files in directory (including language
364 subdirectories). With match string, find files that match given string in
365 directory (including language subdirectories). Alias -f, --glob, -G
366
367 *-G [optional string part of filename]*
368 see --find
369
370 *-g [filename/wildcard]*
371 see --git
372
373 *--git [filename/wildcard]*
374 produces or updates markup source file structure in a git repo (experimental
375 and subject to change). Alias -g
376
377 *--glob [optional string part of filename]*
378 see --find
379
380 *-h [filename/wildcard]*
381 see --html
382
383 *--harvest *.ss[tm]*
384 makes two lists of sisu output based on the sisu markup documents in a
385 directory: list of author and authors works (year and titles), and; list by
386 topic with titles and author. Makes use of header metadata fields (author,
387 title, date, topic_register). Can be used with maintenance (-M) and remote
388 placement (-R) flags.
389
390 *--help [topic]*
391 provides help on the selected topic, where topics (keywords) include: list,
392 (com)mands, short(cuts), (mod)ifiers, (env)ironment, markup, syntax, headers,
393 headings, endnotes, tables, example, customise, skin, (dir)ectories, path,
394 (lang)uage, db, install, setup, (conf)igure, convert, termsheet, search, sql,
395 features, license.
396
397 *--html [filename/wildcard]*
398 produces html output, in two forms (i) segmented text with table of contents
399 (toc.html and index.html) and (ii) the document in a single file (scroll.html).
400 Alias -h
401
402 *--html-scroll [filename/wildcard]*
403 produces html output, the document in a single file (scroll.html) only. Compare
404 --html-seg and --html
405
406 *--html-seg [filename/wildcard]*
407 produces html output, segmented text with table of contents (toc.html and
408 index.html). Compare --html-scroll and --html
409
410 *--html-strict [filename/wildcard]*
411 produces html with --strict option. see --strict
412
413 *-I [filename/wildcard]*
414 see --texinfo
415
416 *-i [filename/wildcard]*
417 see --manpage
418
419 *--i18n-**
420 these flags affect output by filetype and filename): --i18n-mono
421 (--monolingual) output filenames without language code for default language
422 ('en' or as set); --i18n-multi (--multilingual) language code provided as part
423 of the output filename, this is the default. Where output is in one language
424 only the language code may not be desired. see also --output-by-*
425
426 *--inc-**
427 include output feature, overrides configuration settings, (usually the default
428 if none set), has precedence over --exc-* (exclude output feature). Some detail
429 provided under --exc-*, see --exc-*
430
431 *-j [filename/wildcard]*
432 copies images associated with a file for use by html, xhtml & xml outputs
433 (automatically invoked by --dump & redirect).
434
435 *-k*
436 see --color-off
437
438 *--keep-processing-files [filename/wildcard/url]*
439 see --maintenance
440
441 *-M [filename/wildcard/url]*
442 see --maintenance
443
444 *-m [filename/wildcard/url]*
445 see --dal (document abstraction level/layer)
446
447 *--machine [filename/wildcard/url]*
448 see --dal (document abstraction level/layer)
449
450 *--maintenance [filename/wildcard/url]*
451 maintenance mode, interim processing files are preserved and their locations
452 indicated. (also see -V). Aliases -M and --keep-processing-files.
453
454 *--manifest [filename/wildcard]*
455 produces an html summary of output generated (hyperlinked to content) and
456 document specific metadata (sisu_manifest.html). This step is assumed for most
457 processing flags.
458
459 *--manpage [filename/wildcard]*
460 produces man page of file, not suitable for all outputs. Alias -i
461
462 *--markdown [filename/wildcard/url]*
463 markdown smart text (not available)
464
465 *--monolingual*
466 see --i18n-*
467
468 *--multilingual*
469 see --i18n-*
470
471 *-N [filename/wildcard/url]*
472 see --digests
473
474 *-n [filename/wildcard/url]*
475 skip the creation of intermediate processing files (document abstraction) if
476 they already exist, this skips the equivalent of -m which is otherwise assumed
477 by most processing flags.
478
479 *--no-**
480 see --exc-*
481
482 *--numbering*
483 turn on "object citation numbers". See --inc-ocn and --exc-ocn
484
485 *-o [filename/wildcard/url]*
486 see --odt
487
488 *--ocn*
489 "object citation numbers". See --inc-ocn and --exc-ocn
490
491 *--odf [filename/wildcard/url]*
492 see --odt
493
494 *--odt [filename/wildcard/url]*
495 output basic document in opendocument file format (opendocument.odt). Alias -o
496
497 *--output-by-**
498 select output directory structure from 3 alternatives: --output-by-language,
499 (language directory (based on language code) with filetype (html, epub, pdf
500 etc.) subdirectories); --output-by-filetype, (filetype directories with
501 language code as part of filename); --output-by-filename, (filename directories
502 with language code as part of filename). This is configurable. Alias --by-*
503
504 *-P [language_directory/filename language_directory]*
505 see --po4a
506
507 *-p [filename/wildcard]*
508 see --pdf
509
510 *--papersize-(a4|a5|b5|letter|legal)*
511 in conjunction with --pdf set pdf papersize, overriding any configuration
512 settings, to set more than one papersize repeat the option --pdf --papersize-a4
513 --papersize-letter. See also --papersize=*
514
515 *--papersize=a4,a5,b5,letter,legal* in conjunction with --pdf set pdf
516 papersize, overriding any configuration settings, to set more than one
517 papersize list after the equal sign with a comma separator
518 --papersize=a4,letter. See also --papersize-*
519
520 *--pdf [filename/wildcard]*
521 produces /LaTeX/ pdf (portrait.pdf & landscape.pdf). Orientation and papersize
522 may be set on the command-line. Default paper size is set in config file, or
523 document header, or provided with additional command line parameter, e.g.
524 --papersize-a4 preset sizes include: 'A4', U.S. 'letter' and 'legal' and book
525 sizes 'A5' and 'B5' (system defaults to A4), and; --landscape or --portrait,
526 so: e.g. "sisu --pdf-a4 --pdf-letter --landscape --verbose [filename/wildcard]"
527 or "sisu --pdf --landscape --a4 --letter --verbose [filename/wildcard]". --pdf
528 defaults to both landscape & portrait output, and a4 if no other papersizes are
529 configured. Related options --pdf-landscape --pdf-portrait --pdf-papersize-*
530 --pdf-papersize=[list]. Alias -p
531
532 *--pdf-l [filename/wildcard]*
533 See --pdf-landscape
534
535 *--pdf-landscape [filename/wildcard]*
536 sets orientation, produces /LaTeX/ pdf landscape.pdf. Default paper size is set
537 in config file, or document header, or provided with additional command line
538 parameter, e.g. --papersize-a4 preset sizes include: 'A4', U.S. 'letter' and
539 'legal' and book sizes 'A5' and 'B5' (system defaults to A4). Related options
540 --pdf --pdf-portrait. See also --papersize-* or --papersize=[list]. Alias
541 --pdf-l or in conjunction with --pdf --landscape
542
543 *--pdf-p [filename/wildcard]*
544 See --pdf-portrait
545
546 *--pdf-portrait [filename/wildcard]*
547 sets orientation, produces /LaTeX/ pdf portrait.pdf.pdf. Default paper size is
548 set in config file, or document header, or provided with additional command
549 line parameter, e.g. --papersize-a4 preset sizes include: 'A4', U.S. 'letter'
550 and 'legal' and book sizes 'A5' and 'B5' (system defaults to A4). Related
551 options --pdf --pdf-landscape. See also --papersize-* or --papersize=[list].
552 Alias --pdf-p or in conjunction with --pdf --portrait
553
554 *--pg-[instruction] [filename]*
555 database /PostgreSQL/ ( --pgsql may be used instead) possible instructions,
556 include: --pg-createdb; --pg-create; --pg-dropall; --pg-import [filename];
557 --pg-update [filename]; --pg-remove [filename]; see database section below.
558
559 *--po [language_directory/filename language_directory]*
560 see --po4a
561
562 *--po4a [language_directory/filename language_directory]*
563 produces .pot and po files for the file in the languages specified by the
564 language directory. *SiSU* markup is placed in subdirectories named with the
565 language code, e.g. en/ fr/ es/. The sisu config file must set the output
566 directory structure to multilingual. v3, experimental
567
568 *-Q [filename/wildcard]*
569 see --qrcode
570
571 *-q [filename/wildcard]*
572 see --quiet
573
574 *--qrcode [filename/wildcard]*
575 generate QR code image of metadata (used in manifest).
576
577 *--quiet [filename/wildcard]*
578 quiet less output to screen.
579
580 *-R [filename/wildcard]*
581 see --rsync
582
583 *-r [filename/wildcard]*
584 see --scp
585
586 *--redirect[=directory_path] [filename/wildcard]*
587 places output in subdirectory under specified directory, subdirectory uses the
588 filename (without the suffix). If no output directory is specified places the
589 subdirectory under the current directory (pwd). Unlike using default settings
590 /HTML/ files have embedded css. Compare --dump
591
592 *--rst [filename/wildcard/url]*
593 ReST (rST restructured text) smart text (not available)
594
595 *--rsync [filename/wildcard]*
596 copies sisu output files to remote host using rsync. This requires that
597 sisurc.yml has been provided with information on hostname and username, and
598 that you have your "keys" and ssh agent in place. Note the behavior of rsync
599 different if -R is used with other flags from if used alone. Alone the rsync
600 --delete parameter is sent, useful for cleaning the remote directory (when -R
601 is used together with other flags, it is not). Also see --scp. Alias -R
602
603 *-S*
604 see --sisupod
605
606 *-S [filename/wildcard]*
607 see --sisupod
608
609 *-s [filename/wildcard]*
610 see --source
611
612 *--sample-search-form [--db-(pg|sqlite)]*
613 generate examples of (naive) cgi search form for /SQLite/ or PgSQL depends on
614 your already having used sisu to populate an /SQLite/ or PgSQL database, (the
615 /SQLite/ version scans the output directories for existing sisu_sqlite
616 databases, so it is first necessary to create them, before generating the
617 search form) see --sqlite & --pg and the database section below. Optional
618 additional parameters: --db-user='www-data'. The samples are dumped in the
619 present work directory which must be writable, (with screen instructions given
620 that they be copied to the cgi-bin directory). Alias -F
621
622 *--sax [filename/wildcard/url]*
623 see --xml-sax
624
625 *--scp [filename/wildcard]*
626 copies sisu output files to remote host using scp. This requires that
627 sisurc.yml has been provided with information on hostname and username, and
628 that you have your "keys" and ssh agent in place. Also see --rsync. Alias -r
629
630 *--sha256*
631 set hash digest where used to sha256
632
633 *--sha512*
634 set hash digest where used to sha512
635
636 *--sqlite-[instruction] [filename]*
637 database type set to /SQLite/, this produces one of two possible databases,
638 without additional database related instructions it produces a discreet
639 /SQLite/ file for the document processed; with additional instructions it
640 produces a common /SQLite/ database of all processed documents that (come from
641 the same document preparation directory and as a result) share the same output
642 directory base path (possible instructions include: --sqlite-createdb;
643 --sqlite-create; --sqlite-dropall; --sqlite-import [filename]; --sqlite-update
644 [filename]; --sqlite-remove [filename]); see database section below.
645
646 *--sisupod*
647 produces a sisupod a zipped sisu directory of markup files including sisu
648 markup source files and the directories local configuration file, images and
649 skins. Note: this only includes the configuration files or skins contained in
650 ./_sisu not those in ~/.sisu -S [filename/wildcard] option. Note: (this option
651 is tested only with zsh). Alias -S
652
653 *--sisupod [filename/wildcard]*
654 produces a zipped file of the prepared document specified along with associated
655 images, by default named sisupod.zip they may alternatively be named with the
656 filename extension .ssp This provides a quick way of gathering the relevant
657 parts of a sisu document which can then for example be emailed. A sisupod
658 includes sisu markup source file, (along with associated documents if a master
659 file, or available in multilingual versions), together with related images and
660 skin. *SiSU* commands can be run directly against a sisupod contained in a
661 local directory, or provided as a url on a remote site. As there is a security
662 issue with skins provided by other users, they are not applied unless the flag
663 --trust or --trusted is added to the command instruction, it is recommended
664 that file that are not your own are treated as untrusted. The directory
665 structure of the unzipped file is understood by sisu, and sisu commands can be
666 run within it. Note: if you wish to send multiple files, it quickly becomes
667 more space efficient to zip the sisu markup directory, rather than the
668 individual files for sending). See the -S option without [filename/wildcard].
669 Alias -S
670
671 *--source [filename/wildcard]*
672 copies sisu markup file to output directory. Alias -s
673
674 *--strict*
675 together with --html, produces more w3c compliant html, for example not having
676 purely numeric identifiers for text, the location object url#33 becomes url#o33
677
678 *-T [filename/wildcard (*.termsheet.rb)]*
679 standard form document builder, preprocessing feature
680
681 *-t [filename/wildcard]*
682 see --txt
683
684 *--texinfo [filename/wildcard]*
685 produces texinfo and info file, (view with pinfo). Alias -I
686
687 *--textile [filename/wildcard/url]*
688 textile smart text (not available)
689
690 *--txt [filename/wildcard]*
691 produces /plaintext/ with Unix linefeeds and without markup, (object numbers
692 are omitted), has footnotes at end of each paragraph that contains them [ -A
693 for equivalent dos (linefeed) output file] [see -e for endnotes]. (Options
694 include: --endnotes for endnotes --footnotes for footnotes at the end of each
695 paragraph --unix for unix linefeed (default) --msdos for msdos linefeed). Alias
696 -t
697
698 *--txt-asciitext [filename/wildcard]*
699 see --asciitext
700
701 *--txt-markdown [filename/wildcard]*
702 see --markdown
703
704 *--txt-rst [filename/wildcard]*
705 see --rst
706
707 *--txt-textile [filename/wildcard]*
708 see --textile
709
710 *-U [filename/wildcard]*
711 see --urls
712
713 *-u [filename/wildcard]*
714 provides url mapping of output files for the flags requested for processing,
715 also see -U
716
717 *--urls [filename/wildcard]*
718 prints url output list/map for the available processing flags options and
719 resulting files that could be requested, (can be used to get a list of
720 processing options in relation to a file, together with information on the
721 output that would be produced), -u provides url output mapping for those flags
722 requested for processing. The default assumes sisu_webrick is running and
723 provides webrick url mappings where appropriate, but these can be switched to
724 file system paths in sisurc.yml. Alias -U
725
726 *-V*
727 on its own, provides *SiSU* version and environment information (sisu --help
728 env)
729
730 *-V [filename/wildcard]*
731 even more verbose than the -v flag.
732
733 *-v*
734 on its own, provides *SiSU* version information
735
736 *-v [filename/wildcard]*
737 see --verbose
738
739 *--v5 [filename/wildcard]*
740 invokes the sisu v5 document parser/generator. You may run sisu5 instead. This
741 is the current default and is normally omitted.
742
743 *--v6 [filename/wildcard]*
744 invokes the sisu v6 document parser/generator. You may run sisu6 instead.
745
746 *--verbose [filename/wildcard]*
747 provides verbose output of what is being generated, where output is placed (and
748 error messages if any), as with -u flag provides a url mapping of files created
749 for each of the processing flag requests. Alias -v
750
751 *-W*
752 see --webrick
753
754 *-w [filename/wildcard]*
755 see --concordance
756
757 *--webrick*
758 starts ruby' s webrick webserver points at sisu output directories, the default
759 port is set to 8081 and can be changed in the resource configuration files.
760 [tip: the webrick server requires link suffixes, so html output should be
761 created using the -h option rather than -H ; also, note -F webrick ]. Alias -W
762
763 *--wordmap [filename/wildcard]*
764 see --concordance
765
766 *--xhtml [filename/wildcard]*
767 produces xhtml//XML/ output for browser viewing (sax parsing). Alias -b
768
769 *--xml-dom [filename/wildcard]*
770 produces /XML/ output with deep document structure, in the nature of dom. Alias
771 -X
772
773 *--xml-sax [filename/wildcard]*
774 produces /XML/ output shallow structure (sax parsing). Alias -x
775
776 *-X [filename/wildcard]*
777 see --xml-dom
778
779 *-x [filename/wildcard]*
780 see --xml-sax
781
782 *-Y [filename/wildcard]*
783 produces a short sitemap entry for the document, based on html output and the
784 sisu_manifest. --sitemaps generates/updates the sitemap index of existing
785 sitemaps. (Experimental, [g,y,m announcement this week])
786
787 *-y [filename/wildcard]*
788 see --manifest
789
790 *-Z [filename/wildcard]*
791 see --zap
792
793 *--zap [filename/wildcard]*
794 Zap, if used with other processing flags deletes output files of the type about
795 to be processed, prior to processing. If -Z is used as the lone processing
796 related flag (or in conjunction with a combination of -[mMvVq]), will remove
797 the related document output directory. Alias -Z
798
799 COMMAND LINE MODIFIERS
800 ----------------------
801
802 *--no-ocn*
803 [with --html --pdf or --epub] switches off /object citation numbering/. Produce
804 output without identifying numbers in margins of html or /LaTeX//pdf output.
805
806 *--no-annotate*
807 strips output text of editor endnotes[^*1] denoted by asterisk or dagger/plus
808 sign
809
810 *--no-asterisk*
811 strips output text of editor endnotes[^*2] denoted by asterisk sign
812
813 *--no-dagger*
814 strips output text of editor endnotes[^+1] denoted by dagger/plus sign
815
816 DATABASE COMMANDS
817 -----------------
818
819 *dbi - database interface*
820
821 *--pg or --pgsql* set for /PostgreSQL/ *--sqlite* default set for /SQLite/ -d
822 is modifiable with --db=[database type (PgSQL or /SQLite/) ]
823
824 *--pg -v --createall*
825 initial step, creates required relations (tables, indexes) in existing
826 /PostgreSQL/ database (a database should be created manually and given the same
827 name as working directory, as requested) (rb.dbi) [ -dv --createall /SQLite/
828 equivalent] it may be necessary to run sisu -Dv --createdb initially NOTE: at
829 the present time for /PostgreSQL/ it may be necessary to manually create the
830 database. The command would be 'createdb [database name]' where database name
831 would be SiSU_[present working directory name (without path)]. Please use only
832 alphanumerics and underscores.
833
834 *--pg -v --import*
835 [filename/wildcard] imports data specified to /PostgreSQL/ db (rb.dbi) [ -dv
836 --import /SQLite/ equivalent]
837
838 *--pg -v --update*
839 [filename/wildcard] updates/imports specified data to /PostgreSQL/ db (rb.dbi)
840 [ -dv --update /SQLite/ equivalent]
841
842 *--pg --remove*
843 [filename/wildcard] removes specified data to /PostgreSQL/ db (rb.dbi) [ -d
844 --remove /SQLite/ equivalent]
845
846 *--pg --dropall*
847 kills data" and drops (/PostgreSQL/ or /SQLite/) db, tables & indexes [ -d
848 --dropall /SQLite/ equivalent]
849
850 The -v is for verbose output.
851
852 COMMAND LINE WITH FLAGS - BATCH PROCESSING
853 ..........................................
854
855 In the data directory run sisu -mh filename or wildcard eg. "sisu -h cisg.sst"
856 or "sisu -h *.{sst,ssm}" to produce html version of all documents.
857
858 Running sisu (alone without any flags, filenames or wildcards) brings up the
859 interactive help, as does any sisu command that is not recognised. Enter to
860 escape.
861
862 INTRODUCTION TO SISU MARKUP[^3]
863 -------------------------------
864
865 SUMMARY
866 .......
867
868 *SiSU* source documents are /plaintext/ (/UTF-8/)[^4] files
869
870 All paragraphs are separated by an empty line.
871
872 Markup is comprised of:
873
874 * at the top of a document, the document header made up of semantic meta-data
875 about the document and if desired additional processing instructions (such an
876 instruction to automatically number headings from a particular level down)
877
878 * followed by the prepared substantive text of which the most important single
879 characteristic is the markup of different heading levels, which define the
880 primary outline of the document structure. Markup of substantive text includes:
881
882 * heading levels defines document structure
883
884 * text basic attributes, italics, bold etc.
885
886 * grouped text (objects), which are to be treated differently, such as code
887 blocks or poems.
888
889 * footnotes/endnotes
890
891 * linked text and images
892
893 * paragraph actions, such as indent, bulleted, numbered-lists, etc.
894
895 Some interactive help on markup is available, by typing sisu and selecting
896 markup or sisu --help markup
897
898 To check the markup in a file:
899
900 sisu --identify [filename].sst
901
902 For brief descriptive summary of markup history
903
904 sisu --query-history
905
906 or if for a particular version:
907
908 sisu --query-0.38
909
910 MARKUP RULES, DOCUMENT STRUCTURE AND METADATA REQUIREMENTS
911 ..........................................................
912
913 minimal content/structure requirement:
914
915 [metadata]
916
917 A~ (level A [title])
918 1~ (at least one level 1 [segment/(chapter)])
919
920 structure rules (document heirarchy, heading levels):
921
922 there are two sets of heading levels ABCD (title & parts if any) and 123
923 (segment & subsegments if any)
924
925 sisu has the fllowing levels:
926
927 A~ [title] .
928 required (== 1) followed by B~ or 1~
929 B~ [part] *
930 followed by C~ or 1~
931 C~ [subpart] *
932 followed by D~ or 1~
933 D~ [subsubpart] *
934 followed by 1~
935 1~ [segment (chapter)] +
936 required (>= 1) followed by text or 2~
937 text *
938 followed by more text or 1~, 2~
939 or relevant part *()
940 2~ [subsegment] *
941 followed by text or 3~
942 text *
943 followed by more text or 1~, 2~ or 3~
944 or relevant part, see *()
945 3~ [subsubsegment] *
946 followed by text
947 text *
948 followed by more text or 1~, 2~ or 3~ or relevant part, see *()
949
950 *(B~ if none other used;
951 if C~ is last used: C~ or B~;
952 if D~ is used: D~, C~ or B~)
953
954 * level A~ is the tile and is mandatory
955 * there can only be one level A~
956 * heading levels BCD, are optional and there may be several of each
957 (where all three are used corresponding to e.g. Book Part Section)
958 * sublevels that are used must follow each other sequentially
959 (alphabetically),
960 * heading levels A~ B~ C~ D~ are followed by other heading levels rather
961 than substantive text
962 which may be the subsequent sequential (alphabetic) heading part level
963 or a heading (segment) level 1~
964 * there must be at least one heading (segment) level 1~
965 (the level on which the text is segmented, in a book would correspond
966 to the Chapter level)
967 * additional heading levels 1~ 2~ 3~ are optional and there may be several
968 of each
969 * heading levels 1~ 2~ 3~ are followed by text (which may be followed by
970 the same heading level)
971 and/or the next lower numeric heading level (followed by text)
972 or indeed return to the relevant part level
973 (as a corollary to the rules above substantive text/ content
974 must be preceded by a level 1~ (2~ or 3~) heading)
975
976 MARKUP EXAMPLES
977 ...............
978
979
980 ----------------------------------------
981
982 ONLINE
983 ......
984
985 Online markup examples are available together with the respective outputs
986 produced from <http://www.jus.uio.no/sisu/SiSU/examples.html> or from
987 <http://www.jus.uio.no/sisu/sisu_examples/>
988
989 There is of course this document, which provides a cursory overview of sisu
990 markup and the respective output produced:
991 <http://www.jus.uio.no/sisu/sisu_markup/>
992
993 an alternative presentation of markup syntax:
994 /usr/share/doc/sisu/on_markup.txt.gz
995
996
997 ----------------------------------------
998
999 INSTALLED
1000 .........
1001
1002 With *SiSU* installed sample skins may be found in:
1003 /usr/share/doc/sisu/markup-samples (or equivalent directory) and if sisu
1004 -markup-samples is installed also under:
1005 /usr/share/doc/sisu/markup-samples-non-free
1006
1007 MARKUP OF HEADERS
1008 -----------------
1009
1010 Headers contain either: semantic meta-data about a document, which can be used
1011 by any output module of the program, or; processing instructions.
1012
1013 Note: the first line of a document may include information on the markup
1014 version used in the form of a comment. Comments are a percentage mark at the
1015 start of a paragraph (and as the first character in a line of text) followed by
1016 a space and the comment:
1017
1018 % this would be a comment
1019
1020 SAMPLE HEADER
1021 .............
1022
1023 This current document is loaded by a master document that has a header similar
1024 to this one:
1025
1026 % SiSU master 4.0
1027
1028 @title: SiSU
1029 :subtitle: Manual
1030
1031 @creator:
1032 :author: Amissah, Ralph
1033
1034 @publisher: [publisher name]
1035
1036 @rights: Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL 3
1037
1038 @classify:
1039 :topic_register: SiSU:manual;electronic documents:SiSU:manual
1040 :subject: ebook, epublishing, electronic book, electronic publishing,
1041 electronic document, electronic citation, data structure,
1042 citation systems, search
1043
1044 % used_by: manual
1045
1046 @date:
1047 :published: 2008-05-22
1048 :created: 2002-08-28
1049 :issued: 2002-08-28
1050 :available: 2002-08-28
1051 :modified: 2010-03-03
1052
1053 @make:
1054 :num_top: 1
1055 :breaks: new=C; break=1
1056 :bold: /Gnu|Debian|Ruby|SiSU/
1057 :home_button_text: {SiSU}http://sisudoc.org; {git}http://git.sisudoc.org
1058 :footer: {SiSU}http://sisudoc.org; {git}http://git.sisudoc.org
1059 :manpage: name=sisu - documents: markup, structuring, publishing in multiple standard formats, and search;
1060 synopsis=sisu [-abcDdeFhIiMmNnopqRrSsTtUuVvwXxYyZz0-9] [filename/wildcard ]
1061 . sisu [-Ddcv] [instruction]
1062 . sisu [-CcFLSVvW]
1063 . sisu --v5 [operations]
1064 . sisu --v6 [operations]
1065
1066 @links:
1067 { SiSU Homepage }http://www.sisudoc.org/
1068 { SiSU Manual }http://www.sisudoc.org/sisu/sisu_manual/
1069 { Book Samples & Markup Examples }http://www.jus.uio.no/sisu/SiSU/examples.html
1070 { SiSU Download }http://www.jus.uio.no/sisu/SiSU/download.html
1071 { SiSU Changelog }http://www.jus.uio.no/sisu/SiSU/changelog.html
1072 { SiSU Git repo }http://git.sisudoc.org/?p=code/sisu.git;a=summary
1073 { SiSU List Archives }http://lists.sisudoc.org/pipermail/sisu/
1074 { SiSU @ Debian }http://packages.qa.debian.org/s/sisu.html
1075 { SiSU Project @ Debian }http://qa.debian.org/developer.php?login=sisu@lists.sisudoc.org
1076 { SiSU @ Wikipedia }http://en.wikipedia.org/wiki/SiSU
1077
1078 AVAILABLE HEADERS
1079 .................
1080
1081 Header tags appear at the beginning of a document and provide meta information
1082 on the document (such as the /Dublin Core/) , or information as to how the
1083 document as a whole is to be processed. All header instructions take the form
1084 @headername: or on the next line and indented by once space :subheadername: All
1085 /Dublin Core/ meta tags are available
1086
1087 *@identifier:* information or instructions
1088
1089 where the "identifier" is a tag recognised by the program, and the
1090 "information" or "instructions" belong to the tag/identifier specified
1091
1092 Note: a header where used should only be used once; all headers apart from
1093 @title: are optional; the @structure: header is used to describe document
1094 structure, and can be useful to know.
1095
1096 This is a sample header
1097
1098 % SiSU 2.0 [declared file-type identifier with markup version]
1099
1100 @title: [title text] [this header is the only one that is mandatory]
1101 :subtitle: [subtitle if any]
1102 :language: English
1103
1104 @creator:
1105 :author: [Lastname, First names]
1106 :illustrator: [Lastname, First names]
1107 :translator: [Lastname, First names]
1108 :prepared_by: [Lastname, First names]
1109
1110 @date:
1111 :published: [year or yyyy-mm-dd]
1112 :created: [year or yyyy-mm-dd]
1113 :issued: [year or yyyy-mm-dd]
1114 :available: [year or yyyy-mm-dd]
1115 :modified: [year or yyyy-mm-dd]
1116 :valid: [year or yyyy-mm-dd]
1117 :added_to_site: [year or yyyy-mm-dd]
1118 :translated: [year or yyyy-mm-dd]
1119
1120 @rights:
1121 :copyright: Copyright (C) [Year and Holder]
1122 :license: [Use License granted]
1123 :text: [Year and Holder]
1124 :translation: [Name, Year]
1125 :illustrations: [Name, Year]
1126
1127 @classify:
1128 :topic_register: SiSU:markup sample:book;book:novel:fantasy
1129 :type:
1130 :subject:
1131 :description:
1132 :keywords:
1133 :abstract:
1134 :loc: [Library of Congress classification]
1135 :dewey: [Dewey classification
1136
1137 @identify:
1138 :isbn: [ISBN]
1139 :oclc:
1140
1141 @links: { SiSU }http://www.sisudoc.org
1142 { FSF }http://www.fsf.org
1143
1144 @make:
1145 :num_top: 1
1146 :headings: [text to match for each level
1147 (e.g. PART; Chapter; Section; Article; or another: none; BOOK|FIRST|SECOND; none; CHAPTER;)
1148 :breaks: new=:C; break=1
1149 :promo: sisu, ruby, sisu_search_libre, open_society
1150 :bold: [regular expression of words/phrases to be made bold]
1151 :italics: [regular expression of words/phrases to italicise]
1152 :home_button_text: {SiSU}http://sisudoc.org; {git}http://git.sisudoc.org
1153 :footer: {SiSU}http://sisudoc.org; {git}http://git.sisudoc.org
1154
1155 @original:
1156 :language: [language]
1157
1158 @notes:
1159 :comment:
1160 :prefix: [prefix is placed just after table of contents]
1161
1162 MARKUP OF SUBSTANTIVE TEXT
1163 --------------------------
1164
1165 HEADING LEVELS
1166 ..............
1167
1168 Heading levels are :A~ ,:B~ ,:C~ ,1~ ,2~ ,3~ ... :A - :C being part / section
1169 headings, followed by other heading levels, and 1 -6 being headings followed by
1170 substantive text or sub-headings. :A~ usually the title :A~? conditional level
1171 1 heading (used where a stand-alone document may be imported into another)
1172
1173 *:A~ [heading text]* Top level heading [this usually has similar content to the
1174 title @title: ] NOTE: the heading levels described here are in 0.38 notation,
1175 see heading
1176
1177 *:B~ [heading text]* Second level heading [this is a heading level divider]
1178
1179 *:C~ [heading text]* Third level heading [this is a heading level divider]
1180
1181 *1~ [heading text]* Top level heading preceding substantive text of document or
1182 sub-heading 2, the heading level that would normally be marked 1. or 2. or 3.
1183 etc. in a document, and the level on which sisu by default would break html
1184 output into named segments, names are provided automatically if none are given
1185 (a number), otherwise takes the form 1~my_filename_for_this_segment
1186
1187 *2~ [heading text]* Second level heading preceding substantive text of document
1188 or sub-heading 3 , the heading level that would normally be marked 1.1 or 1.2
1189 or 1.3 or 2.1 etc. in a document.
1190
1191 *3~ [heading text]* Third level heading preceding substantive text of document,
1192 that would normally be marked 1.1.1 or 1.1.2 or 1.2.1 or 2.1.1 etc. in a
1193 document
1194
1195 1~filename level 1 heading,
1196
1197 % 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)
1198
1199 FONT ATTRIBUTES
1200 ...............
1201
1202 *markup example:*
1203
1204 normal text, *{emphasis}*, !{bold text}!, /{italics}/, _{underscore}_, "{citation}",
1205 ^{superscript}^, ,{subscript},, +{inserted text}+, -{strikethrough}-, #{monospace}#
1206
1207 normal text
1208
1209 *{emphasis}* [note: can be configured to be represented by bold, italics or underscore]
1210
1211 !{bold text}!
1212
1213 /{italics}/
1214
1215 _{underscore}_
1216
1217 "{citation}"
1218
1219 ^{superscript}^
1220
1221 ,{subscript},
1222
1223 +{inserted text}+
1224
1225 -{strikethrough}-
1226
1227 #{monospace}#
1228
1229 *resulting output:*
1230
1231 normal text, *emphasis*, *bold text*, /italics/, _underscore_, "citation",
1232 ^superscript^, [subscript], +inserted text+, -strikethrough-, #monospace#
1233
1234 normal text
1235
1236 *emphasis* [note: can be configured to be represented by bold, italics or
1237 underscore]
1238
1239 *bold text*
1240
1241 /italics/
1242
1243 _underscore_
1244
1245 "citation"
1246
1247 ^superscript^
1248
1249 [subscript]
1250
1251 +inserted text+
1252
1253 -strikethrough-
1254
1255 #monospace#
1256
1257 INDENTATION AND BULLETS
1258 .......................
1259
1260 *markup example:*
1261
1262 ordinary paragraph
1263
1264 _1 indent paragraph one step
1265
1266 _2 indent paragraph two steps
1267
1268 _9 indent paragraph nine steps
1269
1270 *resulting output:*
1271
1272 ordinary paragraph
1273
1274 indent paragraph one step
1275
1276 indent paragraph two steps
1277
1278 indent paragraph nine steps
1279
1280 *markup example:*
1281
1282 _* bullet text
1283
1284 _1* bullet text, first indent
1285
1286 _2* bullet text, two step indent
1287
1288 *resulting output:*
1289
1290 * bullet text
1291
1292 * bullet text, first indent
1293
1294 * bullet text, two step indent
1295
1296 Numbered List (not to be confused with headings/titles, (document structure))
1297
1298 *markup example:*
1299
1300 # numbered list numbered list 1., 2., 3, etc.
1301
1302 _# numbered list numbered list indented a., b., c., d., etc.
1303
1304 HANGING INDENTS
1305 ...............
1306
1307 *markup example:*
1308
1309 _0_1 first line no indent,
1310 rest of paragraph indented one step
1311
1312 _1_0 first line indented,
1313 rest of paragraph no indent
1314
1315 in each case level may be 0-9
1316
1317 *resulting output:*
1318
1319 first line no indent, rest of paragraph indented one step; first line no
1320 indent, rest of paragraph indented one step; first line no indent, rest of
1321 paragraph indented one step; first line no indent, rest of paragraph indented
1322 one step; first line no indent, rest of paragraph indented one step; first
1323 line no indent, rest of paragraph indented one step; first line no indent,
1324 rest of paragraph indented one step; first line no indent, rest of paragraph
1325 indented one step; first line no indent, rest of paragraph indented one step;
1326
1327 A regular paragraph.
1328
1329 first line indented, rest of paragraph no indent first line indented, rest of
1330 paragraph no indent first line indented, rest of paragraph no indent first line
1331 indented, rest of paragraph no indent first line indented, rest of paragraph no
1332 indent first line indented, rest of paragraph no indent first line indented,
1333 rest of paragraph no indent first line indented, rest of paragraph no indent
1334 first line indented, rest of paragraph no indent first line indented, rest of
1335 paragraph no indent first line indented, rest of paragraph no indent
1336
1337 in each case level may be 0-9
1338
1339 *live-build* A collection of scripts used to build customized *Debian*
1340 Livesystems. /live-build/ was formerly known as live-helper, and even earlier
1341 known as live-package.
1342
1343 *live-build*
1344 A collection of scripts used to build customized *Debian* Livesystems.
1345 /live-build/ was formerly known as live-helper, and even earlier known as
1346 live-package.
1347
1348 FOOTNOTES / ENDNOTES
1349 ....................
1350
1351 Footnotes and endnotes are marked up at the location where they would be
1352 indicated within a text. They are automatically numbered. The output type
1353 determines whether footnotes or endnotes will be produced
1354
1355 *markup example:*
1356
1357 ~{ a footnote or endnote }~
1358
1359 *resulting output:*
1360
1361 [^5]
1362
1363 *markup example:*
1364
1365 normal text~{ self contained endnote marker & endnote in one }~ continues
1366
1367 *resulting output:*
1368
1369 normal text[^6] continues
1370
1371 *markup example:*
1372
1373 normal text ~{* unnumbered asterisk footnote/endnote, insert multiple asterisks if required }~ continues
1374
1375 normal text ~{** another unnumbered asterisk footnote/endnote }~ continues
1376
1377 *resulting output:*
1378
1379 normal text [^*] continues
1380
1381 normal text [^**] continues
1382
1383 *markup example:*
1384
1385 normal text ~[* editors notes, numbered asterisk footnote/endnote series ]~ continues
1386
1387 normal text ~[+ editors notes, numbered plus symbol footnote/endnote series ]~ continues
1388
1389 *resulting output:*
1390
1391 normal text [^*3] continues
1392
1393 normal text [^+2] continues
1394
1395 *Alternative endnote pair notation for footnotes/endnotes:*
1396
1397 % note the endnote marker "~^"
1398
1399 normal text~^ continues
1400
1401 ^~ endnote text following the paragraph in which the marker occurs
1402
1403 the standard and pair notation cannot be mixed in the same document
1404
1405 LINKS
1406 .....
1407
1408
1409 ----------------------------------------
1410
1411 NAKED URLS WITHIN TEXT, DEALING WITH URLS
1412 .........................................
1413
1414 urls found within text are marked up automatically. A url within text is
1415 automatically hyperlinked to itself and by default decorated with angled
1416 braces, unless they are contained within a code block (in which case they are
1417 passed as normal text), or escaped by a preceding underscore (in which case the
1418 decoration is omitted).
1419
1420 *markup example:*
1421
1422 normal text http://www.sisudoc.org/ continues
1423
1424 *resulting output:*
1425
1426 normal text <http://www.sisudoc.org/> continues
1427
1428 An escaped url without decoration
1429
1430 *markup example:*
1431
1432 normal text _http://www.sisudoc.org/ continues
1433
1434 deb _http://www.jus.uio.no/sisu/archive unstable main non-free
1435
1436 *resulting output:*
1437
1438 normal text http://www.sisudoc.org/ continues
1439
1440 deb http://www.jus.uio.no/sisu/archive unstable main non-free
1441
1442 where a code block is used there is neither decoration nor hyperlinking, code
1443 blocks are discussed later in this document
1444
1445 *resulting output:*
1446
1447 deb http://www.jus.uio.no/sisu/archive unstable main non-free
1448 deb-src http://www.jus.uio.no/sisu/archive unstable main non-free
1449
1450
1451 ----------------------------------------
1452
1453 LINKING TEXT
1454 ............
1455
1456 To link text or an image to a url the markup is as follows
1457
1458 *markup example:*
1459
1460 about { SiSU }http://url.org markup
1461
1462 *resulting output:*
1463
1464 about SiSU [link: <http://www.sisudoc.org/>] markup
1465
1466 A shortcut notation is available so the url link may also be provided
1467 automatically as a footnote
1468
1469 *markup example:*
1470
1471 about {~^ SiSU }http://url.org markup
1472
1473 *resulting output:*
1474
1475 about SiSU [link: <http://www.sisudoc.org/>] [^7] markup
1476
1477 Internal document links to a tagged location, including an ocn
1478
1479 *markup example:*
1480
1481 about { text links }#link_text
1482
1483 *resulting output:*
1484
1485 about text links
1486
1487 Shared document collection link
1488
1489 *markup example:*
1490
1491 about { SiSU book markup examples }:SiSU/examples.html
1492
1493 *resulting output:*
1494
1495 about *SiSU* book markup examples
1496
1497
1498 ----------------------------------------
1499
1500 LINKING IMAGES
1501 ..............
1502
1503 *markup example:*
1504
1505 { tux.png 64x80 }image
1506
1507 % various url linked images
1508 [image: "a better way"]
1509 [image: "Way Better - with Gnu/Linux, Debian and Ruby"]
1510
1511 {~^ ruby_logo.png "Ruby" }http://www.ruby-lang.org/en/
1512
1513 *resulting output:*
1514
1515 tux.png 64x80 [link: local image]
1516
1517 tux.png 64x80 "Gnu/Linux - a better way" [link: <http://www.sisudoc.org/>]
1518
1519 GnuDebianLinuxRubyBetterWay.png 100x101 "Way Better - with Gnu/Linux, Debian
1520 and Ruby" [link: <http://www.sisudoc.org/>]
1521
1522 ruby_logo.png 70x90 "Ruby" [link: <http://www.ruby-lang.org/en/>] [^8]
1523
1524 *linked url footnote shortcut*
1525
1526 {~^ [text to link] }http://url.org
1527
1528 % maps to: { [text to link] }http://url.org ~{ http://url.org }~
1529
1530 % which produces hyper-linked text within a document/paragraph, with an endnote providing the url for the text location used in the hyperlink
1531
1532 text marker *~name
1533
1534 note at a heading level the same is automatically achieved by providing names
1535 to headings 1, 2 and 3 i.e. 2~[name] and 3~[name] or in the case of
1536 auto-heading numbering, without further intervention.
1537
1538
1539 ----------------------------------------
1540
1541 LINK SHORTCUT FOR MULTIPLE VERSIONS OF A SISU DOCUMENT IN THE SAME DIRECTORY
1542 TREE
1543 ..............................................................................
1544
1545 *markup example:*
1546
1547 !_ /{"Viral Spiral"}/, David Bollier
1548
1549 { "Viral Spiral", David Bollier [3sS]}viral_spiral.david_bollier.sst
1550
1551 */"Viral Spiral"/, David Bollier*
1552
1553 "Viral Spiral", David Bollier [link: <http://www.sisudoc.org/sisu/en/manifest/viral_spiral.david_bollier.manifest.html>]
1554 document manifest [link: <http://www.sisudoc.org/sisu/en/manifest/viral_spiral.david_bollier.manifest.html>]
1555 html, segmented text [link: <http://www.sisudoc.org/sisu/en/html/viral_spiral.david_bollier/viral_spiral.david_bollier.toc.html>]
1556 html, scroll, document in one [link: <http://www.sisudoc.org/sisu/en/html/viral_spiral.david_bollier.html>]
1557 epub [link: <http://www.sisudoc.org/sisu/en/epub/viral_spiral.david_bollier.epub>]
1558 pdf, landscape [link: <http://www.sisudoc.org/sisu/en/pdf/viral_spiral.david_bollier.landscape.a4.pdf>]
1559 pdf, portrait [link: <http://www.sisudoc.org/sisu/en/pdf/viral_spiral.david_bollier.landscape.a4.pdf>]
1560 odf: odt, open document text [link: <http://www.sisudoc.org/sisu/en/odt/viral_spiral.david_bollier.odt>]
1561 xhtml scroll [link: <http://www.sisudoc.org/sisu/en/xhtml/viral_spiral.david_bollier.xhtml>]
1562 xml, sax [link: <http://www.sisudoc.org/sisu/en/xml_sax/viral_spiral.david_bollier.sax.xml>]
1563 xml, dom [link: <http://www.sisudoc.org/sisu/en/xml_dom/viral_spiral.david_bollier.dom.xml>]
1564 concordance [link: <http://www.sisudoc.org/sisu/en/html/viral_spiral.david_bollier/concordance.html>]
1565 dcc, document content certificate (digests) [link: <http://www.sisudoc.org/sisu/en/digest/viral_spiral.david_bollier.hash_digest.txt>]
1566 markup source text [link: <http://www.sisudoc.org/sisu/en/src/viral_spiral.david_bollier.sst>]
1567 markup source (zipped) pod [link: <http://www.sisudoc.org/sisu/en/src/viral_spiral.david_bollier.sst.zip>]
1568
1569 GROUPED TEXT
1570 ............
1571
1572
1573 ----------------------------------------
1574
1575 TABLES
1576 ......
1577
1578 Tables may be prepared in two either of two forms
1579
1580 *markup example:*
1581
1582 table{ c3; 40; 30; 30;
1583
1584 This is a table
1585 this would become column two of row one
1586 column three of row one is here
1587
1588 And here begins another row
1589 column two of row two
1590 column three of row two, and so on
1591
1592 }table
1593
1594 *resulting output:*
1595
1596 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』
1597
1598 a second form may be easier to work with in cases where there is not much
1599 information in each column
1600
1601 *markup example:*[^9]
1602
1603 !_ Table 3.1: Contributors to Wikipedia, January 2001 - June 2005
1604
1605 {table~h 24; 12; 12; 12; 12; 12; 12;}
1606 |Jan. 2001|Jan. 2002|Jan. 2003|Jan. 2004|July 2004|June 2006
1607 Contributors* | 10| 472| 2,188| 9,653| 25,011| 48,721
1608 Active contributors** | 9| 212| 846| 3,228| 8,442| 16,945
1609 Very active contributors*** | 0| 31| 190| 692| 1,639| 3,016
1610 No. of English language articles| 25| 16,000| 101,000| 190,000| 320,000| 630,000
1611 No. of articles, all languages | 25| 19,000| 138,000| 490,000| 862,000|1,600,000
1612
1613 * Contributed at least ten times; ** at least 5 times in last month; *** more than 100 times in last month.
1614
1615 *resulting output:*
1616
1617 *Table 3.1: Contributors to Wikipedia, January 2001 - June 2005*
1618
1619 ┆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』
1620
1621 * Contributed at least ten times; ** at least 5 times in last month; *** more
1622 than 100 times in last month.
1623
1624
1625 ----------------------------------------
1626
1627 POEM
1628 ....
1629
1630 *basic markup:*
1631
1632 poem{
1633
1634 Your poem here
1635
1636 }poem
1637
1638 Each verse in a poem is given an object number.
1639
1640 *markup example:*
1641
1642 poem{
1643
1644 `Fury said to a
1645 mouse, That he
1646 met in the
1647 house,
1648 "Let us
1649 both go to
1650 law: I will
1651 prosecute
1652 YOU. --Come,
1653 I'll take no
1654 denial; We
1655 must have a
1656 trial: For
1657 really this
1658 morning I've
1659 nothing
1660 to do."
1661 Said the
1662 mouse to the
1663 cur, "Such
1664 a trial,
1665 dear Sir,
1666 With
1667 no jury
1668 or judge,
1669 would be
1670 wasting
1671 our
1672 breath."
1673 "I'll be
1674 judge, I'll
1675 be jury,"
1676 Said
1677 cunning
1678 old Fury:
1679 "I'll
1680 try the
1681 whole
1682 cause,
1683 and
1684 condemn
1685 you
1686 to
1687 death."'
1688
1689 }poem
1690
1691 *resulting output:*
1692
1693 `Fury said to a
1694 mouse, That he
1695 met in the
1696 house,
1697 "Let us
1698 both go to
1699 law: I will
1700 prosecute
1701 YOU. --Come,
1702 I'll take no
1703 denial; We
1704 must have a
1705 trial: For
1706 really this
1707 morning I've
1708 nothing
1709 to do."
1710 Said the
1711 mouse to the
1712 cur, "Such
1713 a trial,
1714 dear Sir,
1715 With
1716 no jury
1717 or judge,
1718 would be
1719 wasting
1720 our
1721 breath."
1722 "I'll be
1723 judge, I'll
1724 be jury,"
1725 Said
1726 cunning
1727 old Fury:
1728 "I'll
1729 try the
1730 whole
1731 cause,
1732 and
1733 condemn
1734 you
1735 to
1736 death."'
1737
1738
1739 ----------------------------------------
1740
1741 GROUP
1742 .....
1743
1744 *basic markup:*
1745
1746 group{
1747
1748 Your grouped text here
1749
1750 }group
1751
1752 A group is treated as an object and given a single object number.
1753
1754 *markup example:*
1755
1756 group{
1757
1758 `Fury said to a
1759 mouse, That he
1760 met in the
1761 house,
1762 "Let us
1763 both go to
1764 law: I will
1765 prosecute
1766 YOU. --Come,
1767 I'll take no
1768 denial; We
1769 must have a
1770 trial: For
1771 really this
1772 morning I've
1773 nothing
1774 to do."
1775 Said the
1776 mouse to the
1777 cur, "Such
1778 a trial,
1779 dear Sir,
1780 With
1781 no jury
1782 or judge,
1783 would be
1784 wasting
1785 our
1786 breath."
1787 "I'll be
1788 judge, I'll
1789 be jury,"
1790 Said
1791 cunning
1792 old Fury:
1793 "I'll
1794 try the
1795 whole
1796 cause,
1797 and
1798 condemn
1799 you
1800 to
1801 death."'
1802
1803 }group
1804
1805 *resulting output:*
1806
1807 `Fury said to a
1808 mouse, That he
1809 met in the
1810 house,
1811 "Let us
1812 both go to
1813 law: I will
1814 prosecute
1815 YOU. --Come,
1816 I'll take no
1817 denial; We
1818 must have a
1819 trial: For
1820 really this
1821 morning I've
1822 nothing
1823 to do."
1824 Said the
1825 mouse to the
1826 cur, "Such
1827 a trial,
1828 dear Sir,
1829 With
1830 no jury
1831 or judge,
1832 would be
1833 wasting
1834 our
1835 breath."
1836 "I'll be
1837 judge, I'll
1838 be jury,"
1839 Said
1840 cunning
1841 old Fury:
1842 "I'll
1843 try the
1844 whole
1845 cause,
1846 and
1847 condemn
1848 you
1849 to
1850 death."'
1851
1852
1853 ----------------------------------------
1854
1855 CODE
1856 ....
1857
1858 Code tags # code{ ... }code # (used as with other group tags described above)
1859 are used to escape regular sisu markup, and have been used extensively within
1860 this document to provide examples of *SiSU* markup. You cannot however use code
1861 tags to escape code tags. They are however used in the same way as group or
1862 poem tags.
1863
1864 A code-block is treated as an object and given a single object number. [an
1865 option to number each line of code may be considered at some later time]
1866
1867 *use of code tags instead of poem compared, resulting output:*
1868
1869 `Fury said to a
1870 mouse, That he
1871 met in the
1872 house,
1873 "Let us
1874 both go to
1875 law: I will
1876 prosecute
1877 YOU. --Come,
1878 I'll take no
1879 denial; We
1880 must have a
1881 trial: For
1882 really this
1883 morning I've
1884 nothing
1885 to do."
1886 Said the
1887 mouse to the
1888 cur, "Such
1889 a trial,
1890 dear Sir,
1891 With
1892 no jury
1893 or judge,
1894 would be
1895 wasting
1896 our
1897 breath."
1898 "I'll be
1899 judge, I'll
1900 be jury,"
1901 Said
1902 cunning
1903 old Fury:
1904 "I'll
1905 try the
1906 whole
1907 cause,
1908 and
1909 condemn
1910 you
1911 to
1912 death."'
1913
1914 From *SiSU* 2.7.7 on you can number codeblocks by placing a hash after the
1915 opening code tag # code{# # as demonstrated here:
1916
1917 1 ┆ `Fury said to a
1918 2 ┆ mouse, That he
1919 3 ┆ met in the
1920 4 ┆ house,
1921 5 ┆ "Let us
1922 6 ┆ both go to
1923 7 ┆ law: I will
1924 8 ┆ prosecute
1925 9 ┆ YOU. --Come,
1926 10 ┆ I'll take no
1927 11 ┆ denial; We
1928 12 ┆ must have a
1929 13 ┆ trial: For
1930 14 ┆ really this
1931 15 ┆ morning I've
1932 16 ┆ nothing
1933 17 ┆ to do."
1934 18 ┆ Said the
1935 19 ┆ mouse to the
1936 20 ┆ cur, "Such
1937 21 ┆ a trial,
1938 22 ┆ dear Sir,
1939 23 ┆ With
1940 24 ┆ no jury
1941 25 ┆ or judge,
1942 26 ┆ would be
1943 27 ┆ wasting
1944 28 ┆ our
1945 29 ┆ breath."
1946 30 ┆ "I'll be
1947 31 ┆ judge, I'll
1948 32 ┆ be jury,"
1949 33 ┆ Said
1950 34 ┆ cunning
1951 35 ┆ old Fury:
1952 36 ┆ "I'll
1953 37 ┆ try the
1954 38 ┆ whole
1955 39 ┆ cause,
1956 40 ┆ and
1957 41 ┆ condemn
1958 42 ┆ you
1959 43 ┆ to
1960 44 ┆ death."'
1961
1962 ADDITIONAL BREAKS - LINEBREAKS WITHIN OBJECTS, COLUMN AND PAGE-BREAKS
1963 .....................................................................
1964
1965
1966 ----------------------------------------
1967
1968 LINE-BREAKS
1969 ...........
1970
1971 To break a line within a "paragraph object", two backslashes \\
1972 with a space before and a space or newline after them
1973 may be used.
1974
1975 To break a line within a "paragraph object",
1976 two backslashes \\ with a space before
1977 and a space or newline after them \\
1978 may be used.
1979
1980 The html break br enclosed in angle brackets (though undocumented) is available
1981 in versions prior to 3.0.13 and 2.9.7 (it remains available for the time being,
1982 but is depreciated).
1983
1984 To draw a dividing line dividing paragraphs, see the section on page breaks.
1985
1986
1987 ----------------------------------------
1988
1989 PAGE BREAKS
1990 ...........
1991
1992 Page breaks are only relevant and honored in some output formats. A page break
1993 or a new page may be inserted manually using the following markup on a line on
1994 its own:
1995
1996 page new =\= breaks the page, starts a new page.
1997
1998 page break -\- breaks a column, starts a new column, if using columns,
1999 else breaks the page, starts a new page.
2000
2001 page break line across page -..- draws a dividing line, dividing paragraphs
2002
2003 page break:
2004
2005 -\\-
2006
2007 page (break) new:
2008
2009 =\\=
2010
2011 page (break) line across page (dividing paragraphs):
2012
2013 -..-
2014
2015 BOOK INDEX
2016 ..........
2017
2018 To make an index append to paragraph the book index term relates to it, using
2019 an equal sign and curly braces.
2020
2021 Currently two levels are provided, a main term and if needed a sub-term.
2022 Sub-terms are separated from the main term by a colon.
2023
2024 Paragraph containing main term and sub-term.
2025 ={Main term:sub-term}
2026
2027 The index syntax starts on a new line, but there should not be an empty line
2028 between paragraph and index markup.
2029
2030 The structure of the resulting index would be:
2031
2032 Main term, 1
2033 sub-term, 1
2034
2035 Several terms may relate to a paragraph, they are separated by a semicolon. If
2036 the term refers to more than one paragraph, indicate the number of paragraphs.
2037
2038 Paragraph containing main term, second term and sub-term.
2039 ={first term; second term: sub-term}
2040
2041 The structure of the resulting index would be:
2042
2043 First term, 1,
2044 Second term, 1,
2045 sub-term, 1
2046
2047 If multiple sub-terms appear under one paragraph, they are separated under the
2048 main term heading from each other by a pipe symbol.
2049
2050 Paragraph containing main term, second term and sub-term.
2051 ={Main term:
2052 sub-term+2|second sub-term;
2053 Another term
2054 }
2055
2056 A paragraph that continues discussion of the first sub-term
2057
2058 The plus one in the example provided indicates the first sub-term spans one
2059 additional paragraph. The logical structure of the resulting index would be:
2060
2061 Main term, 1,
2062 sub-term, 1-3,
2063 second sub-term, 1,
2064 Another term, 1
2065
2066 COMPOSITE DOCUMENTS MARKUP
2067 --------------------------
2068
2069 It is possible to build a document by creating a master document that requires
2070 other documents. The documents required may be complete documents that could be
2071 generated independently, or they could be markup snippets, prepared so as to be
2072 easily available to be placed within another text. If the calling document is a
2073 master document (built from other documents), it should be named with the
2074 suffix *.ssm* Within this document you would provide information on the other
2075 documents that should be included within the text. These may be other documents
2076 that would be processed in a regular way, or markup bits prepared only for
2077 inclusion within a master document *.sst* regular markup file, or *.ssi*
2078 (insert). A secondary file of the composite document is built prior to
2079 processing with the same prefix and the suffix *._sst*
2080
2081 basic markup for importing a document into a master document
2082
2083 << filename1.sst
2084
2085 << filename2.ssi
2086
2087 The form described above should be relied on. Within the /Vim/ editor it
2088 results in the text thus linked becoming hyperlinked to the document it is
2089 calling in which is convenient for editing.
2090
2091 SUBSTITUTIONS
2092 -------------
2093
2094 *markup example:*
2095
2096 The current Debian is ${debian_stable} the next debian will be ${debian_testing}
2097
2098 Configure substitution in _sisu/sisu_document_make
2099
2100 @make:
2101 :substitute: /${debian_stable}/,'*{Wheezy}*' /${debian_testing}/,'*{Jessie}*'
2102
2103 *resulting output:*
2104
2105 The current *Debian* is *Wheezy* the next debian will be *Jessie*
2106
2107 Configure substitution in _sisu/sisu_document_make
2108
2109
2110 ----------------------------------------
2111
2112 [1]: <http://packages.qa.debian.org/s/sisu.html>
2113
2114 [2]: from the *Debian* control file
2115
2116 [*1]: square brackets
2117
2118 [*2]: square brackets
2119
2120 [+1]: square brackets
2121
2122 [3]: From sometime after SiSU 0.58 it should be possible to describe SiSU markup
2123 using SiSU, which though not an original design goal is useful.
2124
2125 [4]: files should be prepared using /UTF-8/ character encoding
2126
2127 [5]: a footnote or endnote
2128
2129 [6]: self contained endnote marker & endnote in one
2130
2131 [*]: unnumbered asterisk footnote/endnote, insert multiple asterisks if required
2132
2133 [**]: another unnumbered asterisk footnote/endnote
2134
2135 [*3]: editors notes, numbered asterisk footnote/endnote series
2136
2137 [+2]: editors notes, numbered plus symbol footnote/endnote series
2138
2139 [7]: <http://www.sisudoc.org/>
2140
2141 [8]: <http://www.ruby-lang.org/en/>
2142
2143 [9]: Table from the Wealth of Networks by Yochai Benkler
2144
2145 <http://www.jus.uio.no/sisu/the_wealth_of_networks.yochai_benkler>