From 50d45c6deb0afd2e4222d2e33a45487a9d1fa676 Mon Sep 17 00:00:00 2001 From: Ralph Amissah Date: Sun, 23 Sep 2007 05:16:21 +0100 Subject: primarily todo with sisu documentation, changelog reproduced below: * start documenting sisu using sisu * sisu markup source files in data/doc/sisu/sisu_markup_samples/sisu_manual/ /usr/share/doc/sisu/sisu_markup_samples/sisu_manual/ * default output [sisu -3] in data/doc/manuals_generated/sisu_manual/ /usr/share/doc/manuals_generated/sisu_manual/ (adds substantially to the size of sisu package!) * help related edits * manpage, work on ability to generate manpages, improved * param, exclude footnote mark count when occurs within code block * plaintext changes made * shared_txt, line wrap visited * file:// link option introduced (in addition to existing https?:// and ftp://) a bit arbitrarily, diff here, [double check changes in sysenv and hub] * minor adjustments * html url match refinement * css added tiny_center * plaintext * endnotes fix * footnote adjustment to make more easily distinguishable from substantive text * flag -a only [flags -A -e -E dropped] controlled by modifiers --unix/msdos --footnote/endnote * defaults, homepage * renamed homepage (instead of index) implications for modifying skins, which need likewise to have any homepage entry renamed * added link to sisu_manual in homepage * css the css for the default homepage is renamed homepage.css (instead of index.css) [consider removing this and relying on html.css] * ruby version < ruby1.9 * place stop on installation and working with for now [ruby String.strip broken in ruby 1.9.0 (2007-09-10 patchlevel 0) [i486-linux], 2007-09-18:38/2] * debian/control restrict use to ruby > 1.8.4 and ruby < 1.9 * debian * debian/control restrict use to ruby > 1.8.4 and ruby < 1.9 * sisu-doc new sub-package for sisu documentation debian/control and sisu-doc.install --- man/man1/sisu_markup.1 | 1532 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1532 insertions(+) create mode 100644 man/man1/sisu_markup.1 (limited to 'man/man1/sisu_markup.1') diff --git a/man/man1/sisu_markup.1 b/man/man1/sisu_markup.1 new file mode 100644 index 00000000..474c67d8 --- /dev/null +++ b/man/man1/sisu_markup.1 @@ -0,0 +1,1532 @@ +.TH "sisu_markup" "1" "2007-09-16" "0.58.3" "SiSU" +.SH +SISU \- MARKUP \ [0.58], +RALPH AMISSAH +.BR + +.SH +SISU MARKUP +.BR + +.SH +1. INTRODUCTION TO SISU MARKUP[^1] +.BR + +.SH +1.1 SUMMARY + +.BR +.B SiSU +source documents are plaintext (UTF\-8)[^2] files + +.BR +All paragraphs are separated by an empty line. + +.BR +Markup is comprised of: + +.BR +* at the top of a document, the document header made up of semantic meta\-data +about the document and if desired additional processing instructions (such an +instruction to automatically number headings from a particular level down) + +.BR +* followed by the prepared substantive text of which the most important single +characteristic is the markup of different heading levels, which define the +primary outline of the document structure. Markup of substantive text includes: + +.BR + * heading levels defines document structure + +.BR + * text basic attributes, italics, bold etc. + +.BR + * grouped text (objects), which are to be treated differently, such as code + blocks or poems. + +.BR + * footnotes/endnotes + +.BR + * linked text and images + +.BR + * paragraph actions, such as indent, bulleted, numbered\-lists, etc. + +.BR +Some interactive help on markup is available, by typing sisu and selecting +markup or sisu \-\-help markup + +.SH +1.2 MARKUP EXAMPLES + +.SH +1.2.1 ONLINE + +.BR +Online markup examples are available together with the respective outputs +produced from or from + + +.BR +There is of course this document, which provides a cursory overview of sisu +markup and the respective output produced: + + +.BR +Some example marked up files are available as html with syntax highlighting for +viewing: + +.BR +an alternative presentation of markup syntax: + + +.SH +1.2.2 INSTALLED + +.BR +With +.B SiSU +installed sample skins may be found in: +/usr/share/doc/sisu/sisu_markup_samples/dfsg (or equivalent directory) and if +sisu\-markup\-samples is installed also under: +/usr/share/doc/sisu/sisu_markup_samples/non\-free + +.SH +2. MARKUP OF HEADERS +.BR + +.BR +Headers consist of semantic meta\-data about a document, which can be used by +any output module of the program; and may in addition include extra processing +instructions. + +.BR +Note: the first line of a document may include information on the markup +version used in the form of a comment. Comments are a percentage mark at the +start of a paragraph (and as the first character in a line of text) followed by +a space and the comment: + + +.nf + % this would be a comment +.fi + +.SH +2.1 SAMPLE HEADER + +.BR +This current document has a header similar to this one (without the comments): + + +.nf + % SiSU 0.57 + @title: SiSU + @subtitle: Markup \ [0.58] + @creator: Ralph Amissah + @rights: Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL 3 + @type: information + @subject: ebook, epublishing, electronic book, electronic publishing, electronic document, electronic citation, data structure, citation systems, search + @date.created: 2002\-08\-28 + @date.issued: 2002\-08\-28 + @date.available: 2002\-08\-28 + @date.modified: 2007\-09\-16 + @date: 2007\-09\-16 + @level: new=C; break=1; num_top=1 + % comment: in this @level header num_top=1 starts automatic heading numbering at heading level 1 (numbering continues 3 levels down); the new and break instructions are used by the LaTeX/pdf and odf output to determine where to put page breaks (that are not used by html output or say sql database population). + @skin: skin_sisu_manual + % skins modify the appearance of a document and are placed in a sub\-directory under ./_sisu/skin ~/.sisu/skin or /etc/sisu/skin. A skin may affect single documents that request them, all documents in a directory, or be site\-wide. (A document is affected by a single skin) + @bold: /Gnu|Debian|Ruby|SiSU/ + @links: { SiSU Manual }http://www.jus.uio.no/sisu/sisu_manual/ + { Book Samples and Markup Examples }http://www.jus.uio.no/sisu/SiSU/2.html + { SiSU @ Wikipedia }http://en.wikipedia.org/wiki/SiSU + { SiSU @ Freshmeat }http://freshmeat.net/projects/sisu/ + { SiSU @ Ruby Application Archive }http://raa.ruby\-lang.org/project/sisu/ + { SiSU @ Debian }http://packages.qa.debian.org/s/sisu.html + { SiSU Download }http://www.jus.uio.no/sisu/SiSU/download.html + { SiSU Changelog }http://www.jus.uio.no/sisu/SiSU/changelog.html +.fi + +.SH +2.2 AVAILABLE HEADERS + +.BR +Header tags appear at the beginning of a document and provide meta information +on the document (such as the Dublin Core), or information as to how the +document as a whole is to be processed. All header instructions take either the +form @headername: or 0~headername. All Dublin Core meta tags are available + +.BR +.B @indentifier: +information or instructions + +.BR +where the \"identifier\" is a tag recognised by the program, and the +\"information\" or \"instructions\" belong to the tag/indentifier specified + +.BR +Note: a header where used should only be used once; all headers apart from +@title: are optional; the @structure: header is used to describe document +structure, and can be useful to know. + +.BR +This is a sample header + +.BR +.B % SiSU 0.38 +\ [declared \ file\-type \ identifier \ with \ markup \ version] + +.BR +.B @title: +\ [title \ text] This is the title of the document and used as such, this +header is the only one that is +.I mandatory + +.BR +.B @subtitle: +The Subtitle if any + +.BR +.B @creator: +\ [or \ @author:] Name of Author + +.BR +.B @subject: +(whatever your subject) + +.BR +.B @description: + +.BR +.B @publisher: + +.BR +.B @contributor: + +.BR +.B @translator: +\ [or \ @translated_by:] + +.BR +.B @illustrator: +\ [or \ @illustrated_by:] + +.BR +.B @prepared_by: +\ [or \ @digitized_by:] + +.BR +.B @date: 2000\-08\-27 +\ [ \ also \ @date.created: \ @date.issued: \ @date.available: \ @date.valid: +\ @date.modified: \ ] + +.BR +.B @type: article + +.BR +.B @format: + +.BR +.B @identifier: + +.BR +.B @source: + +.BR +.B @language: +\ [or \ @language.document:] \ [country \ code \ for \ language \ if \ +available, \ or \ language, \ English, \ en \ is \ the \ default \ setting] (en +\- English, fr \- French, de \- German, it \- Italian, es \- Spanish, pt \- +Portuguese, sv \- Swedish, da \- Danish, fi \- Finnish, no \- Norwegian, is \- +Icelandic, nl \- Dutch, et \- Estonian, hu \- Hungarian, pl \- Polish, ro \- +Romanian, ru \- Russian, el \- Greek, uk \- Ukranian, tr \- Turkish, sk \- +Slovak, sl \- Slovenian, hr \- Croatian, cs \- Czech, bg \- Bul garian ) \ +[however, \ encodings \ are \ not \ available \ for \ all \ of \ the \ +languages \ listed.] + +.BR +[@language.original: \ original \ language \ in \ which \ the \ work \ was \ +published] + +.BR +.B @papersize: +(A4|US_letter|book_B5|book_A5|US_legal) + +.BR +.B @relation: + +.BR +.B @coverage: + +.BR +.B @rights: +Copyright (c) Name of Right Holder, all rights reserved, or as granted: +public domain, copyleft, creative commons variant, etc. + +.BR +.B @owner: + +.BR +.B @keywords: +text document generation processing management latex pdf structured xml +citation \ [your \ keywords \ here, \ used \ for \ example \ by \ rss \ feeds, +\ and \ in \ sql \ searches] + +.BR +.B @abstract: +\ [paper \ abstract, \ placed \ after \ table \ of \ contents] + +.BR +.B @comment: +\ [...] + +.BR +.B @catalogue: +loc=[Library \ of \ Congress \ classification]; dewey=[Dewey \ +classification]; isbn=[ISBN]; pg=[Project \ Gutenberg \ text \ number] + +.BR +.B @classify_loc: +\ [Library \ of \ Congress \ classification] + +.BR +.B @classify_dewey: +\ [Dewey \ classification] + +.BR +.B @classify_isbn: +\ [ISBN] + +.BR +.B @classify_pg: +\ [Project \ Gutenberg \ text \ number] + +.BR +.B @prefix: +\ [prefix \ is \ placed \ just \ after \ table \ of \ contents] + +.BR +.B @prefix_a: +\ [prefix \ is \ placed \ just \ before \ table \ of \ contents \ \- \ not \ +implemented] + +.BR +.B @prefix_b: + +.BR +.B @rcs: +$Id: sisu_markup.sst,v 1.2 2007/09/08 17:12:47 ralph Exp $ \ [used \ by \ rcs +\ or \ cvs \ to \ embed \ version \ (revision \ control) \ information \ into \ +document, \ rcs \ or \ cvs \ can \ usefully \ provide \ a \ history \ of \ +updates \ to \ a \ document \ ] + +.BR +.B @structure: +PART; CHAPTER; SECTION; ARTICLE; none; none; +optional, document structure can be defined by words to match or regular +expression (the regular expression is assumed to start at the beginning of a +line of text i.e. ^) default markers :A~ to :C~ and 1~ to 6~ can be used within +text instead, without this header tag, and may be used to supplement the +instructions provided in this header tag if provided (@structure: is a synonym +for @toc:) + +.BR +.B @level: +newpage=3; breakpage=4 +\ [paragraph \ level, \ used \ by \ latex \ to \ breakpages, \ the \ page \ +is \ optional \ eg. \ in \ newpage] + +.BR +.B @markup: +information on the markup used, e.g. new=1,2,3; break=4; num_top=4 \ [or \ +newpage=1,2,3; \ breakpage=4; \ num_top=4] newpage and breakpage, heading +level, used by LaTeX to breakpages. breakpage: starts on a new page in single +column text and on a new column in double column text; newpage: starts on a new +page for both single and double column texts. +num_top=4 \ [auto\-number \ document, \ starting \ at \ level \ 4. \ the \ +default \ is \ to \ provide \ 3 \ levels, \ as \ in \ 1 \ level \ 4, \ 1.1 \ +level \ 5, \ 1.1.1 \ level \ 6, \ markup \ to \ be \ merged \ within \ level] +num_extract \ [take \ numbering \ of \ headings \ provided \ (manually \ in \ +marked \ up \ source \ document), \ and \ use \ for \ numbering \ of \ +segments. \ Available \ where \ a \ clear \ numbering \ structure \ is \ +provided \ within \ document, \ without \ the \ repetition \ of \ a \ number \ +in \ a \ header.] \ [In \ 0.38 \ notation, \ you \ would \ map \ to \ the \ +equivalent \ levels, \ the \ examples \ provided \ would \ map \ to \ the \ +following \ new=A,B,C; \ break=1; \ num_top=1 \ \ [or \ newpage=A,B,C; \ +breakpage=1; \ num_top=1] see headings] + +.BR +.B @bold: +\ [regular \ expression \ of \ words/phrases \ to \ be \ made \ bold] + +.BR +.B @italics: +\ [regular \ expression \ of \ words/phrases \ to \ italicise] + +.BR +.B @vocabulary: +name of taxonomy/vocabulary/wordlist to use against document + +.BR +.B @skin: +skin_doc_[name_of_desired_document_skin] +skins change default settings related to the appearance of documents +generated, such as the urls of the home site, and the icon/logo for the +document or site. + +.BR +.B @links: +{ +.B SiSU +}http://www.jus.uio.no/sisu/; +{ FSF }http://www.fsf.org + +.BR +.B @promo: +sisu, ruby, search_libre_docs, open_society +\ [places \ content \ in \ right \ pane \ in \ html, \ makes \ use \ of \ +list.yml \ and \ promo.yml, \ commented \ out \ sample \ in \ document \ +sample: \ +free_as_in_freedom.richard_stallman_crusade_for_free_software.sam_williams.sst] + +.SH +3. MARKUP OF SUBSTANTIVE TEXT +.BR + +.SH +3.1 HEADING LEVELS + +.BR +Heading levels are :A~ ,:B~ ,:C~ ,1~ ,2~ ,3~ ... :A \- :C being part / section +headings, followed by other heading levels, and 1 \-6 being headings followed +by substantive text or sub\-headings. :A~ usually the title :A~? conditional +level 1 heading (used where a stand\-alone document may be imported into +another) + +.BR +.B :A~ \ [heading \ text] +Top level heading \ [this \ usually \ has \ similar \ content \ to \ the \ +title \ @title: \ ] NOTE: the heading levels described here are in 0.38 +notation, see heading + +.BR +.B :B~ \ [heading \ text] +Second level heading \ [this \ is \ a \ heading \ level \ divider] + +.BR +.B :C~ \ [heading \ text] +Third level heading \ [this \ is \ a \ heading \ level \ divider] + +.BR +.B 1~ \ [heading \ text] +Top level heading preceding substantive text of document or sub\-heading 2, +the heading level that would normally be marked 1. or 2. or 3. etc. in a +document, and the level on which sisu by default would break html output into +named segments, names are provided automatically if none are given (a number), +otherwise takes the form 1~my_filename_for_this_segment + +.BR +.B 2~ \ [heading \ text] +Second level heading preceding substantive text of document or sub\-heading +3, the heading level that would normally be marked 1.1 or 1.2 or 1.3 or 2.1 +etc. in a document. + +.BR +.B 3~ \ [heading \ text] +Third level heading preceding substantive text of document, that would +normally be marked 1.1.1 or 1.1.2 or 1.2.1 or 2.1.1 etc. in a document + + +.nf + 1~filename level 1 heading, + % 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) +.fi + +.SH +3.2 FONT ATTRIBUTES + +.BR +.B markup example: + + +.nf + normal text !{emphasis}! *{bold text}* _{underscore}_ /{italics}/ \"{citation}\" ^{superscript}^ ,{subscript}, +{inserted text}+ + normal text + !{emphasis}! + *{bold text}* + _{underscore} + /{italics}/ + \"{citation}\" + ^{superscript}^ + ,{subscript}, + +{inserted text}+ + \-{strikethrough}\- +.fi + +.BR +.B resulting output: + +.BR +normal text emphasis +.B bold text +.I underscore +.I italics +citation ^superscript^ \ [subscript] inserted text +strikethrough + +.BR +normal text + +.BR +emphasis + +.BR +.B bold text + +.BR +.I underscore + +.BR +.I italics + +.BR +citation + +.BR +^superscript^ + +.BR +[subscript] + +.BR +inserted text + +.BR +strikethrough + +.SH +3.3 INDENTATION AND BULLETS + +.BR +.B markup example: + + +.nf + ordinary paragraph + _1 indent paragraph one step + _2 indent paragraph two steps + _9 indent paragraph nine steps +.fi + +.BR +.B resulting output: + +.BR +ordinary paragraph + +.BR + indent paragraph one step + +.BR + indent paragraph two steps + +.BR + indent paragraph nine steps + +.BR +.B markup example: + + +.nf + * bullet text + _1* bullet text, first indent + _2* bullet text, two step indent +.fi + +.BR +.B resulting output: + +.BR +* bullet text + +.BR + * bullet text, first indent + +.BR + * bullet text, two step indent + +.BR +Numbered List (not to be confused with headings/titles, (document structure)) + +.BR +.B markup example: + + +.nf + # numbered list numbered list 1., 2., 3, etc. + _# numbered list numbered list indented a., b., c., d., etc. +.fi + +.SH +3.4 FOOTNOTES / ENDNOTES + +.BR +Footnotes and endnotes not distinguished in markup. They are automatically +numbered. Depending on the output file format (html, odf, pdf etc.), the +document output selected will have either footnotes or endnotes. + +.BR +.B markup example: + + +.nf + ~{ a footnote or endnote }~ +.fi + +.BR +.B resulting output: + +.BR +[^3] + +.BR +.B markup example: + + +.nf + normal text~{ self contained endnote marker & endnote in one }~ continues +.fi + +.BR +.B resulting output: + +.BR +normal text[^4] continues + +.BR +.B markup example: + + +.nf + normal text ~{* unnumbered asterisk footnote/endnote, insert multiple asterisks if required }~ continues + normal text ~{** another unnumbered asterisk footnote/endnote }~ continues +.fi + +.BR +.B resulting output: + +.BR +normal text \ [^*] continues + +.BR +normal text \ [^**] continues + +.BR +.B markup example: + + +.nf + normal text ~[* \ editors \ notes, \ numbered \ asterisk \ footnote/endnote \ series \ ]~ continues + normal text ~[+ \ editors \ notes, \ numbered \ asterisk \ footnote/endnote \ series \ ]~ continues +.fi + +.BR +.B resulting output: + +.BR +normal text \ [^*1] continues + +.BR +normal text \ [^+1] continues + +.BR +.B Alternative endnote pair notation for footnotes/endnotes: + + +.nf +.nf + % note the endnote marker \"~^\" + normal text~^ continues + ^~ endnote text following the paragraph in which the marker occurs +.fi + +.BR +the standard and pair notation cannot be mixed in the same document + +.SH +3.5 LINKS + +.SH +3.5.1 NAKED URLS WITHIN TEXT, DEALING WITH URLS + +.BR +urls are found within text and marked up automatically. A url within text is +automatically hyperlinked to itself and by default decorated with angled +braces, unless they are contained within a code block (in which case they are +passed as normal text), or escaped by a preceding underscore (in which case the +decoration is omitted). + +.BR +.B markup example: + + +.nf + normal text http://www.jus.uio.no/sisu continues +.fi + +.BR +.B resulting output: + +.BR +normal text continues + +.BR +An escaped url without decoration + +.BR +.B markup example: + + +.nf + normal text http://www.jus.uio.no/sisu continues + deb http://www.jus.uio.no/sisu/archive unstable main non\-free +.fi + +.BR +.B resulting output: + +.BR +normal text http://www.jus.uio.no/sisu continues + +.BR +deb http://www.jus.uio.no/sisu/archive unstable main non\-free + +.BR +where a code block is used there is neither decoration nor hyperlinking, code +blocks are discussed later in this document + +.BR +.B resulting output: + + +.nf + 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 +.fi + +.BR +To link text or an image to a url the markup is as follows + +.BR +.B markup example: + + +.nf + about { SiSU }http://url.org markup +.fi + +.SH +3.5.2 LINKING TEXT + +.BR +.B resulting output: + +.BR +about SiSU markup + +.BR +A shortcut notation is available so the url link may also be provided +automatically as a footnote + +.BR +.B markup example: + + +.nf + about {~^ SiSU }http://url.org markup +.fi + +.BR +.B resulting output: + +.BR +about SiSU \ [^5] markup + +.SH +3.5.3 LINKING IMAGES + +.BR +.B markup example: + + +.nf + [ tux.png ] + % various url linked images + [ tux.png ] + [ GnuDebianLinuxRubyBetterWay.png ] + {~^ ruby_logo.png \"Ruby\" }http://www.ruby\-lang.org/en/ +.fi + +.BR +.B resulting output: + +.BR +[ tux.png ] + +.BR +tux.png 64x80 \"Gnu/Linux \- a better way\" + +.BR +[ \ ruby_logo \ (png \ missing) \ ] \ [^6] + +.BR +GnuDebianLinuxRubyBetterWay.png 100x101 \"Way Better \- with Gnu/Linux, Debian +and Ruby\" + +.BR +.B linked url footnote shortcut + + +.nf + {~^ \ [text \ to \ link] }http://url.org + % maps to: { \ [text \ to \ link] }http://url.org ~{ http://url.org }~ + % which produces hyper\-linked text within a document/paragraph, with an endnote providing the url for the text location used in the hyperlink +.fi + + +.nf + text marker *~name +.fi + +.BR +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. + +.SH +3.6 GROUPED TEXT + +.SH +3.6.1 TABLES + +.BR +Tables may be prepared in two either of two forms + +.BR +.B markup example: + + +.nf + 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 +.fi + +.BR +.B resulting output: + + \ [table \ omitted, \ see \ other \ document \ formats] + +.BR +a second form may be easier to work with in cases where there is not much +information in each column + +.BR +.B markup example: +[^7] + + +.nf + !_ Table 3.1: Contributors to Wikipedia, January 2001 \- June 2005 + {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 + \* Contributed at least ten times; \** at least 5 times in last month; \*\** more than 100 times in last month. +.fi + +.BR +.B resulting output: + +.BR +.B Table 3.1: Contributors to Wikipedia, January 2001 \- June 2005 + + \ [table \ omitted, \ see \ other \ document \ formats] + +.BR +* Contributed at least ten times; ** at least 5 times in last month; *** more +than 100 times in last month. + +.SH +3.6.2 POEM + +.BR +.B basic markup: + + +.nf + poem{ + Your poem here + }poem + Each verse in a poem is given a separate object number. +.fi + +.BR +.B markup example: + + +.nf + poem{ + \'Fury said to a + mouse, That he + met in the + house, + \"Let us + both go to + law: I will + prosecute + YOU. \-\-Come, + I\'ll take no + denial; We + must have a + trial: For + really this + morning I\'ve + nothing + to do.\" + Said the + mouse to the + cur, \"Such + a trial, + dear Sir, + With + no jury + or judge, + would be + wasting + our + breath.\" + \"I\'ll be + judge, I\'ll + be jury,\" + Said + cunning + old Fury: + \"I\'ll + try the + whole + cause, + and + condemn + you + to + death.\"\' + }poem +.fi + +.BR +.B resulting output: + + + \'Fury said to a +.P + mouse, That he +.P + met in the +.P + house, +.P + \"Let us +.P + both go to +.P + law: I will +.P + prosecute +.P + YOU. \-\-Come, +.P + I\'ll take no +.P + denial; We +.P + must have a +.P + trial: For +.P + really this +.P + morning I\'ve +.P + nothing +.P + to do.\" +.P + Said the +.P + mouse to the +.P + cur, \"Such +.P + a trial, +.P + dear Sir, +.P + With +.P + no jury +.P + or judge, +.P + would be +.P + wasting +.P + our +.P + breath.\" +.P + \"I\'ll be +.P + judge, I\'ll +.P + be jury,\" +.P + Said +.P + cunning +.P + old Fury: +.P + \"I\'ll +.P + try the +.P + whole +.P + cause, +.P + and +.P + condemn +.P + you +.P + to +.P + death.\"\' +.P + +.SH +3.6.3 GROUP + +.BR +.B basic markup: + + +.nf + group{ + Your grouped text here + }group + A group is treated as an object and given a single object number. +.fi + +.BR +.B markup example: + + +.nf + group{ + \'Fury said to a + mouse, That he + met in the + house, + \"Let us + both go to + law: I will + prosecute + YOU. \-\-Come, + I\'ll take no + denial; We + must have a + trial: For + really this + morning I\'ve + nothing + to do.\" + Said the + mouse to the + cur, \"Such + a trial, + dear Sir, + With + no jury + or judge, + would be + wasting + our + breath.\" + \"I\'ll be + judge, I\'ll + be jury,\" + Said + cunning + old Fury: + \"I\'ll + try the + whole + cause, + and + condemn + you + to + death.\"\' + }group +.fi + +.BR +.B resulting output: + + + \'Fury said to a +.P + mouse, That he +.P + met in the +.P + house, +.P + \"Let us +.P + both go to +.P + law: I will +.P + prosecute +.P + YOU. \-\-Come, +.P + I\'ll take no +.P + denial; We +.P + must have a +.P + trial: For +.P + really this +.P + morning I\'ve +.P + nothing +.P + to do.\" +.P + Said the +.P + mouse to the +.P + cur, \"Such +.P + a trial, +.P + dear Sir, +.P + With +.P + no jury +.P + or judge, +.P + would be +.P + wasting +.P + our +.P + breath.\" +.P + \"I\'ll be +.P + judge, I\'ll +.P + be jury,\" +.P + Said +.P + cunning +.P + old Fury: +.P + \"I\'ll +.P + try the +.P + whole +.P + cause, +.P + and +.P + condemn +.P + you +.P + to +.P + death.\"\' +.P + +.SH +3.6.4 CODE + +.BR +Code tags are used to escape regular sisu markup, and have been used +extensively within this document to provide examples of +.B SiSU +markup. You cannot however use code tags to escape code tags. They are +however used in the same way as group or poem tags. + +.BR +A code\-block is treated as an object and given a single object number. \ [an \ +option \ to \ number \ each \ line \ of \ code \ may \ be \ considered \ at \ +some \ later \ time] + +.BR +.B use of code tags instead of poem compared, resulting output: + + +.nf + \'Fury said to a + mouse, That he + met in the + house, + \"Let us + both go to + law: I will + prosecute + YOU. \-\-Come, + I\'ll take no + denial; We + must have a + trial: For + really this + morning I\'ve + nothing + to do.\" + Said the + mouse to the + cur, \"Such + a trial, + dear Sir, + With + no jury + or judge, + would be + wasting + our + breath.\" + \"I\'ll be + judge, I\'ll + be jury,\" + Said + cunning + old Fury: + \"I\'ll + try the + whole + cause, + and + condemn + you + to + death.\"\' +.fi + +.SH +4. COMPOSITE DOCUMENTS MARKUP +.BR + +.BR +It is possible to build a document by creating a master document that requires +other documents. The documents required may be complete documents that could be +generated independently, or they could be markup snippets, prepared so as to be +easily available to be placed within another text. If the calling document is a +master document (built from other documents), it should be named with the +suffix +.B .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 +.B .sst +regular markup file, or +.B .ssi +(insert/information) A secondary file of the composite document is built +prior to processing with the same prefix and the suffix +.B ._sst + +.BR +basic markup for importing a document into a master document + + +.nf + << |filename1.sst|@|^| + << |filename2.ssi|@|^| +.fi + +.BR +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. Alternative markup for importation of +documents under consideration, and occasionally supported have been. + + +.nf + r{filename} + {filename.ssi}require + << {filename.ssi} + % using textlink alternatives + |filename.ssi|@|^|require + << |filename.ssi|@|^| + % using thlnk alternatives + require + << +.fi + +.SH +MARKUP SYNTAX HISTORY +.BR + +.SH +5. NOTES RELATED TO FILES\-TYPES AND MARKUP SYNTAX +.BR + +.BR +0.38 is substantially current, depreciated 0.16 supported, though file names +were changed at 0.37 + +.BR +.B 0.52 +(2007w14/6) declared document type identifier at start of text/document: + +.BR + .B SiSU +0.52 + +.BR +or, backward compatible using the comment marker: + +.BR + % +.B SiSU +0.38 + +.BR +variations include \' +.B SiSU +(text|master|insert) \ [version]\' and \'sisu\-[version]\' + +.BR +.B 0.51 +(2007w13/6) skins changed (simplified), markup unchanged + +.BR +.B 0.42 +(2006w27/4) * (asterisk) type endnotes, used e.g. in relation to author + +.BR +.B 0.38 +(2006w15/7) introduced new/alternative notation for headers, e.g. @title: +(instead of 0~title), and accompanying document structure markup, +:A,:B,:C,1,2,3 (maps to previous 1,2,3,4,5,6) + +.BR +.B 0.37 +(2006w09/7) introduced new file naming convention, .sst (text), .ssm +(master), .ssi (insert), markup syntax unchanged + +.BR +.B 0.35 +(2005w52/3) sisupod, zipped content file introduced + +.BR +.B 0.23 +(2005w36/2) utf\-8 for markup file + +.BR +.B 0.22 +(2005w35/3) image dimensions may be omitted if rmagick is available to be +relied upon + +.BR +.B 0.20.4 +(2005w33/4) header 0~links + +.BR +.B 0.16 +(2005w25/2) substantial changes introduced to make markup cleaner, header +0~title type, and headings \ [1\-6]~ introduced, also percentage sign (%) at +start of a text line as comment marker + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ + + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- Markup \ [0.58] + +.BR +DC Creator: +.I Ralph Amissah + +.BR +DC Rights: +.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL +3 + +.BR +DC Type: +.I information + +.BR +DC Date created: +.I 2002\-08\-28 + +.BR +DC Date issued: +.I 2002\-08\-28 + +.BR +DC Date available: +.I 2002\-08\-28 + +.BR +DC Date modified: +.I 2007\-09\-16 + +.BR +DC Date: +.I 2007\-09\-16 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_markup.sst + +.BR +Filetype: +.I SiSU text 0.58 + +.BR +Sourcefile Digest, MD5(sisu_markup.sst)= +.I 643738c4b96d001d107e3ea72ba17a97 + +.BR +Skin_Digest: +MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +.I 20fc43cf3eb6590bc3399a1aef65c5a9 + +.BR +.B Generated + +.BR +Document (metaverse) last generated: +.I Sun Sep 23 01:13:59 +0100 2007 + +.BR +Generated by: +.I SiSU +.I 0.58.3 +of 2007w36/4 (2007\-09\-06) + +.BR +Ruby version: +.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux] + +.TP +.BI 1. +From sometime after SiSU 0.58 it should be possible to describe SiSU markup +using SiSU, which though not an original design goal is useful. +.TP +.BI 2. +files should be prepared using UTF-8 character encoding +.TP +.BI 3. +a footnote or endnote +.TP +.BI 4. +self contained endnote marker & endnote in one +.TP +.BI *. +unnumbered asterisk footnote/endnote, insert multiple asterisks if required +.TP +.BI **. +another unnumbered asterisk footnote/endnote +.TP +.BI *1. +editors notes, numbered asterisk footnote/endnote series +.TP +.BI +1. +editors notes, numbered asterisk footnote/endnote series +.TP +.BI 5. + +.TP +.BI 6. + +.TP +.BI 7. +Table from the Wealth of Networks by Yochai Benkler + + +.TP +Other versions of this document: +.TP +manifest: +.TP +html: +.TP +pdf: +.TP +pdf: +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_markup/sisu_markup.1 +.TP +at: +.TP +.TP +* Generated by: SiSU 0.58.3 of 2007w36/4 (2007-09-06) +.TP +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +.TP +* Last Generated on: Sun Sep 23 01:14:06 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu -- cgit v1.2.3