v3: documentation, manpage & html (man2html)sisu_3.1.7

3 files changed, 254 insertions, 74 deletions

diff --git a/data/doc/sisu/CHANGELOG_v3 b/data/doc/sisu/CHANGELOG_v3
index 6c5645da..8f9c2cea 100644
--- a/data/doc/sisu/CHANGELOG_v3
+++ b/data/doc/sisu/CHANGELOG_v3
@@ -34,6 +34,9 @@ http://www.jus.uio.no/sisu/pkg/src/sisu_3.1.7.orig.tar.xz
 
   * documentation, add --configure & use ascii characters for dir tree
     correction of a few typos
+    * manpage
+    * html
+
 %% 3.1.6.orig.tar.xz (2011-12-02:48/5)
 http://git.sisudoc.org/?p=code/sisu.git;a=log;h=refs/tags/sisu_3.1.6
 http://git.sisudoc.org/?p=code/sisu.git;a=log;h=refs/tags/debian/sisu_3.1.6-1
diff --git a/data/doc/sisu/html/sisu.1.html b/data/doc/sisu/html/sisu.1.html
index e973641b..106502ee 100644
--- a/data/doc/sisu/html/sisu.1.html
+++ b/data/doc/sisu/html/sisu.1.html
@@ -200,6 +200,16 @@ colour default is set to ’false’ or is undefined screen output will
 colour). Alias -c
 <p> </dd>
 
+<dt><b>--configure</b> </dt>
+<dd>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.
+<p> </dd>
+
 <dt><b>--concordance [filename/wildcard]</b> </dt>
 <dd>produces concordance (wordmap)
 a rudimentary index of all the words in a document. (Concordance files are
@@ -207,10 +217,10 @@ not generated for documents of over 260,000 words unless this limit is
 increased in the file sisurc.yml). Alias -w
 <p> </dd>
 
-<dt><b>-C [--init-site]</b> </dt>
-<dd>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
+<dt><b>-C</b> </dt>
+<dd>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
@@ -218,82 +228,75 @@ is used.
 <p> </dd>
 
 <dt><b>-CC</b> </dt>
-<dd>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.
+<dd>see --configure
+<p> </dd>
+
+<dt><b>-c [filename/wildcard]</b> </dt>
+<dd>see --color-toggle
 <p> </dd>
 
-<dt><b>-c [filename/wildcard]</b>
+<dt><b>--dal [filename/wildcard/url]</b>
 </dt>
-<dd>
-<p>see --color-toggle
+<dd>assumed for most other flags, creates new intermediate files for processing
+(document abstraction) that is used in all subsequent processing of other
+output. This step is assumed for most processing flags. To skip it see -n.
+
+<p>Alias -m
 <p> </dd>
 
-<dt><b>--dal [filename/wildcard/url]</b> </dt>
-<dd>assumed for most other flags,
-creates new intermediate files for processing (document abstraction) that
-is used in all subsequent processing of other output. This step is assumed
-for most processing flags. To skip it see -n. Alias -m
+<dt><b>--delete [filename/wildcard]</b> </dt>
+<dd>see --zap
 <p> </dd>
 
-<dt><b>--delete [filename/wildcard]</b>
+<dt><b>-D [instruction] [filename]</b>
 </dt>
 <dd>
-<p>see --zap
+<p>see --pg
 <p> </dd>
 
-<dt><b>-D [instruction] [filename]</b> </dt>
-<dd>see --pg
-<p> </dd>
-
-<dt><b>-d [--db-[database &nbsp;type &nbsp;(sqlite|pg)]]
---[instruction] [filename]</b> </dt>
+<dt><b>-d [--db-[database &nbsp;type &nbsp;(sqlite|pg)]] --[instruction] [filename]</b> </dt>
 <dd>see --sqlite
+
 <p> </dd>
 
 <dt><b>--epub [filename/wildcard]</b> </dt>
