diff options
Diffstat (limited to 'data/doc/sisu/v2')
11 files changed, 606 insertions, 570 deletions
diff --git a/data/doc/sisu/v2/sisu_user_txt/configuration.txt b/data/doc/sisu/v2/sisu_user_txt/configuration.txt new file mode 100644 index 00000000..1f122d56 --- /dev/null +++ b/data/doc/sisu/v2/sisu_user_txt/configuration.txt @@ -0,0 +1,8 @@ + index.txt +%% configuration --------------------------------------------------------------- + +configuration_sisurc.txt + +configuration_skin.txt + +configuration_css.txt diff --git a/data/doc/sisu/v2/sisu_user_txt/configuration_css.txt b/data/doc/sisu/v2/sisu_user_txt/configuration_css.txt new file mode 100644 index 00000000..17fb2e97 --- /dev/null +++ b/data/doc/sisu/v2/sisu_user_txt/configuration_css.txt @@ -0,0 +1,9 @@ + index.txt + configuration.txt +%% css ------------------------------------------------------------------------ + +the default css may be replaced for the site or particular processing +directories + +[provide information] + diff --git a/data/doc/sisu/v2/sisu_user_txt/configuration_sisurc.txt b/data/doc/sisu/v2/sisu_user_txt/configuration_sisurc.txt new file mode 100644 index 00000000..62a2ce02 --- /dev/null +++ b/data/doc/sisu/v2/sisu_user_txt/configuration_sisurc.txt @@ -0,0 +1,137 @@ + index.txt + configuration.txt +%% config, sisurc.yml ---------------------------------------------------------- + +There are default configuration settings within the program many of which can +be modified in sisurc.yml + +sisurc.yml can be located in one of the following locations: +/etc/sisu/sisurc.yml ~/.sisu/sisurc.yml and ./_sisu/sisurc.yml + +if sisu versions 1 and 2 are both in use, the v2 sisurc.yml can be placed a the +following locations: +/etc/sisu/v2/sisurc.yml ~/.sisu/v2/sisurc.yml and ./_sisu/v2/sisurc.yml + +# Name: SiSU - Simple information Structuring Universe +# Author: Ralph@Amissah.com +# Description: Site wide envionment defaults set here +# system environment info / resource configuration file, for sisu +# License: GPL v3 or later +# site environment configuration file +# this file should be configured and live in +# /etc/sisu #per environment settings, overridden by: +# ~/.sisu #per user settings, overridden by: +# ./_sisu #per local markup directory settings +#% #image source directory, main path and subdirectories +#image: +# path: 'sisu_working' +# public: '_sisu/image' +#% presentation/web directory, main path and subdirectories (most subdirectories are created automatically based on markup directory name) +#webserv: +# url_root: 'http://www.your.url' #without dir stub +# path: '/var/www' #either (i) / [full path from root] or (ii) ~/ [home] or (iii) ./ [pwd] or (iv) will be made from home +# images: '_sisu/image' +# man: 'man' +# cgi: '/usr/lib/cgi-bin' +# feed: 'feed' +# sqlite: 'sisu/sqlite' +# webrick_url: true +#show_output_on: 'filesystem' #for -v and -u url information, alternatives: 'filesystem','webserver','remote_webserver','local:8111','localhost','localhost:8080','webrick','path' +#show_output_on: 'local:8111' +#webserv_cgi: +# host: localhost +# base_path: ~ +# port: '8081' +# user: ~ +show_output_on: 'filesystem_url' +#texinfo display output +#texinfo: +# stub: 'texinfo' +##% processing directories, main path and subdirectories (appended to $HOME), using defaults set in sysenv +#processing: +# path: '~' +# dir: '.sisu_processing~' +# metaverse: 'metaverse' +# tune: 'tune' +# latex: 'tex' +# texinfo: 'texinfo' +# concord_max: 400000 +#% flag - set (non-default) processing flag shortcuts -1, -2 etc. (here adding colour and verbosity as default) +flag: + color: true # making colour default -c is toggle, and will now toggle colour off + default: '-NhwepoabxXyYv' # -m run by default; includes verbose + i: '-hwpoay' # -m run by default + ii: '-NhwepoabxXy' # -m run by default + iii: '-NhwepoabxXyY' # -m run by default + iv: '-NhwepoabxXYDy --update' # -m run by default + v: '-NhwepoabxXYDyv --update' # -m run by default; includes verbose +#% papersize, (LaTeX/pdf) available values: A4, US_letter, book_b5, book_a5, US_legal +default: + papersize: 'A4,letter' + #text_wrap: 78 + #emphasis: 'bold' #make *{emphasis}* 'bold', 'italics' or 'underscore', default if not configured is 'bold' + #digest: 'sha' #sha is sha256, default is md5 + #multilingual: false + #language_file: 2 + #language: 'English' +#% markup, make *{emphasis}* 'bold' or 'italics', default if not configured is 'bold' +#% settings used by ssh scp +#remote: +# - +# user: '[usrname]' +# host: '[remote.hostname]' +# path: '.' #no trailing slash eg 'sisu/www' +# - +# user: '[usrname]' +# host: '[remote.hostname]' +# path: '.' #no trailing slash eg 'sisu/www' +#% webrick information +#webrick: +# port: '8081' +#% sql database info, postgresql and sqlite +#db: +# share_source: false # boolean, default is false +# postgresql: +# port: # '[port (default is 5432)]' +# host: # '[if not localhost, provide host tcp/ip address or domain name]'' +# user: # '[(if different from user) provide username]' +# password: # '[password if required]' +# sqlite: +# path: ~ # './sisu_sqlite.db' +# port: "**" +#% possible values ~, true, false, or command instruction e.g. editor: 'gvim -c :R -c :S'. +#will only ignore if value set to false, absence or nil will not remove program as should operate without rc file +#ie in case of ~ will ignore and use hard coded defaults within program), true, false, or command instruction e.g. editor: 'gvim -c :R -c :S' +#on value true system defaults used, to change, e.g. editor specify +permission_set: + zap: false + css_modify: false +# remote_base_site: true +program_set: + rmagick: false +# wc: true +# editor: true +# postgresql: true +# sqlite: true +# tidy: true +# rexml: true +# pdflatex: true +#program_select: +# editor: 'gvim -c :R -c :S' +# pdf_viewer: 'evince' +# web_browser: 'firefox' #'iceweasel' #'epiphany' #'galeon' #'konqueror' #'kazehakase' +# console_www_browser: 'links2' #'elinks' +# odf_viewer: 'oowriter' #'abiword' +# xml_viewer: 'xml-viewer' +# man: 'nroff -man' #'groff -man -Tascii' # 'nroff -man' +#promo: sisu_icon, sisu, sisu_search_libre, open_society, fsf, ruby +#search: +# sisu: +# flag: true +## action: http://localhost:8081/cgi-bin/sisu_pgsql.cgi +# action: http://search.sisudoc.org +# db: sisu +# title: sample search form +# hyperestraier: +# flag: true +# action: http://search.sisudoc.org/cgi-bin/estseek.cgi? diff --git a/data/doc/sisu/v2/sisu_user_txt/configuration_skin.txt b/data/doc/sisu/v2/sisu_user_txt/configuration_skin.txt new file mode 100644 index 00000000..2695dda8 --- /dev/null +++ b/data/doc/sisu/v2/sisu_user_txt/configuration_skin.txt @@ -0,0 +1,15 @@ + index.txt + configuration.txt +%% skin ------------------------------------------------------------------------ + +skins can be used to modify the appearance of output + +[provide information] + +%% css ------------------------------------------------------------------------ + +the default css may be replaced for the site or particular processing +directories + +[provide information] + diff --git a/data/doc/sisu/v2/sisu_user_txt/index.txt b/data/doc/sisu/v2/sisu_user_txt/index.txt new file mode 100644 index 00000000..3e66cb19 --- /dev/null +++ b/data/doc/sisu/v2/sisu_user_txt/index.txt @@ -0,0 +1,5 @@ +%% Summary --------------------------------------------------------------------- + +markup.txt + +configuration.txt diff --git a/data/doc/sisu/v2/sisu_user_txt/markup.txt b/data/doc/sisu/v2/sisu_user_txt/markup.txt new file mode 100644 index 00000000..4ab55606 --- /dev/null +++ b/data/doc/sisu/v2/sisu_user_txt/markup.txt @@ -0,0 +1,11 @@ + index.txt +%% Summary --------------------------------------------------------------------- + +markup_minimum_requirement.txt + +markup_content.txt + +markup_headers_metadata.txt + +markup_headers_processing_instructions.txt + diff --git a/data/doc/sisu/v2/sisu_user_txt/markup_content.txt b/data/doc/sisu/v2/sisu_user_txt/markup_content.txt new file mode 100644 index 00000000..326fabe1 --- /dev/null +++ b/data/doc/sisu/v2/sisu_user_txt/markup_content.txt @@ -0,0 +1,296 @@ + index.txt + markup.txt +%% The Gory Details ------------------------------------------------------------ + +%% comments -------------------------------------------------------------------- + +Comments in sisu are a percentage sign at the start of a line followed by a +space and then the comment + +% this would be a comment + +%% headings -------------------------------------------------------------------- + +There are two sets of docment heading markers :A~ and an optional :B~ & :C~ and +beneath that 1~, 2~, 3~. These markers are placed at the start of the +line/paragraph, and followed by the heading + +There is usually one :A~ top level heading, which is the document title, +sometimes including the author. This is such a common occurrence that there is +a shortcut where metadata headers are provided for @title: and @creator +:author:, instead of rewriting the title and author's name, you may write :A~ +@title @author + +If you have a document/manuscript that has subsections above the level of +chapter, such as multiple books, parts, section, two additional top level +headings are available :B~ and :C~ + +At the main division level, usually chapter heading level 1~ begins, followed +by 2~ and 3~ if the chapter has subheadings. Because the html and epub +segmented output breaks level 1~ into separate files it is possible to provide +the filename, e.g. 1~prologue Prologue + +Where names are provided following the heading tilde, these become tagged +points within the document which can where the output format permits be +(hyper-)linked to. + +%% font effect, modified font including emphasis ------------------------------- + +Whithin normal text it is possible to modify the font effect of a word or +phrase using the following markers: + +!{ bold }! + +/{ italics }/ + +_{ underscore }_ + +*{ emphasis }* (how emphasis is represented in output text can be defined in +the header @make: section of a document or in the sisurc.yml config file, and +this may be as bold, italics or underscore, the default being bold) + +^{ superscript }^ + +,{ subscript }, + ++{ inserted text }+ + +_{ strikethrough }_ + +An exclamation mark followed by an underscore at the start of a line will bold +that line until the first line-break + +!_ this line would be bold + +It is also possible to define in the header section under the @make: section +which words or patterns should automatically be made bold or italics. + +@make: + :bold: /Gnu|Linux|Debian|Fedora|Ruby|SiSU/ + :italics: /inter alia/ + +%% indent ---------------------------------------------------------------------- + +_1 a paragraph that is indented one level + +_2 a paragraph that is indented two steps + +%% bullet ---------------------------------------------------------------------- + +_* bulleted text + +_1* bulleted indented text + +%% auto-numbering ------------------------------------------------------------- + +Some auto-numbering occurs in the building of sisu documents, either by default +or when requested through configuration options + +%% auto-numbering document objects --------------------------------------------- + +Document objects are automatically given sequential object numbers, object +citation numbers (ocn). If there is text that for some reason should not be +regarded as substantive objects, it is possible to prevent a document number +being given by adding ~# to the end of the object (paragraph/heading, etc.) ~# + +A variation used for headings that are added to provide document structure that +should where possible not be included in output is -# a heading that is marked +with -# is un-numbered and may be excluded from document outputs. + +%% auto-numbering headings ----------------------------------------------------- + +Note auto-numbering of headings may be specified in the header @make: :num_top: +by providing the heading level from which numbering is to start, this is +usually at the chapter level (1~). + +@make: + :num_top: 1 + +numbering continues three levels down, level 1 being numbered 1, 2, 3 ... +level 2: 1.1, 1.2, 1.3 and so on +level 3: 1.1.1, 1.1.2, 1.1.3 + +It is also possible to make an auto-numbered list + +# numbered list numbered list 1., 2., 3, etc. + +_# indented lettered list sub-level of previous list number a., b., c., d., etc. + +%% line breaks ----------------------------------------------------------------- + +<:br> line break + +In paper/ page oriented outputs, such as LaTeX/pdf the following are avaiable + +<:pb> page or column break + +<:pn> new page + +in the header section under @make: :breaks: new and break set a page break or +new page at the levels indicated, e.g. + +@make: + :breaks: new=C; break=1 + +%% footnotes / endnotes -------------------------------------------------------- + +This paragraph contains a footnote~{ a footnote or endnote }~ which would be +automatically numbered + +Footnotes and endnotes are marked up at the location where they would be +indicated within a text. They are automatically numbered. The output type +determines whether footnotes or endnotes will be produced + +In addition to regular footnotes/endnotes there are astrisk and plus sign +numbered and unnumbered footnotes. + +normal text ~[* editors notes, numbered asterisk footnote/endnote series ]~ continues + +normal text ~[+ editors notes, numbered asterisk footnote/endnote series ]~ continues + +normal text ~{* unnumbered asterisk footnote/endnote, insert multiple asterisks if required }~ continues + +%% tag points ------------------------------------------------------------------ + +Tag points are markers within the document which may be used within the +document for (internal document) linking where the output format permits. Tag +names should use alphanumeric characters and underscores [a-z0-9_]+. + +There are different types of tag point, some automatically provided by sisu, +such as each ocn (object citation number) + +Manual tags may be provided either: + +(a) with headings where a name is added to the heading level after the tilde: + +1~prefix [heading] + +(b) a tag marker can be added to a paragraph using an asterisk tilde and the +name *~tag_marker + +%% links and urls -------------------------------------------------------------- + +Urls found within text are marked up automatically, and where the output type +permits is autmatically hyperlinked to inself and decorated with angled braces +(unless contained in a code block, or escaped by a preceeding underscore). + +To link text or an image to a url the markup is as follows + +{ this is the linked section of text}http://url.org + +Where it is wished to include the url for the linked text in a footnote, the +long form of markup would be: +{ SiSU }http://www.jus.uio.no/sisu/ ~{ http://www.jus.uio.no/sisu/ }~ + +A short form is provided for achieving the same: + {~^ SiSU }http://www.jus.uio.no/sisu/ + +%% images ---------------------------------------------------------------------- + +Images are placed in the directory beneath the location of the document to be +processed _sisu/image + +The following are examples of links to images + +{ tux.png 64x80 }image + +{tux.png 64x80 "Gnu/Linux - a better way" }http://www.jus.uio.no/sisu/ + +{GnuDebianLinuxRubyBetterWay.png 100x101 "Way Better - with Gnu/Linux, Debian and Ruby" }http://www.jus.uio.no/sisu/ + +The 64x80 in the first example is the image dimension, (width x height). This +may be omitted if imagemagick or graphicsmagick are installed, as they will +determine the image dimensions + +As with other linked text, the following markup + +{~^ ruby_logo.png "Ruby" }http://www.ruby-lang.org/en/ + +maps to + +{ ruby_logo.png "Ruby" }http://www.ruby-lang.org/en/ ~{ http://www.ruby-lang.org/en/ }~ + +%% grouped text ---------------------------------------------------------------- + +%% group ----------------------------------------------------------------------- + +The start and end of text that is grouped are tagged. Grouped text retains its +line breaks, and is treated as a unit, getting a single ocn + +group{ + +License: GPL 3 or later: + +SiSU, a framework for document structuring, publishing and search + +Copyright (C) Ralph Amissah + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU General Public License as published by the Free Software +Foundation, either version 3 of the License, or (at your option) any later +version. + +This program is distributed in the hope that it will be useful, but WITHOUT ANY +WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A +PARTICULAR PURPOSE. See the GNU General Public License for more details. + +You should have received a copy of the GNU General Public License along with +this program. If not, see <http://www.gnu.org/licenses/>. + +If you have Internet connection, the latest version of the GPL should be +available at these locations: +<http://www.fsf.org/licensing/licenses/gpl.html> +<http://www.gnu.org/licenses/gpl.html> + +}group + +%% poem ------------------------------------------------------------------------ + +The start and end of a poem are tagged. Each verse in a poem is given an object +number. Verses retain their line breaks. + +poem{ + +verse here +declare + +another verse +here + +}poem + +%% table ----------------------------------------------------------------------- + +{table~h 24; 12; 12; 12; 12; 12; 12;} + |Jan. 2001|Jan. 2002|Jan. 2003|Jan. 2004|July 2004|June 2006 +Contributors* | 10| 472| 2,188| 9,653| 25,011| 48,721 +Active contributors** | 9| 212| 846| 3,228| 8,442| 16,945 +Very active contributors*** | 0| 31| 190| 692| 1,639| 3,016 +No. of English language articles| 25| 16,000| 101,000| 190,000| 320,000| 630,000 +No. of articles, all languages | 25| 19,000| 138,000| 490,000| 862,000|1,600,000 + + +table{ c3; 40; 30; 30; + +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 + +}table + +a second form may be easier to work with in cases where there is not much information in each column + +%% code ------------------------------------------------------------------------ + +code{ + +code lines here + +and so on + +}code + diff --git a/data/doc/sisu/v2/sisu_user_txt/markup_headers_metadata.txt b/data/doc/sisu/v2/sisu_user_txt/markup_headers_metadata.txt new file mode 100644 index 00000000..c24789c8 --- /dev/null +++ b/data/doc/sisu/v2/sisu_user_txt/markup_headers_metadata.txt @@ -0,0 +1,34 @@ + index.txt + markup.txt +%% headers --------------------------------------------------------------------- + +%% header metadata ------------------------------------------------------------- + +@title: SiSU + :subtitle: Markup + +@creator: + :author: Amissah, Ralph + +@rights: + :copyright: Copyright (C) Ralph Amissah 2007, part of SiSU documentation + :license: GPL 3 or later + +@classify: + :type: information + :topic_register: electronic documents:SiSU:document:markup;SiSU:document:markup;SiSU:document:markup;SiSU:manual:markup;electronic documents:SiSU:manual:markup + :subject: ebook, epublishing, electronic book, electronic publishing, electronic document, electronic citation, data structure, citation systems, search + +@date: + :created: 2002-08-28 + :issued: 2002-08-28 + :available: 2002-08-28 + :published: 2008-05-22 + :modified: 2010-05-25 + +@links: + { SiSU Manual }http://www.jus.uio.no/sisu/sisu_manual/ + { Book Samples and Markup Examples }http://www.jus.uio.no/SiSU/examples.html + { SiSU @ Wikipedia }http://en.wikipedia.org/wiki/SiSU + { SiSU Download }http://www.jus.uio.no/sisu/SiSU/download.html + { SiSU Changelog }http://www.jus.uio.no/sisu/SiSU/changelog.html diff --git a/data/doc/sisu/v2/sisu_user_txt/markup_headers_processing_instructions.txt b/data/doc/sisu/v2/sisu_user_txt/markup_headers_processing_instructions.txt new file mode 100644 index 00000000..b2c559c1 --- /dev/null +++ b/data/doc/sisu/v2/sisu_user_txt/markup_headers_processing_instructions.txt @@ -0,0 +1,12 @@ + index.txt + markup.txt +%% header processing instructions, @make: -------------------------------------- + +Some document processing parameters can be set in the @make: section of the header + +@make: + :num_top: 1 + :breaks: new=C; break=1 + :skin: skin_sisu_manual + :bold: /Gnu|Debian|Ruby|SiSU/ + diff --git a/data/doc/sisu/v2/sisu_user_txt/markup_minimum_requirement.txt b/data/doc/sisu/v2/sisu_user_txt/markup_minimum_requirement.txt new file mode 100644 index 00000000..5eee046d --- /dev/null +++ b/data/doc/sisu/v2/sisu_user_txt/markup_minimum_requirement.txt @@ -0,0 +1,79 @@ + index.txt + markup.txt +%% Summary --------------------------------------------------------------------- + +sisu takes an ASCII (UTF-8) document and abstracts the document into its +structure and smaller constituent parts, objects. This abstraction is then used +in subsequent processing to reconstitute the document into disparate document +representations, many quite different from one another, e.g. HTML, ODF, LaTeX +and to populate SQL + +SiSU identifies the document structure (headings and their levels) and pulls +the document apart in to its constituent parts, objects (paragraphs, headings, +tables, images etc.) to which it assigns an object number if substantive +content. + +From the marked up document SiSU need to be able to determine a documents +structure, and the objects that a document contains + +The first line of a SiSU marked up document can identify itself with + +%% Identify SiSU Document ------------------------------------------------------ + +% SiSU + +%% The Basic SiSU Markup Document ---------------------------------------------- + +SiSU documents are divided into two parts, (i) the document header and (ii) +substantive content. + +(i) the document header, which contains (a) metadata and (b) processing +instructions if any. Document headers take the form of a tag and the related +related information. The Document header, metadata, should contain at least: + +@title: + +@creator: + :author: + +Processing instructions are grouped under the @make: tag. In the absence of any +program (or configured) defaults will be used. + +(ii) for the substantive content the document structure must be defined, here +structure equates to the headings and their relative levels (this can be done +either by explicit markup where each heading occurs, or in the header @make: +section of the, or both). + +The basic document objects are headings and paragraphs. Paragraphs are +identified automatically, and headings must be defined (with respect to +document structure), so sisu is able to determine the basic objects without +anything further. + +sample_1.sst + +%% Document Structure (heading levels) ----------------------------------------- + +Document structure (heading levels) are determined from information provided in +the markup of the document. There are two ways to identify document structure: +(i) manual markup of headings with their level; (ii) in the sisu header, under +@make: :heading: provide a regex, in the manner understood by sisu, that +identifies what to look for in headings of various levels. + +Document structure is the different headings in a document, and their relative +levels. + +There are two sets of docment level markers :A~ and an optional :B~ & :C~ and +beneath that 1~, 2~, 3~. + +For the first set of document level markers the document Title being the top +level in the hierarchy; beneath that book titles if the document contains more +than one book followed by sections + +%% Document Objects (paragraphs, headings, tables, verse etc.) ----------------- + +Document objects are units of text that are identified, stored and processed as +a block. The most usual document objects would be paragraphs and headings. A +more complete list of objects includes: paragraphs; headings; tables; code +blocks; verse (the poem is identified, but each verse is an object); grouped +text... + diff --git a/data/doc/sisu/v2/sisu_user_txt/sisu_markup.txt b/data/doc/sisu/v2/sisu_user_txt/sisu_markup.txt deleted file mode 100644 index 0af080c5..00000000 --- a/data/doc/sisu/v2/sisu_user_txt/sisu_markup.txt +++ /dev/null @@ -1,570 +0,0 @@ -%% Summary --------------------------------------------------------------------- - -sisu takes an ASCII (UTF-8) document and abstracts the document into its -structure and smaller constituent parts, objects. This abstraction is then used -in subsequent processing to reconstitute the document into disparate document -representations, many quite different from one another, e.g. HTML, ODF, LaTeX -and to populate SQL - -SiSU identifies the document structure (headings and their levels) and pulls -the document apart in to its constituent parts, objects (paragraphs, headings, -tables, images etc.) to which it assigns an object number if substantive -content. - -From the marked up document SiSU need to be able to determine a documents -structure, and the objects that a document contains - -The first line of a SiSU marked up document can identify itself with - -%% Identify SiSU Document ------------------------------------------------------ - -% SiSU - -%% The Basic SiSU Markup Document ---------------------------------------------- - -SiSU documents are divided into two parts: - -(i) the document header, which contains (a) metadata and (b) processing -instructions if any document headers take the form of a tag and the related -related information - -(ii) the substantive content - -%% Minimum (SiSU) Markup Requirements ------------------------------------------ - -minimum requirements for a SiSU document - -(i)(a) document header metadata, should contain at least: - -@title: - -@creator: - :author: - -(i)(b) processing instructions (grouped under @make:) are not required as there -are defaults that will be used - -(ii) the substantive document structure must be defined, here structure equates -to the headings and their relative levels, this can be done either by explicit -markup where each heading occurs, or in the header @make: section of the, or -both - -(iii) the basic document objects are headings and paragraphs. Paragraphs are -identified automatically, and headings must be defined, so sisu is able to -determine the basic objects without anything further - -sample_1.sst - -%% Document Structure ---------------------------------------------------------- - -Document structure (heading levels) are determined from information provided in -the markup of the document. There are two ways to identify document structure: -(i) manual markup of headings with their level; (ii) in the sisu header, under -@make: :heading: provide a regex, in the manner understood by sisu, that -identifies what to look for in headings of various levels. - -Document structure is the different headings in a document, and their relative -levels. - -There are two sets of docment level markers :A~ and an optional :B~ & :C~ and -beneath that 1~, 2~, 3~. - -For the first set of document level markers the document Title being the top -level in the hierarchy; beneath that book titles if the document contains more -than one book followed by sections - -%% Document Objects ------------------------------------------------------------ - -Document objects are units of text that are identified, stored and processed as -a block. The most usual document objects would be paragraphs and headings. A -more complete list of objects includes: paragraphs; headings; tables; code -blocks; verse (the poem is identified, but each verse is an object); grouped -text... - -%% The Gory Details ------------------------------------------------------------ - - -%% comments -------------------------------------------------------------------- - -Comments in sisu are a percentage sign at the start of a line followed by a -space and then the comment - -% this would be a comment - -%% headings -------------------------------------------------------------------- - -There are two sets of docment heading markers :A~ and an optional :B~ & :C~ and -beneath that 1~, 2~, 3~. These markers are placed at the start of the -line/paragraph, and followed by the heading - -There is usually one :A~ top level heading, which is the document title, -sometimes including the author. This is such a common occurrence that there is -a shortcut where metadata headers are provided for @title: and @creator -:author:, instead of rewriting the title and author's name, you may write :A~ -@title @author - -If you have a document/manuscript that has subsections above the level of -chapter, such as multiple books, parts, section, two additional top level -headings are available :B~ and :C~ - -At the main division level, usually chapter heading level 1~ begins, followed -by 2~ and 3~ if the chapter has subheadings. Because the html and epub -segmented output breaks level 1~ into separate files it is possible to provide -the filename, e.g. 1~prologue Prologue - -Where names are provided following the heading tilde, these become tagged -points within the document which can where the output format permits be -(hyper-)linked to. - -%% font effect, modified font including emphasis ------------------------------- - -Whithin normal text it is possible to modify the font effect of a word or -phrase using the following markers: - -!{ bold }! - -/{ italics }/ - -_{ underscore }_ - -*{ emphasis }* (how emphasis is represented in output text can be defined in -the header @make: section of a document or in the sisurc.yml config file, and -this may be as bold, italics or underscore, the default being bold) - -^{ superscript }^ - -,{ subscript }, - -+{ inserted text }+ - -_{ strikethrough }_ - -An exclamation mark followed by an underscore at the start of a line will bold -that line until the first line-break - -!_ this line would be bold - -It is also possible to define in the header section under the @make: section -which words or patterns should automatically be made bold or italics. - -@make: - :bold: /Gnu|Linux|Debian|Fedora|Ruby|SiSU/ - :italics: /inter alia/ - -%% indent ---------------------------------------------------------------------- - -_1 a paragraph that is indented one level - -_2 a paragraph that is indented two steps - -%% bullet ---------------------------------------------------------------------- - -_* bulleted text - -_1* bulleted indented text - -%% auto-numbering ------------------------------------------------------------- - -Some auto-numbering occurs in the building of sisu documents, either by default -or when requested through configuration options - -%% auto-numbering document objects --------------------------------------------- - -Document objects are automatically given sequential object numbers, object -citation numbers (ocn). If there is text that for some reason should not be -regarded as substantive objects, it is possible to prevent a document number -being given by adding ~# to the end of the object (paragraph/heading, etc.) ~# - -A variation used for headings that are added to provide document structure that -should where possible not be included in output is -# a heading that is marked -with -# is un-numbered and may be excluded from document outputs. - -%% auto-numbering headings ----------------------------------------------------- - -Note auto-numbering of headings may be specified in the header @make: :num_top: -by providing the heading level from which numbering is to start, this is -usually at the chapter level (1~). - -@make: - :num_top: 1 - -numbering continues three levels down, level 1 being numbered 1, 2, 3 ... -level 2: 1.1, 1.2, 1.3 and so on -level 3: 1.1.1, 1.1.2, 1.1.3 - -It is also possible to make an auto-numbered list - -# numbered list numbered list 1., 2., 3, etc. - -_# indented lettered list sub-level of previous list number a., b., c., d., etc. - -%% line breaks ----------------------------------------------------------------- - -<:br> line break - -In paper/ page oriented outputs, such as LaTeX/pdf the following are avaiable - -<:pb> page or column break - -<:pn> new page - -in the header section under @make: :breaks: new and break set a page break or -new page at the levels indicated, e.g. - -@make: - :breaks: new=C; break=1 - -%% footnotes / endnotes -------------------------------------------------------- - -This paragraph contains a footnote~{ a footnote or endnote }~ which would be -automatically numbered - -Footnotes and endnotes are marked up at the location where they would be -indicated within a text. They are automatically numbered. The output type -determines whether footnotes or endnotes will be produced - -In addition to regular footnotes/endnotes there are astrisk and plus sign -numbered and unnumbered footnotes. - -normal text ~[* editors notes, numbered asterisk footnote/endnote series ]~ continues - -normal text ~[+ editors notes, numbered asterisk footnote/endnote series ]~ continues - -normal text ~{* unnumbered asterisk footnote/endnote, insert multiple asterisks if required }~ continues - -%% tag points ------------------------------------------------------------------ - -Tag points are markers within the document which may be used within the -document for (internal document) linking where the output format permits. Tag -names should use alphanumeric characters and underscores [a-z0-9_]+. - -There are different types of tag point, some automatically provided by sisu, -such as each ocn (object citation number) - -Manual tags may be provided either: - -(a) with headings where a name is added to the heading level after the tilde: - -1~prefix [heading] - -(b) a tag marker can be added to a paragraph using an asterisk tilde and the -name *~tag_marker - -%% links and urls -------------------------------------------------------------- - -Urls found within text are marked up automatically, and where the output type -permits is autmatically hyperlinked to inself and decorated with angled braces -(unless contained in a code block, or escaped by a preceeding underscore). - -To link text or an image to a url the markup is as follows - -{ this is the linked section of text}http://url.org - -Where it is wished to include the url for the linked text in a footnote, the -long form of markup would be: -{ SiSU }http://www.jus.uio.no/sisu/ ~{ http://www.jus.uio.no/sisu/ }~ - -A short form is provided for achieving the same: - {~^ SiSU }http://www.jus.uio.no/sisu/ - -%% images ---------------------------------------------------------------------- - -Images are placed in the directory beneath the location of the document to be -processed _sisu/image - -The following are examples of links to images - -{ tux.png 64x80 }image - -{tux.png 64x80 "Gnu/Linux - a better way" }http://www.jus.uio.no/sisu/ - -{GnuDebianLinuxRubyBetterWay.png 100x101 "Way Better - with Gnu/Linux, Debian and Ruby" }http://www.jus.uio.no/sisu/ - -The 64x80 in the first example is the image dimension, (width x height). This -may be omitted if imagemagick or graphicsmagick are installed, as they will -determine the image dimensions - -As with other linked text, the following markup - -{~^ ruby_logo.png "Ruby" }http://www.ruby-lang.org/en/ - -maps to - -{ ruby_logo.png "Ruby" }http://www.ruby-lang.org/en/ ~{ http://www.ruby-lang.org/en/ }~ - -%% grouped text ---------------------------------------------------------------- - -%% group ----------------------------------------------------------------------- - -The start and end of text that is grouped are tagged. Grouped text retains its -line breaks, and is treated as a unit, getting a single ocn - -group{ - -License: GPL 3 or later: - -SiSU, a framework for document structuring, publishing and search - -Copyright (C) Ralph Amissah - -This program is free software: you can redistribute it and/or modify it under -the terms of the GNU General Public License as published by the Free Software -Foundation, either version 3 of the License, or (at your option) any later -version. - -This program is distributed in the hope that it will be useful, but WITHOUT ANY -WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A -PARTICULAR PURPOSE. See the GNU General Public License for more details. - -You should have received a copy of the GNU General Public License along with -this program. If not, see <http://www.gnu.org/licenses/>. - -If you have Internet connection, the latest version of the GPL should be -available at these locations: -<http://www.fsf.org/licensing/licenses/gpl.html> -<http://www.gnu.org/licenses/gpl.html> - -}group - -%% poem ------------------------------------------------------------------------ - -The start and end of a poem are tagged. Each verse in a poem is given an object -number. Verses retain their line breaks. - -poem{ - -verse here -declare - -another verse -here - -}poem - -%% table ----------------------------------------------------------------------- - -{table~h 24; 12; 12; 12; 12; 12; 12;} - |Jan. 2001|Jan. 2002|Jan. 2003|Jan. 2004|July 2004|June 2006 -Contributors* | 10| 472| 2,188| 9,653| 25,011| 48,721 -Active contributors** | 9| 212| 846| 3,228| 8,442| 16,945 -Very active contributors*** | 0| 31| 190| 692| 1,639| 3,016 -No. of English language articles| 25| 16,000| 101,000| 190,000| 320,000| 630,000 -No. of articles, all languages | 25| 19,000| 138,000| 490,000| 862,000|1,600,000 - - -table{ c3; 40; 30; 30; - -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 - -}table - -a second form may be easier to work with in cases where there is not much information in each column - -%% code ------------------------------------------------------------------------ - -code{ - -code lines here - -and so on - -}code - -%% headers --------------------------------------------------------------------- - -%% header metadata ------------------------------------------------------------- - -@title: SiSU - :subtitle: Markup - -@creator: - :author: Amissah, Ralph - -@rights: - :copyright: Copyright (C) Ralph Amissah 2007, part of SiSU documentation - :license: GPL 3 or later - -@classify: - :type: information - :topic_register: electronic documents:SiSU:document:markup;SiSU:document:markup;SiSU:document:markup;SiSU:manual:markup;electronic documents:SiSU:manual:markup - :subject: ebook, epublishing, electronic book, electronic publishing, electronic document, electronic citation, data structure, citation systems, search - -@date: - :created: 2002-08-28 - :issued: 2002-08-28 - :available: 2002-08-28 - :published: 2008-05-22 - :modified: 2010-05-25 - -@links: - { SiSU Manual }http://www.jus.uio.no/sisu/sisu_manual/ - { Book Samples and Markup Examples }http://www.jus.uio.no/SiSU/examples.html - { SiSU @ Wikipedia }http://en.wikipedia.org/wiki/SiSU - { SiSU Download }http://www.jus.uio.no/sisu/SiSU/download.html - { SiSU Changelog }http://www.jus.uio.no/sisu/SiSU/changelog.html - -%% header processing instructions, @make: -------------------------------------- - -Some document processing parameters can be set in the @make: section of the header - -@make: - :num_top: 1 - :breaks: new=C; break=1 - :skin: skin_sisu_manual - :bold: /Gnu|Debian|Ruby|SiSU/ - -%% config, sisurc.yml ---------------------------------------------------------- - -There are default configuration settings within the program many of which can -be modified in sisurc.yml - -sisurc.yml can be located in one of the following locations: -/etc/sisu/sisurc.yml ~/.sisu/sisurc.yml and ./_sisu/sisurc.yml - -if sisu versions 1 and 2 are both in use, the v2 sisurc.yml can be placed a the -following locations: -/etc/sisu/v2/sisurc.yml ~/.sisu/v2/sisurc.yml and ./_sisu/v2/sisurc.yml - -# Name: SiSU - Simple information Structuring Universe -# Author: Ralph@Amissah.com -# Description: Site wide envionment defaults set here -# system environment info / resource configuration file, for sisu -# License: GPL v3 or later -# site environment configuration file -# this file should be configured and live in -# /etc/sisu #per environment settings, overridden by: -# ~/.sisu #per user settings, overridden by: -# ./_sisu #per local markup directory settings -#% #image source directory, main path and subdirectories -#image: -# path: 'sisu_working' -# public: '_sisu/image' -#% presentation/web directory, main path and subdirectories (most subdirectories are created automatically based on markup directory name) -#webserv: -# url_root: 'http://www.your.url' #without dir stub -# path: '/var/www' #either (i) / [full path from root] or (ii) ~/ [home] or (iii) ./ [pwd] or (iv) will be made from home -# images: '_sisu/image' -# man: 'man' -# cgi: '/usr/lib/cgi-bin' -# feed: 'feed' -# sqlite: 'sisu/sqlite' -# webrick_url: true -#show_output_on: 'filesystem' #for -v and -u url information, alternatives: 'filesystem','webserver','remote_webserver','local:8111','localhost','localhost:8080','webrick','path' -#show_output_on: 'local:8111' -#webserv_cgi: -# host: localhost -# base_path: ~ -# port: '8081' -# user: ~ -show_output_on: 'filesystem_url' -#texinfo display output -#texinfo: -# stub: 'texinfo' -##% processing directories, main path and subdirectories (appended to $HOME), using defaults set in sysenv -#processing: -# path: '~' -# dir: '.sisu_processing~' -# metaverse: 'metaverse' -# tune: 'tune' -# latex: 'tex' -# texinfo: 'texinfo' -# concord_max: 400000 -#% flag - set (non-default) processing flag shortcuts -1, -2 etc. (here adding colour and verbosity as default) -flag: - color: true # making colour default -c is toggle, and will now toggle colour off - default: '-NhwepoabxXyYv' # -m run by default; includes verbose - i: '-hwpoay' # -m run by default - ii: '-NhwepoabxXy' # -m run by default - iii: '-NhwepoabxXyY' # -m run by default - iv: '-NhwepoabxXYDy --update' # -m run by default - v: '-NhwepoabxXYDyv --update' # -m run by default; includes verbose -#% papersize, (LaTeX/pdf) available values: A4, US_letter, book_b5, book_a5, US_legal -default: - papersize: 'A4,letter' - #text_wrap: 78 - #emphasis: 'bold' #make *{emphasis}* 'bold', 'italics' or 'underscore', default if not configured is 'bold' - #digest: 'sha' #sha is sha256, default is md5 - #multilingual: false - #language_file: 2 - #language: 'English' -#% markup, make *{emphasis}* 'bold' or 'italics', default if not configured is 'bold' -#% settings used by ssh scp -#remote: -# - -# user: '[usrname]' -# host: '[remote.hostname]' -# path: '.' #no trailing slash eg 'sisu/www' -# - -# user: '[usrname]' -# host: '[remote.hostname]' -# path: '.' #no trailing slash eg 'sisu/www' -#% webrick information -#webrick: -# port: '8081' -#% sql database info, postgresql and sqlite -#db: -# share_source: false # boolean, default is false -# postgresql: -# port: # '[port (default is 5432)]' -# host: # '[if not localhost, provide host tcp/ip address or domain name]'' -# user: # '[(if different from user) provide username]' -# password: # '[password if required]' -# sqlite: -# path: ~ # './sisu_sqlite.db' -# port: "**" -#% possible values ~, true, false, or command instruction e.g. editor: 'gvim -c :R -c :S'. -#will only ignore if value set to false, absence or nil will not remove program as should operate without rc file -#ie in case of ~ will ignore and use hard coded defaults within program), true, false, or command instruction e.g. editor: 'gvim -c :R -c :S' -#on value true system defaults used, to change, e.g. editor specify -permission_set: - zap: false - css_modify: false -# remote_base_site: true -program_set: - rmagick: false -# wc: true -# editor: true -# postgresql: true -# sqlite: true -# tidy: true -# rexml: true -# pdflatex: true -#program_select: -# editor: 'gvim -c :R -c :S' -# pdf_viewer: 'evince' -# web_browser: 'firefox' #'iceweasel' #'epiphany' #'galeon' #'konqueror' #'kazehakase' -# console_www_browser: 'links2' #'elinks' -# odf_viewer: 'oowriter' #'abiword' -# xml_viewer: 'xml-viewer' -# man: 'nroff -man' #'groff -man -Tascii' # 'nroff -man' -#promo: sisu_icon, sisu, sisu_search_libre, open_society, fsf, ruby -#search: -# sisu: -# flag: true -## action: http://localhost:8081/cgi-bin/sisu_pgsql.cgi -# action: http://search.sisudoc.org -# db: sisu -# title: sample search form -# hyperestraier: -# flag: true -# action: http://search.sisudoc.org/cgi-bin/estseek.cgi? - - -%% skin ------------------------------------------------------------------------ - -skins can be used to modify the appearance of output - -[provide information] - -%% css ------------------------------------------------------------------------ - -the default css may be replaced for the site or particular processing -directories - -[provide information] |