diff options
Diffstat (limited to 'man/man1/sisu_commands.1')
| -rw-r--r-- | man/man1/sisu_commands.1 | 575 |
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 |