documention relatedsisu_5.5.0

1 files changed, 6 insertions, 79 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*