v4: documentation; markup samples & help

2 files changed, 153 insertions, 188 deletions

diff --git a/lib/sisu/v4/help.rb b/lib/sisu/v4/help.rb
index 0ab87fdd..391e722d 100644
--- a/lib/sisu/v4/help.rb
+++ b/lib/sisu/v4/help.rb
@@ -158,7 +158,7 @@ module SiSU_Help
       end
     end
     def summary
-      print <<WOK
+      print <<-WOK
     SiSU, Copyright (C) 1997 - 2012 Ralph Amissah
     License GPL version 3 or Later. This program comes with ABSOLUTELY NO WARRANTY;
     This is free software, and you are welcome to redistribute it under the conditions of the GPL3 or later.
@@ -192,11 +192,10 @@ alternatively typing #{@cX.orange}sisu --help#{@cX.off} #{@cX.green}[keyword]#{@
       #{@cX.green}license#{@cX.off}        sisu --help license
 
 for help type 'sisu --help', 'sisu --help [help request]', 'man sisu', (or see the system or online documentation)
-WOK
-     # #{@cX.cyan}sisu_convert#{@cX.off}   program for initial (very basic and partial) conversion to sisu file format (html and word97 supported)
+     WOK
   end
   def abstract
-    print <<WOK
+    print <<-WOK
 Features:
 #{@cX.cyan}(i)#{@cX.off} minimal markup requirement
 #{@cX.cyan}(ii)#{@cX.off} single file marked up for multiple outputs
@@ -224,27 +223,18 @@ SiSU was developed in relation to legal documents, and so is strong across a wid
 There is more detailed information available on it from:
   #{@cX.blue}http://www.jus.uio.no/sisu#{@cX.off}
  *  plaintext
- *  html
+ *  HTML
+ *  ODT (Open Document Format text)
+ *  EPUB
  *  XML (structured)
