manpage, help include: sisu --harvest *.ss[tm]

4 files changed, 152 insertions, 117 deletions

diff --git a/data/doc/sisu/html/sisu.1.html b/data/doc/sisu/html/sisu.1.html
index 25b6e7e4..faf8069c 100644
--- a/data/doc/sisu/html/sisu.1.html
+++ b/data/doc/sisu/html/sisu.1.html
@@ -440,102 +440,114 @@ combination of -[mMvVq]), will remove the related document output directory.
 <dd>produces php (zend) [this &nbsp;feature &nbsp;is &nbsp;disabled &nbsp;for
 &nbsp;the &nbsp;time  being] 
 <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. 
+<p> </dd>
 </dl>
-3. COMMAND LINE MODIFIERS  
+3. COMMAND
+LINE MODIFIERS  
 <p> 
 <dl>
 
 <dt><b>--no-ocn</b> </dt>
-<dd>[with &nbsp;-h &nbsp;-H &nbsp;or &nbsp;-p] switches
-off object citation numbering. Produce output without identifying numbers
-in margins of html or LaTeX/pdf output. 
+<dd>[with &nbsp;-h &nbsp;-H &nbsp;or &nbsp;-p] switches off object citation numbering.
+Produce output without identifying numbers in margins of html or LaTeX/pdf
+output. 
 <p> </dd>
 
 <dt><b>--no-annotate</b> </dt>
-<dd>strips output text of
-editor endnotes[^*1] denoted by asterisk or dagger/plus sign 
+<dd>strips output text of editor endnotes[^*1] denoted by
+
+<p>asterisk or dagger/plus sign 
 <p> </dd>
 
-<dt><b>--no-asterisk</b>
-</dt>
-<dd>strips output text of editor endnotes[^*2] denoted by asterisk sign 
+<dt><b>--no-asterisk</b> </dt>
+<dd>strips output text of editor endnotes[^*2]
+
+<p>denoted by asterisk sign 
 <p> </dd>
 
-<dt><b>--no-dagger</b>
-</dt>
-<dd>strips output text of editor endnotes[^+1] denoted by dagger/plus sign 
-<p>
-</dd>
+<dt><b>--no-dagger</b> </dt>
+<dd>strips output text of editor endnotes[^+1]
+
+<p>denoted by dagger/plus sign 
+<p> </dd>
 </dl>
 4. DATABASE COMMANDS  
-<p>  dbi - database interface 
-<p>  -D or --pgsql set for postgresql
--d or --sqlite default set for sqlite -d is modifiable with --db=[database &nbsp;type
-&nbsp;(pgsql &nbsp;or &nbsp;sqlite)] 
+<p>  dbi - database interface
+
+<p>  -D or --pgsql set for postgresql -d or --sqlite default set for sqlite -d is
+modifiable with --db=[database &nbsp;type &nbsp;(pgsql &nbsp;or &nbsp;sqlite)] 
 <p> 
 <dl>
 
 <dt><b>-Dv --createall</b> </dt>
