From 50d45c6deb0afd2e4222d2e33a45487a9d1fa676 Mon Sep 17 00:00:00 2001
From: Ralph Amissah <ralph@amissah.com>
Date: Sun, 23 Sep 2007 05:16:21 +0100
Subject: primarily todo with sisu documentation, changelog reproduced below:

* start documenting sisu using sisu
  * sisu markup source files in
    data/doc/sisu/sisu_markup_samples/sisu_manual/
    /usr/share/doc/sisu/sisu_markup_samples/sisu_manual/
  * default output [sisu -3] in
    data/doc/manuals_generated/sisu_manual/
    /usr/share/doc/manuals_generated/sisu_manual/
    (adds substantially to the size of sisu package!)

* help related edits

* manpage, work on ability to generate manpages, improved

* param, exclude footnote mark count when occurs within code block

* plaintext changes made

* shared_txt, line wrap visited

* file:// link option introduced (in addition to existing https?:// and
  ftp://) a bit arbitrarily, diff here, [double check changes in sysenv and
  hub]

* minor adjustments
  * html url match refinement
  * css added tiny_center

* plaintext
  * endnotes fix
  * footnote adjustment to make more easily distinguishable from substantive
    text
  * flag -a only [flags -A -e -E dropped]
    controlled by modifiers --unix/msdos --footnote/endnote

* defaults, homepage
  * renamed homepage (instead of index) implications for modifying skins,
    which need likewise to have any homepage entry renamed
  * added link to sisu_manual in homepage

* css the css for the default homepage is renamed homepage.css (instead of
  index.css) [consider removing this and relying on html.css]

* ruby version < ruby1.9
  * place stop on installation and working with for now [ruby String.strip
    broken in ruby 1.9.0 (2007-09-10 patchlevel 0) [i486-linux],
    2007-09-18:38/2]
  * debian/control restrict use to ruby > 1.8.4 and ruby < 1.9

* debian
  * debian/control restrict use to ruby > 1.8.4 and ruby < 1.9
  * sisu-doc new sub-package for sisu documentation
    debian/control and sisu-doc.install
---
 lib/sisu/v0/help.rb | 69 +++++++++++++++++++++++++++++++----------------------
 1 file changed, 40 insertions(+), 29 deletions(-)

(limited to 'lib/sisu/v0/help.rb')

diff --git a/lib/sisu/v0/help.rb b/lib/sisu/v0/help.rb
index e22808d1..4805f6ad 100644
--- a/lib/sisu/v0/help.rb
+++ b/lib/sisu/v0/help.rb
@@ -238,9 +238,7 @@ WOK
     def commands
       print <<WOK
 
- #{@cX.ruby}-A#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces  plaintext  with  dos  linefeeds.  Without  markup, (object numbers are omitted), has footnotes at end of each para‐ graph that contains them [ -a for equivalent Unix (ascii) output file] [see -E for endnotes]
-
- #{@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 [ -A for equivalent dos (ascii)  output file] [see -e for endnotes]
+ #{@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
 
   #{@cX.ruby}-b#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces xhtml/XML output for browser viewing (sax parsing)
 
@@ -252,10 +250,6 @@ WOK
 
  #{@cX.ruby}-d#{@cX.off} #{@cX.green}[instruction]#{@cX.off} #{@cX.green}[filename]#{@cX.off} database instruction, see database section below [only -D currently available]
 
- #{@cX.ruby}-E#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces plaintext with dos linefeeds, and without markup,  endnotes follow the main text (in -a endnotes follow the paragraphs that contain them). There are no object numbers [see -e for Unix (ascii) output file] [see -A for footnotes]
-
- #{@cX.ruby}-e#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces plaintext with Unix linefeeds, and without markup, endnotes follow the main text. Object numbers are omitted. [ -E for equivalent dos (ascii) output file] [ -a for footnotes]
-
  #{@cX.ruby}-F#{@cX.off} generate examples of (naive) cgi  search  form  for  sqlite  and  pgsql depends  on  your already having used sisu to populate an sqlite and/or pgsql database, (the sqlite version scans the  output  directories  for existing  sisu_sqlite  databases,  so  it  is first necessary to create them, before generating the search form) see -d  -D  and  the  database section  below.   If  the optional parameter webrick is passed, the cgi examples created will be set up to use the default port set for use  by the  webrick  server,  (otherwise the port is left blank and the system setting used, usually 80). The samples are dumped in the present work directory which must be writable, (with screen instructions given that they be copied to the cgi-bin directory).
 
  #{@cX.ruby}-H#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces html (css version) (creates html (using css)), with url link suffixes (.html .pdf etc.) omitted ("Hide"). For web servers that are confireud so as not to require file extensions to locate and serve files. [behaviour switched see -h]