- *  LaTeX/pdf
- *  texinfo
- *  sql (at present postgresql & sqlite)
-
-A couple of sample inputs and outputs:
-
-The markup for "War and Peace" (chosen because it is a large text & to test the use of SiSU on Project Gutenberg's plaintext), this is the markup, very little after the headers (there is an insert of their legal notices). Took no time at all, it is a particularly simple text to markup though
-A simple document                                                              and a more demanding document
-         #{@cX.blue}http://www.jus.uio.no/sisu/sample/war.and.peace.leo.tolstoy.er20      http://www.jus.uio.no/sisu/sample/autonomy.markup1.er30#{@cX.off}
-Some resulting outputs:
-  html   #{@cX.blue}http://www.jus.uio.no/sisu/war.and.peace.leo.tolstoy/                 http://www.jus.uio.no/sisu/autonomy.markup1/#{@cX.off}
-                                                                               #{@cX.blue}http://www.jus.uio.no/sisu/autonomy.markup1/doc#{@cX.off}
-  pdf    #{@cX.blue}http://www.jus.uio.no/sisu/war.and.peace.leo.tolstoy/portrait         http://www.jus.uio.no/sisu/autonomy.markup1/portrait
-         #{@cX.blue}http://www.jus.uio.no/sisu/war.and.peace.leo.tolstoy/landscape        http://www.jus.uio.no/sisu/autonomy.markup1/landscape#{@cX.off}
-  plaintext  #{@cX.blue}http://www.jus.uio.no/sisu/war.and.peace.leo.tolstoy/doc.txt          http://www.jus.uio.no/sisu/autonomy.markup1/doc.txt#{@cX.off}
-WOK
+ *  LaTeX
+ *  PDF (via LaTeX)
+ *  TeXinfo
+ *  SQL (at postgreSQL & SQLite)
+      WOK
     end
     def commands
-      print <<WOK
+      print <<-WOK
 
  #{@cX.ruby}-a#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces plaintext with Unix linefeeds. Without markup, (object numbers are omitted), has footnotes at end of each para‐ graph that contains them. Modifier options available: --footnotes (default) or --endnotes and for linefeeds --unix (default) or --msdos
 
@@ -333,11 +323,11 @@ WOK
  #{@cX.ruby}-D#{@cX.off} #{@cX.ruby}--recreate#{@cX.off} kills data" and drops (postgresql or sqlite) db, tables & indexes, then creates an empty db with tables and indexes [#{@cX.ruby}-d --recreate#{@cX.off} sqlite equivalent]
 
   also see command #{@cX.green}shortcuts#{@cX.off}, and shorthand mappings for multiple flags
-WOK
+      WOK
     end
     def shortcuts
       cf_defaults=SiSU_Env::InfoProcessingFlag.new
-      print <<WOK
+      print <<-WOK
 
  #{@cX.ruby}Shorthand for multiple flags#{@cX.off}
 
@@ -358,11 +348,10 @@ WOK
   defaults may be changed in active sisurc.yml file under 'flag:'
 
        add -v for verbose mode and -c (color toggle), e.g.
-       sisu -2vc [filename  or  wildcard]
-WOK
+      WOK
     end
     def modifiers
-      print <<WOK
+      print <<-WOK
 
  #{@cX.ruby}Command flag modifiers#{@cX.off}
 
@@ -374,10 +363,10 @@ WOK
 
   #{@cX.ruby}--no-dagger#{@cX.off} strips output text of editor endnotes~[+ square brackets ]~ denoted by dagger/plus sign
 
-WOK
+      WOK
     end
     def misc
-      <<WOK
+      <<-WOK
   #{@cX.cyan}misc#{@cX.off}
   #{@cX.green}-s#{@cX.off} [filename or wildcard]          #{@cX.green}spellcheck#{@cX.off} (aspell previously ispell
   \t#{@cX.green}mailer examples#{@cX.off}
@@ -389,15 +378,15 @@ WOK
   #{@cX.blue}-R #{@cX.off} (yaml|rss)  extraction of semantic data into yaml file for auto build of xml feeds (rss, rdf) #{@cX.fuschia}[work area]#{@cX.off}
   #{@cX.green}-R #{@cX.off} yaml  extraction of semantic data into yaml file for auto build of xml feeds (rss, rdf)
   #{@cX.green}-R #{@cX.off} rss   creates rss2.0 feed
-WOK
+      WOK
     end
     def markup
-      print <<WOK
+      print <<-WOK
 sisu
   Note: files for SiSU should be in UTF-8 character encoding.
 
   #{@cX.cyan}Data text markup#{@cX.off} (alternative to available html subset)
-  #{@cX.green}% SiSU 2.00#{@cX.off}          [statement on first line of document, declared file-type identifier, SiSU markup document, markup used is version 0.38]
+  #{@cX.green}% SiSU 4.00#{@cX.off}          [statement on first line of document, declared file-type identifier, SiSU markup document
 
   #{@cX.green}A~#{@cX.off} heading/title    [levels A to C available (and beneath that 1 to 6)]
 
@@ -514,16 +503,14 @@ sisu
     general text markup: headings; endnotes; tables (which also includes a note on preformatted text)
   configuration and customisation
     document or site wide customisation: customise; skin
-WOK
+      WOK
       help_markup
-#  {../_sisu/image/tux.png http://www.jus.uio.no/sisu/ w=64 c=\"a better way\" }:image        depreciated image eg
-#  <!image http://www.jus.uio.no/sisu/ ../_sisu/image/tux.png  width=\"64\" height=\"80\" !>   old form
     end
     def example
       help_markup
     end
     def example_v1
-      print <<WOK
+      print <<-WOK
 % SiSU 1.0
 
 @title: Working Sample Document
@@ -563,11 +550,11 @@ _1 for a listing type: sisu ~ commands
 _1 for an outline of sisu markup type: sisu ~ markup
 
 The example ends here.
-WOK
+    WOK
     help_markup
   end
     def example_v2
-      print <<WOK
+      print <<-WOK
 % SiSU 2.0
 
 @title: Working Sample Document
@@ -611,11 +598,11 @@ _1 for a listing type: sisu ~ commands
 _1 for an outline of sisu markup type: sisu ~ markup
 
 The example ends here.
-WOK
+    WOK
     help_markup
   end
   def headers
-    print <<WOK
+    print <<-WOK
 Header tags appear at the beginning of a document and provide meta information on the document (such as the Dublin Core), or information as to how the document as a whole is to be processed.
 All header instructions take either the form #{@cX.green}@headername:#{@cX.off} followed on the next line by an indented sub-category header if any #{@cX.green}:sub-headername:#{@cX.off}.
 #{@cX.green}@indentifier:#{@cX.off} information or instructions
@@ -648,12 +635,10 @@ where the #{@cX.green}"identifier"#{@cX.off} is a tag recognised by the program,
   #{@cX.cyan}:topic_register:#{@cX.off} [e.g.:] text markup language; application:text processing;output:html|xml|latex|pdf|sql
   #{@cX.cyan}:subject:#{@cX.off} (whatever your subject)
   #{@cX.cyan}:keywords:#{@cX.off}
-  #{@cX.cyan}:coverage:#{@cX.off}
-  #{@cX.cyan}:relation:#{@cX.off}
-  #{@cX.cyan}:type:#{@cX.off}
-  #{@cX.cyan}:identifier:#{@cX.off}
   #{@cX.cyan}:loc:#{@cX.off} [Library of Congress classification]
   #{@cX.cyan}:dewey:#{@cX.off} [Dewey classification]
+
+#{@cX.ruby}@identifier:#{@cX.off}
   #{@cX.cyan}:isbn:#{@cX.off}
   #{@cX.cyan}:oclc:#{@cX.off}
 
@@ -661,7 +646,12 @@ where the #{@cX.green}"identifier"#{@cX.off} is a tag recognised by the program,
   #{@cX.cyan}:description:#{@cX.off}
   #{@cX.cyan}:abstract:#{@cX.off}
   #{@cX.cyan}:comment:#{@cX.off}
+  #{@cX.cyan}:coverage:#{@cX.off}
+  #{@cX.cyan}:relation:#{@cX.off}
+  #{@cX.cyan}:source:#{@cX.off}
   #{@cX.cyan}:history:#{@cX.off}
+  #{@cX.cyan}:type:#{@cX.off}
+  #{@cX.cyan}:format:#{@cX.off}
   #{@cX.cyan}:prefix:#{@cX.off}
   #{@cX.cyan}:suffix:#{@cX.off}
 
@@ -680,6 +670,9 @@ original language in which the work was published
   #{@cX.cyan}:breaks:#{@cX.off} new=:B; break=1
   #{@cX.cyan}:bold:#{@cX.off} [regular expression of words/phrases to be made bold]
   #{@cX.cyan}:italics:#{@cX.off} [regular expression of words/phrases to italize]
+  #{@cX.cyan}:home_button_image:#{@cX.off} {free_as_in_freedom.png }http://stallman.org/
+  #{@cX.cyan}:home_button_text:#{@cX.off} {Free Culture}http://www.free-culture.cc; {Lawrence Lessig}http://www.lessig.org
+  #{@cX.cyan}:footer:#{@cX.off} {Free Culture}http://www.free-culture.cc; {Lawrence Lessig}http://www.lessig.org
   #{@cX.cyan}:headings:#{@cX.off} PART; CHAPTER; Section; Article;
      #{@cX.grey}% optional, document structure can be defined by words to match or regular expression (the regular expression is assumed to start at the beginning of a line of text i.e. ^) default markers A~ to C~ and 1~ to 6~ can be used within text instead, without this header tag, and may be used to supplement the instructions provided in this header tag if provided#{@cX.off}
   #{@cX.cyan}:papersize:#{@cX.off} (A4|US_letter|book_B5|book_A5|US_legal)
@@ -700,11 +693,11 @@ original language in which the work was published
 
 #{@cX.blue}3~#{@cX.off} Third level heading preceding substantive text of document, that would normally be marked 1.1.1 or 1.1.2 or 1.2.1 or  2.1.1 etc. in a document
 
-WOK
+      WOK
       help_markup
     end
     def customise
-      print <<WOK
+      print <<-WOK
     There are a number of files that control the appearance of a site or a document i.e.
 
     #{@cX.blue}(i)#{@cX.off} files that control #{@cX.green}site-wide appearance#{@cX.off}:
@@ -735,21 +728,21 @@ WOK
           if you have a body of documents the easiest way to give them a particular appearance/skin, is to associate that directory with a skin, all files in that directory take on the specified appearance, changing appearance of documents once directories are set up is as simple as copying the files from one directory to another (or renaming the directory); or associating the directory with a different skin.
 
     see also directories
-WOK
+      WOK
     end
     def configure
-      print <<WOK
+      print <<-WOK
       see the following topics
         install
         setup
         and note for initial configuration it is necessary to run:
           sisu -C
           (this places the default CSS files and DTDs in place)
-WOK
+      WOK
     end
     def path
       help_env
-      puts <<WOK
+      puts <<-WOK
 
 If you have problems check permissions (and if in home directory ownership).
 
@@ -791,12 +784,12 @@ If you have problems check permissions (and if in home directory ownership).
 
    See also
       sisu --help directory
-WOK
+      WOK
       help_env
     end
     def directories
       help_env
-      print <<WOK
+      print <<-WOK
 
   the directory structure used by sisu is controlled by the configuration files #{@cX.blue}sisurc.yml#{@cX.off}
 
@@ -882,7 +875,7 @@ WOK
 
  See also
     sisu --help path
-WOK
+      WOK
       help_env
     end
     def program_found?(program)
@@ -955,7 +948,7 @@ WOK
     def environment
       cf_defaults=SiSU_Env::InfoProcessingFlag.new
       sisu_version
-      x =<<WOK
+      x =<<-WOK
   #{@cX.green}current and output directories#{@cX.off}
   user:                                          #{@cX.blue}#{@env.user}#{@cX.off}
   home:                                          #{@cX.blue}#{@env.path.home}#{@cX.off}
@@ -1017,11 +1010,11 @@ WOK
                                                   (true/false defaults may be changed in active sisurc.yml file under permissions_set:)
 
 NOTE: for HELP type 'sisu --help', 'sisu --help [help request]', 'man sisu', (or see the system or online documentation)
-WOK
-print x
+      WOK
+      print x
     end
     def dublin_core
-    print <<WOK
+    print <<-WOK
 @title:
 
 @subtitle: [is added to title for purposes of Dublin Core description]
@@ -1056,10 +1049,10 @@ print x
 
 @rights:
 
-WOK
+      WOK
     end
     def headings
-      print <<WOK
+      print <<-WOK
 These are not required, a header is quicker to prepare if a documents structure can be defined by matching words or a regular expression, see headers).
 
 @structure: PART; CHAPTER; SECTION; ARTICLE; none; none;
