diff options
Diffstat (limited to 'data/doc/sisu/html/sisu.1.html')
| -rw-r--r-- | data/doc/sisu/html/sisu.1.html | 1335 |
1 files changed, 1335 insertions, 0 deletions
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 @@ + <!-- manual page source format generated by PolyglotMan v3.2, --> +<!-- available at http://polyglotman.sourceforge.net/ --> + +<html> +<head> +<title>"sisu"("1") manual page</title> +</head> +<body bgcolor='white'> +<a href='#toc'>Table of Contents</a><p> + +<h2><a name='sect0' href='#toc0'>Name</a></h2> +<b>SiSU</b> - Structured information, Serialized Units - a document +publishing system +<h2><a name='sect1' href='#toc1'>Synopsis</a></h2> +<b>sisu</b> <b>[</b> <i>-AabcDdEeFHhIMmNnopqrRSstUuVvwXxYyZz0-9</i> +<b>] [</b> <i>filename/</i> wildcard <b>]</b> <p> +<b>sisu</b> <b>[</b> <i>-Ddcv</i> <b>] [</b> <i>instruction</i> <b>]</b> <p> +<b>sisu</b> <b>[</b> <i>-CcFLSVvW</i> +<b>]</b> <p> +Note: commands should be issued from within the directory that contains +the marked up files, cd to markup directory. +<h2><a name='sect2' href='#toc2'>Description</a></h2> +<b>SiSU</b> 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: <i><<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a> +></i> <p> + +<h2><a name='sect3' href='#toc3'>Summary of man page</a></h2> + +<dl> + +<dt>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. </dt> +<dd> </dd> +</dl> + +<h2><a name='sect4' href='#toc4'>Document Processing Command Flags</a></h2> + +<dl> + +<dt><b>-A</b><i> [filename/wildcard]</i> +</dt> +<dd>produces <i>plaintext</i> with <i>dos</i> linefeeds and without markup, (object numbers +are omitted), has footnotes at end of each paragraph that contains them +[ <i>-a</i> for equivalent Unix (linefeed) output file] [see <i>-E</i> for endnotes]. </dd> + +<dt><b>-a</b><i> [filename/wildcard]</i> +</dt> +<dd>produces <i>plaintext</i> with <i>Unix</i> linefeeds and without markup, (object numbers +are omitted), has footnotes at end of each paragraph that contains them +[ <i>-A</i> for equivalent dos (linefeed) output file] [see <i>-e</i> for endnotes]. </dd> + +<dt><b>-b</b><i> [filename/wildcard]</i> +</dt> +<dd>produces <i>xhtml/XML</i> output for browser viewing (sax parsing). </dd> + +<dt><b>-C</b><i> [--init=site]</i> +</dt> +<dd><i>configure/initialise</i> 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). <b>-C</b><i> --init=site</i> <i>configure/initialise</i> +site more extensive than <i>-C</i> 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. </dd> + +<dt><b>-c</b><i> [filename/wildcard]</i> </dt> +<dd>screen <i>toggle</i> 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). </dd> + +<dt><b>-D</b><i> [instruction]</i><b> [filename]</b> </dt> +<dd>database postgresql +( <i>--pgsql</i> may be used instead) possible instructions, include: <i>--createdb;</i> +<i>--create;</i> <i>--dropall;</i> <i>--import</i> [filename]; <i>--update</i> [filename]; <i>--remove</i> [filename]; +see database section below. </dd> + +<dt><b>-d</b><i> [--db-[database</i><b> type</b><i> (sqlite|pg)]]</i><b> --[instruction]</b><i> [filename]</i> +</dt> +<dd>database type default set to sqlite, (for which <i>--sqlite</i> may be used instead) +or to specify another database <i>--db-[pgsql,</i> sqlite] (however see -D) possible +instructions include: <i>--createdb;</i> <i>--create;</i> <i>--dropall;</i> <i>--import</i> [filename]; <i>--update</i> + [filename]; <i>--remove</i> [filename]; see database section below. </dd> + +<dt><b>-E</b><i> [filename/wildcard]</i> +</dt> +<dd>produces <i>plaintext</i> with <i>dos</i> linefeeds, and without markup, endnotes follow +the main text (in <i>-a</i> endnotes follow the paragraphs that contain them). +There are no object numbers [see <i>-e</i> for Unix (linefeed) output file] [see +<i>-A</i> for footnotes]. </dd> + +<dt><b>-e</b><i> [filename/wildcard]</i> </dt> +<dd>produces <i>plaintext</i> with <i>Unix</i> linefeeds, +and without markup, endnotes follow the main text. Object numbers are omitted. +[ <i>-E</i> for equivalent dos (linefeed) output file] [ <i>-a</i> for footnotes]. </dd> + +<dt><b>-F</b><i> [--webserv=webrick]</i> +</dt> +<dd>generate examples of (naive) <i>cgi</i> search form for <i>sqlite</i> and <i>pgsql</i> 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 <i>-d</i> <i>-D</i> and the <i>database</i> section below. If the optional +parameter <i>--webserv=webrick</i> 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 <i>cgi-bin</i> directory). +<i>-Fv</i> (in addition to the above) provides some information on setting up +<i>hyperestraier</i> for sisu </dd> + +<dt> <b>-H</b><i> [filename/wildcard]</i> </dt> +<dd>produces <i>html</i> without +link suffixes (.html .pdf etc.) ("Hide"). Requires an appropriately configured +web server. [behaviour switched after 0.35 see -h]. </dd> + +<dt><b>-h</b><i> [filename/wildcard]</i> </dt> +<dd>produces + <i>html</i> (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]. </dd> + +<dt><b>-I</b><i> [filename/wildcard]</i> +</dt> +<dd>produces <i>texinfo</i> file. </dd> + +<dt><b>-L</b> </dt> +<dd>prints license information. </dd> + +<dt><b>-M</b><i> [filename/wildcard/url]</i> +</dt> +<dd><i>maintenance</i> mode files created for processing preserved and their locations +indicated. (also see -V) </dd> + +<dt><b>-m</b><i> [filename/wildcard/url]</i> </dt> +<dd>assumed for most other +flags, creates new meta-markup file, (the <i>metaverse</i> ) that is used in all +subsequent processing of other output. This step is assumed for most processing +flags. To skip it see <i>-n</i> </dd> + +<dt><b>-N</b><i> [filename/wildcard/url]</i> </dt> +<dd>document <i>digest</i> or <i>document</i> +content certificate ( <i>DCC</i> ) as <i>md5</i> 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). +<i>-NV</i> for verbose digest output to screen. </dd> + +<dt><b>-n</b><i> [filename/wildcard/url]</i> </dt> +<dd>skip meta-markup +(building of "metaverse"), this skips the equivalent of <i>-m</i> which is otherwise +assumed by most processing flags. </dd> + +<dt><b>-o</b><i> [filename/wildcard/url]</i> </dt> +<dd>output basic +document in <i>opendocument</i> file format (opendocument.odt). </dd> + +<dt><b>-p</b><i> [filename/wildcard]</i> +</dt> +<dd>produces <i>LaTeX</i> 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. <i>--papersize-a4</i> preset sizes include: ’A4’, U.S. ’letter’ and +’legal’ and book sizes ’A5’ and ’B5’ (system defaults to A4). </dd> + +<dt><b>-q</b><i> [filename/wildcard]</i> +</dt> +<dd><i>quiet</i> less output to screen. </dd> + +<dt><b>-R</b><i> [filename/wildcard]</i> </dt> +<dd><i>copies</i> sisu output files +to <i>remote</i> 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 <i>-r</i> </dd> + +<dt><b>-r</b><i> [filename/wildcard]</i> </dt> +<dd><i>copies</i> sisu +output files to <i>remote</i> 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 <i>-R</i> </dd> + +<dt><b>-S</b> </dt> +<dd>produces a <i>sisupod</i> a zipped +sisu directory of markup files including <i>sisu</i> markup source files and +the directories local <i>configuration</i> file, <i>images</i> and <i>skins.</i> <b>Note:</b> this +only includes the configuration files or skins contained in <i>./_sisu</i> not +those in <i>~/.sisu</i> <i>-S</i> [filename/wildcard] option. <b>Note:</b> (this option is tested +only with zsh). </dd> + +<dt><b>-S</b><i> [filename/wildcard]</i> </dt> +<dd>produces a zipped file of the prepared +document specified along with associated images, by default named <i>sisupod.zip</i> +they may alternatively be named with the filename extension <i>.ssp</i> This provides +a quick way of gathering the relevant parts of a sisu document which can +then for example be emailed. A sisupod includes <i>sisu</i> markup source file, + (along with associated documents if a master file, or available in multilingual +versions), together with related <i>images</i> and <i>skin.</i> 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. <b>Note:</b> +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 <i>-S</i> option without [filename/wildcard]. </dd> + +<dt><b>-s</b><i> [filename/wildcard]</i> +</dt> +<dd>copies sisu markup file to output directory. </dd> + +<dt><b>-t</b><i> [filename/wildcard</i><b> (*.termsheet.rb)]</b> +</dt> +<dd>standard form document builder, preprocessing feature </dd> + +<dt><b>-U</b><i> [filename/wildcard]</i> +</dt> +<dd>prints <i>url</i> 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), <i>-u</i> provides <i>url</i> 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 </dd> + +<dt><b>-u</b><i> [filename/wildcard]</i> +</dt> +<dd>provides <i>url</i> mapping of output files for the flags requested for processing, +also see <i>-U</i> </dd> + +<dt><b>-V</b> </dt> +<dd>on its own, provides SiSU <i>version</i> and <i>environment</i> information +(sisu --help env) </dd> + +<dt><b>-V</b><i> [filename/wildcard]</i> </dt> +<dd>even more <i>verbose</i> than the <i>-v</i> flag. +(also see -M) </dd> + +<dt><b>-v</b> </dt> +<dd>on its own, provides SiSU <i>version</i> information </dd> + +<dt><b>-v</b><i> [filename/wildcard]</i> +</dt> +<dd>provides <i>verbose</i> output of what is being built, where it is being built +(and error messages if any), as with <i>-u</i> flag provides a url mapping of +files created for each of the processing flag requests. See also <b>-V</b> </dd> + +<dt><b>-W</b> </dt> +<dd>starts +ruby’s <i>webrick</i> 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 <i>-h</i> option rather than <i>-H</i> ; also, note <i>-F</i> webrick +]. </dd> + +<dt><b>-w</b><i> [filename/wildcard]</i> </dt> +<dd>produces <i>concordance</i> (wordmap) a rudimentary +index of all the words in a document. </dd> + +<dt><b>-X</b><i> [filename/wildcard]</i> </dt> +<dd>produces <i>XML</i> +output with deep document structure, in the nature of dom. </dd> + +<dt><b>-x</b><i> [filename/wildcard]</i> +</dt> +<dd>produces <i>XML</i> output shallow structure (sax parsing). </dd> + +<dt><b>-Y</b><i> [filename/wildcard]</i> +</dt> +<dd>produces a short sitemap entry for the document, based on html output and +the sisu_manifest. <i>--sitemaps</i> generates/updates the sitemap index of existing +sitemaps. (Experimental, [g,y,m announcement this week]) </dd> + +<dt><b>-y</b><i> [filename/wildcard]</i> +</dt> +<dd>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. </dd> + +<dt><b>-Z</b><i> [filename/wildcard]</i> </dt> +<dd>Zap, if used with other processing +flags <i>deletes</i> 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. </dd> + +<dt><b>-z</b><i> [filename/wildcard]</i> </dt> +<dd>produces <i>php</i> (zend) [this feature is disabled +for the time being] </dd> +</dl> + +<h2><a name='sect5' href='#toc5'>modifiers</a></h2> + +<dl> + +<dt><b>--no-ocn</b> </dt> +<dd>[with -h -H or -p] switches off object +citation numbering. Produce output without identifying numbers in margins +of html or LaTeX/pdf output. </dd> + +<dt><b>--no-annotate</b> </dt> +<dd>strips output text of editor endnotes~[* +square brackets ]~ denoted by asterisk or dagger/plus sign </dd> + +<dt><b>--no-asterisk</b> </dt> +<dd>strips +output text of editor endnotes~[* square brackets ]~ denoted by asterisk +sign </dd> + +<dt><b>--no-dagger</b> </dt> +<dd>strips output text of editor endnotes~[+ square brackets +]~ denoted by dagger/plus sign </dd> +</dl> + +<h2><a name='sect6' href='#toc6'>databases</a></h2> + +<dl> + +<dt>dbi - database interface +</dt> +<dd><b>-D</b> or <b>--pgsql</b> set for <i>postgresql</i> <b>-d</b> or <b>--sqlite</b> default set for <i>sqlite</i> -d is +modifiable with --db=[database type (pgsql or sqlite)] </dd> + +<dt><b>-Dv --createall</b> </dt> +<dd>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) [ <i>-dv</i> --createall sqlite equivalent] +it may be necessary to run sisu <i>-Dv</i> --createdb initially </dd> + +<dt>NOTE: at the present +time for postgresql it may be necessary to manually create the database. +The command would be </dt> +<dd><i>’createdb</i> [database name]’ where database name would +be SiSU_[present working directory name (without path)]. Please use only +alphanumerics and underscores. </dd> + +<dt><b>-Dv --import </b> </dt> +<dd><i>[filename/wildcard]</i> imports data +specified to postgresql db (rb.dbi) [ <i>-dv</i> --import sqlite equivalent] </dd> + +<dt><b>-Dv --update +</b> </dt> +<dd><i>[filename/wildcard]</i> updates/imports specified data to postgresql db (rb.dbi) +[ <i>-dv</i> --update sqlite equivalent] </dd> + +<dt><b>-D --remove</b> </dt> +<dd><i>[filename/wildcard]</i> removes specified +data to postgresql db (rb.dbi) [ <i>-d</i> --remove sqlite equivalent] </dd> + +<dt><b>-D --dropall</b> +</dt> +<dd>kills data" and drops (postgresql or sqlite) db, tables & indexes [ <i>-d</i> --dropall +sqlite equivalent] </dd> + +<dt>The v in e.g. -Dv is for verbose output. </dt> +<dd></dd> +</dl> +</blockquote> + +<h2><a name='sect7' href='#toc7'>Shortcuts, Shorthand +for multiple flags</a></h2> + +<dl> + +<dt><b>--update</b><i> [filename/wildcard]</i> </dt> +<dd>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. </dd> + +<dt>-0 to -5 [filename or +wildcard] </dt> +<dd>Default shorthand mappings (note that the defaults can be +changed/configured in the sisurc.yml file): </dd> +</dl> +<p> +<i>-0</i> -mNhwpAobxXyYv [this is the +default action run when no options are give, i.e. on ’sisu [filename]’] <p> +<i>-1</i> -mNHwpy +<p> +<i>-2</i> -mNHwpaoy <p> +<i>-3</i> -mNhwpAobxXyY <p> +<i>-4</i> -mNhwpAobxXDyY --import <p> +<i>-5</i> -mNhwpAobxXDyY --update +<p> +add <i>-v</i> for verbose mode and <i>-c</i> for color, e.g. <i>sisu</i> -2vc [filename or wildcard] +<p> +consider <i>-u</i> for appended url info or <i>-v</i> for verbose output +<h2><a name='sect8' href='#toc8'>Document Markup</a></h2> +<b>SiSU +Markup</b> an incomplete summary. <p> +<b>Note:</b> files should be marked up for SiSU +using <i>UTF-8</i> encoding. <p> +Some interactive help on markup is available, by typing + <i>sisu</i> and selecting <i>markup</i> or <i>sisu</i> --help markup +<dl> + +<dt>Sample markup files can +be used as examples: </dt> +<dd><i><<a href='http://www.jus.uio.no/sisu/sample'>http://www.jus.uio.no/sisu/sample</a> +></i> </dd> + +<dt>actual marked up plaintext +files ready for use: </dt> +<dd><i><<a href='http://www.jus.uio.no/sisu/sample/markup'>http://www.jus.uio.no/sisu/sample/markup</a> +></i> </dd> + +<dt>as html with +syntax highlighting for viewing: </dt> +<dd><i><<a href='http://www.jus.uio.no/sisu/sample/syntax'>http://www.jus.uio.no/sisu/sample/syntax</a> +></i> +</dd> + +<dt>an alternative presentation of markup syntax: </dt> +<dd><i><<a href='http://www.jus.uio.no/sisu/sample/on_markup.txt'>http://www.jus.uio.no/sisu/sample/on_markup.txt</a> +></i> + </dd> +</dl> + +<h2><a name='sect9' href='#toc9'>Basic Markup</a></h2> +Data text markup (alternative to available html subset) <p> +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. <i>:A~</i> usually the title <i>:A~?</i> conditional level 1 heading +(used where a stand-alone document may be imported into another) <p> +<i>1~filename</i> +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) <p> +<i>!{</i> emphasis <i>}!</i> <p> +<i>*{</i> bold text <i>}*</i> +<p> +<i>_{</i> underscore <i>}_</i> <p> +<i>/{</i> italics <i>}/</i> <p> +<i>’"{</i> citation <i>}"</i> <p> +<i>^{</i> superscript <i>}^</i> <p> +<i>,{</i> subscript +<i>},</i> <p> +<i>+{</i> inserted text <i>}+</i> <p> +<i>-{</i> strikethrough <i>}-</i> +<h2><a name='sect10' href='#toc10'>Footnotes/Endnotes</a></h2> +<p> +<i>~{</i> a footnote +or endnote <i>}~</i> <p> +footnote/endnote <i>~{</i> self contained endnote marker & endnote +in one <i>}~</i> <p> +<i>~{*</i> unnumbered asterisk footnote/endnote, insert multiple asterisks +if required <i>}~</i> <p> +<i>~[*</i> editors notes, numbered asterisk footnote/endnote series +<i>]~</i> (+ the plus sign may be used as well) <p> +alternative endnote pair notation: +<p> +<i>~^</i> endnote marker <p> +<i>^~</i> endnote text following the paragraph in which the marker +occurs +<h2><a name='sect11' href='#toc11'>Line Operations (marker placed at start of line)</a></h2> +<p> +<i>!_</i> bold line <p> +<i>_1</i> +indent paragraph one level <p> +<i>_2</i> indent paragraph two steps <p> +<i>_*</i> bullet paragraph +<p> +<i>#</i> number paragraph (see headers for numbering document headings) +<p> +<i>_#</i> number paragraph level 2 (see headers for numbering document headings) + +<h2><a name='sect12' href='#toc12'>Links</a></h2> +<p> +<i>{</i> link name <i>}<a href='http://url.org'>http://url.org</i></a> + <p> +<i>{</i> image.png <i>}<a href='http://url.org'>http://url.org</i></a> + <p> +<i>{</i> image.png <i>}image</i> +<p> +<i>{</i> tux.png 64x80 <i>}image</i> <p> +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] <p> +the shortcut: <p> +<i>{~^</i> [text to link] <i>}<a href='http://url.org'>http://url.org</i></a> + +<p> +is equivalent to: <p> +<i>{</i> [text to link] <i>}<a href='http://url.org'>http://url.org</i></a> + <i>~{</i> <a href='http://url.org'>http://url.org</a> + <i>}~</i> +<p> +(which produces hyper-linked text within a document/paragraph, with an endnote +providing the url for the text location used in the hyperlink) <p> +url example: +<p> +<i>{</i> SiSU Geek Writer <i>}<a href='http://www.jus.uio.no/sisu/'>http://www.jus.uio.no/sisu/</i></a> + <p> +linked image: <p> +<i>{</i> tux.png 64x80 +"a better way" <i>}<a href='http://www.jus.uio.no/sisu/'>http://www.jus.uio.no/sisu/</i></a> + image example with all options +<p> +note width x height <p> +the shortcut: <p> +<i>{</i> [text to link] <i>[3sS]}markup_source_filename.sst</i> +<p> +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. +<h2><a name='sect13' href='#toc13'>Adding a fixed names in html</a></h2> +<p> +<i>*~[name]</i> +manual location marker/tagging at present only in html to produce <a name="[name]"></a> +(use sparingly) <blockquote>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. </blockquote> + +<h2><a name='sect14' href='#toc14'>Escape object +citation numbering</a></h2> +<p> +(place marker at end of paragraph) <p> +<i>~#</i> unnumbered paragraph +<p> +<i>-#</i> unnumbered paragraph, delete when not required (place marker at end of +paragraph) [used in dummy headings, eg. for segmented html] <p> +It is convenient +to mention here that the <i>-0</i> flag generates html and latex/pdf output without +visible object character numbers. <p> +<i>sisu</i> -0 [filename.sst] +<h2><a name='sect15' href='#toc15'>Page breaks (LaTeX/pdf)</a></h2> +<p> +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 <p> +<i><:pb></i> page break, which breaks +a page, starting a new page in single column text and a new column in double +column text <p> +<i><:pn></i> page new, which starts a new page, in both single and double +column text (leaving an empty column in double column text if necessary). + +<h2><a name='sect16' href='#toc16'>Comment line</a></h2> +<p> +<i>%</i> ignored by sisu in processing if placed at beginning of +line <p> +<i>%%</i> ignored by sisu in processing if placed at beginning of line, used +for folding by vim folds +<h2><a name='sect17' href='#toc17'>Special characters</a></h2> +special characters can be escaped +with a backslash <i>{</i> } < > are contextual special characters, (in combination +with other characters). <i>~</i> - _ / % ^ and occasionally <i>!</i> # + , are special characters +in particular circumstances, see the syntax chart. [note that SiSU is not +optimised for technical writing] +<h2><a name='sect18' href='#toc18'>Tables</a></h2> +<p> +<i>table{</i> [number of columns] [column +width %];[column width %] +<p> [table content, line breaks are important +see example below]<br> + +<p> <i>}table</i> +<p> sample table:<br> + +<p> <i>table{~h</i> c3; 26; 32; 32; +<p> This is a table, column1<br> + this would become row one of column two<br> + column three of row one is here<br> + +<p> column one row 2<br> + column two of row two<br> + column three of row two, and so on<br> + +<p> column one row three<br> + and so on<br> + here<br> + <br> + <i>}table</i> +<p> whole table gets an object citation number +<p> +<h2><a name='sect19' href='#toc19'>Other Grouped or +Pre-formatted Text</a></h2> +<i>poem{</i> +<p> [Text here]<br> + +<p> [Text here]<br> + +<p> <i>}poem</i> +<p> each verse is given an object citation number +<p> ----<br> + +<p> <i>group{</i> +<p> [Text here]<br> + +<p> <i>}group</i> +<p> whole group gets an object citation number +<p> ----<br> + +<p> <i>code{</i> +<p> [Text here]<br> + +<p> <i>}code</i> +<p> whole group gets an object citation number +<p> +<h2><a name='sect20' href='#toc20'>Composite Documents</a></h2> +<p> +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 <i>.ssm</i> (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 <i>.sst</i> regular markup +file, or <i>.ssi</i> (insert/information) <i>.sst</i> A secondary file of the composite +document is built prior to processing with the same prefix and the suffix + <i>._sst</i> and <i>._sst</i> 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: +<p> +<dl> + +<dt>basic markup for importing a document +</dt> +<dd> +<p> <i>r{</i> filename <i>}</i> +<p> <i>{</i> filename.si <i>}require</i> +<p> <i><<</i> { filename.si <i>}</i> #for vim folds +<p> +</dd> + +<dt>importing a document with textlink syntax </dt> +<dd> +<p> <i>|filename.si|@|^|require</i> +<p> <i><<</i> |filename.si|@|^| + +<p>#for vim folds +<p> </dd> + +<dt>importing a document with thlnk syntax </dt> +<dd> +<p> <i><url:filename.si>require</i> + +<p> <i><<</i> <url:filename.si> #for vim folds +<p> </dd> + +<dt>remote documents may be called with the +thlnk syntax (or regular sisu syntax), e.g. </dt> +<dd> +<p> <i><<</i> <url:<a href='http://www.url.com/filename.si'>http://www.url.com/filename.si</a> +> + +<p> </dd> +</dl> + +<h2><a name='sect21' href='#toc21'>Document Headers</a></h2> +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. +<p> All +header instructions may take either form: <i>@headername:</i> [introduced in 0.38] + +<p>or <i>0~headername</i> All Dublin Core meta tags are available +<p> <i>@indentifier:</i> +information or instructions [introduced in 0.38] +<p> or +<p> <i>0~indentifier</i> information +or instructions, old equivalent, depreciated +<p> where the "identifier" is +a tag recognised by the program, and the "information" or "instructions" +belong to the tag/indentifier specified. +<p> 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. +<p> @structure: PART; CHAPTER; SECTION; ARTICLE; +none; none; +<p> 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. ^) +<p> For help see one of the following (and markup samples):<br> + +<p> * interactive help - type ’sisu --help headers’<br> + +<p> * marked up text samples<br> + +<p> * the SiSU_Markup.txt file provided with the program<br> + +<p> * an outline of headers is provided below --><br> + +<h2><a name='sect22' href='#toc22'>Outline of header options</a></h2> +<i>%</i> SiSU 0.38 [declared file-type identifier with +markup version] +<p> <i>@title:</i> My Title - This is now the Title of the Document + +<p>and used as such +<p> <i>@subtitle:</i> The Subtitle if any +<p> <i>@creator:</i> [or ~author] + +<p>Ralph Amissah +<p> <i>@subject:</i> (whatever your subject) +<p> <i>@description:</i> +<p> <i>@publisher:</i> + +<p> <i>@contributor:</i> +<p> <i>@translator:</i> [or ~translated_by] +<p> <i>@illustrator:</i> [or ~illustrated_by] + +<p> <i>@prepared_by:</i> [or ~digitized_by] +<p> <i>@date:</i> 2000-08-27 [ also @date.created: +@date.issued: @date.available: @date.valid: @date.modified: ] +<p> <i>@type:</i> article + +<p> <i>@format:</i> +<p> <i>@identifier:</i> +<p> <i>@source:</i> +<p> <i>@language:</i> [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.] +<p> <i>@language.original:</i> + +<p>original language in which the work was published +<p> <i>@papersize:</i> (A4|US_letter|book_B5|book_A5|US_legal) + +<p> <i>@relation:</i> +<p> <i>@coverage:</i> +<p> <i>@rights:</i> copyright, all rights reserved, public +domain, copyleft, creative commons variant, etc. +<p> <i>@owner:</i> +<p> <i>@keywords:</i> text +document generation processing management LaTeX pdf structured XML citation +[your keywords here, used for example by rss feeds, and in sql sear ches] + +<p> <i>@abstract:</i> [paper abstract, placed after table of contents] +<p> <i>@comment:</i> +[...] +<p> <i>@catalogue:</i> loc=[Library of Congress classification]; dewey=[Dewey +classification]; isbn=[ISBN]; pg=[Project Gutenberg text number] +<p> <i>@classify_loc:</i> + +<p>Library of Congress classification +<p> <i>@classify_dewey:</i> Dewey classification + +<p> <i>@classify_isbn:</i> ISBN +<p> <i>@classify_pg:</i> Project Gutenberg text number +<p> <i>@prefix_a:</i> +[prefix is placed just before table of contents - not implemented] +<p> <i>@prefix_b:</i> +or @prefix: [prefix is placed just after table of contents] +<p> <i>@rcs:</i> $Id$ +[or <i>@cvs:</i> 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 ] +<p> <i>@structure:</i> 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:) +<p> <i>@markup:</i> information on the markup used, e.g. <i>new=1,2,3;</i> +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. +<i>num_top=4</i> [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] <i>num_extract</i> [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] +<p> <i>@bold:</i> [regular expression of words/phrases to be made bold] + +<p> <i>@italics:</i> [regular expression of words/phrases to italicise] <br> + <i>@vocabulary:</i> name of taxonomy/vocabulary/wordlist to use against document + +<p> <i>@skin:</i> skin_doc_[name_of_desired_document_skin] +<p> <i>@links:</i> { SiSU }<a href='http://www.jus.uio.no/sisu/'>http://www.jus.uio.no/sisu/</a> + +{ FSF }<a href='http://www.fsf.org'>http://www.fsf.org</a> + +<p> <i>@promo:</i> 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] + +<p> <i>:A~</i> 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 + +<p> <i>:B~</i> Second level heading [this is a heading level divider] +<p> <i>:C~</i> Third +level heading [this is a heading level divider] +<p> <i>1~</i> 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 + +<p>form 1~my_filename_for_this_segment +<p> <i>2~</i> 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. +<p> <i>3~</i> 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 +<p> 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) +<p> For some help on document structure try +<p> <i>sisu</i> --help + +<p>headings +<p> and view sample markup documents provided +<p> +<p> +<h2><a name='sect23' href='#toc23'>Configuration +Files</a></h2> +<p> +Some configuration is required for SiSU, specifying in which directory +processing should be done, and where the generated output should be placed. +<p> +SiSU resource configuration is determined by looking at the following files +if they exist: <p> +<i>./_sisu/sisurc.yml</i> <p> +<i>~/.sisu/sisurc.yml</i> <p> +<i>/etc/sisu/sisurc.yml</i> <p> +In +the absence of instructions in any of these it falls back to the internal +program defaults. <p> +Configuration determines the output and processing directories +and the database access details. <p> +A sample sisurc.yml may be found in /etc/sisu/sisurc.yml + +<p> +<h2><a name='sect24' href='#toc24'>More HELP on Markup and headers</a></h2> +type: sisu ~<br> + sisu --help<br> + +<p> markup help is available on:<br> + document wide instructions: headers (document structure)<br> + general text markup: headings; endnotes; tables<br> + +<p> A markup table and sample marked-up files (also in html with syntax highlighting) +are available at: +<p> <i><<a href='http://www.jus.uio.no/sisu/sample'>http://www.jus.uio.no/sisu/sample</a> +></i> +<p> +<h2><a name='sect25' href='#toc25'>DIRECTORY STRUCTURE +& Document Output</a></h2> + +<dl> + +<dt>SiSU determines output directories by looking at the resource +configuration files, and in their absence the programs internal defaults. +</dt> +<dd> </dd> +</dl> + +<h2><a name='sect26' href='#toc26'>Default Directories</a></h2> + +<dl> + +<dt>In the absence of other specifications in </dt> +<dd><i>~/.sisu/sisurc.yml</i> +in <i>/etc/sisu/sisurc.yml</i> SiSU writes to the following directories, processing +files are placed in sub-directories within <i>./_sisu/processing</i> and if that +is not writable to <i>/tmp/sisu_processing</i> </dd> +</dl> +<p> +Output is written to sub-directories +within <i>/var/www/</i> if it exists and is writable, and otherwise to <i>~/sisu_output</i> + +<h2><a name='sect27' href='#toc27'>Markup Document Directories and File Mapping</a></h2> + +<dl> + +<dt>Ideally documents should be +placed as collections sub-directories of their own, with a common denominator, +such as subject or author. </dt> +<dd></dd> + +<dt>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. </dt> +<dd></dd> + +<dt>the document </dt> +<dd></dd> +</dl> +<p> +<blockquote><i>~/ebook/free_culture.sst</i> </blockquote> + +<dl> + +<dt>would map to </dt> +<dd></dd> +</dl> +<p> +<blockquote><i>~[configured</i> +output path]/ebook/free_culture </blockquote> + +<dl> + +<dt>within which would be placed all html, +XML, pdf output, typically under the names: </dt> +<dd></dd> +</dl> +<p> +<blockquote><i>index.html</i> index for segmented +text <p> +<i>doc.html</i> full length scrollable document <p> +<i>toc.html</i> index for segmented +text <p> +html segments, as many as there may be... +<dl> + +<dt><i>portrait.pdf</i> </dt> +<dd></dd> +</dl> +<p> +<i>landscape.pdf</i> <p> +<i>sax.xml</i> +XML shallow structure, sax type parsing <p> +<i>dom.xml</i> XML deeper structure, dom +type parsing <p> +<i>scroll.xhtml</i> xhtml <p> +<i>plain.txt</i> plain text </blockquote> + +<h2><a name='sect28' href='#toc28'>Multi-language Document +File Naming and Directory Mapping</a></h2> + +<dl> + +<dt>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 </dt> +<dd></dd> + +<dt>filename~es.sst </dt> +<dd></dd> + +<dt>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: </dt> +<dd></dd> + +<dt>(1) +[output directory path]/filename/es.index.html </dt> +<dd></dd> + +<dt>(2) [output directory path]/filename/index.es.html +</dt> +<dd></dd> + +<dt>(3) [output directory path]/filename/index.html.es (which Apache for example +can be configured to use to automatically serve each users preference) +</dt> +<dd></dd> + +<dt>filename~fr.sst </dt> +<dd></dd> + +<dt>filename~de.sst </dt> +<dd></dd> + +<dt>etc. would be placed in the same directory +using the same convention as indeed would: </dt> +<dd></dd> + +<dt>filename.sst </dt> +<dd></dd> + +<dt>using the default +convention mapping convention. </dt> +<dd></dd> + +<dt>Selecting this form of filename will overide +other language settings including the language header within a document. +</dt> +<dd> </dd> +</dl> + +<h2><a name='sect29' href='#toc29'>Markup Document Directories and Database Mapping</a></h2> +<p> +Similarly there is a mapping +to the database into which documents are placed. <p> +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. <p> +Documents within +the directory <i>~/ebook</i> <p> +<blockquote><i>~/ebook/free_culture.sst</i> </blockquote> +<p> +would be placed in tables +within the database <p> +<blockquote><i>SiSU_ebook</i> </blockquote> + +<h2><a name='sect30' href='#toc30'>SKINS - document, directory and site skins</a></h2> +<p> +Skins +modify the default appearance of document output on a document, directory, +or site wide basis. Skins are looked for in the following locations: <p> +<i>./_sisu/skin</i> +<p> +<i>~/.sisu/skin</i> <p> +<i>/etc/sisu/skin</i> <p> +Within the skin directory are the following +the default sub-directories for document skins: <p> +<i>./skin/doc</i> <p> +<i>./skin/dir</i> <p> +<i>./skin/site</i> +<p> +Documents take on a document skin, if the header of the document specifies +a skin to be used. <p> +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 <p> +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. <p> +A site skin, modifies the program default skin. <p> +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) <p> +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) +<h2><a name='sect31' href='#toc31'>Document Naming Convention</a></h2> +<p> +SiSU documents are named with the +suffix <i>ss</i> followed by a third distinguishing letter, usually t for ordinary +text files. <p> +<i>.sst</i> is used by regular documents, and for most purposes is all +you need to be aware of <p> +<i>.ssm</i> 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. <p> +<i>.ssi</i> 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. <p> +<i>._sst</i> and <i>.-sst</i> 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. + +<p> <i>.sxs.xml</i> simple xml sax, sisu markup representation +<p> <i>.sxd.xml</i> simple xml dom, + +<p>sisu markup representation +<p> <i>.sxn.xml</i> simple xml node, sisu markup representation + +<p> <i>.sxs.xml.sst</i> or <i>.sxd.xml.sst</i> or <i>.sxn.xml.sst</i> auto-converted from a simple xml markup +representation (sxs, sxd, sxn) +<h2><a name='sect32' href='#toc32'>Remote Operations</a></h2> +<p> +These may be of three +basic types. <p> +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. * <p> +The downloading of a remote file for processing using SiSU locally, +which is achieved in one of two ways: <p> +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. <p> +A file may request the inclusion of a remote document within it, +see comments on "Composite Documents" for the request syntax. <p> +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. <p> +* 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. +<h2><a name='sect33' href='#toc33'>Note</a></h2> +<p> +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 <i><<a href='http://www.jus.uio.no/sisu/sample'>http://www.jus.uio.no/sisu/sample</a> +></i> and referred +to in the text <i><<a href='http://www.jus.uio.no/sisu/SiSU'>http://www.jus.uio.no/sisu/SiSU</a> +></i> 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. +<p> +<h2><a name='sect34' href='#toc34'>Processing Examples</a></h2> +<p> +To initialise a new directory <b>sisu</b> <i>-C</i> <p> +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. <p> +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: <b>sisu</b> <i>-m</i> [filename or wildcard] <p> +to create html and pdf output, +with verbose output of samplefile1.sst and samplefile2.sst <b>sisu</b> <i>-mhpv</i> samplefile1.sst +samplefile2.sst <blockquote>Note: <i>-m</i> does initial processing, and <i>-H</i> omits filename +suffixes and requires a properly configured web server. <i>-h</i> is used to include +filename suffixes for file system viewing </blockquote> +<p> +generate html, a word map and +pdf with verbose output for all marked up documents in a directory: <b>sisu</b> +<i>-mhwpv</i> * <p> +generate html, word map, pdf, plaintext, xhtml, xml sax and xml +dom versions with verbose output for all marked up documents in a directory: +<b>sisu</b> <i>-mhwpabxXv</i> * <p> +to create html, pdf, xml, plaintext and a concordance +file (wordmap) as output, with verbose output of all marked up files in +a directory <b>sisu</b> <i>-mhpxXawv</i> *.{r,s}? <p> +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 <i>-mrv</i> [filenames/wildcard]): <b>sisu</b> <i>-mhwprv</i> example_file.sst other_example_file.sst +<p> +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): <b>sisu</b> <i>-mhwpv</i> <a href='http://www.jus.uio.no/sisu/sample/markup/gpl2.fsf.sst'>http://www.jus.uio.no/sisu/sample/markup/gpl2.fsf.sst</a> + http://www.jus.uio.no/sisu/sample/markup/autonomy_markup0.sst +<p> +one file is local the other remote process (html,pdf,concordance,plaintext +and place on pre-set remote destination): <b>sisu</b> <i>-mhwparv</i> gpl2.fsf.sst <a href='http://www.jus.uio.no/sisu/sample/markup/autonomy_markup0.sst'>http://www.jus.uio.no/sisu/sample/markup/autonomy_markup0.sst</a> + +<p> +initialize database, create relations (first manually create database with +same name as working directory): <b>sisu</b> <i>-Dv</i> createall <p> +it may be necessary +to first run <b>sisu</b> <i>-Dv</i> createdb <p> +import all marked up files first time into +a database: <b>sisu</b> <i>-Dv</i> import * <p> +<i>-c</i> toggles color +<h2><a name='sect35' href='#toc35'>Interactive Help Options</a></h2> +<p> +SiSU +has an interactive help, which is accessed by typing just "sisu" at the +command line, or as described below: <b>sisu</b> commands, document preparation, +customisation, installation etc. <br> +<pre>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 +</pre> +<p> +<h2><a name='sect36' href='#toc36'>SiSU VERSION CONVERSION</a></h2> +<p> +<i>sisu</i> --to-current [filename/wildcard] converts from +0.37 markup to current markup (0.38) +<p> <i>sisu</i> --to-38 [filename/wildcard] converts + +<p>from 0.37 markup to 0.38 +<p> <i>sisu</i> --to-37 [filename/wildcard] converts from 0.38 + +<p>markup to 0.37 +<p> <i>sisu</i> --convert-36to37 [filename/wildcard] re-names file from + +<p>pre-0.36 convention to 0.37 +<p> <i>sisu</i> --convert-footnotes [filename/wildcard] converts + +<p>footnotes to preferred embedded footnote markup style +<p> <i>sisu</i> --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. +<p> convert from sst to simple xml +representations (sax, dom and node): +<p> <i>sisu</i> --to-sax [filename/wildcard] or +<i>sisu</i> --to-sxs [filename/wildcard] +<p> <i>sisu</i> --to-dom [filename/wildcard] or <i>sisu</i> +--to-sxd [filename/wildcard] +<p> <i>sisu</i> --to-node [filename/wildcard] or <i>sisu</i> --to-sxn +[filename/wildcard] +<p> convert to sst from simple xml representations (sax, +dom and node): +<p> <i>sisu</i> --from-xml2sst [filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]] + +<p> or the same: +<p> <i>sisu</i> --from-sxml [filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]] + +<p> <i>sisu</i> --from-kdi [kdissert filename] attempts to convert a kdissert file (.kdi) + +<p>to sisu markup +<p> <i>sisu</i> --identify [filename/wildcard] attempts to identify + +<p>the markup version of the file +<p> <i>sisu</i> --query=[version number] and <i>sisu</i> --query=history + +<p>provides a brief summary of changes to SiSU markup +<p> +<h2><a name='sect37' href='#toc37'>Sample Markup Documents</a></h2> +<p> + +<p> +Sample markup documents are provided in sisu-examples and are available +online. +<p> +<h2><a name='sect38' href='#toc38'>Home Page</a></h2> +<p> +<i><<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a> +></i> +<p> +<h2><a name='sect39' href='#toc39'>Author</a></h2> +Ralph Amissah <i><ralph@amissah.com></i> +or <i><ralph.amissah@gmail.com></i> +<p> +<h2><a name='sect40' href='#toc40'>See Also</a></h2> +<a href='http:~/bin/man2html?sisu:8'><b>sisu(8)</a> +,</b> <a href='http:~/bin/man2html?sisu_webrick:1'><b>sisu_webrick(1)</a> +,</b> <a href='http:~/bin/man2html?sisu_termsheet:1'><b>sisu_termsheet(1)</a> +,</b> +<a href='http:~/bin/man2html?sisu_pdf:1'><b>sisu_pdf(1)</b></a> + <a href='http:~/bin/man2html?sisu_sqlite:1'><b>sisu_sqlite(1)</b></a> + <a href='http:~/bin/man2html?sisu_postgresql:1'><b>sisu_postgresql(1)</b></a> + <a href='http:~/bin/man2html?sisu_vim:7'><b>sisu_vim(7)</b></a> + <p> + +<hr><p> +<a name='toc'><b>Table of Contents</b></a><p> +<ul> +<li><a name='toc0' href='#sect0'>Name</a></li> +<li><a name='toc1' href='#sect1'>Synopsis</a></li> +<li><a name='toc2' href='#sect2'>Description</a></li> +<li><a name='toc3' href='#sect3'>Summary of man page</a></li> +<li><a name='toc4' href='#sect4'>Document Processing Command Flags</a></li> +<li><a name='toc5' href='#sect5'>modifiers</a></li> +<li><a name='toc6' href='#sect6'>databases</a></li> +<li><a name='toc7' href='#sect7'>Shortcuts, Shorthand for multiple flags</a></li> +<li><a name='toc8' href='#sect8'>Document Markup</a></li> +<li><a name='toc9' href='#sect9'>Basic Markup</a></li> +<li><a name='toc10' href='#sect10'>Footnotes/Endnotes</a></li> +<li><a name='toc11' href='#sect11'>Line Operations (marker placed at start of line)</a></li> +<li><a name='toc12' href='#sect12'>Links</a></li> +<li><a name='toc13' href='#sect13'>Adding a fixed names in html</a></li> +<li><a name='toc14' href='#sect14'>Escape object citation numbering</a></li> +<li><a name='toc15' href='#sect15'>Page breaks (LaTeX/pdf)</a></li> +<li><a name='toc16' href='#sect16'>Comment line</a></li> +<li><a name='toc17' href='#sect17'>Special characters</a></li> +<li><a name='toc18' href='#sect18'>Tables</a></li> +<li><a name='toc19' href='#sect19'>Other Grouped or Pre-formatted Text</a></li> +<li><a name='toc20' href='#sect20'>Composite Documents</a></li> +<li><a name='toc21' href='#sect21'>Document Headers</a></li> +<li><a name='toc22' href='#sect22'>Outline of header options</a></li> +<li><a name='toc23' href='#sect23'>Configuration Files</a></li> +<li><a name='toc24' href='#sect24'>More HELP on Markup and headers</a></li> +<li><a name='toc25' href='#sect25'>DIRECTORY STRUCTURE & Document Output</a></li> +<li><a name='toc26' href='#sect26'>Default Directories</a></li> +<li><a name='toc27' href='#sect27'>Markup Document Directories and File Mapping</a></li> +<li><a name='toc28' href='#sect28'>Multi-language Document File Naming and Directory Mapping</a></li> +<li><a name='toc29' href='#sect29'>Markup Document Directories and Database Mapping</a></li> +<li><a name='toc30' href='#sect30'>SKINS - document, directory and site skins</a></li> +<li><a name='toc31' href='#sect31'>Document Naming Convention</a></li> +<li><a name='toc32' href='#sect32'>Remote Operations</a></li> +<li><a name='toc33' href='#sect33'>Note</a></li> +<li><a name='toc34' href='#sect34'>Processing Examples</a></li> +<li><a name='toc35' href='#sect35'>Interactive Help Options</a></li> +<li><a name='toc36' href='#sect36'>SiSU VERSION CONVERSION</a></li> +<li><a name='toc37' href='#sect37'>Sample Markup Documents</a></li> +<li><a name='toc38' href='#sect38'>Home Page</a></li> +<li><a name='toc39' href='#sect39'>Author</a></li> +<li><a name='toc40' href='#sect40'>See Also</a></li> +</ul> +</body> +</html> |