@@ -456,19 +450,19 @@ sisu
   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 requiring 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), by convention it should be named with the suffix .ssc or .ssm The documents called if complete documents would have the suffix .sst, [.ssf, or .ssd], and if markup snippets .ssi. A temporary file of the composite document is built prior to processing with the same prefix and the suffix ._sst There are a number of alternative syntaxes for requiring external documents in order to permit use of ascii hypertext linking available in the vim editor. They are as follows (place at start of line):
+    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}._sst#{@cX.off}
 
     #{@cX.cyan}#basic sisu markup alternatives#{@cX.off}
-      #{@cX.green}{#{@cX.off}filename.si#{@cX.green}}require#{@cX.off}
-      #{@cX.green}<< {#{@cX.off}filename.si#{@cX.green}}#{@cX.off}
+      #{@cX.green}{#{@cX.off}filename.ssi#{@cX.green}}require#{@cX.off}
+      #{@cX.green}<< {#{@cX.off}filename.ssi#{@cX.green}}#{@cX.off}
 
     #{@cX.cyan}#using textlink alternatives#{@cX.off}
-      #{@cX.green}|#{@cX.off}filename.si#{@cX.green}|@|^|require#{@cX.off}
-      #{@cX.green}<< |#{@cX.off}filename.si#{@cX.green}|@|^|#{@cX.off}
+      #{@cX.green}|#{@cX.off}filename.ssi#{@cX.green}|@|^|require#{@cX.off}
+      #{@cX.green}<< |#{@cX.off}filename.ssi#{@cX.green}|@|^|#{@cX.off}
 
     #{@cX.cyan}#using thlnk alternatives#{@cX.off}
-      #{@cX.green}<url:#{@cX.off}filename.si#{@cX.green}>require#{@cX.off}
-      #{@cX.green}<< <url:#{@cX.off}filename.si#{@cX.green}>#{@cX.off}
+      #{@cX.green}<url:#{@cX.off}filename.ssi#{@cX.green}>require#{@cX.off}
+      #{@cX.green}<< <url:#{@cX.off}filename.ssi#{@cX.green}>#{@cX.off}
 
   #{@cX.cyan}Composite documents - remote parts#{@cX.off}
     Composite documents may be built from remote parts, by using the composite document syntax with a url. This makes sense using either sisu regular syntax (which is just a convenient way of marking up), or thlnk syntax, which also recognises remote urls, and permits hyperlinking ascii to the url location.