@@ -1068,10 +1061,6 @@ structure can be defined by a match words or regular expression (the regular exp
 
 The following heading or level (structuring) defaults are available (for use instead of or together with @structure: header):
 
-  1~  2~  3~  4~  5~  6~
-
-or, [0.38]
-
   A~  B~  C~  1~  2~  3~
 
 Heading tags take either of the forms above, ranging from 1-6
@@ -1084,26 +1073,6 @@ segments (in html output) are by default created on level 4
 assigned a file name automatically according to the title number,
 unless you explicitly specify otherwise)
 
-eg.
-
-% SiSU 0.16 - 0.37
-
-1~ Document Title
-
-2~ Document Subtitle whatever it is
-
-3~ Part
-
-4~ Chapter
-
-5~ Heading
-
-6~ sub-heading
-
-in the 0.38 notation this maps to:
-
-% SiSU 0.38
-
 A~ Document Title
 
 B~ Document Subtitle whatever it is
@@ -1116,8 +1085,6 @@ C~ Part
 
 3~ sub-heading
 
-(a conversion script provided in sisu-examples, modify.rb makes conversion between 0.37 and 0.38 markup simple)
-
 Normal text would follow each heading level as appropriate, though it is most usual to start with ordinary writing beneath level 4 as it is at this level that segments are created.
 
 Automatic numbering of paragraphs is usually set to start at level 4 trough level 6 and takes the form 1. then 1.1 then 1.1.1 this being given as a Header tag 0~ There may be up to 6 levels in a document,
