Merge branch 'upstream' into debian/sid

1 files changed, 575 insertions, 0 deletions

diff --git a/man/man1/sisu_commands.1 b/man/man1/sisu_commands.1
new file mode 100644
index 00000000..eba91bb4
--- /dev/null
+++ b/man/man1/sisu_commands.1
@@ -0,0 +1,575 @@
+.TH "sisu_commands" "1" "2007-09-16" "0.58.3" "SiSU"
+.SH
+SISU \- COMMANDS \ [0.58],
+RALPH AMISSAH
+.BR
+
+.SH
+SISU COMMANDS
+.BR
+
+.SH
+1. COMMANDS SUMMARY
+.BR
+
+.SH
+1.1 SYNOPSIS
+
+.BR
+.B SiSU
+\- Structured information, Serialized Units \- a document publishing system
+
+.BR
+sisu \ [ \ \-abcDdFHhIiMmNnopqRrSsTtUuVvwXxYyZz0\-9 \ ] \ [ \ filename/ \
+wildcard \ ]
+
+.BR
+sisu \ [ \ \-Ddcv \ ] \ [ \ instruction \ ]
+
+.BR
+sisu \ [ \ \-CcFLSVvW \ ]
+
+.BR
+Note: commands should be issued from within the directory that contains the
+marked up files, cd to markup directory.
+
+.SH
+1.2 DESCRIPTION
+
+.BR
+.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: <http://www.jus.uio.no/sisu>
+
+.SH
+1.3 DOCUMENT PROCESSING COMMAND FLAGS
+
+.TP
+.B \ \-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]. (Options include: \-\-endnotes for endnotes \-\-footnotes for
+footnotes at the end of each paragraph \-\-unix for unix linefeed (default)
+\-\-msdos for msdos linefeed)
+
+.TP
+.B \ \-b \ \ [filename/wildcard]
+produces xhtml/XML output for browser viewing (sax parsing).
+
+.TP
+.B \ \-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.
+
+.TP
+.B \ \-CC
+\ 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). \ The \ equivalent \ of: \ \-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 \ \-CC \ is \ used. \
+
+.TP
+.B \ \-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).
+
+.TP
+.B \ \-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.
+
+.TP
+.B \ \-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.
+
+.TP
+.B \ \-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
+
+.TP
+.B \ \-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].
+
+.TP
+.B \ \-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].
+
+.TP
+.B \ \-I \ \ [filename/wildcard]
+produces texinfo and info file, (view with pinfo).
+
+.TP
+.B \ \-L
+\ prints \ license \ information. \
+
+.TP
+.B \ \-M \ \ [filename/wildcard/url]
+maintenance mode files created for processing preserved and their locations
+indicated. (also see \-V)
+
+.TP
+.B \ \-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
+
+.TP
+.B \ \-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.
+
+.TP
+.B \ \-n \ \ [filename/wildcard/url]
+skip meta\-markup (building of \"metaverse\"), this skips the equivalent of
+\-m which is otherwise assumed by most processing flags.
+
+.TP
+.B \ \-o \ \ [filename/wildcard/url]
+output basic document in opendocument file format (opendocument.odt).
+
+.TP
+.B \ \-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).
+
+.TP
+.B \ \-q \ \ [filename/wildcard]
+quiet less output to screen.
+
+.TP
+.B \ \-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
+
+.TP
+.B \ \-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
+
+.TP
+.B \ \-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).
+
+.TP
+.B \ \-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.
+.B 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].
+
+.TP
+.B \ \-s \ \ [filename/wildcard]
+copies sisu markup file to output directory.
+
+.TP
+.B \ \-t \ \ [filename/wildcard \ (*.termsheet.rb)]
+standard form document builder, preprocessing feature
+
+.TP
+.B \ \-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
+
+.TP
+.B \ \-u \ \ [filename/wildcard]
+provides url mapping of output files for the flags requested for processing,
+also see \-U
+
+.TP
+.B \ \-V
+\ on \ its \ own, \ provides
+.B \ SiSU
+\ version \ and \ environment \ information \ (sisu \ \-\-help \ env) \
+
+.TP
+.B \ \-V \ \ [filename/wildcard]
+even more verbose than the \-v flag. (also see \-M)
+
+.TP
+.B \ \-v
+\ on \ its \ own, \ provides
+.B \ SiSU
+\ version \ information \
+
+.TP
+.B \ \-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
+
+.TP
+.B \ \-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 \ ].
+
+.TP
+.B \ \-w \ \ [filename/wildcard]
+produces concordance (wordmap) a rudimentary index of all the words in a
+document. (Concordance files are not generated for documents of over 260,000
+words unless this limit is increased in the file sisurc.yml)
+
+.TP
+.B \ \-X \ \ [filename/wildcard]
+produces XML output with deep document structure, in the nature of dom.
+
+.TP
+.B \ \-x \ \ [filename/wildcard]
+produces XML output shallow structure (sax parsing).
+
+.TP
+.B \ \-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])
+
+.TP
+.B \ \-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.
+
+.TP
+.B \ \-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.
+
+.TP
+.B \ \-z \ \ [filename/wildcard]
+produces php (zend) \ [this \ feature \ is \ disabled \ for \ the \ time \
+being]
+
+.SH
+2. COMMAND LINE MODIFIERS
+.BR
+
+.TP
+.B \ \-\-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.
+
+.TP
+.B \ \-\-no\-annotate
+\ strips \ output \ text \ of \ editor \ endnotes[^*1] denoted by asterisk or
+dagger/plus sign
+
+.TP
+.B \ \-\-no\-asterisk
+\ strips \ output \ text \ of \ editor \ endnotes[^*2] denoted by asterisk
+sign
+
+.TP
+.B \ \-\-no\-dagger
+\ strips \ output \ text \ of \ editor \ endnotes[^+1] denoted by dagger/plus
+sign
+
+.SH
+3. DATABASE COMMANDS
+.BR
+
+.BR
+dbi \- database interface
+
+.BR
+\-D or \-\-pgsql set for postgresql \-d or \-\-sqlite default set for sqlite
+\-d is modifiable with \-\-db=[database \ type \ (pgsql \ or \ sqlite)]
+
+.TP
+.B \ \-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.
+
+.TP
+.B \ \-Dv \ \-\-import
+\ \ [filename/wildcard] imports data specified to postgresql db (rb.dbi) \ [
+\ \-dv \ \-\-import \ sqlite \ equivalent]
+
+.TP
+.B \ \-Dv \ \-\-update
+\ \ [filename/wildcard] updates/imports specified data to postgresql db
+(rb.dbi) \ [ \ \-dv \ \-\-update \ sqlite \ equivalent]
+
+.TP
+.B \ \-D \ \-\-remove
+\ \ [filename/wildcard] removes specified data to postgresql db (rb.dbi) \ [
+\ \-d \ \-\-remove \ sqlite \ equivalent]
+
+.TP
+.B \ \-D \ \-\-dropall
+\ kills \ data\" \ and \ drops \ (postgresql \ or \ sqlite) \ db, \ tables \
+& \ indexes \ \ [ \ \-d \ \-\-dropall \ sqlite \ equivalent]
+
+.BR
+The v in e.g. \-Dv is for verbose output.
+
+.SH
+4. SHORTCUTS, SHORTHAND FOR MULTIPLE FLAGS
+.BR
+
+.TP
+.B \ \-\-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.
+
+.TP
+.B \ \-0 \ to \ \-5 \ \ [filename \ or \ wildcard]
+Default shorthand mappings (note that the defaults can be changed/configured
+in the sisurc.yml file):
+
+.TP
+.B \ \-0
+\ \-mNhwpAobxXyYv \ \ [this \ is \ the \ default \ action \ run \ when \ no \
+options \ are \ give, \ i.e. \ on \ \'sisu \ \ [filename]\']
+
+.TP
+.B \ \-1
+\ \-mNHwpy \
+
+.TP
+.B \ \-2
+\ \-mNHwpaoy \
+
+.TP
+.B \ \-3
+\ \-mNhwpAobxXyY \
+
+.TP
+.B \ \-4
+\ \-mNhwpAobxXDyY \ \-\-import \
+
+.TP
+.B \ \-5
+\ \-mNhwpAobxXDyY \ \-\-update \
+
+.BR
+add \-v for verbose mode and \-c for color, e.g. sisu \-2vc \ [filename \ or \
+wildcard]
+
+.BR
+consider \-u for appended url info or \-v for verbose output
+
+.SH
+4.0.1 COMMAND LINE WITH FLAGS \- BATCH PROCESSING
+
+.BR
+In the data directory run sisu \-mh filename or wildcard eg. \"sisu \-h
+cisg.sst\" or \"sisu \-h *.{sst,ssm}\" to produce html version of all
+documents.
+
+.BR
+Running sisu (alone without any flags, filenames or wildcards) brings up the
+interactive help, as does any sisu command that is not recognised. Enter to
+escape.
+
+.SH
+DOCUMENT INFORMATION (METADATA)
+.BR
+
+.SH
+METADATA
+.BR
+
+.BR
+Document Manifest @
+<http://www.jus.uio.no/sisu/sisu_manual/sisu_commands/sisu_manifest.html>
+
+.BR
+.B Dublin Core
+(DC)
+
+.BR
+.I DC tags included with this document are provided here.
+
+.BR
+DC Title:
+.I SiSU \- Commands \ [0.58]
+
+.BR
+DC Creator:
+.I Ralph Amissah
+
+.BR
+DC Rights:
+.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL
+3
+
+.BR
+DC Type:
+.I information
+
+.BR
+DC Date created:
+.I 2002\-08\-28
+
+.BR
+DC Date issued:
+.I 2002\-08\-28
+
+.BR
+DC Date available:
+.I 2002\-08\-28
+
+.BR
+DC Date modified:
+.I 2007\-09\-16
+
+.BR
+DC Date:
+.I 2007\-09\-16
+
+.BR
+.B Version Information
+
+.BR
+Sourcefile:
+.I sisu_commands.sst
+
+.BR
+Filetype:
+.I SiSU text 0.58
+
+.BR
+Sourcefile Digest, MD5(sisu_commands.sst)=
+.I 8101d9e72f3de2510ef887202f8db3f9
+
+.BR
+Skin_Digest:
+MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)=
+.I 20fc43cf3eb6590bc3399a1aef65c5a9
+
+.BR
+.B Generated
+
+.BR
+Document (metaverse) last generated:
+.I Sun Sep 23 01:13:58 +0100 2007
+
+.BR
+Generated by:
+.I SiSU
+.I 0.58.3
+of 2007w36/4 (2007\-09\-06)
+
+.BR
+Ruby version:
+.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux]
+
+.TP
+.BI *1.
+square brackets
+.TP
+.BI *2.
+square brackets
+.TP
+.BI +1.
+square brackets
+
+.TP
+Other versions of this document:
+.TP
+manifest: <http://www.jus.uio.no/sisu/sisu_commands/sisu_manifest.html>
+.TP
+html: <http://www.jus.uio.no/sisu/sisu_commands/toc.html>
+.TP
+pdf: <http://www.jus.uio.no/sisu/sisu_commands/portrait.pdf>
+.TP
+pdf: <http://www.jus.uio.no/sisu/sisu_commands/landscape.pdf>
+." .TP
+." manpage: http://www.jus.uio.no/sisu/sisu_commands/sisu_commands.1
+.TP
+at: <http://www.jus.uio.no/sisu>
+.TP
+.TP
+* Generated by: SiSU 0.58.3 of 2007w36/4 (2007-09-06)
+.TP
+* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux]
+.TP
+* Last Generated on: Sun Sep 23 01:14:05 +0100 2007
+.TP
+* SiSU http://www.jus.uio.no/sisu