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