@@ -1131,13 +1098,13 @@ the words can be used to identify the levels in a header tag:
 0~toc Part; Chapter; Section; Article; none; none
 instead of providing individual heading tags
 
-sisu structure, (0.38) alternative notation, A,B,C,1,2,3 mapping to 1,2,3,4,5,6
+sisu structure, notation, A,B,C,1,2,3
 
  SiSU has in effect two sets of levels to be considered
 
- 1-3 headings/levels, (A-C [0.38]) pre-ordinary paragraphs /pre-substantive text, and
+ A-C pre-ordinary paragraphs /pre-substantive text, and
 
- 4-6 headings/levels, (1-3 [0.38]) levels which are followed by ordinary text.
+ 1-3 levels which are followed by ordinary text.
 
  This may be conceptualised as levels A,B,C, 1,2,3, and using such letter number notation, in effect:
 
@@ -1149,7 +1116,7 @@ sisu structure, (0.38) alternative notation, A,B,C,1,2,3 mapping to 1,2,3,4,5,6
 
 on the positive side: (a) the A,B,C,1,2,3 alternative makes explicit an aspect of structuring documents in SiSU that is not otherwise obvious to the newcomer (though it appears more complicated, is more in your face and likely to be understood fairly quickly); (b) the substantive text follows levels 1,2,3 and it is 'nice' to do most work in those levels
 
