From 4adb525fb4f143781a05c0e62c3798730f9b0713 Mon Sep 17 00:00:00 2001 From: Ralph Amissah Date: Wed, 29 May 2013 19:50:40 -0400 Subject: v4 v5: help, documentation update, concentrate on man pages * documentation, manpage update * interactive help, out of date, removed --- data/doc/sisu/html/sisu.1.html | 220 +++++++++++++++++++---------------------- 1 file changed, 101 insertions(+), 119 deletions(-) (limited to 'data/doc/sisu/html/sisu.1.html') diff --git a/data/doc/sisu/html/sisu.1.html b/data/doc/sisu/html/sisu.1.html index 56535d2e..6f4eb681 100644 --- a/data/doc/sisu/html/sisu.1.html +++ b/data/doc/sisu/html/sisu.1.html @@ -296,8 +296,7 @@ affects html (seg), epub) ; see also --inc-* match given string in directory (including language subdirectories). Alias -f, --glob, -G -
-G [optional string part of filename] -
+
-G [optional string part of filename]
see --find
-g [filename/wildcard]
@@ -309,7 +308,7 @@ structure in a git repo (experimental and subject to change). Alias -g
--glob [optional string part of filename]
-
see --find
+
see --find
-h [filename/wildcard]
see --html
@@ -375,9 +374,8 @@ invoked by --dump & redirect).
see --dal (document abstraction level/layer)
--maintenance [filename/wildcard/url]
-
maintenance mode, interim -processing files are preserved and their locations indicated. (also see --V). Aliases -M and --keep-processing-files.
+
maintenance mode, interim processing files are preserved and their locations +indicated. (also see -V). Aliases -M and --keep-processing-files.
--manpage [filename/wildcard]
produces man page of file, not suitable for all outputs. Alias -i
@@ -531,33 +529,39 @@ with other flags, it is not). Also see --scp. Alias -R
-s [filename/wildcard]
see --source
-
--sample-search-form [--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). Alias -F
- -
--scp [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 --rsync. Alias -r
- -
--sqlite --[instruction] [filename]
-
database type set to -SQLite, this produces one of two possible databases, without additional -database related instructions it produces a discreet SQLite file for the -document processed; with additional instructions it produces a common SQLite -database of all processed documents that (come from the same document preparation -directory and as a result) share the same output directory base path (possible -instructions include: --createdb; --create; --dropall; --import [filename]; --update -[filename]; --remove [filename]); see database section below. Alias -d
+
--sample-search-form [--db=(pgsql|sqlite)] +[--webserv=webrick]
+
generate examples of (naive) cgi search form for SQLite +or PgSQL depends on your already having used sisu to populate an SQLite +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 --sqlite & --pg and the database section +below. Optional additional parameters include: url location of webserver +search form and db: --webserv-search=’[url]’; location of webserver output: +--webserv-output=’[url]’; cgi search form link name: --cgi-search-form-name=’[name.cgi]’; +for pgsql, database user: --db-user=’[username]’. 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). Alias -F
+ +
--scp [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 --rsync. Alias -r
+ +
--sqlite --[instruction] +[filename]
+
database type set to SQLite, this produces one of two possible +databases, without additional database related instructions it produces +a discreet SQLite file for the document processed; with additional instructions +it produces a common SQLite database of all processed documents that (come +from the same document preparation directory and as a result) share the +same output directory base path (possible instructions include: --createdb; +--create; --dropall; --import [filename]; --update [filename]; --remove [filename]); +see database section below. Alias -d
--sisupod
produces a sisupod a zipped sisu directory of markup files including sisu @@ -566,23 +570,23 @@ and skins. Note: this only includes the configuration files or skins contained in is tested only with zsh). Alias -S
--sisupod [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]. Alias -S
+
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]. +Alias -S
--source [filename/wildcard]
copies sisu markup file to output directory. Alias -s
@@ -594,16 +598,15 @@ rather than the individual files for sending). See the -S option without
see --txt
--texinfo [filename/wildcard]
-
produces texinfo and info file, (view with -pinfo). Alias -I
+
produces texinfo and info file, (view with pinfo). Alias -I
--txt [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). Alias -t
+
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). Alias +-t
-U [filename/wildcard]
see --urls
@@ -613,14 +616,13 @@ output file] [see -e for endnotes]. (Options include: --endnotes for endnotes requested for processing, also see -U
--urls [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. Alias -U
+
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. Alias -U
-V
on its own, provides SiSU version @@ -872,49 +874,30 @@ sisu man pages <http://www.jus.uio. > [^10]

-

Sisu Built-in Interactive Help

- -

This is particularly useful for getting -the current sisu setup/environment information: -

sisu --help -

sisu --help -[subject] -

sisu --help commands -

sisu --help markup -

sisu --help env [for -feedback on the way your system is setup with regard to sisu ]
- -

sisu -V [environment information, same as above command] -

sisu (on its -own provides version and some help information) -

Apart from real-time information -on your current configuration the SiSU manual and man pages are likely -to contain more up-to-date information than the sisu interactive help (for -example on commands and markup). -

NOTE: Running the command 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. -

Introduction -to Sisu Markup[^11]

+

Sisu Built-in Interactive Help, [discontinued]

+ +

This fell out of date +and has been discontinued. +

Introduction to Sisu Markup[^11]

Summary

-

SiSU source documents are plaintext ( UTF-8 -)[^12] files -

All paragraphs are separated by an empty line. -

Markup is -comprised of: -

* at the top of a document, the document header made up -of semantic meta-data about the document and if desired additional processing -instructions (such an instruction to automatically number headings from -a particular level down) -

* followed by the prepared substantive text -of which the most important single characteristic is the markup of different -heading levels, which define the primary outline of the document structure. -Markup of substantive text includes: -

* heading levels defines document -structure
+

SiSU +source documents are plaintext ( UTF-8 )[^12] files +

All paragraphs are +separated by an empty line. +

Markup is comprised of: +

* at the top of +a document, the document header made up of semantic meta-data about the +document and if desired additional processing instructions (such an instruction +to automatically number headings from a particular level down) +

* followed +by the prepared substantive text of which the most important single characteristic +is the markup of different heading levels, which define the primary outline +of the document structure. Markup of substantive text includes: +

* heading +levels defines document structure

* text basic attributes, italics, bold etc.
@@ -2040,12 +2023,11 @@ if a .sst file is renamed .ssm without requiring any other documents; the .ssm marker flags that the document may contain other documents.

Note: a secondary file of the composite document is built prior to processing -with the same prefix and the suffix ._sst [^18] -

+with the same prefix and the suffix ._sst [^19]

Sisu Insert Files (.ssi)

- Inserts are documents prepared solely for the purpose of being incorporated +Inserts are documents prepared solely for the purpose of being incorporated into one or more master documents. They resemble regular SiSU text files except they are ignored by the SiSU processor. Making a file a .ssi file is a quick and convenient way of flagging that it is not intended that @@ -2170,7 +2152,7 @@ DOM: dom.css may use homepage.css or html. css

Under consideration is to permit the placement of a CSS file with a different name in directory _sisu/css directory -or equivalent.[^19] +or equivalent.[^20]

Organising Content - Directory Structure and Mapping

@@ -2524,8 +2506,8 @@ or in various output formats.

Populating Sql Type Databases

SiSU feeds -sisu markupd documents into sql type databases PostgreSQL [^20] and/or SQLite -[^21] database together with information related to document structure. +sisu markupd documents into sql type databases PostgreSQL [^21] and/or SQLite +[^22] database together with information related to document structure.

This is one of the more interesting output forms, as all the structural data of the documents are retained (though can be ignored by the user of @@ -2687,14 +2669,14 @@ an sqlite database, this being part of SiSU - man sisu) .

Synopsis

sisu --d [instruction] [filename/wildcard if required] +-d [instruction] [filename/wildcard if required]

sisu -d --(sqlite|pg) --[instruction] -[filename/wildcard if required] +[filename/wildcard if required]

Commands

-

Mappings to two databases -are provided by default, postgresql and sqlite, the same commands are used +

Mappings to two databases are +provided by default, postgresql and sqlite, the same commands are used within sisu to construct and populate databases however -d (lowercase) denotes sqlite and -D (uppercase) denotes postgresql, alternatively --sqlite or --pgsql @@ -2769,9 +2751,9 @@ and Sisu Features, INCLUDING OBJECT CITATION NUMBERING (BACKEND CURRENTLY POSTGRESQL)

Sample search frontend <http://search.sisudoc.org -> [^22] A small +> [^23] A small database and sample query front-end (search from) that makes use of the -citation system, .I object citation numbering to demonstrates functionality.[^23] +citation system, object citation numbering to demonstrates functionality.[^24]

SiSU can provide information on which documents are matched and at what locations within each document the matches are found. These results are @@ -2783,7 +2765,7 @@ the matched objects (paragraphs) in the documents matched. set results either for documents matched and object number locations within each matched document meeting the search criteria; or display the names of the documents matched along with the objects (paragraphs) that meet -the search criteria.[^24] +the search criteria.[^25]

@@ -3173,7 +3155,7 @@ or <http://www.jus.uio.no/sisu/
  • Help
  • Sisu Manual
  • Sisu Man Pages
    • -
  • Sisu Built-in Interactive Help
    • +
  • Sisu Built-in Interactive Help, [discontinued]
  • Introduction to Sisu Markup[^11]
  • Summary
  • Markup Examples
    • -- cgit v1.2.3