-<dd>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) [ &nbsp;-dv &nbsp;--createall sqlite &nbsp;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 &rsquo;createdb
-[database name]&rsquo; where database name would be SiSU_[present &nbsp;working &nbsp;directory
-&nbsp;name &nbsp;(without &nbsp;path)]. Please use only alphanumerics and underscores. 
+<dd>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) [ &nbsp;-dv &nbsp;--createall sqlite &nbsp;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 &rsquo;createdb [database name]&rsquo; where database name would
+be SiSU_[present &nbsp;working &nbsp;directory &nbsp;name &nbsp;(without &nbsp;path)]. Please use only
+alphanumerics and underscores. 
 <p> </dd>
 
-<dt><b>-Dv
---import</b> </dt>
-<dd>[filename/wildcard] imports data specified to postgresql db (rb.dbi)
-[ &nbsp;-dv &nbsp;--import &nbsp;sqlite &nbsp;equivalent] 
+<dt><b>-Dv --import</b> </dt>
+<dd>[filename/wildcard] imports data
+specified to postgresql db (rb.dbi) [ &nbsp;-dv &nbsp;--import &nbsp;sqlite &nbsp;equivalent] 
 <p> </dd>
 
-<dt><b>-Dv --update</b> </dt>
-<dd>[filename/wildcard] updates/imports
-specified data to postgresql db (rb.dbi) [ &nbsp;-dv &nbsp;--update &nbsp;sqlite &nbsp;equivalent]
-
+<dt><b>-Dv --update</b>
+</dt>
+<dd>[filename/wildcard] updates/imports specified data to postgresql db (rb.dbi)
+[ &nbsp;-dv &nbsp;--update &nbsp;sqlite &nbsp;equivalent] 
 <p> </dd>
 
 <dt><b>-D --remove</b> </dt>
-<dd>[filename/wildcard] removes specified data to postgresql db (rb.dbi)
-[ &nbsp;-d &nbsp;--remove &nbsp;sqlite &nbsp;equivalent] 
+<dd>[filename/wildcard] removes specified
+data to postgresql db (rb.dbi) [ &nbsp;-d &nbsp;--remove &nbsp;sqlite &nbsp;equivalent] 
 <p> </dd>
 
-<dt><b>-D --dropall</b> </dt>
-<dd>kills data --dropall &nbsp;sqlite &nbsp;equivalent]
+<dt><b>-D --dropall</b>
+</dt>
+<dd>kills data --dropall &nbsp;sqlite &nbsp;equivalent] 
+<p>  The v in e.g. -Dv is for verbose output.
 
-<p>  The v in e.g. -Dv is for verbose output. 
 <p> </dd>
 </dl>
-5. SHORTCUTS, SHORTHAND FOR MULTIPLE
-FLAGS  
+5. SHORTCUTS, SHORTHAND FOR MULTIPLE FLAGS  
 <p> 
 <dl>
 
-<dt><b>--update [filename/wildcard]</b> </dt>
-<dd>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. 
+<dt><b>--update [filename/wildcard]</b>
+</dt>
+<dd>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. 
 <p> </dd>
 
 <dt><b>-0 to -5 [filename &nbsp;or &nbsp;wildcard]</b> </dt>
-<dd>Default
-shorthand mappings (note that the defaults can be changed/configured in
-the sisurc.yml file): 
+<dd>Default shorthand mappings (note that
+the defaults can be changed/configured in the sisurc.yml file): 
 <p> </dd>
 
 <dt><b>-0</b> </dt>
-<dd>-mNhwpAobxXyYv [this &nbsp;is &nbsp;the &nbsp;default &nbsp;action &nbsp;run &nbsp;when
-&nbsp;no &nbsp;i.e. &nbsp;on &nbsp;&rsquo;sisu &nbsp;[filename]&rsquo;] 
+<dd>-mNhwpAobxXyYv
+[this &nbsp;is &nbsp;the &nbsp;default &nbsp;action &nbsp;run &nbsp;when &nbsp;no &nbsp;i.e. &nbsp;on &nbsp;&rsquo;sisu &nbsp;[filename]&rsquo;] 
 <p> </dd>
 
 <dt><b>-1</b> </dt>
-<dd>-mNHwpy 
+<dd>-mNHwpy
+
 <p> </dd>
 
 <dt><b>-2</b> </dt>
@@ -547,33 +559,31 @@ the sisurc.yml file):
 <p> </dd>
 
 <dt><b>-4</b> </dt>
-<dd>-mNhwpAobxXDyY
-
-<p>-
-<p>-
-<p>import 
+<dd>-mNhwpAobxXDyY --import 
 <p> </dd>
 
 <dt><b>-5</b> </dt>