-WOK
+      WOK
     end
     def languages
       lang=SiSU_i18n::Languages.new.language.table
@@ -1160,7 +1127,7 @@ WOK
           puts "#{lng[:c]}:  #{lng[:t]} (#{lng[:n]})"
         end
       end
-      puts <<WOK
+      puts <<-WOK
 
  Multi-language Document File Naming and Directory Mapping
 
@@ -1196,10 +1163,10 @@ WOK
 
   Selecting this form of filename will overide other language settings including the language header within a document.
 
-WOK
+      WOK
     end
     def endnotes
-      print <<WOK
+      print <<-WOK
 
 (1) Footnote/endnotes tags take a number of possible forms, the simplest being to embed an endnote within your text~{ this would appear as an endnote, and would have an automatically assigned number }~ Embedded endnotes~{this is an endnote}~ and at the end of the paragraph~{* an asterisk marked note }~ writing the endnote:~{another endnote}~
 
@@ -1212,10 +1179,10 @@ WOK
 
 ^~ another endnote
 
-WOK
+      WOK
     end
     def tables
-      print <<WOK
+      print <<-WOK
 
 #{@cX.green}table{ [number of columns] [column width %];[column width %]#{@cX.off}
 
@@ -1272,17 +1239,17 @@ preformatted text
 
 #{@cX.green}}code#{@cX.off}
 
-WOK
+      WOK
     end
     def modules
-      print <<WOK
+      print <<-WOK
 
       #{@cX.ruby}IGNORE#{@cX.off}
 
-WOK
+      WOK
     end
     def install                                                        #% system configuration
-      print <<WOK
+      print <<-WOK
   #{@cX.green}Install SiSU#{@cX.off}
 
   Presumably if you are reading this interactively you have a copy of SiSU already installed, nevertheless here are a few notes.
@@ -1339,10 +1306,10 @@ WOK
 
     sisu --help
 
-WOK
+      WOK
     end
     def setup
-      print <<WOK
+      print <<-WOK
 
      #{@cX.green}configuration files#{@cX.off}
      sisurc.yml used:
@@ -1363,10 +1330,10 @@ WOK
         #{@cX.blue}man 8 sisu#{@cX.off}
       and
         #{@cX.blue}http://www.jus.uio.no/sisu/SiSU#{@cX.off}
-WOK
+      WOK
     end
     def termsheet
-      print <<WOK
+      print <<-WOK
 
   #{@cX.green}sisu --termsheet [termsheetname].termsheet.rb#{@cX.off}
     will produce the collection of documents associated with [termsheetname.termsheet.rb]
@@ -1395,29 +1362,29 @@ WOK
 
   it is necessary to purge the directory ~facilityData when old files are removed
 
-WOK
+      WOK
     end
     def help_commands
-      print <<WOK
+      print <<-WOK
 
     also see:
       sisu --help commands
       man sisu
-WOK
+      WOK
     end
     def help_env
-      print <<WOK
+      print <<-WOK
 
     for sisu environment information see:
       sisu --help env
-WOK
+      WOK
     end
     def help_general
       help_env
       help_commands
     end
     def help_markup
-      print <<WOK
+      print <<-WOK
 
     for help with sisu markup see:
       sisu --help markup
@@ -1429,8 +1396,6 @@ WOK
 
       for brief descriptive summary of markup history
         sisu --query-history
-      or if for a particular version
-        sisu --query-0.38
 
       for markup:
         sisu --help example
@@ -1439,19 +1404,14 @@ WOK
         #{@cX.green}/usr/share/doc/sisu/markup-samples#{@cX.off}
       and online
         #{@cX.green}www.jus.uio.no/sisu#{@cX.off}
-WOK
+        WOK
       end
     def convert
-      print <<WOK
+      print <<-WOK
 
       for information on the markup version used within a sisu markup file:
         sisu --inspect [filename]
 
-      to convert between sst markup versions 0.37 and 0.38:
-        sisu --to-current
-        sisu --to-38  [filename/wildcard]
-        sisu --to-37  [filename/wildcard]
-
       convert an sst file with footnotes following text to (preferred) inline footnotes
         sisu --convert-footnotes  [filename/wildcard]
 
