From 50d45c6deb0afd2e4222d2e33a45487a9d1fa676 Mon Sep 17 00:00:00 2001 From: Ralph Amissah Date: Sun, 23 Sep 2007 05:16:21 +0100 Subject: primarily todo with sisu documentation, changelog reproduced below: * start documenting sisu using sisu * sisu markup source files in data/doc/sisu/sisu_markup_samples/sisu_manual/ /usr/share/doc/sisu/sisu_markup_samples/sisu_manual/ * default output [sisu -3] in data/doc/manuals_generated/sisu_manual/ /usr/share/doc/manuals_generated/sisu_manual/ (adds substantially to the size of sisu package!) * help related edits * manpage, work on ability to generate manpages, improved * param, exclude footnote mark count when occurs within code block * plaintext changes made * shared_txt, line wrap visited * file:// link option introduced (in addition to existing https?:// and ftp://) a bit arbitrarily, diff here, [double check changes in sysenv and hub] * minor adjustments * html url match refinement * css added tiny_center * plaintext * endnotes fix * footnote adjustment to make more easily distinguishable from substantive text * flag -a only [flags -A -e -E dropped] controlled by modifiers --unix/msdos --footnote/endnote * defaults, homepage * renamed homepage (instead of index) implications for modifying skins, which need likewise to have any homepage entry renamed * added link to sisu_manual in homepage * css the css for the default homepage is renamed homepage.css (instead of index.css) [consider removing this and relying on html.css] * ruby version < ruby1.9 * place stop on installation and working with for now [ruby String.strip broken in ruby 1.9.0 (2007-09-10 patchlevel 0) [i486-linux], 2007-09-18:38/2] * debian/control restrict use to ruby > 1.8.4 and ruby < 1.9 * debian * debian/control restrict use to ruby > 1.8.4 and ruby < 1.9 * sisu-doc new sub-package for sisu documentation debian/control and sisu-doc.install --- .../sisu_manual/sisu_commands/plain.txt | 545 +++++++++++++++++++++ 1 file changed, 545 insertions(+) create mode 100644 data/doc/manuals_generated/sisu_manual/sisu_commands/plain.txt (limited to 'data/doc/manuals_generated/sisu_manual/sisu_commands/plain.txt') diff --git a/data/doc/manuals_generated/sisu_manual/sisu_commands/plain.txt b/data/doc/manuals_generated/sisu_manual/sisu_commands/plain.txt new file mode 100644 index 00000000..3db69c10 --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/sisu_commands/plain.txt @@ -0,0 +1,545 @@ +SISU - COMMANDS [0.58], +RALPH AMISSAH +************************************** + +SISU COMMANDS +============= + +1. COMMANDS SUMMARY +------------------- + +1.1 SYNOPSIS +............ + +*SiSU* - Structured information, Serialized Units - a document publishing +system + + +sisu [ -abcDdFHhIiMmNnopqRrSsTtUuVvwXxYyZz0-9 ] [ filename/ wildcard ] + + +sisu [ -Ddcv ] [ instruction ] + + +sisu [ -CcFLSVvW ] + + +Note: commands should be issued from within the directory that contains the +marked up files, cd to markup directory. + + +1.2 DESCRIPTION +............... + +*SiSU* *SiSU* is a document publishing system, that from a simple single +marked-up document, produces multiple of output formats including: plaintext, +html, LaTeX, pdf, xhtml, XML, info, and SQL (PostgreSQL and SQLite), which +share numbered text objects ("object citation numbering") and the same document +structure information. For more see: + + +1.3 DOCUMENT PROCESSING COMMAND FLAGS +..................................... + +*-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) + + +*-b [filename/wildcard] * +produces xhtml/XML output for browser viewing (sax parsing). + + +*-C [--init-site] * +configure/initialise shared output directory files initialize shared output +directory (config files such as css and dtd files are not updated if they +already exist unless modifier is used). -C --init-site configure/initialise +site more extensive than -C on its own, shared output directory files/force +update, existing shared output config files such as css and dtd files are +updated if this modifier is used. + + +*-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. + + +*-c [filename/wildcard] * +screen toggle ansi screen colour on or off depending on default set (unless +-c flag is used: if sisurc colour default is set to 'true', output to screen +will be with colour, if sisurc colour default is set to 'false' or is undefined +screen output will be without colour). + + +*-D [instruction] [filename] * +database postgresql ( --pgsql may be used instead) possible instructions, +include: --createdb; --create; --dropall; --import [filename]; --update +[filename]; --remove [filename]; see database section below. + + +*-d [--db-[database type (sqlite|pg)]] --[instruction] [filename] * +database type default set to sqlite, (for which --sqlite may be used instead) +or to specify another database --db-[pgsql, sqlite] (however see -D) possible +instructions include: --createdb; --create; --dropall; --import [filename]; +--update [filename]; --remove [filename]; see database section below. + + +*-F [--webserv=webrick] * +generate examples of (naive) cgi search form for sqlite and pgsql depends on +your already having used sisu to populate an sqlite and/or pgsql database, (the +sqlite version scans the output directories for existing sisu_sqlite databases, +so it is first necessary to create them, before generating the search form) see +-d -D and the database section below. If the optional parameter +--webserv=webrick is passed, the cgi examples created will be set up to use the +default port set for use by the webrick server, (otherwise the port is left +blank and the system setting used, usually 80). The samples are dumped in the +present work directory which must be writable, (with screen instructions given +that they be copied to the cgi-bin directory). -Fv (in addition to the above) +provides some information on setting up hyperestraier for sisu + + +*-H [filename/wildcard] * +produces html without link suffixes (.html .pdf etc.) ("Hide"). Requires an +appropriately configured web server. [behaviour switched after 0.35 see -h]. + + +*-h [filename/wildcard] * +produces html (with hardlinks i.e. with name suffixes in links/local urls). +html, with internal document links that include the document suffix, i.e. +whether it is .html or .pdf (required for browsing directly off a file system, +and works with most web servers). [behaviour switched after 0.35 see -H]. + + +*-I [filename/wildcard] * +produces texinfo and info file, (view with pinfo). + + +*-L * +prints license information. + + +*-M [filename/wildcard/url] * +maintenance mode files created for processing preserved and their locations +indicated. (also see -V) + + +*-m [filename/wildcard/url] * +assumed for most other flags, creates new meta-markup file, (the metaverse ) +that is used in all subsequent processing of other output. This step is assumed +for most processing flags. To skip it see -n + + +*-N [filename/wildcard/url] * +document digest or document content certificate ( DCC ) as md5 digest tree of +the document: the digest for the document, and digests for each object +contained within the document (together with information on software versions +that produced it) (digest.txt). -NV for verbose digest output to screen. + + +*-n [filename/wildcard/url] * +skip meta-markup (building of "metaverse"), this skips the equivalent of -m +which is otherwise assumed by most processing flags. + + +*-o [filename/wildcard/url] * +output basic document in opendocument file format (opendocument.odt). + + +*-p [filename/wildcard] * +produces LaTeX pdf (portrait.pdf & landscape.pdf). Default paper size is set +in config file, or document header, or provided with additional command line +parameter, e.g. --papersize-a4 preset sizes include: 'A4', U.S. 'letter' and +'legal' and book sizes 'A5' and 'B5' (system defaults to A4). + + +*-q [filename/wildcard] * +quiet less output to screen. + + +*-R [filename/wildcard] * +copies sisu output files to remote host using rsync. This requires that +sisurc.yml has been provided with information on hostname and username, and +that you have your "keys" and ssh agent in place. Note the behavior of rsync +different if -R is used with other flags from if used alone. Alone the rsync +--delete parameter is sent, useful for cleaning the remote directory (when -R +is used together with other flags, it is not). Also see -r + + +*-r [filename/wildcard] * +copies sisu output files to remote host using scp. This requires that +sisurc.yml has been provided with information on hostname and username, and +that you have your "keys" and ssh agent in place. Also see -R + + +*-S * +produces a sisupod a zipped sisu directory of markup files including sisu +markup source files and the directories local configuration file, images and +skins. Note: this only includes the configuration files or skins contained in +./_sisu not those in ~/.sisu -S [filename/wildcard] option. Note: (this option +is tested only with zsh). + + +*-S [filename/wildcard] * +produces a zipped file of the prepared document specified along with +associated images, by default named sisupod.zip they may alternatively be named +with the filename extension .ssp This provides a quick way of gathering the +relevant parts of a sisu document which can then for example be emailed. A +sisupod includes sisu markup source file, (along with associated documents if a +master file, or available in multilingual versions), together with related +images and skin. *SiSU* commands can be run directly against a sisupod +contained in a local directory, or provided as a url on a remote site. As there +is a security issue with skins provided by other users, they are not applied +unless the flag --trust or --trusted is added to the command instruction, it is +recommended that file that are not your own are treated as untrusted. The +directory structure of the unzipped file is understood by sisu, and sisu +commands can be run within it. Note: if you wish to send multiple files, it +quickly becomes more space efficient to zip the sisu markup directory, rather +than the individual files for sending). See the -S option without +[filename/wildcard]. + + +*-s [filename/wildcard] * +copies sisu markup file to output directory. + + +*-t [filename/wildcard (*.termsheet.rb)] * +standard form document builder, preprocessing feature + + +*-U [filename/wildcard] * +prints url output list/map for the available processing flags options and +resulting files that could be requested, (can be used to get a list of +processing options in relation to a file, together with information on the +output that would be produced), -u provides url output mapping for those flags +requested for processing. The default assumes sisu_webrick is running and +provides webrick url mappings where appropriate, but these can be switched to +file system paths in sisurc.yml + + +*-u [filename/wildcard] * +provides url mapping of output files for the flags requested for processing, +also see -U + + +*-V * +on its own, provides *SiSU* version and environment information (sisu --help +env) + + +*-V [filename/wildcard] * +even more verbose than the -v flag. (also see -M) + + +*-v * +on its own, provides *SiSU* version information + + +*-v [filename/wildcard] * +provides verbose output of what is being built, where it is being built (and +error messages if any), as with -u flag provides a url mapping of files created +for each of the processing flag requests. See also -V + + +*-W * +starts ruby's webrick webserver points at sisu output directories, the +default port is set to 8081 and can be changed in the resource configuration +files. [tip: the webrick server requires link suffixes, so html output should +be created using the -h option rather than -H; also, note -F webrick ]. + + +*-w [filename/wildcard] * +produces concordance (wordmap) a rudimentary index of all the words in a +document. (Concordance files are not generated for documents of over 260,000 +words unless this limit is increased in the file sisurc.yml) + + +*-X [filename/wildcard] * +produces XML output with deep document structure, in the nature of dom. + + +*-x [filename/wildcard] * +produces XML output shallow structure (sax parsing). + + +*-Y [filename/wildcard] * +produces a short sitemap entry for the document, based on html output and the +sisu_manifest. --sitemaps generates/updates the sitemap index of existing +sitemaps. (Experimental, [g,y,m announcement this week]) + + +*-y [filename/wildcard] * +produces an html summary of output generated (hyperlinked to content) and +document specific metadata (sisu_manifest.html). This step is assumed for most +processing flags. + + +*-Z [filename/wildcard] * +Zap, if used with other processing flags deletes output files of the type +about to be processed, prior to processing. If -Z is used as the lone +processing related flag (or in conjunction with a combination of -[mMvVq]), +will remove the related document output directory. + + +*-z [filename/wildcard] * +produces php (zend) [this feature is disabled for the time being] + + +2. COMMAND LINE MODIFIERS +------------------------- + +*--no-ocn * +[with -h -H or -p] switches off object citation numbering. Produce output +without identifying numbers in margins of html or LaTeX/pdf output. + + +*--no-annotate * +strips output text of editor endnotes[^*1] denoted by asterisk or dagger/plus +sign + + +- [*1]: square brackets + +*--no-asterisk * +strips output text of editor endnotes[^*2] denoted by asterisk sign + + +- [*2]: square brackets + +*--no-dagger * +strips output text of editor endnotes[^+1] denoted by dagger/plus sign + + +- [+1]: square brackets + +3. DATABASE COMMANDS +-------------------- + +dbi - database interface + + +-D or --pgsql set for postgresql -d or --sqlite default set for sqlite -d is +modifiable with --db=[database type (pgsql or sqlite)] + + +*-Dv --createall * +initial step, creates required relations (tables, indexes) in existing +postgresql database (a database should be created manually and given the same +name as working directory, as requested) (rb.dbi) [ -dv --createall sqlite +equivalent] it may be necessary to run sisu -Dv --createdb initially NOTE: at +the present time for postgresql it may be necessary to manually create the +database. The command would be 'createdb [database name]' where database name +would be SiSU_[present working directory name (without path)]. Please use only +alphanumerics and underscores. + + +*-Dv --import * +[filename/wildcard] imports data specified to postgresql db (rb.dbi) [ -dv +--import sqlite equivalent] + + +*-Dv --update * +[filename/wildcard] updates/imports specified data to postgresql db (rb.dbi) +[ -dv --update sqlite equivalent] + + +*-D --remove * +[filename/wildcard] removes specified data to postgresql db (rb.dbi) [ -d +--remove sqlite equivalent] + + +*-D --dropall * +kills data" and drops (postgresql or sqlite) db, tables & indexes [ -d +--dropall sqlite equivalent] + + +The v in e.g. -Dv is for verbose output. + + +4. SHORTCUTS, SHORTHAND FOR MULTIPLE FLAGS +------------------------------------------ + +*--update [filename/wildcard] * +Checks existing file output and runs the flags required to update this +output. This means that if only html and pdf output was requested on previous +runs, only the -hp files will be applied, and only these will be generated this +time, together with the summary. This can be very convenient, if you offer +different outputs of different files, and just want to do the same again. + + +*-0 to -5 [filename or wildcard] * +Default shorthand mappings (note that the defaults can be changed/configured +in the sisurc.yml file): + + +*-0 * +-mNhwpAobxXyYv [this is the default action run when no options are give, i.e. +on 'sisu [filename]'] + + +*-1 * +-mNHwpy + + +*-2 * +-mNHwpaoy + + +*-3 * +-mNhwpAobxXyY + + +*-4 * +-mNhwpAobxXDyY --import + + +*-5 * +-mNhwpAobxXDyY --update + + +add -v for verbose mode and -c for color, e.g. sisu -2vc [filename or wildcard] + + +consider -u for appended url info or -v for verbose output + + +4.0.1 COMMAND LINE WITH FLAGS - BATCH PROCESSING +................................................ + +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. + + +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. + + +DOCUMENT INFORMATION (METADATA) +******************************* + +METADATA +-------- + +Document Manifest @ + + + +*Dublin Core* (DC) + + +/DC tags included with this document are provided here./ + + +DC Title: _SiSU - Commands [0.58]_ + + +DC Creator: _Ralph Amissah_ + + +DC Rights: _Copyright (C) Ralph Amissah 2007, part of SiSU documentation, +License GPL 3_ + + +DC Type: _information_ + + +DC Date created: _2002-08-28_ + + +DC Date issued: _2002-08-28_ + + +DC Date available: _2002-08-28_ + + +DC Date modified: _2007-09-16_ + + +DC Date: _2007-09-16_ + + +*Version Information* + + +Sourcefile: _sisu_commands.sst_ + + +Filetype: _SiSU text 0.58_ + + +Sourcefile Digest, MD5(sisu_commands.sst)= _8101d9e72f3de2510ef887202f8db3f9_ + + +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)= +_20fc43cf3eb6590bc3399a1aef65c5a9_ + + +*Generated* + + +Document (metaverse) last generated: _Sun Sep 23 04:10:59 +0100 2007_ + + +Generated by: _SiSU_ _0.59.0_ of 2007w38/0 (2007-09-23) + + +Ruby version: _ ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux]_ + + + +============================================================================== + + title: SiSU - Commands [0.58] + + creator: Ralph Amissah + + rights: Copyright (C) Ralph Amissah 2007, part of SiSU documentation, + License GPL 3 + + type: information + + subject: ebook, epublishing, electronic book, electronic publishing, + electronic document, electronic citation, data structure, + citation systems, search + + date.created: 2002-08-28 + + date.issued: 2002-08-28 + + date.available: 2002-08-28 + + date.modified: 2007-09-16 + + date: 2007-09-16 + + + + + +============================================================================== +nil + +Other versions of this document: +manifest: + http://www.jus.uio.no/sisu/sisu_commands/sisu_manifest.html +html: + http://www.jus.uio.no/sisu/sisu_commands/toc.html +pdf: + http://www.jus.uio.no/sisu/sisu_commands/portrait.pdf + http://www.jus.uio.no/sisu/sisu_commands/landscape.pdf +plaintext (plain text): + http://www.jus.uio.no/sisu/sisu_commands/plain.txt +at: + http://www.jus.uio.no/sisu +* Generated by: SiSU 0.59.0 of 2007w38/0 (2007-09-23) +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +* Last Generated on: Sun Sep 23 04:11:50 +0100 2007 +* SiSU http://www.jus.uio.no/sisu -- cgit v1.2.3