-<dd>-mNhwpAobxXDyY --update 
-<p>  add -v for verbose mode and -c for color,
-e.g. sisu -2vc [filename &nbsp;or 
-<p>  consider -u for appended url info or -v for verbose
+<dd>-mNhwpAobxXDyY --update
 
-<p>output 
+<p>  add -v for verbose mode and -c for color, e.g. sisu -2vc [filename &nbsp;or 
+<p>  consider
+
+<p>-
+<p>u for appended url info or -v for verbose output 
 <p> </dd>
 </dl>
-5.1 COMMAND LINE WITH FLAGS - BATCH PROCESSING 
-<p>  In the data directory
-run sisu -mh filename or wildcard eg. cisg.sst documents. 
-<p>  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. 
-<p> 6. HELP
- 
+5.1 COMMAND LINE WITH FLAGS
+- BATCH PROCESSING 
+<p>  In the data directory run sisu -mh filename or wildcard
+eg. cisg.sst documents. 
+<p>  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. 
+<p> 6. HELP  
 <p> 6.1 SISU MANUAL 
-<p>  The most up to date information on sisu should be contained
-in the sisu_manual, available at: 
+<p>  The most
+up to date information on sisu should be contained in the sisu_manual,
+available at: 
 <p>    &lt;<a href='http://sisudoc.org/sisu/sisu_manual/'>http://sisudoc.org/sisu/sisu_manual/</a>
 &gt;<br>
  
@@ -743,8 +753,7 @@ one (without the comments):
   @title: SiSU
   @subtitle: Markup
   @creator: Amissah, Ralph
-  % note formatting on author / creator field, surname comma then other
-names, if more than one author separate using semi-colon
+  % note formatting rules on author / creator field,
   @rights: Copyright (C) Ralph Amissah 2007, part of SiSU documentation,
 License GPL 3
   @type: information
@@ -3241,47 +3250,47 @@ html pages[^28]
 <p>  <b>Dublin Core</b> (DC) 
 <p>  <i>DC</i> tags included with this document are provided here.
 
-<p> DC Title: <i>SiSU</i> - Manual 
-<p> DC Creator: <i>Ralph</i> Amissah 
-<p> DC Rights: 3 
-<p>  DC Type:
+<p> Title: <i>SiSU</i> - Manual 
+<p> Creator: <i>Ralph</i> Amissah 
+<p> Rights: <i>Copyright</i> (C) Ralph
+Amissah 2008, part of SiSU documentation, License GPL 3 
+<p>  Type: <i>information</i>
 
-<p><i>information</i> 
-<p>  DC Date created: <i>2002-08-28</i> 
-<p>  DC Date issued: <i>2002-08-28</i> 
-<p>  DC
-Date available: <i>2002-08-28</i> 
-<p>  DC Date modified: <i>2008-05-22</i> 
-<p>  DC Date: <i>2008-05-22</i>
+<p>  Date created: <i>2002-08-28</i> 
+<p>  Date issued: <i>2002-08-28</i> 
+<p>  Date available: <i>2002-08-28</i>
 
+<p>  Date modified: <i>2008-12-16</i> 
+<p>  Date: <i>2008-12-16</i> 
+<p> 
 <p>  <b>Version Information</b> 
-<p>  Sourcefile: <i>sisu.ssm.sst</i> 
-<p>  Filetype: <i>SiSU</i> text insert
+<p>  Sourcefile:
 
-<p>0.67 
-<p>  Sourcefile Digest, MD5(sisu.ssm.sst)= <i>7fbab3b7c0fd0ed2e128585c2982c5c8</i>
+<p><i>sisu.ssm.sst</i> 
+<p>  Filetype: <i>SiSU</i> text insert 0.67 
+<p>  Sourcefile Digest, MD5(sisu.ssm.sst)=
 
-<p>  Skin_Digest: MD5(skin_sisu_manual.rb)= <i>072b2584bedea82ea8a416587b9fa244</i>
+<p><i>96d1e268b43e0430a2720e67a5876e5e</i> 
+<p>  Skin_Digest: MD5(skin_sisu_manual.rb)=
 
+<p><i>072b2584bedea82ea8a416587b9fa244</i> 
 <p>  <b>Generated</b> 
-<p>  Document (metaverse) last generated: <i>Mon</i> Jul 21 02:54:34
+<p>  Document (metaverse) last
+generated: <i>Tue</i> Dec 16 00:16:50 -0500 2008 
+<p>  Generated by: <i>SiSU</i> <i>0.70.2</i> of 2008w50/2
+(2008-12-16) 
+<p>  Ruby version: <i>ruby</i> 1.8.7 (2008-08-11 patchlevel 72) &nbsp;[i486-linux]
 
-<p>-
-<p>0400 2008 
-<p>  Generated by: <i>SiSU</i> <i>0.68.0</i> of 2008w29/1 (2008-07-21) 
-<p>  Ruby version:
-<i>ruby</i> 1.8.7 (2008-06-20 patchlevel 22) &nbsp;[i486-linux] 
 <p> 
 <ol>
-<b>.</b><li>objects include: headings,
-paragraphs, verse, tables, images, but not footnotes/endnotes which are
-numbered separately and tied to the object from which they are referenced.
-</li><b>.</b><li>i.e. the html, pdf, odf outputs are each built individually and optimised
-for that form of presentation, rather than for example the html being a
-saved version of the odf, or the pdf being a saved version of the html.
-</li><b>.</b><li>the different heading levels </li><b>.</b><li>units of text, primarily paragraphs and headings,
-also any tables, poems, code-blocks </li><b>.</b><li>Specification submitted by Adobe to
-ISO to become a full open ISO specification &lt;<a href='http://www.linux-watch.com/news/NS7542722606.html'>http://www.linux-watch.com/news/NS7542722606.html</a>
+<b>.</b><li>objects include: headings, paragraphs, verse, tables, images, but not
+footnotes/endnotes which are numbered separately and tied to the object
+from which they are referenced. </li><b>.</b><li>i.e. the html, pdf, odf outputs are each built
+individually and optimised for that form of presentation, rather than for
+example the html being a saved version of the odf, or the pdf being a saved
+version of the html. </li><b>.</b><li>the different heading levels </li><b>.</b><li>units of text, primarily
+paragraphs and headings, also any tables, poems, code-blocks </li><b>.</b><li>Specification
+submitted by Adobe to ISO to become a full open ISO specification &lt;<a href='http://www.linux-watch.com/news/NS7542722606.html'>http://www.linux-watch.com/news/NS7542722606.html</a>
 &gt;
 </li><b>.</b><li>ISO/IEC 26300:2006 </dd>
 
@@ -3377,7 +3386,7 @@ of this document: </dt>
 <dt>pdf: &lt;<a href='http://www.jus.uio.no/sisu/sisu/landscape.pdf'><a href='http://www.jus.uio.no/sisu/sisu/landscape.pdf'>http://www.jus.uio.no/sisu/sisu/landscape.pdf</a>
 </a>
 &gt; </dt>
-<dd></dd>
+<dd>  </dd>
 
 <dt>at: &lt;<a href='http://www.jus.uio.no/sisu'><a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a>
 </a>
@@ -3385,15 +3394,15 @@ of this document: </dt>
 </dt>
 <dd></dd>
 
-<dt>* Generated by: SiSU 0.70.0 of 2008w48/3 (2008-12-03) </dt>
+<dt>* Generated by: SiSU 0.70.2 of 2008w50/2 (2008-12-16) </dt>
 <dd></dd>
 
 <dt>* Ruby version: ruby
 1.8.7 (2008-08-11 patchlevel 72) [i486-linux] </dt>
 <dd></dd>
 
-<dt>* Last Generated on: Tue Dec 09
-12:24:07 -0500 2008 </dt>
+<dt>* Last Generated on: Tue Dec 16
+00:16:50 -0500 2008 </dt>
 <dd></dd>
 
 <dt>* SiSU <a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a>
diff --git a/data/doc/sisu/sisu_markup_samples/sisu_manual/sisu.ssm b/data/doc/sisu/sisu_markup_samples/sisu_manual/sisu.ssm
index 9e891fcb..1d2e34c6 100644
--- a/data/doc/sisu/sisu_markup_samples/sisu_manual/sisu.ssm
+++ b/data/doc/sisu/sisu_markup_samples/sisu_manual/sisu.ssm
@@ -18,9 +18,9 @@
 
 @date.available: 2002-08-28
 
-@date.modified: 2008-12-14
+@date.modified: 2008-12-16
 
-@date: 2008-12-14
+@date: 2008-12-16
 
 @level: new=C; break=1; num_top=1
 
@@ -76,7 +76,7 @@ sisu [-CcFLSVvW]
 
 % :B~? SiSU Output and Markup Examples
 
-<< sisu_examples.sst
+<< sisu_examples.ssi
 
 << sisu_search_intro.ssi
 
diff --git a/data/doc/sisu/sisu_markup_samples/sisu_manual/sisu_commands.sst b/data/doc/sisu/sisu_markup_samples/sisu_manual/sisu_commands.sst
index d8cd48cb..4c53ac74 100644
--- a/data/doc/sisu/sisu_markup_samples/sisu_manual/sisu_commands.sst
+++ b/data/doc/sisu/sisu_markup_samples/sisu_manual/sisu_commands.sst
@@ -18,9 +18,9 @@
 
 @date.available: 2002-08-28
 
-@date.modified: 2007-09-16
+@date.modified: 2008-12-16
 
-@date: 2007-09-16
+@date: 2008-12-16
 
 @level: new=C; break=1; num_top=1
 
@@ -189,6 +189,9 @@ Zap, if used with other processing flags deletes output files of the type about
 !_ -z [filename/wildcard] <br>
 produces php (zend) [this feature is disabled for the time being]
 
+!_ --harvest *.ss[tm] <br>
+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.
+
 1~command_modifiers command line modifiers
 
 !_ --no-ocn <br>
@@ -203,6 +206,7 @@ strips output text of editor endnotes~[* square brackets ]~ denoted by asterisk
 !_ --no-dagger <br>
 strips output text of editor endnotes~[+ square brackets ]~ denoted by dagger/plus sign
 
+
 1~commands_database database commands
 
 dbi - database interface
@@ -228,7 +232,6 @@ The v in e.g. -Dv is for verbose output.
 
 1~command_shorcuts Shortcuts, Shorthand for multiple flags
 
-
 !_ --update [filename/wildcard] <br>
 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.
 
diff --git a/data/doc/sisu/sisu_markup_samples/sisu_manual/sisu_examples.ssi b/data/doc/sisu/sisu_markup_samples/sisu_manual/sisu_examples.ssi
new file mode 100644
index 00000000..06f1ec23
--- /dev/null
+++ b/data/doc/sisu/sisu_markup_samples/sisu_manual/sisu_examples.ssi
@@ -0,0 +1,23 @@
+% SiSU 0.57
+
+@title: SiSU
+
+@subtitle: Markup Samples, Output Examples
+
+@creator: Ralph Amissah
+
+@rights: Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL 3
+
+:A~? @title @creator
+
+:B~? SiSU Markup and Output Examples
+
+1~examples Markup and Output Examples
+
+2~ Markup examples *~markup
+
+Current markup examples and document output samples are provided at http://www.jus.uio.no/sisu/SiSU/examples.html
+
+Some markup with syntax highlighting may be found under http://www.jus.uio.no/sisu/sample/syntax but is not as up to date.
+
+For some documents hardly any markup at all is required at all, other than a header, and an indication that the levels to be taken into account by the program in generating its output are.