@@ -1472,50 +1432,50 @@ WOK
       to attempt to convert a kdissert (.kdi) file to sisu markup:
         sisu --from-kdi  [kdissert filename]
         (very basic and experimental)
-WOK
+      WOK
     end
     def dal
-      print <<WOK
+      print <<-WOK
 
     sisu --dal [filename/wildcard]    creates the metaverse, used by all other modules for downstream processing
     sisu -m [filename/wildcard]    creates the metaverse, used by all other modules for downstream processing
-WOK
+      WOK
       help_commands
     end
     def utf8
-      print <<WOK
+      print <<-WOK
 
       documents prepared for sisu processing should be stored in utf8
-WOK
+      WOK
     end
     def plaintext
-      print <<WOK
+      print <<-WOK
 
     sisu --txt [filename/wildcard]    plaintext with Unix linefeeds (footnotes follow paragraphs)
     sisu -t [filename/wildcard]    plaintext with Unix linefeeds (footnotes follow paragraphs)
 
-WOK
+      WOK
       help_commands
     end
     def html
-      print <<WOK
+      print <<-WOK
 
     sisu --html [filename/wildcard]    html document type suffixes included
     sisu -h [filename/wildcard]    html document type suffixes included
 
-WOK
+      WOK
       help_commands
     end
     def xhtml
-      print <<WOK
+      print <<-WOK
 
     sisu --xhtml [filename/wildcard]    xhtml document
     sisu -b [filename/wildcard]    xhtml document
-WOK
+      WOK
       help_commands
     end
     def xml
-      print <<WOK
+      print <<-WOK
 
     sisu --xml-sax [filename/wildcard]    xml document (sax type parsing)
     sisu -x [filename/wildcard]    xml document (sax type parsing)
@@ -1528,52 +1488,52 @@ WOK
 
     sisu --epub [filename/wildcard]    odt document, (epub document)
     sisu -e [filename/wildcard]    odt document, (epub document)
-WOK
+      WOK
       help_commands
     end
     def odf
-      print <<WOK
+      print <<-WOK
 
     sisu --odt [filename/wildcard]    odt document, (odf open document format)
 
     sisu -o [filename/wildcard]    odt document, (odf open document format)
-WOK
+      WOK
       help_commands
     end
     def epub
-      print <<WOK
+      print <<-WOK
 
     sisu --epub [filename/wildcard]    epub document, (open format for e-books)
     sisu -e [filename/wildcard]    epub document, (open format for e-books)
-WOK
+      WOK
       help_commands
     end
     def php
-      print <<WOK
+      print <<-WOK
 
     not supported
     [php output has been removed]
-WOK
+      WOK
       help_commands
     end
     def pdf
-      print <<WOK
+      print <<-WOK
 
     sisu --pdf [filename/wildcard]     produces pdf files from LaTeX output
     sisu -p [filename/wildcard]     produces pdf files from LaTeX output
-WOK
+      WOK
       help_commands
     end
     def latex
-      print <<WOK
+      print <<-WOK
 
     sisu --pdf [filename/wildcard]     produces pdf files from LaTeX output
     sisu -p [filename/wildcard]     produces pdf files from LaTeX output
-WOK
+      WOK
       help_commands
     end
     def texinfo
-      print <<WOK
+      print <<-WOK
 
     sisu --texinfo [filename]     produces texinfo and info files
     sisu -I [filename]     produces texinfo and info files
@@ -1587,29 +1547,29 @@ WOK
 
     and then to point at the file using
       pinfo ./[filename]
-WOK
+      WOK
       help_commands
     end
     def lout
-      print <<WOK
+      print <<-WOK
 
     sisu -l [filename/wildcard]
 
     not currently supported, revisit someday?
-WOK
+      WOK
       help_commands
     end
     def concordance
-      print <<WOK
+      print <<-WOK
 
     sisu --concordance        starts the sisu webrick server, default port 8081
     sisu --wordmap        starts the sisu webrick server, default port 8081
     sisu -W        starts the sisu webrick server, default port 8081
-WOK
+      WOK
       help_commands
     end
     def help_search
-      print <<WOK
+      print <<-WOK
 
       SiSU searches,
       depending on how you wish to implement search,
@@ -1618,10 +1578,10 @@ WOK
         sisu --help searchform    (or 'sisu --help cgi')
         sisu --help hyperestraier (or 'sisu --help est')
         sisu --help webrick
