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