v3: markup samples, and help, minor updates

1 files changed, 96 insertions, 107 deletions

diff --git a/lib/sisu/v3/help.rb b/lib/sisu/v3/help.rb
index 980380c3..0ab87fdd 100644
--- a/lib/sisu/v3/help.rb
+++ b/lib/sisu/v3/help.rb
@@ -397,9 +397,12 @@ 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 0.38#{@cX.off}          [statement on first line of document, declared file-type identifier, SiSU markup document, markup used is version 0.38]
-  #{@cX.green}:A~#{@cX.off} heading/title    [levels :A to :C available (and beneath that 1 to 6)]
+  #{@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}A~#{@cX.off} heading/title    [levels A to C available (and beneath that 1 to 6)]
+
   #{@cX.green}1~#{@cX.off}filename heading   [segmentation level, levels 1 to 6 available]
+
   #{@cX.green}!{#{@cX.off}emphasis#{@cX.green}}!#{@cX.off}
   #{@cX.green}*{#{@cX.off}bold text#{@cX.green}}*#{@cX.off}
   #{@cX.green}_{#{@cX.off}underscore#{@cX.green}}_#{@cX.off}
@@ -409,18 +412,28 @@ sisu
   #{@cX.green},{#{@cX.off}subscript#{@cX.green}},#{@cX.off}
   #{@cX.green}+{#{@cX.off}inserted text#{@cX.green}}+#{@cX.off}
   #{@cX.green}-{#{@cX.off}strikethrough#{@cX.green}}-#{@cX.off}
+
   ------------------------------------------
   #{@cX.cyan}Indentation and bullets#{@cX.off}
+
   #{@cX.green}_1#{@cX.off}                     indent paragraph one level
+
   #{@cX.green}_2#{@cX.off}                     indent paragraph two steps
+
   #{@cX.green}_*#{@cX.off}                     bullet text
+
   #{@cX.green}_1*#{@cX.off}                    bullet text, first indent
+
   ------------------------------------------
   #{@cX.cyan}Numbered List#{@cX.off} (not to be confused with headings/titles, (document structure))
+
   #{@cX.green}##{@cX.off} numbered list        numbered list 1., 2., 3, etc.
+
   #{@cX.green}_##{@cX.off} numbered list       numbered list indented second level a., b., c., d., etc.
+
   ------------------------------------------
   #{@cX.cyan}Endnotes#{@cX.off}
+
   #{@cX.green}~{#{@cX.off}footnote/endnote#{@cX.green}}~#{@cX.off}    endnote#{@cX.green}~{#{@cX.off}self contained endnote marker & endnote in one#{@cX.green}}~#{@cX.off}
   #{@cX.green}~{*#{@cX.off}asterisk footnote/endnote#{@cX.green}}~#{@cX.off}
   editor's annotations, square bracket notes
@@ -430,8 +443,10 @@ sisu
   alternative endnote pair notation
   #{@cX.green}~^#{@cX.off}                                           endnote marker
   #{@cX.green}^~#{@cX.off} endnote text following the paragraph in which the marker occurs
+
   ------------------------------------------
   #{@cX.cyan}Links#{@cX.off}
+
     http://url.org                           on its own would be automatically marked up and hyperlinked to itself
     #{@cX.green}{#{@cX.off} [text to link] #{@cX.green}}#{@cX.off}http://url.org
     #{@cX.green}{#{@cX.off}image.png#{@cX.green}}#{@cX.off}http://url.org
@@ -450,19 +465,24 @@ sisu
     if  a  server host name has been provided/configured, will provide a list of available output types that would be generated using the shortcut command and the markup file provided, i.e. output generated using the command (as configured):
        "sisu -3sS markup_source_filename.sst"
     using server host, directory stub, filename to compose the link.
+
   ------------------------------------------
   adding fixed names in html, manual location marker/tagging
   #{@cX.green}*~[name]#{@cX.off}           <a name="[name]">
+
   ------------------------------------------
   #{@cX.green}~##{@cX.off}         unnumbered paragraph (place marker at end of paragraph)
   #{@cX.green}-##{@cX.off}         unnumbered paragraph, delete when not required (place marker at end of paragraph) [used in dummy headings, eg. for segmented html]
+
   ------------------------------------------
   manual page breaks (LaTeX/pdf)
   #{@cX.green}<:pb>#{@cX.off}  page  break,  which  breaks a page, starting a new page in single column text and a new column in double column text
   #{@cX.green}<:pn>#{@cX.off} page new, which starts a new page, in both single and double column text (leaving an empty column in double column text if necessary).
   Note: page breaks are usually introduced to pdfs either as header instructions, indicating that pages should break at given levels
+
   ------------------------------------------
   #{@cX.cyan}Composite documents#{@cX.off}
