documentation relatedsisu_5.5.2

3 files changed, 91 insertions, 80 deletions

diff --git a/README b/README
index 5f87fcdd..aa51a33b 100644
--- a/README
+++ b/README
@@ -297,11 +297,8 @@ 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). Alias -w
 
-*-D [instruction] [filename]*
-see --pg
-
-*-d [--db-[database type (sqlite|pg)]] --[instruction] [filename]*
-see --sqlite
+*-d [filename/wildcard/url]*
+see --docbook
 
 *--dal [filename/wildcard/url]*
 (abstract objects, document abstraction renamed abstract objects in sisu5) see
@@ -310,6 +307,13 @@ see --sqlite
 *--delete [filename/wildcard]*
 see --zap
 
+*--digests [filename/wildcard/url]*
+document digest or document content certificate ( DCC ) as sha 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). --digests -V for verbose digest output to
+screen.
+
 *--docbook [filename/wildcard/url]*
 docbook xml
 
@@ -444,12 +448,17 @@ see --dal (document abstraction level/layer)
 maintenance mode, interim processing files are preserved and their locations
 indicated. (also see -V). Aliases -M and --keep-processing-files.
 
-*--markdown [filename/wildcard/url]*
-markdown smart text (not available)
+*--manifest [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.
 
 *--manpage [filename/wildcard]*
 produces man page of file, not suitable for all outputs. Alias -i
 
+*--markdown [filename/wildcard/url]*
+markdown smart text (not available)
+
 *--monolingual*
 see --i18n-*
 
@@ -457,10 +466,7 @@ see --i18n-*
 see --i18n-*
 
 *-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.
+see --digests
 
 *-n [filename/wildcard/url]*
 skip the creation of intermediate processing files (document abstraction) if
@@ -542,10 +548,10 @@ and 'legal' and book sizes 'A5' and 'B5' (system defaults to A4). Related
 options --pdf --pdf-landscape. See also --papersize-* or --papersize=[list].
 Alias --pdf-p or in conjunction with --pdf --portrait
 
-*--pg [instruction] [filename]*
+*--pg-[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. Alias -D
+include: --pg-createdb; --pg-create; --pg-dropall; --pg-import [filename];
+--pg-update [filename]; --pg-remove [filename]; see database section below.
 
 *--po [language_directory/filename language_directory]*
 see --po4a
@@ -621,15 +627,15 @@ set hash digest where used to sha256
 *--sha512*
 set hash digest where used to sha512
 
-*--sqlite --[instruction] [filename]*
+*--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
+directory base path (possible instructions include: --sqlite-createdb;
+--sqlite-create; --sqlite-dropall; --sqlite-import [filename]; --sqlite-update
+[filename]; --sqlite-remove [filename]); see database section below.
 
 *--sisupod*
 produces a sisupod a zipped sisu directory of markup files including sisu
@@ -773,9 +779,7 @@ 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.
+see --manifest
 
 *-Z [filename/wildcard]*
 see --zap
@@ -808,8 +812,8 @@ 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/) ]
+*--pg or --pgsql* set for /PostgreSQL/ *--sqlite* default set for /SQLite/ -d
+is modifiable with --db=[database type (PgSQL or /SQLite/) ]
 
 *--pg -v --createall*
 initial step, creates required relations (tables, indexes) in existing
@@ -1626,7 +1630,7 @@ This is a table┆this would become column two of row one┆column three of row
 a second form may be easier to work with in cases where there is not much
 information in each column
 
-*markup example:*[^10]
+*markup example:*[^9]
 
 !_ Table 3.1: Contributors to Wikipedia, January 2001 - June 2005
 
@@ -2168,6 +2172,6 @@ Configure substitution in _sisu/sisu_document_make
 
  [8]: <http://www.ruby-lang.org/en/>
 
- [10]: Table from the Wealth of Networks by Yochai Benkler
+ [9]: Table from the Wealth of Networks by Yochai Benkler
 
  <http://www.jus.uio.no/sisu/the_wealth_of_networks.yochai_benkler>
diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_commands.sst b/data/doc/sisu/markup-samples/manual/en/sisu_commands.sst
index 16661dd6..7af33161 100644
--- a/data/doc/sisu/markup-samples/manual/en/sisu_commands.sst
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_commands.sst
@@ -79,11 +79,8 @@ configure/initialise shared output directory files initialize shared output dire
 !_ --concordance [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). Alias -w
 
-!_ -D [instruction] [filename] \\
-see --pg
-
-!_ -d [--db-[database type (sqlite|pg)]] --[instruction] [filename] \\
-see --sqlite
+!_ -d [filename/wildcard/url] \\
+see --docbook
 
 !_ --dal [filename/wildcard/url] \\
 (abstract objects, document abstraction renamed abstract objects in sisu5) see --ao
@@ -91,6 +88,9 @@ see --sqlite
 !_ --delete [filename/wildcard] \\
 see --zap
 
+!_ --digests [filename/wildcard/url] \\
+document digest or document content certificate ( DCC ) as sha 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). --digests -V for verbose digest output to screen.
+
 !_ --docbook [filename/wildcard/url] \\
 docbook xml
 
