From 65477054fd798728bf186aa2938727ddddbe86a5 Mon Sep 17 00:00:00 2001 From: Ralph Amissah Date: Tue, 22 May 2007 02:06:46 +0100 Subject: Imported upstream version 0.52.7 --- data/doc/sisu/html/sisu.1.html | 1335 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1335 insertions(+) create mode 100644 data/doc/sisu/html/sisu.1.html (limited to 'data/doc/sisu/html/sisu.1.html') diff --git a/data/doc/sisu/html/sisu.1.html b/data/doc/sisu/html/sisu.1.html new file mode 100644 index 00000000..4922bab1 --- /dev/null +++ b/data/doc/sisu/html/sisu.1.html @@ -0,0 +1,1335 @@ + + + + + +"sisu"("1") manual page + + +Table of Contents

+ +

Name

+SiSU - Structured information, Serialized Units - a document +publishing system +

Synopsis

+sisu [ -AabcDdEeFHhIMmNnopqrRSstUuVvwXxYyZz0-9 +] [ filename/ wildcard ]

+sisu [ -Ddcv ] [ instruction ]

+sisu [ -CcFLSVvW +]

+Note: commands should be issued from within the directory that contains +the marked up files, cd to markup directory. +

Description

+SiSU SiSU is a +document publishing system, that from a simple single marked-up document, +produces multiple of output formats including: plaintext, html, LaTeX, +pdf, xhtml, XML, info, and SQL (PostgreSQL and SQLite), which share numbered +text objects ("object citation numbering") and the same document structure +information. For more see: <http://www.jus.uio.no/sisu +>

+ +

Summary of man page

+ +
+ +
This +man page covers a number of subjects in brief, including: document processing +command flags; document markup (basic markup and headers); configuration +files; directory structure; skins; document naming; interactive help and +other information.
+
+
+ +

Document Processing Command Flags