-<dd>produces
-an epub document, [sisu &nbsp;version &nbsp;&gt;=2 &nbsp;] (filename.epub). Alias -e
+<dd>produces an epub document, [sisu &nbsp;version &nbsp;&gt;=2 &nbsp;]
+(filename.epub). Alias -e
 <p> </dd>
 
-<dt><b>-e [filename/wildcard]</b>
-</dt>
-<dd>
-<p>see --epub
+<dt><b>-e [filename/wildcard]</b> </dt>
+<dd>see --epub
 <p> </dd>
 
-<dt><b>--find [optional &nbsp;string &nbsp;part &nbsp;of &nbsp;filename]</b> </dt>
-<dd>without match string,
-glob all .sst .ssm files in directory (including language subdirectories).
-With match string, find files that match given string in directory (including
-language subdirectories). Alias -f, --glob, -G
+<dt><b>--find [optional
+&nbsp;string &nbsp;part &nbsp;of &nbsp;filename]</b> </dt>
+<dd>without match string, glob all .sst .ssm files in
+directory (including language subdirectories). With match string, find files
+that match given string in directory (including language subdirectories).
+Alias -f, --glob, -G
 <p> </dd>
 
 <dt><b>-F [--webserv=webrick]</b> </dt>
 <dd>see --sample-search-form
-
 <p> </dd>
 
-<dt><b>-f [optional &nbsp;string &nbsp;part &nbsp;of &nbsp;filename]</b> </dt>
+<dt><b>-f [optional
+&nbsp;string &nbsp;part &nbsp;of &nbsp;filename]</b> </dt>
 <dd>see --find
 <p> </dd>
 
-<dt><b>--git [filename/wildcard]</b>
-</dt>
-<dd>produces or updates markup source file structure in a git repo (experimental
-and subject to change). Alias -g
+<dt><b>--git [filename/wildcard]</b> </dt>
+<dd>produces or
+updates markup source file structure in a git repo (experimental and subject
+to change). Alias -g
 <p> </dd>
 
-<dt><b>--glob [optional &nbsp;string &nbsp;part &nbsp;of &nbsp;filename]</b>
-</dt>
-<dd>
-<p>see --find
+<dt><b>--glob [optional &nbsp;string &nbsp;part &nbsp;of &nbsp;filename]</b> </dt>
+<dd>see --find
 <p> </dd>
 
-<dt><b>-G [optional &nbsp;string &nbsp;part &nbsp;of &nbsp;filename]</b> </dt>
+<dt><b>-G
+[optional &nbsp;string &nbsp;part &nbsp;of &nbsp;filename]</b> </dt>
 <dd>see --find
 <p> </dd>
 
@@ -304,19 +307,19 @@ and subject to change). Alias -g
 <p> </dd>
 
 <dt><b>--harvest *.ss[tm]</b> </dt>
-<dd>makes two lists of sisu output based on the sisu
-markup documents in a directory: list of author and authors works (year
-and titles), and; list by topic with titles and author. Makes use of header
-metadata fields (author, title, date, topic_register). Can be used with
-maintenance (-M) and remote placement (-R) flags.
+<dd>makes two lists of sisu output based on the sisu markup
+documents in a directory: list of author and authors works (year and titles),
+and; list by topic with titles and author. Makes use of header metadata
+fields (author, title, date, topic_register). Can be used with maintenance
+(-M) and remote placement (-R) flags.
 <p> </dd>
 
 <dt><b>--help [topic]</b> </dt>
-<dd>provides help
-on the selected topic, where topics (keywords) include: list, (com)mands,
-short(cuts), (mod)ifiers, (env)ironment, markup, syntax, headers, headings,
-endnotes, tables, example, customise, skin, (dir)ectories, path, (lang)uage,
-db, install, setup, (conf)igure, convert, termsheet, search, sql, features,
+<dd>provides help on the selected
+topic, where topics (keywords) include: list, (com)mands, short(cuts),
+(mod)ifiers, (env)ironment, markup, syntax, headers, headings, endnotes,
+tables, example, customise, skin, (dir)ectories, path, (lang)uage, db,
+install, setup, (conf)igure, convert, termsheet, search, sql, features,
 
 <p>license
 <p> </dd>