@@ -203,12 +203,15 @@ 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.
 
-!_ --markdown [filename/wildcard/url] \\
-markdown smart text (not available)
+!_ --manifest [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.
 
 !_ --manpage [filename/wildcard] \\
 produces man page of file, not suitable for all outputs. Alias -i
 
+!_ --markdown [filename/wildcard/url] \\
+markdown smart text (not available)
+
 !_ --monolingual \\
 see --i18n-*
 
@@ -216,7 +219,7 @@ see --i18n-*
 see --i18n-*
 
 !_ -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.
+see --digests
 
 !_ -n [filename/wildcard/url] \\
 skip the creation of intermediate processing files (document abstraction) if they already exist, this skips the equivalent of -m which is otherwise assumed by most processing flags.
@@ -273,8 +276,8 @@ See --pdf-portrait
 !_ --pdf-portrait [filename/wildcard] \\
 sets orientation, produces LaTeX pdf portrait.pdf.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). Related options --pdf --pdf-landscape. See also --papersize-* or --papersize=[list]. Alias --pdf-p or in conjunction with --pdf --portrait
 
-!_ --pg [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. Alias -D
+!_ --pg-[instruction] [filename] \\
+database PostgreSQL ( --pgsql may be used instead) possible instructions, include: --pg-createdb; --pg-create; --pg-dropall; --pg-import [filename]; --pg-update [filename]; --pg-remove [filename]; see database section below.
 
 !_ --po [language_directory/filename language_directory] \\
 see --po4a
@@ -330,8 +333,8 @@ set hash digest where used to sha256
 !_ --sha512 \\
 set hash digest where used to sha512
 
-!_ --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
+!_ --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: --sqlite-createdb; --sqlite-create; --sqlite-dropall; --sqlite-import [filename]; --sqlite-update [filename]; --sqlite-remove [filename]); see database section below.
 
 !_ --sisupod \\
 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). Alias -S
@@ -433,7 +436,7 @@ see --xml-sax
 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.
+see --manifest
 
 !_ -Z [filename/wildcard] \\
 see --zap
@@ -459,9 +462,9 @@ strips output text of editor endnotes~[+ square brackets ]~ denoted by dagger/pl
 
 !_ dbi - database interface
 
-!_ -D or --pgsql
+!_ --pg or --pgsql
 set for PostgreSQL
-!_ -d or --sqlite
+!_ --sqlite
 default set for SQLite -d is modifiable with --db=[database type (PgSQL or SQLite)]
 
 !_ --pg -v --createall \\
diff --git a/man/man1/sisu.1 b/man/man1/sisu.1
index 93677518..5cc2c7d9 100644
--- a/man/man1/sisu.1
+++ b/man/man1/sisu.1
@@ -1,4 +1,4 @@
-.TH "sisu" "1" "2014-07-15" "6.1.1" "SiSU"
+.TH "sisu" "1" "2014-07-22" "5.5.2" "SiSU"
 .br
 .SH NAME
 .br
@@ -194,11 +194,8 @@ 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). Alias -w
 .TP
-.B -D [instruction] [filename]
-see --pg
-.TP
-.B -d [--db-[database type (sqlite|pg)]] --[instruction] [filename]
-see --sqlite
+.B -d [filename/wildcard/url]
+see --docbook
 .TP
 .B --dal [filename/wildcard/url]
 (abstract objects, document abstraction renamed abstract objects in sisu5) see
@@ -207,6 +204,13 @@ see --sqlite
 .B --delete [filename/wildcard]
 see --zap
 .TP
+.B --digests [filename/wildcard/url]
+document digest or document content certificate ( DCC ) as sha 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). --digests -V for verbose digest output to
+screen.
+.TP
 .B --docbook [filename/wildcard/url]
 docbook xml
 .TP
@@ -342,12 +346,17 @@ see --dal (document abstraction level/layer)
 maintenance mode, interim processing files are preserved and their locations
 indicated. (also see -V). Aliases -M and --keep-processing-files.
 .TP