+ +
+ +
-A [filename/wildcard] +
+
produces plaintext with dos linefeeds and without markup, (object numbers +are omitted), has footnotes at end of each paragraph that contains them +[ -a for equivalent Unix (linefeed) output file] [see -E for endnotes].
+ +
-a [filename/wildcard] +
+
produces plaintext with Unix linefeeds and without markup, (object numbers +are omitted), has footnotes at end of each paragraph that contains them +[ -A for equivalent dos (linefeed) output file] [see -e for endnotes].
+ +
-b [filename/wildcard] +
+
produces xhtml/XML output for browser viewing (sax parsing).
+ +
-C [--init=site] +
+
configure/initialise shared output directory files initialize shared output +directory (config files such as css and dtd files are not updated if they +already exist unless modifier is used). -C --init=site configure/initialise +site more extensive than -C on its own, shared output directory files/force +update, existing shared output config files such as css and dtd files are +updated if this modifier is used.
+ +
-c [filename/wildcard]
+
screen toggle ansi +screen colour on or off depending on default set (unless -c flag is used: +if sisurc colour default is set to ’true’, output to screen will be with +colour, if sisurc colour default is set to ’false’ or is undefined screen +output will be without colour).
+ +
-D [instruction] [filename]
+
database postgresql +( --pgsql may be used instead) possible instructions, include: --createdb; +--create; --dropall; --import  [filename]; --update  [filename]; --remove  [filename]; +see database section below.
+ +
-d [--db-[database type (sqlite|pg)]] --[instruction] [filename] +
+
database type default set to sqlite, (for which --sqlite may be used instead) +or to specify another database --db-[pgsql, sqlite] (however see -D) possible +instructions include: --createdb; --create; --dropall; --import  [filename]; --update + [filename]; --remove  [filename]; see database section below.
+ +
-E [filename/wildcard] +
+
produces plaintext with dos linefeeds, and without markup, endnotes follow +the main text (in -a endnotes follow the paragraphs that contain them). +There are no object numbers [see -e for Unix (linefeed) output file] [see +-A for footnotes].
+ +
-e [filename/wildcard]
+
produces plaintext with Unix linefeeds, +and without markup, endnotes follow the main text. Object numbers are omitted. +[ -E for equivalent dos (linefeed) output file] [ -a for footnotes].
+ +
-F [--webserv=webrick] +
+
generate examples of (naive) cgi search form for sqlite and pgsql depends +on your already having used sisu to populate an sqlite and/or pgsql database, +(the sqlite version scans the output directories for existing sisu_sqlite +databases, so it is first necessary to create them, before generating the +search form) see -d -D and the database section below. If the optional +parameter --webserv=webrick is passed, the cgi examples created will be set +up to use the default port set for use by the webrick server, (otherwise +the port is left blank and the system setting used, usually 80). The samples +are dumped in the present work directory which must be writable, (with +screen instructions given that they be copied to the cgi-bin directory). +-Fv (in addition to the above) provides some information on setting up +hyperestraier for sisu
+ +
-H [filename/wildcard]
+
produces html without +link suffixes (.html .pdf etc.) ("Hide"). Requires an appropriately configured +web server. [behaviour switched after 0.35 see -h].
+ +
-h [filename/wildcard]
+
produces + html (with hardlinks i.e. with name suffixes in links/local urls). html, +with internal document links that include the document suffix, i.e. whether +it is .html or .pdf (required for browsing directly off a file system, and +works with most web servers). [behaviour switched after 0.35 see -H].
+ +
-I [filename/wildcard] +
+
produces texinfo file.
+ +
-L
+
prints license information.
+ +
-M [filename/wildcard/url] +
+
maintenance mode files created for processing preserved and their locations +indicated. (also see -V)
+ +
-m [filename/wildcard/url]
+
assumed for most other +flags, creates new meta-markup file, (the metaverse ) that is used in all +subsequent processing of other output. This step is assumed for most processing +flags. To skip it see -n
+ +
-N [filename/wildcard/url]
+
document digest or document +content certificate ( DCC ) as md5 digest tree of the document: the digest +for the document, and digests for each object contained within the document +(together with information on software versions that produced it) (digest.txt). +-NV for verbose digest output to screen.
+ +
-n [filename/wildcard/url]
+
skip meta-markup +(building of "metaverse"), this skips the equivalent of -m which is otherwise +assumed by most processing flags.
+ +
-o [filename/wildcard/url]
+
output basic +document in opendocument file format (opendocument.odt).
+ +
-p [filename/wildcard] +
+
produces LaTeX pdf (portrait.pdf & landscape.pdf). Default paper size is set +in config file, or document header, or provided with additional command +line parameter, e.g. --papersize-a4 preset sizes include: ’A4’, U.S. ’letter’ and +’legal’ and book sizes ’A5’ and ’B5’ (system defaults to A4).
+ +
-q [filename/wildcard] +
+
quiet less output to screen.
+ +
-R [filename/wildcard]
+
copies sisu output files +to remote host using rsync. This requires that sisurc.yml has been provided +with information on hostname and username, and that you have your "keys" +and ssh agent in place. Note the behavior of rsync different if -R is used +with other flags from if used alone. Alone the rsync --delete parameter is +sent, useful for cleaning the remote directory (when -R is used together +with other flags, it is not). Also see -r
+ +
-r [filename/wildcard]
+
copies sisu +output files to remote host using scp. This requires that sisurc.yml has +been provided with information on hostname and username, and that you have +your "keys" and ssh agent in place. Also see -R
+ +
-S
+
produces a sisupod a zipped +sisu directory of markup files including sisu markup source files and +the directories local configuration file, images and skins. Note: this +only includes the configuration files or skins contained in ./_sisu not +those in ~/.sisu -S  [filename/wildcard] option. Note: (this option is tested +only with zsh).
+ +
-S [filename/wildcard]
+
produces a zipped file of the prepared +document specified along with associated images, by default named sisupod.zip +they may alternatively be named with the filename extension .ssp This provides +a quick way of gathering the relevant parts of a sisu document which can +then for example be emailed. A sisupod includes sisu markup source file, + (along with associated documents if a master file, or available in multilingual +versions), together with related images and skin. SiSU commands can be +run directly against a sisupod contained in a local directory, or provided +as a url on a remote site. As there is a security issue with skins provided +by other users, they are not applied unless the flag --trust or --trusted is +added to the command instruction, it is recommended that file that are +not your own are treated as untrusted. The directory structure of the unzipped +file is understood by sisu, and sisu commands can be run within it. Note: +if you wish to send multiple files, it quickly becomes more space efficient +to zip the sisu markup directory, rather than the individual files for +sending). See the -S option without [filename/wildcard].
+ +
-s [filename/wildcard] +
+
copies sisu markup file to output directory.
+ +
-t [filename/wildcard (*.termsheet.rb)] +
+
standard form document builder, preprocessing feature
+ +
-U [filename/wildcard] +
+
prints url output list/map for the available processing flags options +and resulting files that could be requested, (can be used to get a list +of processing options in relation to a file, together with information +on the output that would be produced), -u provides url output mapping +for those flags requested for processing. The default assumes sisu_webrick +is running and provides webrick url mappings where appropriate, but these +can be switched to file system paths in sisurc.yml
+ +
-u [filename/wildcard] +
+
provides url mapping of output files for the flags requested for processing, +also see -U
+ +
-V
+
on its own, provides SiSU version and environment information +(sisu --help env)
+ +
-V [filename/wildcard]
+
even more verbose than the -v flag. +(also see -M)
+ +
-v
+
on its own, provides SiSU version information
+ +
-v [filename/wildcard] +
+
provides verbose output of what is being built, where it is being built +(and error messages if any), as with -u flag provides a url mapping of +files created for each of the processing flag requests. See also -V
+ +
-W
+
starts +ruby’s webrick webserver points at sisu output directories, the default +port is set to 8081 and can be changed in the resource configuration files. +[tip: the webrick server requires link suffixes, so html output should +be created using the -h option rather than -H ; also, note -F webrick +].
+ +
-w [filename/wildcard]
+
produces concordance (wordmap) a rudimentary +index of all the words in a document.
+ +
-X [filename/wildcard]
+
produces XML +output with deep document structure, in the nature of dom.
+ +
-x [filename/wildcard] +
+
produces XML output shallow structure (sax parsing).
+ +
-Y [filename/wildcard] +
+
produces a short sitemap entry for the document, based on html output and +the sisu_manifest. --sitemaps generates/updates the sitemap index of existing +sitemaps. (Experimental, [g,y,m announcement this week])
+ +
-y [filename/wildcard] +
+
produces an html summary of output generated (hyperlinked to content) and +document specific metadata (sisu_manifest.html). This step is assumed for +most processing flags.
+ +
-Z [filename/wildcard]
+
Zap, if used with other processing +flags deletes output files of the type about to be processed, prior to +processing. If -Z is used as the lone processing related flag (or in conjunction +with a combination of -[mMvVq]), will remove the related document output +directory.
+ +
-z [filename/wildcard]
+
produces php (zend) [this feature is disabled +for the time being]
+
+ +

