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