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