-WOK
+      WOK
     end
     def cgi
-      print <<WOK
+      print <<-WOK
 
       sisu --sample-search-form                 generates a sample search form
       sisu -F                generates a sample search form
@@ -1631,12 +1591,12 @@ WOK
       sisu -W                starts the webrick server
 
       the generated search form must be copied to the webserver directory as instructed
-WOK
+      WOK
       help_search
       help_general
     end
     def sql
-      print <<WOK
+      print <<-WOK
 
     Mappings to two databases are provided by default,
     postgresql (--pg or -D) and sqlite (--sqlite or -d),
@@ -1667,21 +1627,21 @@ WOK
    By default, [unless otherwise specified] databases are built on a directory basis, from collections of documents within that directory.
    The name of the directory you choose to work from is used as the database name,
    i.e. if you are working in a directory called #{@cX.blue}#{@env.path.home}/ebook#{@cX.off} the database #{@cX.blue}#{Db[:name_prefix]}ebook#{@cX.off} is used. [otherwise a manual mapping for the collection is necessary]
-WOK
+      WOK
       help_search
       help_general
     end
     def webrick
-      print <<WOK
+      print <<-WOK
 
     sisu --webrick  starts the sisu webrick server, default port 8081
     sisu -W         starts the sisu webrick server, default port 8081
-WOK
+      WOK
       help_commands
     end
     def hyperestraier
       out_dir='(' + `ls #{@env.path.webserv}`.split("\n").join('|') + ')'
-      print <<WOK
+      print <<-WOK
   Not tested recently, not up-to-date
 
   NOTE: The examples that follow assume that sisu output is placed in the directory
@@ -1738,10 +1698,10 @@ WOK
    and try open the url: #{@cX.blue}
      #{@env.url.webserv_host_base}/cgi-bin/estseek.cgi #{@cX.off}
 
-WOK
+      WOK
     end
     def yaml
-      print <<WOK
+      print <<-WOK
    Yaml sisurc files may be used to configure sisu, these are searched for in the following locations:
 
    under the current SiSU markup data directory: #{@cX.blue}#{Dir.pwd}/_sisu/sisurc.yml#{@cX.off}
@@ -1756,10 +1716,10 @@ WOK
 
    these may be called by the sisurc.yml, skins for document, directory or site, or from individual document headers in the header @@promo: [a commented out example header may be found in  document  sample: free_as_in_freedom.richard_stallman_cru‐ sade_for_free_software.sam_williams.sst, it calls for the specified lists in list.yml, which in turn calls the widgets named in promo.yml which are used to build content in the right pane of html output]
 
-WOK
+      WOK
     end
     def sitemap
-      print <<WOK
+      print <<-WOK
 
       SiSU sitemaps,
       an experimental feature (following g,y,m announcement to use them this week)
@@ -1769,11 +1729,11 @@ WOK
 
       to generate/update the index of sitemaps
         sisu --sitemaps
-WOK
+      WOK
     end
     def license
 
-      print <<WOK
+      print <<-WOK
 
  * License: GPL 3 or later:
 
@@ -1798,7 +1758,6 @@ WOK
    available at these locations:
      <#{@cX.blue}http://www.fsf.org/licenses/gpl.html#{@cX.off}>
      <#{@cX.blue}http://www.gnu.org/licenses/gpl.html#{@cX.off}>
-     <#{@cX.blue}http://www.jus.uio.no/sisu/gpl.fsf#{@cX.off}>
 
  * SiSU uses:
    * Standard SiSU markup syntax,
@@ -1806,20 +1765,21 @@ WOK
    * Standard SiSU object citation numbering and system
 
  * Hompages:
-   <#{@cX.blue}http://www.jus.uio.no/sisu#{@cX.off}>
    <#{@cX.blue}http://www.sisudoc.org#{@cX.off}>
+   <#{@cX.blue}http://www.jus.uio.no/sisu#{@cX.off}>
 
  * Download:
-   <#{@cX.blue}http://www.jus.uio.no/sisu/SiSU/download.html#{@cX.off}>
+   <#{@cX.blue}http://sources.sisudoc.org#{@cX.off}>
+   <#{@cX.blue}http://www.jus.uio.no/sisu/en/html/SiSU/download.html#{@cX.off}>
 
    Ralph Amissah
    <#{@cX.blue}ralph@amissah.com#{@cX.off}>
    <#{@cX.blue}ralph.amissah@gmail.com#{@cX.off}>
 
