diff options
Diffstat (limited to 'data/doc/sisu/v2/on_sisu_markup/sisu_markup.txt')
| -rw-r--r-- | data/doc/sisu/v2/on_sisu_markup/sisu_markup.txt | 570 |
1 files changed, 570 insertions, 0 deletions
diff --git a/data/doc/sisu/v2/on_sisu_markup/sisu_markup.txt b/data/doc/sisu/v2/on_sisu_markup/sisu_markup.txt new file mode 100644 index 00000000..0af080c5 --- /dev/null +++ b/data/doc/sisu/v2/on_sisu_markup/sisu_markup.txt @@ -0,0 +1,570 @@ +%% 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] |