modifiers

+ +
+ +
--no-ocn
+
[with -h -H or -p] switches off object +citation numbering. Produce output without identifying numbers in margins +of html or LaTeX/pdf output.
+ +
--no-annotate
+
strips output text of editor endnotes~[* +square brackets ]~ denoted by asterisk or dagger/plus sign
+ +
--no-asterisk
+
strips +output text of editor endnotes~[* square brackets ]~ denoted by asterisk +sign
+ +
--no-dagger
+
strips output text of editor endnotes~[+ square brackets +]~ denoted by dagger/plus sign
+
+ +

databases

+ +
+ +
dbi - database interface +
+
-D or --pgsql set for postgresql -d or --sqlite default set for sqlite -d is +modifiable with --db=[database  type  (pgsql  or  sqlite)]
+ +
-Dv --createall
+
initial +step, creates required relations (tables, indexes) in existing postgresql +database (a database should be created manually and given the same name +as working directory, as requested) (rb.dbi) [ -dv --createall sqlite equivalent] +it may be necessary to run sisu -Dv --createdb initially
+ +
NOTE: at the present +time for postgresql it may be necessary to manually create the database. +The command would be
+
’createdb [database name]’ where database name would +be SiSU_[present working directory name (without path)]. Please use only +alphanumerics and underscores.
+ +
-Dv --import
+
[filename/wildcard] imports data +specified to postgresql db (rb.dbi) [ -dv --import sqlite equivalent]
+ +
-Dv --update +
+
[filename/wildcard] updates/imports specified data to postgresql db (rb.dbi) +[ -dv --update sqlite equivalent]
+ +
-D --remove
+
[filename/wildcard] removes specified +data to postgresql db (rb.dbi) [ -d --remove sqlite equivalent]
+ +
-D --dropall +
+
kills data" and drops (postgresql or sqlite) db, tables & indexes [ -d --dropall +sqlite equivalent]
+ +
The v in e.g. -Dv is for verbose output.
+
+
+ + +

Shortcuts, Shorthand +for multiple flags

+ +
+ +
--update [filename/wildcard]
+
Checks existing file output +and runs the flags required to update this output. This means that if only +html and pdf output was requested on previous runs, only the -hp files will +be applied, and only these will be generated this time, together with the +summary. This can be very convenient, if you offer different outputs of +different files, and just want to do the same again.
+ +
-0 to -5 [filename or +wildcard]
+
Default shorthand mappings (note that the defaults can be +changed/configured in the sisurc.yml file):
+
+

+-0 -mNhwpAobxXyYv [this is the +default action run when no options are give, i.e. on ’sisu [filename]’]

+-1 -mNHwpy +

+-2 -mNHwpaoy

+-3 -mNhwpAobxXyY

+-4 -mNhwpAobxXDyY  --import

+-5 -mNhwpAobxXDyY  --update +

+add -v for verbose mode and -c for color, e.g. sisu -2vc [filename or wildcard] +

+consider -u for appended url info or -v for verbose output +

Document Markup

+SiSU +Markup an incomplete summary.

+Note: files should be marked up for SiSU +using UTF-8 encoding.

+Some interactive help on markup is available, by typing + sisu and selecting markup or sisu --help markup +

+ +
Sample markup files can +be used as examples:
+
<http://www.jus.uio.no/sisu/sample +>
+ +
actual marked up plaintext +files ready for use:
+
<http://www.jus.uio.no/sisu/sample/markup +>
+ +
as html with +syntax highlighting for viewing:
+
<http://www.jus.uio.no/sisu/sample/syntax +> +
+ +
an alternative presentation of markup syntax:
+
<http://www.jus.uio.no/sisu/sample/on_markup.txt +> +
+
+ +

Basic Markup

+Data text markup (alternative to available html subset)

+Heading +levels are :A~ ,:B~ ,:C~ ,1~ ,2~ ,3~ ... :A - :C being part / section headings, +followed by other heading levels, and 1 -6 being headings followed by substantive +text or sub-headings. :A~ usually the title :A~? conditional level 1 heading +(used where a stand-alone document may be imported into another)

+1~filename +level 1 heading, 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)

+!{ emphasis }!

+*{ bold text }* +

+_{ underscore }_

+/{ italics }/

+’"{ citation }"

+^{ superscript }^

+,{ subscript +},

++{ inserted text }+

+-{ strikethrough }- +

Footnotes/Endnotes

+

+~{ a footnote +or endnote }~

