documention relatedsisu_5.5.0

6 files changed, 25 insertions, 97 deletions

diff --git a/README b/README
index 9d0ce281..a4970509 100644
--- a/README
+++ b/README
@@ -112,7 +112,6 @@ ruby setup.rb setup
 #[as root:]
 ruby setup.rb install
 
-
 further information:
 <http://i.loveruby.net/en/projects/setup/>
 <http://i.loveruby.net/en/projects/setup/doc/usage.html>
@@ -135,7 +134,6 @@ as root, Using apt-get:
 
   apt get install sisu-complete
 
-
 (all sisu dependencies should be taken care of)
 
 If there are newer versions of *SiSU* upstream, they will be available by
@@ -146,7 +144,6 @@ adding the following to your sources list /etc/apt/sources.list
 deb http://www.jus.uio.no/sisu/archive unstable main non-free
 deb-src http://www.jus.uio.no/sisu/archive unstable main non-free
 
-
 The non-free section is for sisu markup samples provided, which contain
 authored works the substantive text of which cannot be changed, and which as a
 result do not meet the debian free software guidelines.
@@ -192,14 +189,12 @@ graphicsmagick, keychain, openssh-client | lsh-client, po4a, qrencode, rake,
 ruby-rmagick, tidy, tree, vim-addon-manager
 Suggests: lv, calibre, pinfo, poedit, texinfo, trang
 
-
 Package: sisu-complete
 Depends: ruby | ruby-interpreter, sisu (= ${source:Version}), sisu-pdf (=
 ${source:Version}), sisu-postgresql (= ${source:Version}), sisu-sqlite (=
 ${source:Version})
 Description-en: installs all SiSU related packages
 
-
 Package: sisu-pdf
 Depends: ruby | ruby-interpreter, sisu (= ${source:Version}),
 texlive-latex-base, texlive-fonts-recommended, texlive-generic-recommended,
@@ -207,22 +202,18 @@ texlive-latex-recommended, texlive-latex-extra, texlive-math-extra,
 texlive-xetex, fonts-liberation, lmodern, latex-cjk-all, texlive-lang-cjk
 Suggests: evince | pdf-viewer
 
-
 Package: sisu-postgresql
 Depends: ruby | ruby-interpreter, sisu (= ${source:Version}), postgresql,
 ruby-dbd-pg, ruby-dbi, ruby-fcgi
 Suggests: postgresql-contrib
 
-
 Package: sisu-sqlite
 Depends: ruby | ruby-interpreter, sisu (= ${source:Version}), sqlite3,
 ruby-sqlite3, ruby-dbd-sqlite3, ruby-dbi, ruby-fcgi
 
-
 Package: sisu-markup-samples
 Depends: sisu
 
-
 COMMANDS
 ********
 
@@ -606,22 +597,15 @@ see --sisupod
 *-s [filename/wildcard]*
 see --source
 
-*--sample-search-form [--db=(pgsql|sqlite)] [--webserv=webrick]*
+*--sample-search-form [--db-(pg|sqlite)]*
 generate examples of (naive) cgi search form for /SQLite/ or PgSQL depends on
 your already having used sisu to populate an /SQLite/ 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 --sqlite & --pg and the database section below. Optional
-additional parameters include: url location of webserver search form and db:
---webserv-search='[url]'; location of webserver output:
---webserv-output='[url]'; cgi search form link name:
---cgi-search-form-name='[name.cgi]'; for pgsql, database user:
---db-user='[username]'. If the optional parameter --webserv=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). Alias -F
+additional parameters: --db-user='www-data'. 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). Alias -F
 
 *--scp [filename/wildcard]*
 copies sisu output files to remote host using scp. This requires that
@@ -958,7 +942,6 @@ minimal content/structure requirement:
 A~ (level A [title])
 1~ (at least one level 1 [segment/(chapter)])
 
-
 structure rules (document heirarchy, heading levels):
 
 there are two sets of heading levels ABCD (title & parts if any) and 123
@@ -993,7 +976,6 @@ text                    *
   if C~ is last used: C~ or B~;
   if D~ is used: D~, C~ or B~)
 
-
 * level A~ is the tile and is mandatory
 * there can only be one level A~
 * heading levels BCD, are optional and there may be several of each
@@ -1016,7 +998,6 @@ text                    *
   (as a corollary to the rules above substantive text/ content
   must be preceded by a level 1~ (2~ or 3~) heading)
 
-
 MARKUP EXAMPLES
 ...............
 