+
     It is possible to build a document by creating a master document that requires other documents. The documents required may complete documents that could be generated independently, or they could be markup snippets, prepared so as to be easily available to be placed within another text. If the calling document is a master document (built mainly from other documents), it should be named with the suffix #{@cX.blue}.ssm#{@cX.off} Within this document you would provide information on the other documents that should be included within the text. These may be other documents that would be processed in a regular way, or markup bits prepared only for inclusion within a master document #{@cX.blue}.sst#{@cX.off} regular markup file, or #{@cX.blue}.ssi#{@cX.off} (insert/information) A secondary file of the composite document is built prior to processing with the same prefix and the suffix #{@cX.blue}.ssm.sst#{@cX.off}
 
     #{@cX.cyan}#basic sisu markup alternatives#{@cX.off}
@@ -522,9 +542,9 @@ WOK
 
 @links: { SiSU }http://www.jus.uio.no/sisu { FSF }http://www.fsf.org
 
-:A~ A Sample Document
+A~ A Sample Document
 
-:B~ just for fun
+B~ just for fun
 
 1~ This is Chapter One or Article One
 
@@ -570,9 +590,9 @@ WOK
 @links:
  { SiSU }http://www.jus.uio.no/sisu { FSF }http://www.fsf.org
 
-:A~ @title @author
+A~ @title @author
 
-:B~ just for fun
+B~ just for fun
 
 1~ This is Chapter One or Article One
 
@@ -600,109 +620,79 @@ Header tags appear at the beginning of a document and provide meta information o
 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
 where the #{@cX.green}"identifier"#{@cX.off} is a tag recognised by the program, and the #{@cX.green}"information"#{@cX.off} or #{@cX.green}"instructions"#{@cX.off} belong to the tag/indentifier specified