@@ -676,7 +679,8 @@ deep document structure, in the nature of dom. Alias -X
 <p> </dd>
 
 <dt><b>-Y [filename/wildcard]</b> </dt>
-<dd>produces a short sitemap entry for the document, based on html output and the sisu_manifest.
+<dd>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 &nbsp;announcement &nbsp;this &nbsp;week])
 <p> </dd>
@@ -1486,7 +1490,7 @@ normal text &lt;<a href='http://www.sisudoc.org/'>http://www.sisudoc.org/</a>
 <b>markup example:</b>
 <p> <br>
 <pre>  normal text _http://www.sisudoc.org/ continues
-  deb http://www.jus.uio.no/sisu/archive unstable main non-free
+  deb _http://www.jus.uio.no/sisu/archive unstable main non-free
 </pre>
 <p> <br>
 <b>resulting output:</b>
@@ -1555,6 +1559,13 @@ Debian and Ruby" }http://www.sisudoc.org/
   {~^ ruby_logo.png "Ruby" }http://www.ruby-lang.org/en/
 
 
+markup example:
+  { tux.png 64x80 }image
+  % various url linked images
+  {tux.png 64x80 "a better way" }http://www.sisudoc.org/
+  {GnuDebianLinuxRubyBetterWay.png 100x101 "Way Better - with Gnu/Linux,
+Debian and Ruby" }http://www.sisudoc.org/
+  {~^ ruby_logo.png "Ruby" }http://www.ruby-lang.org/en/
 </pre>
 <p> <br>
 <b>resulting output:</b>
@@ -1634,8 +1645,8 @@ Tables</a></h2>
 320,000|  630,000
   No. of articles, all languages  |       25|   19,000|  138,000|  490,000|
 862,000|1,600,000
-  \* Contributed at least ten times; \** at least 5 times in last month;
-\*\** more than 100 times in last month.
+  * Contributed at least ten times; ** at least 5 times in last month;
+*** more than 100 times in last month.
 </pre>
 <p> <br>
 <b>resulting output:</b>
@@ -2148,7 +2159,7 @@ If multiple sub-terms appear under one paragraph, they are separated under
 the main term heading from each other by a pipe symbol.
 <p> <br>
 <pre>    Paragraph containing main term, second term and sub-term.
-    ={Main term:sub-term+1|second sub-term
+    ={Main term:sub-term+1|second sub-term}
     A paragraph that continues discussion of the first sub-term
 </pre>
 <p> <br>
@@ -2773,6 +2784,7 @@ CSS file that is looked for in a skin.[^18]
 structures of which there are 3 alternatives.
 <p>
 <h2><a name='sect66' href='#toc66'>17.1 Document Source Directory</a></h2>
+
 <p>
 <br>
 The document source directory is the directory in which sisu processing
@@ -2860,6 +2872,34 @@ by filetype.
 <p> <br>
 output_dir_structure_by: language
 <p> <br>
+<pre>    |-- en
+    |-- epub
+    |-- hashes
+    |-- html
+    | |-- viral_spiral.david_bollier
+    | |-- manifest
+    | |-- qrcode
+    | |-- odt
+    | |-- pdf
+    | |-- sitemaps
+    | |-- txt
+    | |-- xhtml
+    | &lsquo;-- xml
+    |-- po4a
+    | &lsquo;-- live-manual
+    |     |-- po
+    |     |-- fr
+    |     &lsquo;-- pot
+    &lsquo;-- _sisu
+        |-- css
+        |-- image
+        |-- image_sys -&gt; ../../_sisu/image_sys
+        &lsquo;-- xml
+            |-- rnc
+            |-- rng
+            &lsquo;-- xsd
+</pre>
+<p> <br>
 #by: language subject_dir/en/manifest/filename.html
 <p>
 <h2><a name='sect72' href='#toc72'>17.2.4 by Filetype</a></h2>
@@ -2874,6 +2914,33 @@ given a language extension.
 <p> <br>
 output_dir_structure_by: filetype
 <p> <br>
+<pre>    |-- epub
+    |-- hashes
+    |-- html
+    |-- viral_spiral.david_bollier
+    |-- manifest
+    |-- qrcode
+    |-- odt
+    |-- pdf
+    |-- po4a
+    |-- live-manual
+    |     |-- po
+    |     |-- fr
+    |     &lsquo;-- pot
+    |-- _sisu
+    | |-- css
+    | |-- image
+    | |-- image_sys -&gt; ../../_sisu/image_sys
+    | &lsquo;-- xml
+    |     |-- rnc
+    |     |-- rng
+    |     &lsquo;-- xsd
+    |-- sitemaps
+    |-- txt
+    |-- xhtml
+    &lsquo;-- xml
+</pre>
+<p> <br>
 #by: filetype subject_dir/html/filename/manifest.en.html
 <p>
 <h2><a name='sect73' href='#toc73'>17.2.5 by Filename</a></h2>
@@ -2888,6 +2955,26 @@ file (the different filetypes) in a common directory.
 <p> <br>
 output_dir_structure_by: filename
 <p> <br>
+<pre>    |-- epub
+    |-- po4a
+    |-- live-manual
+    |     |-- po
+    |     |-- fr
+    |     &lsquo;-- pot
+    |-- _sisu
+    | |-- css
+    | |-- image
+    | |-- image_sys -&gt; ../../_sisu/image_sys
+    | &lsquo;-- xml
+    |     |-- rnc
+    |     |-- rng
+    |     &lsquo;-- xsd
+    |-- sitemaps
+    |-- src
+    |-- pod
+    &lsquo;-- viral_spiral.david_bollier
+</pre>
+<p> <br>
 #by: filename subject_dir/filename/manifest.en.html
 <p>
 <h2><a name='sect74' href='#toc74'>17.2.6 Remote Directories</a></h2>
diff --git a/man/man1/sisu.1 b/man/man1/sisu.1
index 9a3e5535..1d4d280b 100644
--- a/man/man1/sisu.1
+++ b/man/man1/sisu.1
@@ -1,4 +1,4 @@
-.TH "sisu" "1" "2011-10-03" "3.1.0" "SiSU"
+.TH "sisu" "1" "2011-12-08" "3.1.7" "SiSU"
 .br
 .SH NAME
 .br
@@ -221,13 +221,22 @@ be with colour, if sisurc colour default is set to 'false' or is undefined
 screen output will be without colour). Alias \-c
 
 .TP
+.B \-\-configure
+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 \-\-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
 
 .TP
-.B \-C [\-\-init\-site]
+.B \-C
 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
@@ -237,12 +246,7 @@ 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.
+see \-\-configure
 
 .TP
 .B \-c [filename/wildcard]
@@ -1520,7 +1524,7 @@ An escaped url without decoration
 
 .nf
   normal text _http://www.sisudoc.org/ continues
-  deb http://www.jus.uio.no/sisu/archive unstable main non\-free
+  deb _http://www.jus.uio.no/sisu/archive unstable main non\-free
 .fi
 
 .br
@@ -1597,6 +1601,14 @@ about SiSU <http://www.sisudoc.org/> [^14] markup
   {~^ ruby_logo.png "Ruby" }http://www.ruby\-lang.org/en/
 .br
 .br
+.B markup example:
+
+.nf
+  { tux.png 64x80 }image
+  % various url linked images
+  {tux.png 64x80 "a better way" }http://www.sisudoc.org/
+  {GnuDebianLinuxRubyBetterWay.png 100x101 "Way Better \- with Gnu/Linux, Debian and Ruby" }http://www.sisudoc.org/
+  {~^ ruby_logo.png "Ruby" }http://www.ruby\-lang.org/en/
 .fi
 
 .br
@@ -1677,7 +1689,7 @@ information in each column
   Very active contributors***     |        0|       31|      190|      692|    1,639|    3,016
   No. of English language articles|       25|   16,000|  101,000|  190,000|  320,000|  630,000
   No. of articles, all languages  |       25|   19,000|  138,000|  490,000|  862,000|1,600,000
-  \e* Contributed at least ten times; \e** at least 5 times in last month; \e*\e** more than 100 times in last month.
+  * Contributed at least ten times; ** at least 5 times in last month; *** more than 100 times in last month.
 .fi
 
 .br
@@ -2223,7 +2235,7 @@ main term heading from each other by a pipe symbol.
 
 .nf
     Paragraph containing main term, second term and sub\-term.
-    ={Main term:sub\-term+1|second sub\-term
+    ={Main term:sub\-term+1|second sub\-term}
     A paragraph that continues discussion of the first sub\-term
 .fi
 
@@ -3076,6 +3088,35 @@ Its selection is configured in sisurc.yml
 .br
 output_dir_structure_by: language
 
+.nf
+    |\-\- en
+    |\-\- epub
+    |\-\- hashes
+    |\-\- html
+    | |\-\- viral_spiral.david_bollier
+    | |\-\- manifest
+    | |\-\- qrcode
+    | |\-\- odt
+    | |\-\- pdf
+    | |\-\- sitemaps
+    | |\-\- txt
+    | |\-\- xhtml
+    | `\-\- xml
+    |\-\- po4a
+    | `\-\- live\-manual
+    |     |\-\- po
+    |     |\-\- fr
+    |     `\-\- pot
+    `\-\- _sisu
+        |\-\- css
+        |\-\- image
+        |\-\- image_sys \-> \../../_sisu/image_sys
+        `\-\- xml
+            |\-\- rnc
+            |\-\- rng
+            `\-\- xsd
+.fi
+
 .br
 #by: language subject_dir/en/manifest/filename.html
 
@@ -3092,6 +3133,34 @@ Its selection is configured in sisurc.yml
 .br
 output_dir_structure_by: filetype
 
+.nf
+    |\-\- epub
+    |\-\- hashes
+    |\-\- html
+    |\-\- viral_spiral.david_bollier
+    |\-\- manifest
+    |\-\- qrcode
+    |\-\- odt
+    |\-\- pdf
+    |\-\- po4a
+    |\-\- live\-manual
+    |     |\-\- po
+    |     |\-\- fr
+    |     `\-\- pot
+    |\-\- _sisu
+    | |\-\- css
+    | |\-\- image
+    | |\-\- image_sys \-> \../../_sisu/image_sys
+    | `\-\- xml
+    |     |\-\- rnc
+    |     |\-\- rng
+    |     `\-\- xsd
+    |\-\- sitemaps
+    |\-\- txt
+    |\-\- xhtml
+    `\-\- xml
+.fi
+
 .br
 #by: filetype subject_dir/html/filename/manifest.en.html
 
@@ -3107,6 +3176,27 @@ Its selection is configured in sisurc.yml
 .br
 output_dir_structure_by: filename
 
+.nf
+    |\-\- epub
+    |\-\- po4a
+    |\-\- live\-manual
+    |     |\-\- po
+    |     |\-\- fr
+    |     `\-\- pot
+    |\-\- _sisu
+    | |\-\- css
+    | |\-\- image
+    | |\-\- image_sys \-> \../../_sisu/image_sys
+    | `\-\- xml
+    |     |\-\- rnc
+    |     |\-\- rng
+    |     `\-\- xsd
+    |\-\- sitemaps
+    |\-\- src
+    |\-\- pod
+    `\-\- viral_spiral.david_bollier
+.fi
+
 .br
 #by: filename subject_dir/filename/manifest.en.html