+footnote/endnote ~{ self contained endnote marker & endnote +in one }~

+~{* unnumbered asterisk footnote/endnote, insert multiple asterisks +if required }~

+~[* editors notes, numbered asterisk footnote/endnote series +]~ (+ the plus sign may be used as well)

+alternative endnote pair notation: +

+~^ endnote marker

+^~ endnote text following the paragraph in which the marker +occurs +

Line Operations (marker placed at start of line)

+

+!_ bold line

+_1 +indent paragraph one level

+_2 indent paragraph two steps

+_* bullet paragraph +

+# number paragraph (see headers for numbering document headings) +

+_# number paragraph level 2 (see headers for numbering document headings) + +

Links

+

+{ link name }http://url.org +

+{ image.png }http://url.org +

+{ image.png }image +

+{ tux.png 64x80 }image

+NOTE: (a) png and jpg support only (no gif) (b) width +x height, not required if imagemagick is installed, (where provided, dimensions +may be smaller than the actual image), [images should be no larger than +width: 480 and height: 640]

+the shortcut:

+{~^ [text to link] }http://url.org + +

+is equivalent to:

+{ [text to link] }http://url.org + ~{ http://url.org + }~ +

+(which produces hyper-linked text within a document/paragraph, with an endnote +providing the url for the text location used in the hyperlink)

+url example: +

+{ SiSU Geek Writer }http://www.jus.uio.no/sisu/ +

+linked image:

+{ tux.png 64x80 +"a better way" }http://www.jus.uio.no/sisu/ + image example with all options +

+note width x height

+the shortcut:

+{ [text to link] [3sS]}markup_source_filename.sst +

+if a server host name has been provided/configured, will provide a list +of available output types that would be generated using the shortcut command +and the markup file provided, i.e. output generated using the command (as +configured): "sisu -3sS markup_source_filename.sst", using server host, directory +stub, filename to compose the link. +

Adding a fixed names in html

+

+*~[name] +manual location marker/tagging at present only in html to produce <a name="[name]"></a> +(use sparingly)

note at a heading level the same is automatically achieved +by providing names to headings 5 and 6 i.e. 5~[name] and 6~[name] or in the +case of auto-heading numbering, without further intervention.
+ +

Escape object +citation numbering

+

+(place marker at end of paragraph)

+~# unnumbered paragraph +

+-# unnumbered paragraph, delete when not required (place marker at end of +paragraph) [used in dummy headings, eg. for segmented html]

+It is convenient +to mention here that the -0 flag generates html and latex/pdf output without +visible object character numbers.

+sisu -0 [filename.sst] +

Page breaks (LaTeX/pdf)

+

+page +breaks are introduced to pdfs either as header instructions, indicating +that pages should break at given levels, and mentioned in the header section, +or manually, using the following notation

+<:pb> page break, which breaks +a page, starting a new page in single column text and a new column in double +column text

+<:pn> page new, which starts a new page, in both single and double +column text (leaving an empty column in double column text if necessary). + +

Comment line

+

+% ignored by sisu in processing if placed at beginning of +line

+%% ignored by sisu in processing if placed at beginning of line, used +for folding by vim folds +

Special characters

+special characters can be escaped +with a backslash { } < > are contextual special characters, (in combination +with other characters). ~ - _ / % ^ and occasionally ! # + , are special characters +in particular circumstances, see the syntax chart. [note that SiSU is not +optimised for technical writing] +

Tables

+

+table{ [number of columns] [column +width %];[column width %] +

[table content, line breaks are important +see example below]
+ +

}table +

sample table:
+ +

table{~h c3; 26; 32; 32; +

This is a table, column1
+ this would become row one of column two
+ column three of row one is here
+ +

column one row 2
+ column two of row two
+ column three of row two, and so on
+ +

column one row three
+ and so on
+ here
+
+ }table +

whole table gets an object citation number +

+

Other Grouped or +Pre-formatted Text

+poem{ +

[Text here]
+ +

[Text here]
+ +

}poem +

each verse is given an object citation number +

----
+ +

group{ +

[Text here]
+ +

}group +

whole group gets an object citation number +

----
+ +

code{ +

[Text here]
+ +

}code +

whole group gets an object citation number +

+

Composite Documents

+

+It +is possible to build a document by requiring other documents. The documents +required may complete documents that could be generated independently, +or they could be markup snippets, prepared so as to be easily available +to be placed within another text. If the calling document is a master document +(built mainly from other documents), by convention it should be named with +the suffix .ssm (master) Within this document you would provide information +on the other documents that should be included within the text. These may +be other documents that would be processed in a regular way, or markup +bits prepared only for inclusion within a master document .sst regular markup +file, or .ssi (insert/information) .sst A secondary file of the composite +document is built prior to processing with the same prefix and the suffix + ._sst and ._sst There are a number of alternative syntaxes for requiring +external documents in order to permit use of ascii hypertext linking available +in the vim editor. They are as follows: +

+

+ +
basic markup for importing a document +
+
+

r{ filename } +

{ filename.si }require +

<< { filename.si } #for vim folds +

+

+ +
importing a document with textlink syntax
+
+

|filename.si|@|^|require +

<< |filename.si|@|^| + +