@@ -1061,7 +1042,6 @@ a space and the comment:
 
 % this would be a comment
 
-
 SAMPLE HEADER
 .............
 
@@ -1120,7 +1100,6 @@ to this one:
   { SiSU Project @ Debian }http://qa.debian.org/developer.php?login=sisu@lists.sisudoc.org
   { SiSU @ Wikipedia }http://en.wikipedia.org/wiki/SiSU
 
-
 AVAILABLE HEADERS
 .................
 
@@ -1143,19 +1122,16 @@ This is a sample header
 
 % SiSU 2.0 [declared file-type identifier with markup version]
 
-
 @title: [title text] [this header is the only one that is mandatory]
   :subtitle: [subtitle if any]
   :language: English
 
-
 @creator:
   :author: [Lastname, First names]
   :illustrator: [Lastname, First names]
   :translator: [Lastname, First names]
   :prepared_by: [Lastname, First names]
 
-
 @date:
   :published: [year or yyyy-mm-dd]
   :created: [year or yyyy-mm-dd]
@@ -1166,7 +1142,6 @@ This is a sample header
   :added_to_site: [year or yyyy-mm-dd]
   :translated: [year or yyyy-mm-dd]
 
-
 @rights:
   :copyright: Copyright (C) [Year and Holder]
   :license: [Use License granted]
@@ -1174,7 +1149,6 @@ This is a sample header
   :translation: [Name, Year]
   :illustrations: [Name, Year]
 
-
 @classify:
   :topic_register: SiSU:markup sample:book;book:novel:fantasy
   :type:
