summaryrefslogtreecommitdiffstats
path: root/README
diff options
context:
space:
mode:
authorRalph Amissah <ralph@amissah.com>2014-07-11 04:17:43 +0000
committerRalph Amissah <ralph@amissah.com>2014-07-11 04:24:55 +0000
commitbf076ed40633fa31cc33e225c00e2dcb1f526ce8 (patch)
tree3b6ed9d2ca50f3681164432f791ca8bf104ecfba /README
parentv5 v6: src, sisupod composite source, nested includes (diff)
downloadsisu-bf076ed40633fa31cc33e225c00e2dcb1f526ce8.zip
sisu-bf076ed40633fa31cc33e225c00e2dcb1f526ce8.tar.xz
documention relatedsisu_5.5.0
Diffstat (limited to 'README')
-rw-r--r--README85
1 files changed, 6 insertions, 79 deletions
diff --git a/README b/README
index 9d0ce28..a497050 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*