#for vim folds +

+ +
importing a document with thlnk syntax
+
+

<url:filename.si>require + +

<< <url:filename.si> #for vim folds +

+ +
remote documents may be called with the +thlnk syntax (or regular sisu syntax), e.g.
+
+

<< <url:http://www.url.com/filename.si +> + +

+
+ +

Document Headers

+Header tags appear at the beginning of a document and +provide meta information on the document (such as the Dublin Core), or +information as to how the document as a whole is to be processed. +

All +header instructions may take either form: @headername: [introduced in 0.38] + +

or 0~headername All Dublin Core meta tags are available +

@indentifier: +information or instructions [introduced in 0.38] +

or +

0~indentifier information +or instructions, old equivalent, depreciated +

where the "identifier" is +a tag recognised by the program, and the "information" or "instructions" +belong to the tag/indentifier specified. +

Note: a header where used should +only be used once; all headers apart from @title: (0~title) are optional; +the @structure: (0~toc) header is used to describe document structure, +and can be useful to know. +

@structure: PART; CHAPTER; SECTION; ARTICLE; +none; none; +

structure can be defined by a match words or regular expression +(the regular expression is assumed to start at the beginning of a line +of text i.e. ^) +

For help see one of the following (and markup samples):
+ +

* interactive help - type ’sisu --help headers’
+ +

* marked up text samples
+ +

* the SiSU_Markup.txt file provided with the program
+ +

* an outline of headers is provided below -->
+ +

Outline of header options

+% SiSU 0.38 [declared file-type identifier with +markup version] +

@title: My Title - This is now the Title of the Document + +

and used as such +

@subtitle: The Subtitle if any +

@creator: [or ~author] + +

Ralph Amissah +

@subject: (whatever your subject) +

@description: +

@publisher: + +

@contributor: +

@translator: [or ~translated_by] +

@illustrator: [or ~illustrated_by] + +

@prepared_by: [or ~digitized_by] +

@date: 2000-08-27 [ also @date.created: +@date.issued: @date.available: @date.valid: @date.modified: ] +

@type: article + +

@format: +

@identifier: +

@source: +

@language: [or @language.document:] +language in which current version of document is published. Some country +settings result in processing adjustments, e.g. in LaTeX hyphenation, some +country codes are recognized, but the language name in Engish is preferred. +English is the default setting. (en - English, fr - French, de - German, it +- Italian, es - Spanish, pt - Portuguese, sv - Swedish, da - Danish, fi - Finnish, +no - Norwegian, is - Icelandic, nl - Dutch, ee - Estonian, hu - Hungarian, pl +- Polish, ro - Romanian, ru - Russian, gl - Greek, uk - Ukranian, tr - Turkish, +si - Slovene, sk - Slovak, hr - Croatian, cs - Czech, bg - Bulgarian ) [however, +encodings are not available for all of the languages listed.] +

@language.original: + +

original language in which the work was published +

@papersize: (A4|US_letter|book_B5|book_A5|US_legal) + +

@relation: +

@coverage: +

@rights: copyright, all rights reserved, public +domain, copyleft, creative commons variant, etc. +

@owner: +

@keywords: text +document generation processing management LaTeX pdf structured XML citation +[your keywords here, used for example by rss feeds, and in sql sear ches] + +

@abstract: [paper abstract, placed after table of contents] +

@comment: +[...] +

@catalogue: loc=[Library of Congress classification]; dewey=[Dewey +classification]; isbn=[ISBN]; pg=[Project Gutenberg text number] +

@classify_loc: + +

Library of Congress classification +

@classify_dewey: Dewey classification + +

@classify_isbn: ISBN +

@classify_pg: Project Gutenberg text number +

@prefix_a: +[prefix is placed just before table of contents - not implemented] +

@prefix_b: +or @prefix: [prefix is placed just after table of contents] +

@rcs: $Id$ +[or @cvs: used by rcs or cvs to embed version (revision control) information +into document, rcs or cvs can usefully provide a history of updates to +a document ] +

@structure: PART; CHAPTER; SECTION; ARTICLE; none; none; +optional, where document structure can be defined by a match words or regular +expression (the regular expression is assumed to start at the beginning +of a line of text i.e. ^) default markers :A~ to :C~ and 1~ to 6~ can be used +within text instead, without this header ta g, and may be used to supplement +the instructions provided in this header tag if provided (@structure: is +a synonym for @toc:) +

@markup: information on the markup used, e.g. new=1,2,3; +break=4; num_top=4 [or newpage=1,2,3; breakpage=4; num_top=4] newpage and +breakpage, heading level, used by LaTeX to breakpages. breakpage: starts +on a new page in single column text and on a new column in double column +text; newpage: starts on a new page for both single and double column texts. +num_top=4 [auto-number document, starting at level 4. the default is to provide +3 levels, as in 1 level 4, 1.1 level 5, 1.1.1 level 6, markup to be merged +within level] num_extract [take numbering of headings provided (manually +in marked up source document), and use for numbering of segments. Available +where a clear numbering structure is provided within document, without +the repetition of a number in a header.] [In 0.38 notation, you would map +to the equivalent levels, the examples provided would map to the following +new=A,B,C; break=1; num_top=1 [or newpage=A,B,C; breakpage=1; num_top=1] +see headings] +