-WOK
+      WOK
     end
     def standards
-      print <<WOK
+      print <<-WOK
 
  * SiSU uses:
    *  Standard SiSU markup syntax,
@@ -1830,7 +1790,7 @@ Copyright (C) Ralph Amissah 1997, current 2012.
 All Rights Reserved.
 
 Information on these may be obtained from:
-  http://www.jus.uio.no/sisu
+  <#{@cX.blue}http://sisudoc.org#{@cX.off}>
 
 More information to be provided later.
 
@@ -1839,10 +1799,10 @@ More information to be provided later.
 * Ralph Amissah ralph@amissah.com
   Ralph Amissah ralph.amissah@gmail.com
 
-WOK
+      WOK
     end
     def conversion
-      print <<WOK
+      print <<-WOK
 sisu_convert does the initial conversion from a couple of file formats to SiSU file format, currently only html and word97
   #{@cX.cyan}sisu_convert#{@cX.off} [keyword]
   sisu [keyword]
@@ -1850,10 +1810,10 @@ sisu_convert does the initial conversion from a couple of file formats to SiSU f
   ------------------------------------------
   Preparing Documents for SiSU
     #{@cX.green}--word97#{@cX.off}       sisu --help markup     (an incomplete overview)
-WOK
+      WOK
     end
     def external_programs
-      puts <<WOK
+      puts <<-WOK
 
     external ruby programs
 
@@ -1873,10 +1833,10 @@ WOK
         #{@cX.brown}suggested/recommended#{@cX.off}
           tidy  (xml, xhtml well formed check)
           trang (relaxng, rnc to dtd conversion)
-WOK
+      WOK
     end
     def scratch
-      print <<WOK
+      print <<-WOK
 Types of tag,
 
 then there are various tags which occur within the document.
@@ -1903,7 +1863,7 @@ This makes citation a lot easier... regardless of the form of output that is bei
 It also permits the building of various addons, like the concordance feature which identifies each word and the paragraphs in which the word appears with links to the paragraph...
 
 Urls are automatically turned to live links in the html and pdf files created...
-WOK
+      WOK
     end
   end
 end
diff --git a/lib/sisu/v4/manpage.rb b/lib/sisu/v4/manpage.rb
index 4d293d92..34df23cd 100644
--- a/lib/sisu/v4/manpage.rb
+++ b/lib/sisu/v4/manpage.rb
@@ -174,21 +174,26 @@ GSUB
         @manpage[:tail] <<<<WOK
 #{@br}
 .TP
-Other versions of this document:
+.SH SEE ALSO
+       sisu(1),
+       sisu-epub(1),
+       sisu-harvest(1),
+       sisu-html(1),
+       sisu-odf(1),
+       sisu-pdf(1),
+       sisu-pg(1),
+       sisu-sqlite(1),
+       sisu-txt(1).
+       sisu_vim(7)
 .TP
-  manifest: <#{@md.file.output_path.digest.url}/#{@md.file.base_filename.digest}>
+.SH HOMEPAGE
+       More information about SiSU can be found at <http://www.sisudoc.org/> or <http://www.jus.uio.no/sisu/>
 .TP
-at: <#{vz.url_site}>
+.SH SOURCE
+       <http://sources.sisudoc.org/>
 .TP
-#{sc}
-.TP
-* #{generator}
-.TP
-* #{rubyv}
-.TP
-* #{lastdone}
-.TP
-* SiSU #{vz.url_sisu}
+.SH AUTHOR
+       SiSU is written by Ralph Amissah <ralph@amissah.com>
 WOK
       end
       def manpage_structure(dob='',hname='') #% Used to extract the structure of a document
@@ -254,10 +259,10 @@ WOK
         @data_mod,@endnotes,@level,@cont,@copen,@manpage_contents_close=Array.new(6){[]}
         (0..6).each { |x| @cont[x]=@level[x]=false }
         (4..6).each { |x| @manpage_contents_close[x]='' }
-        manpage_tail #($1,$2)
+        #manpage_tail #stop call
         table_message='[table omitted, see other document formats]'
         fix=[]
-        manpage_metadata
+        #manpage_metadata
         data.each do |dob|
           if dob.is==:comment \
           || dob.is==:heading_insert