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