@bold: [regular expression of words/phrases to be made bold] + +

@italics: [regular expression of words/phrases to italicise]
+ @vocabulary: name of taxonomy/vocabulary/wordlist to use against document + +

@skin: skin_doc_[name_of_desired_document_skin] +

@links: { SiSU }http://www.jus.uio.no/sisu/ + +{ FSF }http://www.fsf.org + +

@promo: sisu, ruby, search_libre_docs, open_society +[places content in right pane in html, makes use of list.yml and promo.yml, +commented out sample in document sample: free_as_in_freedom.richard_stallman_crusade_for_free_software.sam_williams.sst] + +

:A~ Top level heading [this usually has similar content to the title @title: +] NOTE: the heading levels described here are in 0.38 notation, see heading + +

:B~ Second level heading [this is a heading level divider] +

:C~ Third +level heading [this is a heading level divider] +

1~ Top level heading preceding +substantive text of document or sub-heading 2, the heading level that would +normally be marked 1. or 2. or 3. etc. in a document, and the level on which +sisu by default would break html output into named segments, names are +provided automatically if none are given (a number), otherwise takes the + +

form 1~my_filename_for_this_segment +

2~ Second level heading preceding +substantive text of document or sub-heading 3 , the heading level that would +normally be marked 1.1 or 1.2 or 1.3 or 2.1 etc. in a document. +

3~ Third level +heading preceding substantive text of document, that would normally be +marked 1.1.1 or 1.1.2 or 1.2.1 or 2.1.1 etc. in a document +

NOTE: headers and heading +levels used in the description provided refer to 0.38 markup (a conversion +script provided in sisu-examples, modify.rb makes conversion between 0.37 +and 0.38 markup simple) +

For some help on document structure try +

sisu --help + +

headings +

and view sample markup documents provided +

+

+

Configuration +Files

+

+Some configuration is required for SiSU, specifying in which directory +processing should be done, and where the generated output should be placed. +

+SiSU resource configuration is determined by looking at the following files +if they exist:

+./_sisu/sisurc.yml

+~/.sisu/sisurc.yml

+/etc/sisu/sisurc.yml

+In +the absence of instructions in any of these it falls back to the internal +program defaults.

+Configuration determines the output and processing directories +and the database access details.

+A sample sisurc.yml may be found in /etc/sisu/sisurc.yml + +

+

More HELP on Markup and headers

+type: sisu ~
+ sisu --help
+ +

markup help is available on:
+ document wide instructions: headers (document structure)
+ general text markup: headings; endnotes; tables
+ +

A markup table and sample marked-up files (also in html with syntax highlighting) +are available at: +

<http://www.jus.uio.no/sisu/sample +> +

+

DIRECTORY STRUCTURE +& Document Output

+ +
+ +
SiSU determines output directories by looking at the resource +configuration files, and in their absence the programs internal defaults. +
+
+
+ +

Default Directories

+ +
+ +
In the absence of other specifications in
+
~/.sisu/sisurc.yml +in /etc/sisu/sisurc.yml SiSU writes to the following directories, processing +files are placed in sub-directories within ./_sisu/processing and if that +is not writable to /tmp/sisu_processing
+
+

+Output is written to sub-directories +within /var/www/ if it exists and is writable, and otherwise to ~/sisu_output + +

Markup Document Directories and File Mapping

+ +
+ +
Ideally documents should be +placed as collections sub-directories of their own, with a common denominator, +such as subject or author.
+
+ +
The last part of a directory path is used to +create a sub-directory into which generated documents are placed, in (sub-sub)directories +of their own.
+
+ +
the document
+
+
+

+

~/ebook/free_culture.sst
+ +
+ +
would map to
+
+
+

+

~[configured +output path]/ebook/free_culture
+ +
+ +
within which would be placed all html, +XML, pdf output, typically under the names:
+
+
+

+

index.html index for segmented +text

+doc.html full length scrollable document

+toc.html index for segmented +text

+html segments, as many as there may be... +

+ +
portrait.pdf
+
+
+

+landscape.pdf

+sax.xml +XML shallow structure, sax type parsing

+dom.xml XML deeper structure, dom +type parsing

+scroll.xhtml xhtml

+plain.txt plain text

+ +

Multi-language Document +File Naming and Directory Mapping

+ +
+ +
If the same document exists in different +language versions, and it is desired that the published language versions +should reside in the same output directory, the following filenaming convention +should be observed, using Spannish as the sample language code (es) [it +is very likley the use of country codes as language codes will be changed +or extended in future] [filename]~[language code].sst
+
+ +
filename~es.sst
+
+ +
within +sisurc.yml under the heading default the setting of language file: at 1, +2 or 3 determines the output filenaming convention used, as follows:
+
+ +
(1) +[output directory path]/filename/es.index.html
+
+ +
(2) [output directory path]/filename/index.es.html +
+
+ +
(3) [output directory path]/filename/index.html.es (which Apache for example +can be configured to use to automatically serve each users preference) +
+
+ +
filename~fr.sst
+
+ +
filename~de.sst
+
+ +
etc. would be placed in the same directory +using the same convention as indeed would:
+
+ +
filename.sst
+
+ +
using the default +convention mapping convention.
+
+ +
Selecting this form of filename will overide +other language settings including the language header within a document. +
+
+
+ +