@@ -598,7 +592,7 @@ This is a sample header (#{@cX.fuschia}Dublin Core in fuschia,#{@cX.off} #{@cX.c
 
 #{@cX.cyan}@subtitle:#{@cX.off} The Subtitle if any
 
-#{@cX.fuschia}@creator:#{@cX.off} [or ~author] Ralph Amissah
+#{@cX.fuschia}@creator:#{@cX.off} [or @author:] Name of Author
 
 #{@cX.fuschia}@subject:#{@cX.off} (whatever your subject)
 
@@ -608,11 +602,11 @@ This is a sample header (#{@cX.fuschia}Dublin Core in fuschia,#{@cX.off} #{@cX.c
 
 #{@cX.fuschia}@contributor:#{@cX.off}
 
-#{@cX.fuschia}@translator:#{@cX.off} [or ~translated_by]
+#{@cX.fuschia}@translator:#{@cX.off} [or @translated_by:]
 
-#{@cX.fuschia}@illustrator:#{@cX.off} [or ~illustrated_by]
+#{@cX.fuschia}@illustrator:#{@cX.off} [or @illustrated_by:]
 
-#{@cX.fuschia}@prepared_by:#{@cX.off} [or ~digitized_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} ]
@@ -625,7 +619,13 @@ This is a sample header (#{@cX.fuschia}Dublin Core in fuschia,#{@cX.off} #{@cX.c
 
 #{@cX.fuschia}@source:#{@cX.off}
 
-#{@cX.fuschia}@language:#{@cX.off} [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 - Bul garian ) [however, encodings are not available for all of the languages listed.]
+#{@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 - Bul garian ) [however, encodings are not available for all of the languages listed.]
+
+#{@cX.fuschia}@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}
 
@@ -658,24 +658,23 @@ This is a sample header (#{@cX.fuschia}Dublin Core in fuschia,#{@cX.off} #{@cX.c
 #{@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;
- structure can be defined by a match words or regular expression (the regular expression is assumed to start at the beginning of a line of text i.e. ^)
- can be used within text instead, without this header tag, and may be used to suppliment the instructions provided in this header tag if provided
+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} [list of words to make bold with semi colon separator]
+#{@cX.ruby}@bold:#{@cX.off} [regular expression of words/phrases to be made bold]
 
-#{@cX.ruby}@italics:#{@cX.off} [list of words to italize with semi colon separator]
+#{@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} http://google.com; Google;
+#{@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_cru‐ sade_for_free_software.sam_williams.sst]
+#{@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.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
@@ -770,7 +769,7 @@ This is a sample header (#{@cX.fuschia}Dublin Core in fuschia,#{@cX.off} #{@cX.c
 
 #{@cX.green}0~#{@cX.off}#{@cX.ruby}toc#{@cX.off} PART; CHAPTER; SECTION; ARTICLE; none; none;
 optional, where document structure can be defined by a match words or regular expression (the regular expression is assumed to start at the beginning of a line of text i.e. ^)
-default markers 1~ to 6~ can be used within text instead, without this header tag, and may be used to suppliment the instructions provided in this header tag if provided
+default markers 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.green}0~#{@cX.off}#{@cX.ruby}level#{@cX.off} newpage=3; breakpage=4 [paragraph level, used by latex to breakpages, the page is optional eg. in newpage]
 
@@ -784,7 +783,7 @@ default markers 1~ to 6~ can be used within text instead, without this header ta
 
 #{@cX.green}0~#{@cX.off}#{@cX.ruby}skin#{@cX.off} skin_doc_[name_of_desired_document_skin]
 
-#{@cX.green}0~#{@cX.off}#{@cX.ruby}links#{@cX.off} http://google.com; Google;
+#{@cX.green}0~#{@cX.off}#{@cX.ruby}links#{@cX.off} { Google }http://google.com;
 
 #{@cX.grey}% header ends here, NB only 0~title is mandatory [this would be a comment]#{@cX.off}
 
@@ -1733,6 +1732,18 @@ WOK
    #{@cX.off} #{@cX.orange}
    man estcmd
    #{@cX.off}
+
+   on sisu_hyperestraier:
+
+   #{@cX.blue}
+    man sisu_hyperestraier
+
+   /usr/share/doc/sisu/sisu_markup/sisu_hyperestraier/index.html
+   #{@cX.off}
+
+  NOTE: The examples that follow assume that sisu output is placed in the directory
+  /home/ralph/sisu_www
+
  (A)  to generate the index
    within the webserver directory to be indexed:
       #{@cX.orange}estcmd gather -sd [index name] [directory path to index]#{@cX.off}
@@ -1754,13 +1765,13 @@ WOK
 
      as sisu duplicates output in multiple file formats,
      it it is probably preferable to limit the estraier index
-     to html output, and as it may also be desireable to
+     to html output, and as it may also be desirable to
      exclude files 'doc.html' and 'concordance.html', as these
      duplicate information held in other html output e.g. #{@cX.green}
 
      find /home/ralph/sisu_www -type f | egrep '/sisu_www/(sisu|bookmarks)/.+?\.html$' | egrep -v '(doc|concordance)\.html$' |estcmd gather -sd casket - #{@cX.off}
 
-     from your current document preperation/markup directory, you would construct a rune along the following lines: #{@cX.green}
+     from your current document preparation/markup directory, you would construct a rune along the following lines: #{@cX.green}
 
      find /home/ralph/sisu_www -type f | egrep '#{@env.path.webserv}/([specify first directory for inclusion]|[specify second directory for inclusion]|[another directory for inclusion? ...])/.+?\.html$' | egrep -v '(doc|concordance)\.html$' |estcmd gather -sd #{@env.path.webserv}/casket - #{@cX.off}
 
-- 
cgit v1.2.3