From bf076ed40633fa31cc33e225c00e2dcb1f526ce8 Mon Sep 17 00:00:00 2001 From: Ralph Amissah Date: Fri, 11 Jul 2014 00:17:43 -0400 Subject: documention related --- README | 85 +++++------------------------------------------------------------- 1 file changed, 6 insertions(+), 79 deletions(-) (limited to 'README') 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: @@ -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 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: ] markup @@ -1542,7 +1495,6 @@ automatically as a footnote about {~^ SiSU }http://url.org markup - *resulting output:* about SiSU [link: ] [^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: ] [^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: ] @@ -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* -- cgit v1.2.3