Markup Document Directories and Database Mapping

+

+Similarly there is a mapping +to the database into which documents are placed.

+The last part of a directory +path is used to create a sub-directory into which generated documents are +placed, in a database of the same name, unless overridden.

+Documents within +the directory ~/ebook

+

~/ebook/free_culture.sst
+

+would be placed in tables +within the database

+

SiSU_ebook
+ +

SKINS - document, directory and site skins

+

+Skins +modify the default appearance of document output on a document, directory, +or site wide basis. Skins are looked for in the following locations:

+./_sisu/skin +

+~/.sisu/skin

+/etc/sisu/skin

+Within the skin directory are the following +the default sub-directories for document skins:

+./skin/doc

+./skin/dir

+./skin/site +

+Documents take on a document skin, if the header of the document specifies +a skin to be used.

+A directory may be mapped on to a particular skin, so +all documents within that directory take on a particular appearance. If +a skin exists in the skin/dir with the same name as the document directory, +it will automatically be used for each of the documents in that directory, +(except where a document specifies the use of another skin, in the skin/doc +directory). when end

+A personal habit is to place all skins within the +doc directory, and symbolic links as needed from the site, or dir directories +as required.

+A site skin, modifies the program default skin.

+Sample skins +may be found in /etc/sisu/skin/doc and /usr/share/doc/sisu/sisu_markup_samples/dfsg/_sisu/skin/doc +(or equivalent directory)

+Samples of list.yml and promo.yml may be found +in /usr/share/doc/sisu/sisu_markup_samples/dfsg/_sisu/skin/yml (or equivalent +directory) +

Document Naming Convention

+

+SiSU documents are named with the +suffix ss followed by a third distinguishing letter, usually t for ordinary +text files.

+.sst is used by regular documents, and for most purposes is all +you need to be aware of

+.ssm suffix indicates a master or composite document, +i.e. a document which requests other documents, which may have the file extension +.sst or .ssi. See section on Composite Documents for information on how these +are prepared.

+.ssi indicates some prepared sisu markup information that is +to be requested within master or composite document(s) and is not to be +processed as a stand-alone document.

+._sst and .-sst suffix are reserved for +SiSU processing, and indicate a secondary file. Such secondary files are +created when a composite file is constructed, and when a url is provided, +it is saved locally for processing, as a secondary processing file. Secondary +files may be clobbered by SiSU at will, and are not a way of storing information. + +

.sxs.xml simple xml sax, sisu markup representation +

.sxd.xml simple xml dom, + +

sisu markup representation +

.sxn.xml simple xml node, sisu markup representation + +

.sxs.xml.sst or .sxd.xml.sst or .sxn.xml.sst auto-converted from a simple xml markup +representation (sxs, sxd, sxn) +

Remote Operations

+

+These may be of three +basic types.

+Instruction that processed files are to be copied to a remote +server, using the -r or -R flag as part of the processing instruction. This +requires previous setting up/configuration of the method to be used (eg +scp assumed for -r and rsync for -R) and url to which these files are to +be sent. *

+The downloading of a remote file for processing using SiSU locally, +which is achieved in one of two ways:

+A processing instruction may include +the url to the a remote file that is to be processed - this will be downloaded +and given a temporary file .t extension, and will be processed using SiSU +locally.

+A file may request the inclusion of a remote document within it, +see comments on "Composite Documents" for the request syntax.

+Finally SiSU +may be run on a remote server, which you download marked up files to for +processing. This is not really a function of the operation of SiSU, just +an available possibility given that not much bandwidth is required.

+* with +regard to remote files processed locally, the -r option, a limitation is +that it is up to the user to ensure that the remote file does not have +an identical filename to another, e.g. local file, that is to be processed +in the same directory. So far this has not been found to happen in practice... +Alternative solutions are under consideration, but it is desired that filenames +be human assigned, and meaningful, so hash keys of contents for filenames +are not amongst the options considered. +

Note

+

+For basic use only a fraction +of the information provided here is required. There may be a bit of an information +management problem in determining what though. For the markup of a book +see the samples provided in <http://www.jus.uio.no/sisu/sample +> and referred +to in the text <http://www.jus.uio.no/sisu/SiSU +> The flags to generate html +and pdf for use locally would be sisu -mHp [name of file to be processed] +This does assume an ok install and setup of SiSU and the associated software +it uses. +

+

Processing Examples

+

+To initialise a new directory sisu -C

+Note: +this create a corresponding output subdirectory and this copies css stylesheet +files and basic image files to the output directory. The output directory +is created in the output path/directory as a subdirectory with its name +corresponding to that of the directory you are currently initialising.