- Note: a header where used should only be used once; all  headers  apart from @title: are optional; the @structure: or 0~toc header is used to describe document structure, and can be useful to know.
-This is a sample header (#{@cX.fuschia}Dublin Core in fuschia,#{@cX.off} #{@cX.cyan}other information headers in cyan,#{@cX.off} #{@cX.ruby}markup instructions in red#{@cX.off}):
-
-#{@cX.fuschia}@title:#{@cX.off} My Title - This is now the Title of the Document and used as such
- #{@cX.cyan}:subtitle:#{@cX.off} The Subtitle if any
-
-#{@cX.fuschia}@creator:#{@cX.off}
- #{@cX.fuschia}:author:#{@cX.off} Surname, Other names (if more than one author separate author names with a semi colon, if name is of an institution just write name or the name contains a comma enclose in quotation marks)
-
-#{@cX.fuschia}@classify:#{@cX.off}
- #{@cX.fuschia}:topic_register:#{@cX.off} [e.g.:] text markup language; application:text processing;output:html|xml|latex|pdf|sql
-
-#{@cX.fuschia}@subject:#{@cX.off} (whatever your subject)
-
-#{@cX.fuschia}@description:#{@cX.off}
-
-#{@cX.fuschia}@publisher:#{@cX.off}
-
-#{@cX.fuschia}@contributor:#{@cX.off}
-
-#{@cX.fuschia}@translator:#{@cX.off} [or @translated_by:]
-
-#{@cX.fuschia}@illustrator:#{@cX.off} [or @illustrated_by:]
-
-#{@cX.fuschia}@prepared_by:#{@cX.off} [or @digitized_by:]
-
-#{@cX.fuschia}@date:#{@cX.off} 2000-08-27
-\t[ also #{@cX.fuschia}@date.created:#{@cX.off} #{@cX.fuschia}@date.issued:#{@cX.off} #{@cX.fuschia}@date.available:#{@cX.off} #{@cX.fuschia}@date.valid:#{@cX.off} #{@cX.fuschia}@date.modified:#{@cX.off} ]
-
-#{@cX.fuschia}@type:#{@cX.off} article
-
-#{@cX.fuschia}@format:#{@cX.off}
-
-#{@cX.fuschia}@identifier:#{@cX.off}
-
-#{@cX.fuschia}@source:#{@cX.off}
-
-#{@cX.fuschia}@language:#{@cX.off} [or @language.document:] [country code for language if available, or language, English, en is the default setting] (en - English, fr - French, de - German, it - Italian, es - Spanish, pt - Portuguese, sv - Swedish, da - Danish, fi - Finnish, no - Norwegian, is - Icelandic, nl - Dutch, et - Estonian, hu - Hungarian, pl - Polish, ro - Romanian, ru - Russian, el - Greek, uk - Ukranian, tr - Turkish, sk - Slovak, sl - Slovenian, hr - Croatian, cs - Czech, bg - Bulgarian ) [however, encodings are not available for all of the languages listed.]
-
-#{@cX.fuschia}@language.original:#{@cX.off}
+ Note: a header where used should only be used once; all  headers  apart from #{@cX.ruby}@title:#{@cX.off} are optional.
+
+#{@cX.ruby}@title:#{@cX.off} My Title - This is now the Title of the Document and used as such
+  #{@cX.cyan}:subtitle:#{@cX.off} The Subtitle if any
+
+#{@cX.ruby}@creator:#{@cX.off}
+  #{@cX.cyan}:author:#{@cX.off} Surname, Other names (if more than one author separate author names with a semi colon, if name is of an institution just write name or the name contains a comma enclose in quotation marks)
+  #{@cX.cyan}:contributor:#{@cX.off}
+  #{@cX.cyan}:translator:#{@cX.off} [or :translated_by:]
+  #{@cX.cyan}:illustrator:#{@cX.off} [or :illustrated_by:]
+  #{@cX.cyan}:prepared_by:#{@cX.off} [or :digitized_by:]
+
+#{@cX.ruby}@date:#{@cX.off}
+  #{@cX.cyan}:published:#{@cX.off}
+  #{@cX.cyan}:created:#{@cX.off}
+  #{@cX.cyan}:issued:#{@cX.off}
+  #{@cX.cyan}:available:#{@cX.off}
+  #{@cX.cyan}:valid:#{@cX.off}
+  #{@cX.cyan}:modified:#{@cX.off}
+
+#{@cX.ruby}@rights:#{@cX.off}
+  #{@cX.cyan}:copyright:#{@cX.off} Author's name, all rights reserved
+  #{@cX.cyan}:license:#{@cX.off} public domain, copyleft, creative commons variant, etc.
+
+#{@cX.ruby}@classify:#{@cX.off}
+  #{@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.cyan}:isbn:#{@cX.off}
+  #{@cX.cyan}:oclc:#{@cX.off}
+
+#{@cX.ruby}@notes:#{@cX.off}
+  #{@cX.cyan}:description:#{@cX.off}
+  #{@cX.cyan}:abstract:#{@cX.off}
+  #{@cX.cyan}:comment:#{@cX.off}
+  #{@cX.cyan}:history:#{@cX.off}
+  #{@cX.cyan}:prefix:#{@cX.off}
+  #{@cX.cyan}:suffix:#{@cX.off}
+
+#{@cX.ruby}@publisher:#{@cX.off}
+
+#{@cX.ruby}@language:#{@cX.off} [or @language.document:] [country code for language if available, or language, English, en is the default setting] (en - English, fr - French, de - German, it - Italian, es - Spanish, pt - Portuguese, sv - Swedish, da - Danish, fi - Finnish, no - Norwegian, is - Icelandic, nl - Dutch, et - Estonian, hu - Hungarian, pl - Polish, ro - Romanian, ru - Russian, el - Greek, uk - Ukranian, tr - Turkish, sk - Slovak, sl - Slovenian, hr - Croatian, cs - Czech, bg - Bulgarian ) [however, encodings are not available for all of the languages listed.]
+
+#{@cX.ruby}@language.original:#{@cX.off}
 original language in which the work was published
 
-#{@cX.fuschia}@papersize:#{@cX.off}
-(A4|US_letter|book_B5|book_A5|US_legal)
-
-#{@cX.fuschia}@relation:#{@cX.off}
-
-#{@cX.fuschia}@coverage:#{@cX.off}
-
-#{@cX.fuschia}@rights:#{@cX.off} copyright, all rights reserved, public domain, copyleft, creative commons variant, etc.
-
-#{@cX.cyan}@owner:#{@cX.off}
-
-#{@cX.cyan}@keywords:#{@cX.off} text document generation processing management latex pdf structured xml citation [your keywords here, used for example by rss feeds, and in sql searches]
-
-#{@cX.cyan}@abstract:#{@cX.off} [paper abstract, placed after table of contents]
-
-#{@cX.cyan}@comment:#{@cX.off} [...]
-
-#{@cX.cyan}@catalogue:#{@cX.off} #{@cX.green}loc=#{@cX.off}[Library  of  Congress  classification]; #{@cX.green}dewey=#{@cX.off}[Dewey classification]; #{@cX.green}isbn=#{@cX.off}[ISBN]; #{@cX.green}pg=#{@cX.off}[Project Gutenberg text number]
-
-#{@cX.cyan}@classify_loc:#{@cX.off} [Library of Congress classification]
-
-#{@cX.cyan}@classify_dewey:#{@cX.off} [Dewey classification]
-
-#{@cX.cyan}@classify_isbn:#{@cX.off} [ISBN]
-
-#{@cX.cyan}@classify_pg:#{@cX.off} [Project Gutenberg text number]
-
-#{@cX.cyan}@prefix_a:#{@cX.off} [prefix is placed just before table of contents - not implemented]
-
-#{@cX.cyan}@prefix_b:#{@cX.off} or #{@cX.cyan}@prefix:#{@cX.off} [prefix is placed just after table of contents]
-
-#{@cX.cyan}@rcs:#{@cX.off} $Id$ [used by rcs or cvs to embed version (revision control) information into document, rcs or cvs can usefully provide a history of updates to a document ]
-
-#{@cX.ruby}@structure:#{@cX.off} PART; CHAPTER; SECTION; ARTICLE; none; none;
-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 (@structure: is a synonym for @toc:)
-
-#{@cX.ruby}@level:#{@cX.off} newpage=3; breakpage=4 [paragraph level, used by latex to breakpages, the page is optional eg. in newpage]
-
-#{@cX.ruby}@markup:#{@cX.off} num_top=4 [various markup instructions, eg: num_top=4 headings tobe numbered, starting at heading level 4... the default is to provide 3 levels, as in 1 level 4, 1.1 level 5, 1.1.1 level 6, markup to be merged within level]
-
-#{@cX.ruby}@bold:#{@cX.off} [regular expression of words/phrases to be made bold]
-
-#{@cX.ruby}@italics:#{@cX.off} [regular expression of words/phrases to italize]
-
-#{@cX.ruby}@vocabulary:#{@cX.off} name of taxonomy/vocabulary/wordlist to use against document
-
-#{@cX.ruby}@skin:#{@cX.off} skin_doc_[name_of_desired_document_skin]
-
-#{@cX.ruby}@links:#{@cX.off} { SiSU }http://www.jus.uio.no/sisu/; { FSF }http://www.fsf.org
+#{@cX.ruby}@links:#{@cX.off}
+  { SiSU }http://www.jus.uio.no/sisu/
+  { FSF }http://www.fsf.org
 
-#{@cX.ruby}@@promo:#{@cX.off} sisu, ruby, search_libre_docs, open_society [places content in right pane in html, makes use of list.yml and promo.yml, commented out sample in  document  sample:  free_as_in_freedom.richard_stallman_crusade_for_free_software.sam_williams.sst]
+#{@cX.ruby}@make:#{@cX.off}
+  #{@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}: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)
+  #{@cX.cyan}:markup:#{@cX.off} num_top=4 [various markup instructions, eg: num_top=4 headings tobe numbered, starting at heading level 4... the default is to provide 3 levels, as in 1 level 4, 1.1 level 5, 1.1.1 level 6, markup to be merged within level]
+  #{@cX.cyan}:promo:#{@cX.off} sisu, ruby, search_libre_docs, open_society [places content in right pane in html, makes use of list.yml and promo.yml, commented out sample in  document  sample:  free_as_in_freedom.richard_stallman_crusade_for_free_software.sam_williams.sst]
 
 #{@cX.grey}% header ends here, NB only @title: is mandatory [this would be a comment]#{@cX.off}
-#{@cX.grey}% NOTE: headings/levels below refer to 0.38 expermental markup
-  (a conversion script provided in sisu-examples, modify.rb makes conversion between 0.37 and 0.38 markup simple)#{@cX.off}
 
-#{@cX.blue}:A~#{@cX.off} Top level heading [this is usually the same as the title @title: ]
+#{@cX.blue}A~#{@cX.off} Top level heading [this is usually the same as the title @title: ]
 
-#{@cX.blue}:B~#{@cX.off} Second level heading [this is a heading level divider]
+#{@cX.blue}B~#{@cX.off} Second level heading [this is a heading level divider]
 
-#{@cX.blue}:C~#{@cX.off} Third level heading [this is a heading level divider]
+#{@cX.blue}C~#{@cX.off} Third level heading [this is a heading level divider]
 
 #{@cX.blue}1~#{@cX.off} Top level heading preceding substantive text of document or sub-heading 5, the heading level that would normally be marked 1. or 2. or 3. etc. in a document
 
@@ -1082,7 +1072,7 @@ The following heading or level (structuring) defaults are available (for use ins
 
 or, [0.38]
 
-  :A~  :B~  :C~  1~  2~  3~
+  A~  B~  C~  1~  2~  3~
 
 Heading tags take either of the forms above, ranging from 1-6
 
@@ -1114,11 +1104,11 @@ in the 0.38 notation this maps to:
 
 % SiSU 0.38
 
-:A~ Document Title
+A~ Document Title
 
-:B~ Document Subtitle whatever it is
+B~ Document Subtitle whatever it is
 
-:C~ Part
+C~ Part
 
 1~ Chapter
 
@@ -1291,8 +1281,7 @@ WOK
 
 WOK
     end
-    def install
-                                                                 #% system configuration
+    def install                                                        #% system configuration
       print <<WOK
   #{@cX.green}Install SiSU#{@cX.off}