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

2 files changed, 153 insertions, 63 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>