+generate +the metafile used in subsequent processing only (note changes made to the +markup file will not appear in subsequently generated text unless this +flag is used: sisu -m [filename or wildcard]

+to create html and pdf output, +with verbose output of samplefile1.sst and samplefile2.sst sisu -mhpv samplefile1.sst +samplefile2.sst

Note: -m does initial processing, and -H omits filename +suffixes and requires a properly configured web server. -h is used to include +filename suffixes for file system viewing
+

+generate html, a word map and +pdf with verbose output for all marked up documents in a directory: sisu +-mhwpv *

+generate html, word map, pdf, plaintext, xhtml, xml sax and xml +dom versions with verbose output for all marked up documents in a directory: +sisu -mhwpabxXv *

+to create html, pdf, xml, plaintext and a concordance +file (wordmap) as output, with verbose output of all marked up files in +a directory sisu -mhpxXawv *.{r,s}?

+generate html, word map and pdf and place +on remote server with verbose output 2 named example files in a directory +(assumes has been set up, and first time must be run without other flags +ie sisu -mrv [filenames/wildcard]): sisu -mhwprv example_file.sst other_example_file.sst +

+to process a remote sisu marked up file (html,pdf,concordance), provide +the url(s) (works for text only files, will be downloaded and processed +locally): sisu -mhwpv http://www.jus.uio.no/sisu/sample/markup/gpl2.fsf.sst + http://www.jus.uio.no/sisu/sample/markup/autonomy_markup0.sst +

+one file is local the other remote process (html,pdf,concordance,plaintext +and place on pre-set remote destination): sisu -mhwparv gpl2.fsf.sst http://www.jus.uio.no/sisu/sample/markup/autonomy_markup0.sst + +

+initialize database, create relations (first manually create database with +same name as working directory): sisu -Dv createall

+it may be necessary +to first run sisu -Dv createdb

+import all marked up files first time into +a database: sisu -Dv import *

+-c toggles color +

Interactive Help Options

+

+SiSU +has an interactive help, which is accessed by typing just "sisu" at the +command line, or as described below: sisu commands, document preparation, +customisation, installation etc.
+

try:
+sisu --help  
+  sisu help
+    help             sisu --help
+    commands         sisu --help commands
+    environment      sisu --help env
+  ------------------------------------------
+  Using SiSU
+    commands:        sisu --help commands
+  ------------------------------------------
+  Preparing Documents for SiSU
+    markup:          sisu --help markup     (an incomplete overview)
+    headers:         sisu --help headers    (document-wide instructions, meta-data)
+    structure        sisu --help structure  (document structure, headings,
+tables of contents)
+    endnotes:        sisu --help endnotes
+    tables:          sisu --help tables
+    an example 0.37: sisu --help example37
+    an example 0.38: sisu --help example38
+  ------------------------------------------
+    search           sisu --help search
+  ------------------------------------------
+    customise:       sisu --help customise
+  ------------------------------------------
+  SiSU’s License
+    license:         sisu --help license
+  sisu interactive help topics include:
+        keywords include: list, commands, shortcuts, markup, syntax, headers,
+        headings, endnotes, tables, example, customise, skin, environment,
+        directories, path, language, db, install, setup, configure,
+        external_programs, dublincore, termsheet, search, features,
+        external_programs, license, exit
+
+

+

SiSU VERSION CONVERSION

+

+sisu --to-current [filename/wildcard] converts from +0.37 markup to current markup (0.38) +

sisu --to-38 [filename/wildcard] converts + +

from 0.37 markup to 0.38 +

sisu --to-37 [filename/wildcard] converts from 0.38 + +

markup to 0.37 +

sisu --convert-36to37 [filename/wildcard] re-names file from + +

pre-0.36 convention to 0.37 +

sisu --convert-footnotes [filename/wildcard] converts + +

footnotes to preferred embedded footnote markup style +

sisu --convert-footnotes-force +[filename/wildcard] converts footnotes to preferred embedded footnote markup +style, even if there is a mismatch of footnote numbers. WARNING: there is +a problem with the source document and it is necessary to manually check +where each footnotes actually should be. +

convert from sst to simple xml +representations (sax, dom and node): +

sisu --to-sax [filename/wildcard] or +sisu --to-sxs [filename/wildcard] +

sisu --to-dom [filename/wildcard] or sisu +--to-sxd [filename/wildcard] +

sisu --to-node [filename/wildcard] or sisu --to-sxn +[filename/wildcard] +

convert to sst from simple xml representations (sax, +dom and node): +

sisu --from-xml2sst [filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]] + +

or the same: +

sisu --from-sxml [filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]] + +

sisu --from-kdi [kdissert filename] attempts to convert a kdissert file (.kdi) + +

to sisu markup +

sisu --identify [filename/wildcard] attempts to identify + +

the markup version of the file +

sisu --query=[version number] and sisu --query=history + +

provides a brief summary of changes to SiSU markup +

+

Sample Markup Documents

+

+ +

+Sample markup documents are provided in sisu-examples and are available +online. +

+

Home Page

+

+<http://www.jus.uio.no/sisu +> +

+

Author

+Ralph Amissah <ralph@amissah.com> +or <ralph.amissah@gmail.com> +

+

See Also

+sisu(8) +, sisu_webrick(1) +, sisu_termsheet(1) +, +sisu_pdf(1) + sisu_sqlite(1) + sisu_postgresql(1) + sisu_vim(7) +

+ +

+Table of Contents

+

+ + -- cgit v1.2.3