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