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