-.B --markdown [filename/wildcard/url]
-markdown smart text (not available)
+.B --manifest [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 --manpage [filename/wildcard]
 produces man page of file, not suitable for all outputs. Alias -i
 .TP
+.B --markdown [filename/wildcard/url]
+markdown smart text (not available)
+.TP
 .B --monolingual
 see --i18n-*
 .TP
@@ -355,10 +364,7 @@ see --i18n-*
 see --i18n-*
 .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.
+see --digests
 .TP
 .B -n [filename/wildcard/url]
 skip the creation of intermediate processing files (document abstraction) if
@@ -448,12 +454,12 @@ preset sizes include: 'A4', U.S. 'letter' and 'legal' and book sizes 'A5' and
 --papersize-* or --papersize=[list]. Alias --pdf-p or in conjunction with --pdf
 --portrait
 .TP
-.B --pg [instruction] [filename]
+.B --pg-[instruction] [filename]
 database
 .I PostgreSQL
-( --pgsql may be used instead) possible instructions, include: --createdb;
---create; --dropall; --import [filename]; --update [filename]; --remove
-[filename]; see database section below. Alias -D
+( --pgsql may be used instead) possible instructions, include: --pg-createdb;
+--pg-create; --pg-dropall; --pg-import [filename]; --pg-update [filename];
+--pg-remove [filename]; see database section below.
 .TP
 .B --po [language_directory/filename language_directory]
 see --po4a
@@ -536,7 +542,7 @@ set hash digest where used to sha256
 .B --sha512
 set hash digest where used to sha512
 .TP
-.B --sqlite --[instruction] [filename]
+.B --sqlite-[instruction] [filename]
 database type set to
 .I SQLite,
 this produces one of two possible databases, without additional database
@@ -547,9 +553,9 @@ common
 .I 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
+path (possible instructions include: --sqlite-createdb; --sqlite-create;
+--sqlite-dropall; --sqlite-import [filename]; --sqlite-update [filename];
+--sqlite-remove [filename]); see database section below.
 .TP
 .B --sisupod
 produces a sisupod a zipped sisu directory of markup files including sisu
@@ -703,9 +709,7 @@ 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.
+see --manifest
 .TP
 .B -Z [filename/wildcard]
 see --zap
@@ -743,10 +747,10 @@ strips output text of editor endnotes[^+1] denoted by dagger/plus sign
 
 .BR
 
-.B -D or --pgsql
+.B --pg or --pgsql
 set for
 .I PostgreSQL
-.B -d or --sqlite
+.B --sqlite
 default set for
 .I SQLite
 -d is modifiable with --db=[database type (PgSQL or
@@ -2582,7 +2586,7 @@ contain other documents.
 
 .BR
 Note: a secondary file of the composite document is built prior to processing
-with the same prefix and the suffix ._sst [^11]
+with the same prefix and the suffix ._sst [^10]
 .SH SISU INSERT FILES (.SSI)
 
 
@@ -2782,7 +2786,7 @@ The default homepage may use homepage.css or html. css
 
 .BR
 Under consideration is to permit the placement of a CSS file with a different
-name in directory _sisu/css directory or equivalent.[^12]
+name in directory _sisu/css directory or equivalent.[^11]
 .SH ORGANISING CONTENT - DIRECTORY STRUCTURE AND MAPPING
 
 
@@ -3283,9 +3287,9 @@ formats.
 .B SiSU
 feeds sisu markupd documents into sql type databases
 .I PostgreSQL
-[^13] and/or
+[^12] and/or
 .I SQLite
-[^14] database together with information related to document structure.
+[^13] database together with information related to document structure.
 
 .BR
 This is one of the more interesting output forms, as all the structural data of
@@ -3555,10 +3559,10 @@ INCLUDING OBJECT CITATION NUMBERING (BACKEND CURRENTLY POSTGRESQL)
 
 
 .BR
-Sample search frontend <http://search.sisudoc.org> [^15] A small database and
+Sample search frontend <http://search.sisudoc.org> [^14] A small database and
 sample query front-end (search from) that makes use of the citation system, .I
 object citation numbering
-to demonstrates functionality.[^16]
+to demonstrates functionality.[^15]
 
 .BR
 
@@ -3583,7 +3587,7 @@ documents matched.
 Note you may 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.[^17]
+meet the search criteria.[^16]
 .TP
 .B sisu -F --webserv-webrick
 builds a cgi web search frontend for the database created
@@ -3966,13 +3970,13 @@ editors notes, numbered plus symbol footnote/endnote series
 
 .BR
 .TP
-.BI 10.
+.BI 9.
 Table from the Wealth of Networks by Yochai Benkler
 <http://www.jus.uio.no/sisu/the_wealth_of_networks.yochai_benkler>
 
 .BR
 .TP
-.BI 11.
+.BI 10.
 \.ssc (for composite) is under consideration but \._sst makes clear that this
 is not a regular file to be worked on, and thus less likely that people will
 have "accidents", working on a \.ssc file that is overwritten by subsequent
@@ -3981,37 +3985,37 @@ appropriate suffix to use.
 
 .BR
 .TP
-.BI 12.
+.BI 11.
 SiSU has worked this way in the past, though this was dropped as it was
 thought the complexity outweighed the flexibility, however, the balance was
 rather fine and this behaviour could be reinstated.
 
 .BR
 .TP
-.BI 13.
+.BI 12.
 <http://www.postgresql.org/> <http://advocacy.postgresql.org/>
 <http://en.wikipedia.org/wiki/Postgresql>
 
 .BR
 .TP
-.BI 14.
+.BI 13.
 <http://www.hwaci.com/sw/sqlite/> <http://en.wikipedia.org/wiki/Sqlite>
 
 .BR
 .TP
-.BI 15.
+.BI 14.
 <http://search.sisudoc.org>
 
 .BR
 .TP
-.BI 16.
+.BI 15.
 (which could be extended further with current back-end). As regards scaling
 of the database, it is as scalable as the database (here Postgresql) and
 hardware allow.
 
 .BR
 .TP
-.BI 17.
+.BI 16.
 of this feature when demonstrated to an IBM software innovations evaluator
 in 2004 he said to paraphrase: this could be of interest to us. We have large
 document management systems, you can search hundreds of thousands of documents