@@ -1185,16 +1159,13 @@ This is a sample header
   :loc: [Library of Congress classification]
   :dewey: [Dewey classification
 
-
 @identify:
   :isbn: [ISBN]
   :oclc:
 
-
 @links: { SiSU }http://www.sisudoc.org
   { FSF }http://www.fsf.org
 
-
 @make:
   :num_top: 1
   :headings: [text to match for each level
@@ -1206,16 +1177,13 @@ This is a sample header
   :home_button_text: {SiSU}http://sisudoc.org; {git}http://git.sisudoc.org
   :footer: {SiSU}http://sisudoc.org; {git}http://git.sisudoc.org
 
-
 @original:
   :language: [language]
 
-
 @notes:
   :comment:
   :prefix: [prefix is placed just after table of contents]
 
-
 MARKUP OF SUBSTANTIVE TEXT
 --------------------------
 
@@ -1253,7 +1221,6 @@ document
 
 % the primary division such as Chapter that is followed by substantive text, and may be further subdivided (this is the level on which by default html segments are made)
 
-
 FONT ATTRIBUTES
 ...............
 
@@ -1284,7 +1251,6 @@ _{underscore}_
 
 #{monospace}#
 
-
 *resulting output:*
 
 normal text, *emphasis*, *bold text*, /italics/, _underscore_, "citation",
@@ -1326,7 +1292,6 @@ _2 indent paragraph two steps
 
 _9 indent paragraph nine steps
 
-
 *resulting output:*
 
 ordinary paragraph
@@ -1345,7 +1310,6 @@ _1* bullet text, first indent
 
 _2* bullet text, two step indent
 
-
 *resulting output:*
 
 * bullet text
@@ -1362,7 +1326,6 @@ Numbered List (not to be confused with headings/titles, (document structure))
 
 _# numbered list numbered list indented a., b., c., d., etc.
 
-
 HANGING INDENTS
 ...............
 
@@ -1376,7 +1339,6 @@ rest of paragraph no indent
 
 in each case level may be 0-9
 
-
 *resulting output:*
 
 first line no indent, rest of paragraph indented one step; first line no
@@ -1419,7 +1381,6 @@ determines whether footnotes or endnotes will be produced
 
 ~{ a footnote or endnote }~
 
-
 *resulting output:*
 
 [^5]
@@ -1428,7 +1389,6 @@ determines whether footnotes or endnotes will be produced
 
 normal text~{ self contained endnote marker & endnote in one }~ continues
 
-
 *resulting output:*
 
 normal text[^6] continues
@@ -1439,7 +1399,6 @@ normal text ~{* unnumbered asterisk footnote/endnote, insert multiple asterisks
 
 normal text ~{** another unnumbered asterisk footnote/endnote }~ continues
 
-
 *resulting output:*
 
 normal text [^*] continues
@@ -1452,7 +1411,6 @@ normal text ~[* editors notes, numbered asterisk footnote/endnote series ]~ cont
 
 normal text ~[+ editors notes, numbered plus symbol footnote/endnote series ]~ continues
 
-
 *resulting output:*
 
 normal text [^*3] continues
@@ -1467,7 +1425,6 @@ normal text~^ continues
 
 ^~ endnote text following the paragraph in which the marker occurs
 
-
 the standard and pair notation cannot be mixed in the same document
 
 LINKS
@@ -1489,7 +1446,6 @@ decoration is omitted).
 
 normal text http://www.sisudoc.org/ continues
 
-
 *resulting output:*
 
 normal text <http://www.sisudoc.org/> continues
@@ -1502,7 +1458,6 @@ normal text _http://www.sisudoc.org/ continues
 
 deb _http://www.jus.uio.no/sisu/archive unstable main non-free
 
-
 *resulting output:*
 
 normal text http://www.sisudoc.org/ continues
@@ -1518,7 +1473,6 @@ deb http://www.jus.uio.no/sisu/archive unstable main non-free
 deb-src http://www.jus.uio.no/sisu/archive unstable main non-free
 
 
-
 ----------------------------------------
 
 LINKING TEXT
@@ -1530,7 +1484,6 @@ To link text or an image to a url the markup is as follows
 
 about { SiSU }http://url.org markup
 
-
 *resulting output:*
 
 about SiSU [link: <http://www.sisudoc.org/>] markup
@@ -1542,7 +1495,6 @@ automatically as a footnote
 
 about {~^ SiSU }http://url.org markup
 
-
 *resulting output:*
 
 about SiSU [link: <http://www.sisudoc.org/>] [^7] markup
@@ -1553,7 +1505,6 @@ Internal document links to a tagged location, including an ocn
 
 about { text links }#link_text
 
-
 *resulting output:*
 
 about text links
@@ -1564,7 +1515,6 @@ Shared document collection link
 
 about { SiSU book markup examples }:SiSU/examples.html
 
-
 *resulting output:*
 
 about *SiSU* book markup examples
@@ -1585,7 +1535,6 @@ LINKING IMAGES
 
 {~^ ruby_logo.png "Ruby" }http://www.ruby-lang.org/en/
 
-
 *resulting output:*
 
 tux.png 64x80 [link: local image]
@@ -1605,10 +1554,8 @@ ruby_logo.png 70x90 "Ruby" [link: <http://www.ruby-lang.org/en/>] [^8]
 
 % which produces hyper-linked text within a document/paragraph, with an endnote providing the url for the text location used in the hyperlink
 
-
 text marker *~name
 
-
 note at a heading level the same is automatically achieved by providing names
 to headings 1, 2 and 3 i.e. 2~[name] and 3~[name] or in the case of
 auto-heading numbering, without further intervention.
@@ -1626,7 +1573,6 @@ TREE
 
 { "Viral Spiral", David Bollier [3sS]}viral_spiral.david_bollier.sst
 
-
 */"Viral Spiral"/, David Bollier*
 
 "Viral Spiral", David Bollier [link: <http://www.sisudoc.org/sisu/en/manifest/viral_spiral.david_bollier.manifest.html>]
@@ -1670,7 +1616,6 @@ column three of row two, and so on
 
 }table
 
-
 *resulting output:*
 
 This is a table┆this would become column two of row one┆column three of row one is here』And here begins another row┆column two of row two┆column three of row two, and so on』
@@ -1692,7 +1637,6 @@ No. of articles, all languages  |       25|   19,000|  138,000|  490,000|  862,0
 
 * Contributed at least ten times; ** at least 5 times in last month; *** more than 100 times in last month.
 
-
 *resulting output:*
 
 *Table 3.1: Contributors to Wikipedia, January 2001 - June 2005*
@@ -1718,7 +1662,6 @@ poem{
 
 Each verse in a poem is given an object number.
 
-
 *markup example:*
 
 poem{
@@ -1770,7 +1713,6 @@ poem{
 
 }poem
 
-
 *resulting output:*
 
                     `Fury said to a
@@ -1834,7 +1776,6 @@ group{
 
 A group is treated as an object and given a single object number.
 
-
 *markup example:*
 
 group{
@@ -1886,7 +1827,6 @@ group{
 
 }group
 
-
 *resulting output:*
 
                     `Fury said to a
@@ -1996,7 +1936,6 @@ option to number each line of code may be considered at some later time]
                       to
                        death."'
 
-
 From *SiSU* 2.7.7 on you can number codeblocks by placing a hash after the
 opening code tag # code{# # as demonstrated here:
 
@@ -2063,7 +2002,6 @@ two backslashes \\ with a space before
 and a space or newline after them \\
 may be used.
 
-
 The html break br enclosed in angle brackets (though undocumented) is available
 in versions prior to 3.0.13 and 2.9.7 (it remains available for the time being,
 but is depreciated).
@@ -2091,17 +2029,14 @@ page break:
 
 -\\-
 
-
 page (break) new:
 
 =\\=
 
-
 page (break) line across page (dividing paragraphs):
 
 -..-
 
-
 BOOK INDEX
 ..........
 
@@ -2114,7 +2049,6 @@ Sub-terms are separated from the main term by a colon.
   Paragraph containing main term and sub-term.
   ={Main term:sub-term}
 
-
 The index syntax starts on a new line, but there should not be an empty line
 between paragraph and index markup.
 
@@ -2123,21 +2057,18 @@ The structure of the resulting index would be:
   Main term, 1
     sub-term, 1
 
-
 Several terms may relate to a paragraph, they are separated by a semicolon. If
 the term refers to more than one paragraph, indicate the number of paragraphs.
 
   Paragraph containing main term, second term and sub-term.
   ={first term; second term: sub-term}
 
-
 The structure of the resulting index would be:
 
   First term, 1,
   Second term, 1,
     sub-term, 1
 
-
 If multiple sub-terms appear under one paragraph, they are separated under the
 main term heading from each other by a pipe symbol.
 
@@ -2149,7 +2080,6 @@ main term heading from each other by a pipe symbol.
 
   A paragraph that continues discussion of the first sub-term
 
-
 The plus one in the example provided indicates the first sub-term spans one
 additional paragraph. The logical structure of the resulting index would be:
 
@@ -2158,7 +2088,6 @@ additional paragraph. The logical structure of the resulting index would be:
     second sub-term, 1,
   Another term, 1
 
-
 COMPOSITE DOCUMENTS MARKUP
 --------------------------
 
@@ -2171,8 +2100,8 @@ suffix *.ssm* 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 *.sst* regular markup file, or *.ssi*
-(insert/information) A secondary file of the composite document is built prior
-to processing with the same prefix and the suffix *._sst*
+(insert). A secondary file of the composite document is built prior to
+processing with the same prefix and the suffix *._sst*
 
 basic markup for importing a document into a master document
 
@@ -2180,7 +2109,6 @@ basic markup for importing a document into a master document
 
 << filename2.ssi
 
-
 The form described above should be relied on. Within the /Vim/ editor it
 results in the text thus linked becoming hyperlinked to the document it is
 calling in which is convenient for editing.
@@ -2197,7 +2125,6 @@ Configure substitution in _sisu/sisu_document_make
 @make:
 :substitute: /${debian_stable}/,'*{Wheezy}*' /${debian_testing}/,'*{Jessie}*'
 
-
 *resulting output:*
 
 The current *Debian* is *Wheezy* the next debian will be *Jessie*
diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_filetypes.sst b/data/doc/sisu/markup-samples/manual/en/sisu_filetypes.sst
index d36acac0..4b5c31e7 100644
--- a/data/doc/sisu/markup-samples/manual/en/sisu_filetypes.sst
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_filetypes.sst
@@ -53,7 +53,7 @@ Note: a secondary file of the composite document is built prior to processing wi
 
 3~ sisu insert files (.ssi)
 
-Inserts are documents prepared solely for the purpose of being incorporated into one or more master documents. They resemble regular SiSU text files except they are ignored by the SiSU processor. Making a file a .ssi file is a quick and convenient way of flagging that it is not intended that the file should be processed on its own.
+Inserts are documents prepared solely for the purpose of being incorporated into one or more master documents. They resemble regular SiSU text files (.sst). Since sisu-5.5.0 (6.1.0) .ssi files can like .ssm files include other .sst or .ssm files. .ssi files cannot be called by the sisu processor directly and can only be incorporated in other documents. Making a file a .ssi file is a quick and convenient way of breaking up a document that is to be included in a master document, and flagging that the file to be incorporated .ssi is not intended that the file should be processed on its own.
 
 2~ sisupod, zipped binary container (sisupod.zip, .ssp)
 
diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_markup.sst b/data/doc/sisu/markup-samples/manual/en/sisu_markup.sst
index 08128821..7db8416e 100644
--- a/data/doc/sisu/markup-samples/manual/en/sisu_markup.sst
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_markup.sst
@@ -1344,7 +1344,7 @@ code{
 
 1~ Composite documents markup
 
-It is possible to build a document by creating a master document that requires other documents. The documents required may be 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 from other documents), it should be named with the suffix *{.ssm}* 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 *{.sst}* regular markup file, or *{.ssi}* (insert/information) A secondary file of the composite document is built prior to processing with the same prefix and the suffix *{._sst}*
+It is possible to build a document by creating a master document that requires other documents. The documents required may be 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 from other documents), it should be named with the suffix *{.ssm}* 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 *{.sst}* regular markup file, or *{.ssi}* (insert). A secondary file of the composite document is built prior to processing with the same prefix and the suffix *{._sst}*
 
 basic markup for importing a document into a master document
 
diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_search_cgi.ssi b/data/doc/sisu/markup-samples/manual/en/sisu_search_cgi.ssi
index 4e833b9b..301cfa72 100644
--- a/data/doc/sisu/markup-samples/manual/en/sisu_search_cgi.ssi
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_search_cgi.ssi
@@ -59,6 +59,7 @@ To create a sample search form, from within the same directory run:
 ``` code
 sisu --sample-search-form --db-pg
 ```
+
 and copy the resulting cgi form to your cgi-bin directory
 
 A sample setup for nginx is provided that assumes data will be stored under /srv/www and cgi scripts under /srv/cgi
diff --git a/data/doc/sisu/sisu.org b/data/doc/sisu/sisu.org
index 8800572d..64246368 100644
--- a/data/doc/sisu/sisu.org
+++ b/data/doc/sisu/sisu.org
@@ -2264,15 +2264,6 @@ allowing .ssi to also include other .ssi or .sst could lead to recursive .ssi
 
 stopping after an additional level of includes seems arbitrary, and possibly prone to error if you are dealing with many documents
 
-***** Discard
-a possibility would be to have another file extension to flag the role of the file,
-.ssmi (not very attractive) might do it
-(providing visual cue signalling its role as both a master file and an insertion/included file that cannot be processed independently)
-a .ssmi file must be included in a .ssm file
-a .ssmi file (like .ssm) permits the inclusion only of .sst or .ssi files
-
-will work on eventually
-
 **** TODO [#C] #744409 [w|u] sisu output: urls in code blocks are not linkified
       <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744409>
 
diff --git a/man/man1/sisu.1 b/man/man1/sisu.1
index f6f4a943..8789a75d 100644
--- a/man/man1/sisu.1
+++ b/man/man1/sisu.1
@@ -1,4 +1,4 @@
-.TH "sisu" "1" "2014-05-18" "6.0.6" "SiSU"
+.TH "sisu" "1" "2014-07-11" "6.1.0" "SiSU"
 .br
 .SH NAME
 .br
@@ -2458,8 +2458,8 @@ master document
 .B .sst
 regular markup file, or
 .B .ssi
-(insert/information) A secondary file of the composite document is built prior
-to processing with the same prefix and the suffix
+(insert). A secondary file of the composite document is built prior to
+processing with the same prefix and the suffix
 .B ._sst
 
 .BR
@@ -2587,10 +2587,12 @@ with the same prefix and the suffix ._sst [^11]
 Inserts are documents prepared solely for the purpose of being incorporated
 into one or more master documents. They resemble regular
 .B SiSU
-text files except they are ignored by the
-.B SiSU
-processor. Making a file a .ssi file is a quick and convenient way of flagging
-that it is not intended that the file should be processed on its own.
+text files (.sst). Since sisu -5.5.0 (6.1.0) .ssi files can like .ssm files
+include other .sst or .ssm files. .ssi files cannot be called by the sisu
+processor directly and can only be incorporated in other documents. Making a
+file a .ssi file is a quick and convenient way of breaking up a document that
+is to be included in a master document, and flagging that the file to be
+incorporated .ssi is not intended that the file should be processed on its own.
 .SH SISUPOD, ZIPPED BINARY CONTAINER (SISUPOD.ZIP, .SSP)
 
 
@@ -3534,6 +3536,13 @@ sisu --pg --update -v en/sisu_manual.ssm
 
 .BR
 To create a sample search form, from within the same directory run:
+.nf
+sisu --sample-search-form --db-pg
+.fi
+
+
+.BR
+and copy the resulting cgi form to your cgi-bin directory
 
 .BR
 A sample setup for nginx is provided that assumes data will be stored under