From 87a7cfcd56eed6746b1500c88df3fc3e76a81668 Mon Sep 17 00:00:00 2001 From: Ralph Amissah Date: Mon, 15 Sep 2008 21:52:19 -0400 Subject: various small fixes * html segments, name more accurately * rough description of how book index markup works * clean out book index from these outputs * book markup sample, free as in freedom, start doing book index, only letter "A" done so far * texpdf, url matching, special characters * # Please enter the commit message for your changes. --- data/doc/sisu/html/sisu.1.html | 1918 ++++++++++---------- ...lman_crusade_for_free_software.sam_williams.sst | 55 +- .../sisu_manual/sisu_markup.sst | 68 +- 3 files changed, 1097 insertions(+), 944 deletions(-) (limited to 'data') diff --git a/data/doc/sisu/html/sisu.1.html b/data/doc/sisu/html/sisu.1.html index f7b70fcd..1848611b 100644 --- a/data/doc/sisu/html/sisu.1.html +++ b/data/doc/sisu/html/sisu.1.html @@ -10,13 +10,13 @@

Name

sisu - documents: markup, structuring, publishing in multiple standard -formats, and search +formats, and search

Synopsis

sisu [-abcDdFHhIiMmNnopqRrSsTtUuVvwXxYyZz0-9] [filename/wildcard ] sisu [-Ddcv] [instruction] sisu [-CcFLSVvW] SISU - -MANUAL, RALPH AMISSAH -

WHAT IS SISU? -

1. INTRODUCTION - WHAT IS SISU? +MANUAL, RALPH AMISSAH +

WHAT IS SISU? +

1. INTRODUCTION - WHAT IS SISU?

SiSU is a framework for document structuring, publishing (in multiple open standard formats) and search, comprising of: (a) a lightweight document @@ -24,13 +24,13 @@ structure and presentation markup syntax; and (b) an accompanying engine for generating standard document format outputs from documents prepared in sisu markup syntax, which is able to produce multiple standard outputs (including the population of sql databases) that (can) share a common numbering -system for the citation of text within a document. +system for the citation of text within a document.

SiSU is developed under an open source, software libre license (GPL3). Its use case for development is to cope with medium to large document sets with evolving markup related technologies, which should be prepared once, and for which you want multiple output formats that can be updated and a common mechanism for cross-output-format -citation, and search. +citation, and search.

SiSU both defines a markup syntax and provides an engine that produces open standards format outputs from documents prepared with SiSU markup. From a single lightly prepared document sisu custom builds @@ -42,7 +42,7 @@ of representation of the document. Significantly SiSU markup is more spar than html and outputs which include html, LaTeX, landscape and portrait pdfs, Open Document Format (ODF), all of which can be added to and updated. SiSU is also able to populate SQL type databases at an object level, which -means that searches can be made with that degree of granularity. +means that searches can be made with that degree of granularity.

Source document preparation and output generation is a two step process: (i) document source is prepared, that is, marked up in sisu markup syntax and (ii) the @@ -59,14 +59,14 @@ by these documents and at these locations within each document). Document output formats share a common object numbering system for locating content. This is particularly suitable for works (finalized texts as opposed to works that are frequently changed or updated) for which it provides a fixed -means of reference of content. +means of reference of content.

In preparing a SiSU document you optionally provide semantic information related to the document in a document header, and in marking up the substantive text provide information on the structure of the document, primarily indicating heading levels and footnotes. You also provide information on basic text attributes where used. The rest is automatic, sisu from this information custom builds[^2] the different forms -of output requested. +of output requested.

SiSU works with an abstraction of the document based on its structure which is comprised of its structure (or frame)[^3] and the objects[^4] it contains, which enables SiSU to represent the document @@ -80,7 +80,7 @@ pages; and in publishing in different formats, html, landscape and portrait pdf etc. again page numbers are of no use to cite text in a manner that is relevant against the different output types. Dealing with documents at an object level together with object numbering also has implications for -search. +search.

One of the challenges of maintaining documents is to keep them in a format that would allow users to use them without depending on a proprietary software popular at the time. Consider the ease of dealing with legacy proprietary @@ -104,38 +104,38 @@ and the archival of documents), and existing output to be updated (html has evolved and the related module has been updated repeatedly over the years, presumably when the World Wide Web Consortium (w3c) finalises html 5 which is currently under development, the html module will again be updated -allowing all existing documents to be regenerated as html 5). +allowing all existing documents to be regenerated as html 5).

The document formats are written to the file-system and available for indexing by independent indexing tools, whether off the web like Google and Yahoo or on the site -like Lucene and Hyperestraier. +like Lucene and Hyperestraier.

SiSU also provides other features such as concordance files and document content certificates, and the working against an abstraction of document structure has further possibilities for the research and development of other document representations, the availability of objects is useful for example for topic maps and the commercial law thesaurus by Vikki Rogers and Al Krtizer, together with the flexibility -of SiSU offers great possibilities. +of SiSU offers great possibilities.

SiSU is primarily for published works, which can take advantage of the citation system to reliably reference its documents. SiSU works well in a complementary manner with such collaborative technologies as Wikis, which can take advantage of and be used to discuss -the substance of content prepared in SiSU +the substance of content prepared in SiSU

<http://www.jus.uio.no/sisu -> +>

2. -COMMANDS SUMMARY -

2.1 SYNOPSIS +COMMANDS SUMMARY +

2.1 SYNOPSIS

SiSU - Structured information, Serialized -Units - a document publishing system +Units - a document publishing system

sisu [  -abcDdFHhIiMmNnopqRrSsTtUuVvwXxYyZz0-9 - ] [  filename/  wildcard  ] -

sisu [  -Ddcv  ] [  instruction  ] + ] [  filename/  wildcard  ] +

sisu [  -Ddcv  ] [  instruction  ]

sisu [  -CcFLSVvW - ] + ]

Note: commands should be issued from within the directory that contains -the marked up files, cd to markup directory. -

2.2 DESCRIPTION +the marked up files, cd to markup directory. +

2.2 DESCRIPTION

SiSU SiSU is a document publishing system, that from a simple single marked-up document, produces multiple of output formats including: plaintext, html, LaTeX, @@ -143,8 +143,8 @@ pdf, xhtml, XML, info, and SQL (PostgreSQL and SQLite), which share numbered text objects ( structure information. For more see: <http://www.jus.uio.no/sisu > -

2.3 DOCUMENT PROCESSING COMMAND FLAGS -

+

2.3 DOCUMENT PROCESSING COMMAND FLAGS +

-a [filename/wildcard]
@@ -153,12 +153,12 @@ with Unix linefeeds and without markup, (object numbers are omitted), has footnotes at end of each paragraph that contains them [  -A  for  equivalent  dos  (linefeed)  output  file] [see  -e  for (Options include: --endnotes for endnotes --footnotes for footnotes at the end of each paragraph --unix for unix linefeed -(default) --msdos for msdos linefeed) +(default) --msdos for msdos linefeed)

-b [filename/wildcard]
produces xhtml/XML -output for browser viewing (sax parsing). +output for browser viewing (sax parsing).

-C [--init-site]
@@ -168,7 +168,7 @@ files such as css and dtd files are not updated if they already exist unless modifier is used). -C --init-site configure/initialise site more extensive than -C on its own, shared output directory files/force update, existing shared output config files such as css and dtd files are updated if this modifier -is used. +is used.

-CC
@@ -177,7 +177,7 @@ shared output directory (config files such as css and dtd files are not updated if they already exist unless modifier is used). The equivalent of: -C --init-site configure/initialise site, more extensive than -C on its own, shared output directory files/force update, existing shared output config -files such as css and dtd files are updated if -CC is used. +files such as css and dtd files are updated if -CC is used.

-c [filename/wildcard] @@ -185,14 +185,14 @@ files such as css and dtd files are updated if -CC is used.
screen toggle ansi screen colour on or off depending on default set (unless -c flag is used: if sisurc colour default is set to ’true’, output to screen will be with colour, if sisurc colour default is set to ’false’ or is undefined -screen output will be without colour). +screen output will be without colour).

-D [instruction] [filename]
database postgresql ( --pgsql may be used instead) possible instructions, include: --createdb; --create; --dropall; --import [filename]; --update [filename]; --remove -[filename]; see database section below. +[filename]; see database section below.

-d [--db-[database  type  (sqlite|pg)]] @@ -201,7 +201,7 @@ postgresql ( --pgsql may be used instead) possible instructions, include: --sqlite may be used instead) or to specify another database --db-[pgsql,  sqlite] (however see -D) possible instructions include: --createdb; --create; --dropall; --import [filename]; --update [filename]; --remove [filename]; see database section -below. +below.

-F [--webserv=webrick]
@@ -217,13 +217,13 @@ usually 80). The samples are dumped in the present work directory which must be writable, (with screen instructions given that they be copied to the cgi-bin directory). -Fv (in addition to the above) provides some information -

on setting up hyperestraier for sisu +

on setting up hyperestraier for sisu

-H [filename/wildcard]
produces html without link suffixes (.html .pdf etc.) ( an appropriately configured web -server. [behaviour  switched  after  0.35 see  -h]. +server. [behaviour  switched  after  0.35 see  -h].

-h [filename/wildcard]
@@ -231,34 +231,34 @@ server. [behaviour  switched  after  0.35 see  -h]. html (with hardlinks i.e. with name suffixes in links/local urls). html, with internal document links that include the document suffix, i.e. whether it is .html or .pdf (required for browsing directly off a file system, and works -with most web servers). [behaviour  switched  after  0.35  see  -H]. +with most web servers). [behaviour  switched  after  0.35  see  -H].

-I [filename/wildcard]
-
produces texinfo and info file, (view with pinfo). +
produces texinfo and info file, (view with pinfo).

-i [filename/wildcard]
-
produces man page of file, not suitable for all outputs. +
produces man page of file, not suitable for all outputs.

-L
prints license -information. +information.

-M [filename/wildcard/url]
maintenance mode files created for -processing preserved and their locations indicated. (also see -V) +processing preserved and their locations indicated. (also see -V)

-m [filename/wildcard/url]
assumed for most other flags, creates new meta-markup file, (the metaverse ) that is used in all subsequent processing of other output. This step is -assumed for most processing flags. To skip it see -n +assumed for most processing flags. To skip it see -n

-N [filename/wildcard/url] @@ -266,18 +266,18 @@ assumed for most processing flags. To skip it see -n
document digest or document content certificate ( DCC ) as md5 digest tree of the document: the digest for the document, and digests for each object contained within the document (together with information on software versions -that produced it) (digest.txt). -NV for verbose digest output to screen. +that produced it) (digest.txt). -NV for verbose digest output to screen.

-n [filename/wildcard/url]
skip meta-markup (building of -m which is otherwise -assumed by most processing flags. +assumed by most processing flags.

-o [filename/wildcard/url]
output basic -document in opendocument file format (opendocument.odt). +document in opendocument file format (opendocument.odt).

-p [filename/wildcard] @@ -285,12 +285,12 @@ document in opendocument file format (opendocument.odt).
produces LaTeX pdf (portrait.pdf & landscape.pdf). Default paper size is set in config file, or document header, or provided with additional command line parameter, e.g. --papersize-a4 preset sizes include: ’A4’, U.S. ’letter’ and -’legal’ and book sizes ’A5’ and ’B5’ (system defaults to A4). +’legal’ and book sizes ’A5’ and ’B5’ (system defaults to A4).

-q [filename/wildcard]
-
quiet less output to screen. +
quiet less output to screen.

-R [filename/wildcard]
@@ -299,7 +299,7 @@ to remote host using rsync. This requires that sisurc.yml has been provided with information on hostname and username, and that you have your different if -R is used with other flags from if used alone. Alone the rsync --delete parameter is sent, useful for cleaning the remote directory (when -R is -used together with other flags, it is not). Also see -r +used together with other flags, it is not). Also see -r

-r [filename/wildcard] @@ -307,7 +307,7 @@ used together with other flags, it is not). Also see -r
copies sisu output files to remote host using scp. This requires that sisurc.yml has been provided with information on hostname and username, and that you -

have your +

have your

-S
@@ -316,7 +316,7 @@ including sisu markup source files and the directories local configuration file, images and skins. Note: this only includes the configuration files or skins contained in ./_sisu not those in ~/.sisu -S [filename/wildcard] option. Note: (this
- option is tested only with zsh). + option is tested only with zsh).

-S [filename/wildcard]
@@ -340,12 +340,12 @@ the individual files for sending). See the -S option without [filename/wildcard]

-s [filename/wildcard]
-
copies sisu markup file to output directory. +
copies sisu markup file to output directory.

-t [filename/wildcard  (*.termsheet.rb)]
-
standard form document builder, preprocessing feature +
standard form document builder, preprocessing feature

@@ -357,35 +357,35 @@ information on the output that would be produced), -u provides url output mapping for those flags requested for processing. The default assumes sisu_webrick is running and provides webrick url mappings where appropriate, but these -

can be switched to file system paths in sisurc.yml +

can be switched to file system paths in sisurc.yml

-u [filename/wildcard]
provides url mapping of output files for the flags requested for processing, -

also see -U +

also see -U

-V
on its own, provides SiSU version and environment information -(sisu --help env) +(sisu --help env)

-V [filename/wildcard]
even more verbose than the -v flag. -(also see -M) +(also see -M)

-v
-
on its own, provides SiSU version information +
on its own, provides SiSU version information

-v [filename/wildcard]
provides verbose output of what is being built, where it is being built (and error messages if any), as with -u flag provides a url mapping of files -created for each of the processing flag requests. See also -V +created for each of the processing flag requests. See also -V

-W
@@ -393,7 +393,7 @@ created for each of the processing flag requests. See also -V webrick webserver points at sisu output directories, the default port is set to 8081 and can be changed in the resource configuration files. [tip:  the  webrick  server  requires  link  suffixes,  so  html  output  should  be  created - using  the  -h  option  rather  than and search -H;  also,  note  -F  webrick  ]. + using  the  -h  option  rather  than and search -H;  also,  note  -F  webrick  ].

-w @@ -401,24 +401,24 @@ set to 8081 and can be changed in the resource configuration files. [tip:
produces concordance (wordmap) a rudimentary index of all the words in a document. (Concordance files are not generated for documents of over 260,000 words unless this limit is increased in the file -sisurc.yml) +sisurc.yml)

-X [filename/wildcard]
produces XML output with deep document -structure, in the nature of dom. +structure, in the nature of dom.

-x [filename/wildcard]
produces XML output -shallow structure (sax parsing). +shallow structure (sax parsing).

-Y [filename/wildcard]
produces a short sitemap entry for the document, based on html output and the sisu_manifest. --sitemaps generates/updates the sitemap index of existing sitemaps. (Experimental, -[g,y,m  announcement  this  week]) +[g,y,m  announcement  this  week])

-y [filename/wildcard]
@@ -438,41 +438,41 @@ combination of -[mMvVq]), will remove the related document output directory.
-z [filename/wildcard]
produces php (zend) [this  feature  is  disabled  for - the  time being] + the  time being]

-3. COMMAND LINE MODIFIERS -

+3. COMMAND LINE MODIFIERS +

--no-ocn
[with  -h  -H  or  -p] switches off object citation numbering. Produce output without identifying numbers -in margins of html or LaTeX/pdf output. +in margins of html or LaTeX/pdf output.

--no-annotate
strips output text of -editor endnotes[^*1] denoted by asterisk or dagger/plus sign +editor endnotes[^*1] denoted by asterisk or dagger/plus sign

--no-asterisk
-
strips output text of editor endnotes[^*2] denoted by asterisk sign +
strips output text of editor endnotes[^*2] denoted by asterisk sign

--no-dagger
-
strips output text of editor endnotes[^+1] denoted by dagger/plus sign +
strips output text of editor endnotes[^+1] denoted by dagger/plus sign

-4. DATABASE COMMANDS -

dbi - database interface +4. DATABASE COMMANDS +

dbi - database interface

-D or --pgsql set for postgresql -d or --sqlite default set for sqlite -d is modifiable with --db=[database  type - (pgsql  or  sqlite)] -

+ (pgsql  or  sqlite)] +

-Dv --createall
@@ -483,13 +483,13 @@ created manually and given the same name as working directory, as requested) -Dv --createdb initially NOTE: at the present time for postgresql it may be necessary to manually create the database. The command would be ’createdb [database name]’ where database name would be SiSU_[present  working  directory - name  (without  path)]. Please use only alphanumerics and underscores. + name  (without  path)]. Please use only alphanumerics and underscores.

-Dv --import
[filename/wildcard] imports data specified to postgresql db (rb.dbi) -[  -dv  --import  sqlite  equivalent] +[  -dv  --import  sqlite  equivalent]

-Dv --update
@@ -500,18 +500,18 @@ specified data to postgresql db (rb.dbi) [  -dv  --update  sqlite
-D --remove
[filename/wildcard] removes specified data to postgresql db (rb.dbi) -[  -d  --remove  sqlite  equivalent] +[  -d  --remove  sqlite  equivalent]

-D --dropall
kills data --dropall  sqlite  equivalent] -

The v in e.g. -Dv is for verbose output. +

The v in e.g. -Dv is for verbose output.

5. SHORTCUTS, SHORTHAND FOR MULTIPLE -FLAGS -

+FLAGS +

--update [filename/wildcard]
@@ -520,30 +520,30 @@ the flags required to update this output. This means that if only html and pdf output was requested on previous runs, only the -hp files will be applied, and only these will be generated this time, together with the summary. This can be very convenient, if you offer different outputs of different files, -and just want to do the same again. +and just want to do the same again.

-0 to -5 [filename  or  wildcard]
Default shorthand mappings (note that the defaults can be changed/configured in -the sisurc.yml file): +the sisurc.yml file):

-0
-mNhwpAobxXyYv [this  is  the  default  action  run  when - no  i.e.  on  ’sisu  [filename]’] + no  i.e.  on  ’sisu  [filename]’]

-1
-
-mNHwpy +
-mNHwpy

-2
-
-mNHwpaoy +
-mNHwpaoy

-3
-
-mNhwpAobxXyY +
-mNhwpAobxXyY

-4
@@ -551,164 +551,164 @@ the sisurc.yml file):

-

- -

import +

import

-5
-
-mNhwpAobxXDyY --update +
-mNhwpAobxXDyY --update

add -v for verbose mode and -c for color, -e.g. sisu -2vc [filename  or +e.g. sisu -2vc [filename  or

consider -u for appended url info or -v for verbose -

output +

output

-5.1 COMMAND LINE WITH FLAGS - BATCH PROCESSING +5.1 COMMAND LINE WITH FLAGS - BATCH PROCESSING

In the data directory -run sisu -mh filename or wildcard eg. cisg.sst documents. +run sisu -mh filename or wildcard eg. cisg.sst documents.

Running sisu (alone without any flags, filenames or wildcards) brings up the interactive help, -as does any sisu command that is not recognised. Enter to escape. +as does any sisu command that is not recognised. Enter to escape.

6. HELP - -

6.1 SISU MANUAL + +

6.1 SISU MANUAL

The most up to date information on sisu should be contained -in the sisu_manual, available at: +in the sisu_manual, available at:

<http://sisudoc.org/sisu/sisu_manual/ >
- +

The manual can be generated from source, found respectively, either -within the SiSU tarball or installed locally at: +within the SiSU tarball or installed locally at:

./data/doc/sisu/sisu_markup_samples/sisu_manual/
- +

/usr/share/doc/sisu/sisu_markup_samples/sisu_manual/
- -

move to the respective directory and type e.g.: + +

move to the respective directory and type e.g.:

sisu sisu_manual.ssm
- -

6.2 SISU MAN PAGES + +

6.2 SISU MAN PAGES

If SiSU is installed on your system usual man commands -should be available, try: +should be available, try:

man sisu
- +

man sisu_markup
- +

man sisu_commands
- +

Most SiSU man pages are generated directly from sisu documents that are used to prepare the sisu manual, the sources files for which are located -within the SiSU tarball at: +within the SiSU tarball at:

./data/doc/sisu/sisu_manual/
- -

Once installed, directory equivalent to: + +

Once installed, directory equivalent to:

/usr/share/doc/sisu/sisu_manual/
- -

Available man pages are converted back to html using man2html: + +

Available man pages are converted back to html using man2html:

/usr/share/doc/sisu/html/
- +

./data/doc/sisu/html/
- -

An online version of the sisu man page is available here: + +

An online version of the sisu man page is available here:

* various sisu man pages <http://www.jus.uio.no/sisu/man/ -> [^7] +> [^7]

* sisu.1 <http://www.jus.uio.no/sisu/man/sisu.1.html > -[^8] -

6.3 SISU BUILT-IN INTERACTIVE HELP +[^8] +

6.3 SISU BUILT-IN INTERACTIVE HELP

This is particularly useful for -getting the current sisu setup/environment information: +getting the current sisu setup/environment information:

sisu --help
- +

sisu --help [subject]
- +

sisu --help commands
- +

sisu --help markup
- +

sisu --help env [for  feedback  on  the  way  your  system  is
setup  with  regard  to  sisu]
- +

sisu -V [environment  information,  same  as  above  command]
- +

sisu (on its own provides version and some help information)
- +

Apart from real-time information on your current configuration the SiSU manual and man pages are likely to contain more up-to-date information than -the sisu interactive help (for example on commands and markup). +the sisu interactive help (for example on commands and markup).

NOTE: Running the command sisu (alone without any flags, filenames or wildcards) brings up the interactive help, as does any sisu command that is not recognised. -Enter to escape. -

6.4 HELP SOURCES +Enter to escape. +

6.4 HELP SOURCES

For lists of alternative help sources, -see: -

man page +see: +

man page

man sisu_help_sources
- -

man2html + +

man2html

/usr/share/doc/sisu/sisu_manual/sisu_help_sources/index.html
- -

sisu generated html + +

sisu generated html

/usr/share/doc/sisu/html/sisu_help_sources/index.html
- +

<http://sisudoc.org/sisu/sisu_help_sources/index.html >
- -

7. INTRODUCTION TO SISU MARKUP[^9] -

7.1 SUMMARY + +

7. INTRODUCTION TO SISU MARKUP[^9] +

7.1 SUMMARY

SiSU source documents -are plaintext (UTF-8)[^10] files +are plaintext (UTF-8)[^10] files

All paragraphs are separated by an empty -line. -

Markup is comprised of: +line. +

Markup is comprised of:

* 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) +from a particular level down)

* 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: +structure. Markup of substantive text includes:

* heading levels defines document structure
- +

* text basic attributes, italics, bold etc.
- +

* grouped text (objects), which are to be treated differently, such as code
blocks or poems.
- +

* footnotes/endnotes
- +

* linked text and images
- +

* paragraph actions, such as indent, bulleted, numbered-lists, etc.
- +

Some interactive help on markup is available, by typing sisu and selecting -

markup or sisu --help markup -

To check the markup in a file: +

markup or sisu --help markup +

To check the markup in a file:

sisu --identify [filename].sst
- -

For brief descriptive summary of markup history + +

For brief descriptive summary of markup history

sisu --query-history
- -

or if for a particular version: + +

or if for a particular version:

sisu --query-0.38
- -

7.2 MARKUP EXAMPLES -

7.2.1 ONLINE + +

7.2 MARKUP EXAMPLES +

7.2.1 ONLINE

Online markup examples are available together with the respective outputs produced from <http://www.jus.uio.no/sisu/SiSU/examples.html > or from <http://www.jus.uio.no/sisu/sisu_examples/ -> +>

There is of course this document, which provides a cursory overview of sisu markup and the respective output produced: <http://www.jus.uio.no/sisu/sisu_markup/ -> +>

Some example marked up files are available as html with syntax highlighting for viewing: <http://www.jus.uio.no/sisu/sample/syntax > @@ -716,28 +716,28 @@ up files are available as html with syntax highlighting for viewing: < an alternative presentation of markup syntax: <http://www.jus.uio.no/sisu/sample/on_markup.txt > -

7.2.2 INSTALLED +

7.2.2 INSTALLED

With 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 -

8. MARKUP OF HEADERS +

/usr/share/doc/sisu/sisu_markup_samples/non-free +

8. MARKUP OF HEADERS

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. +processing instructions.

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: -

+in a line of text) followed by a space and the comment: +


  % this would be a comment
-

8.1 SAMPLE HEADER +

8.1 SAMPLE HEADER

This current document has a header similar to this -one (without the comments): -

+one (without the comments): +


  % SiSU 0.57
   @title: SiSU
@@ -775,50 +775,50 @@ documents that request them, all documents in a directory, or be site-wide.
   { SiSU Download }http://www.jus.uio.no/sisu/SiSU/download.html
   { SiSU Changelog }http://www.jus.uio.no/sisu/SiSU/changelog.html
-

8.2 AVAILABLE HEADERS +

8.2 AVAILABLE HEADERS

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 +

Dublin Core meta tags are available

@indentifier: information or instructions -

where the information +

where the information

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. +is used to describe document structure, and can be useful to know.

This -

is a sample header +

is a sample header

% SiSU 0.38 [declared  file-type  identifier  with  markup - version] -

+ version] +

@title:  [title  text] This is the title of the document and used as such, this header is the only one that is
- mandatory -

@subtitle: The Subtitle if any + mandatory +

@subtitle: The Subtitle if any

@creator: [or  @author:] Name -

of Author -

@subject: (whatever your subject) -

@description: +

of Author +

@subject: (whatever your subject) +

@description:

@publisher: -

@contributor: -

@translator:  [or  @translated_by:] +

@contributor: +

@translator:  [or  @translated_by:]

@illustrator:  [or - @illustrated_by:] -

@prepared_by:  [or  @digitized_by:] + @illustrated_by:] +

@prepared_by:  [or  @digitized_by:]

@date: 2000-08-27 -[  also  @date.created:  @date.issued:  @date.available:  @date.valid:  ] -

+[  also  @date.created:  @date.issued:  @date.available:  @date.valid:  ] +

@type: -

article -

@format: -

@identifier: -

@source: +

article +

@format: +

@identifier: +

@source:

@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 @@ -826,50 +826,50 @@ used as such, this header is the only one that is
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.] + are  not  available  for  all  of  the languages  listed.]

[@language.original: - original  language  in  which  the  work  was published] + original  language  in  which  the  work  was published]

@papersize: (A4|US_letter|book_B5|book_A5|US_legal) -

@relation: -

@coverage: +

@relation: +

@coverage:

@rights: Copyright (c) Name of Right Holder, all rights reserved, or as granted: public domain, copyleft, creative commons -variant, etc. -

@owner: +variant, etc. +

@owner:

@keywords: text document generation processing management latex pdf structured xml citation [your  keywords  here,  used - for  example  by  rss  feeds, + for  example  by  rss  feeds,

@abstract: [paper  abstract,  placed  after  table - of  contents] -

@comment: [...] + of  contents] +

@comment: [...]

@catalogue: loc=[Library  of  Congress  classification]; dewey=[Dewey rss  feeds, isbn=[ISBN]; pg=[Project  Gutenberg  text  number] -

@classify_loc: [Library  of  Congress  classification] +

@classify_loc: [Library  of  Congress  classification]

@classify_dewey: -[Dewey  classification] -

@classify_isbn: [ISBN] +[Dewey  classification] +

@classify_isbn: [ISBN]

@classify_pg: [Project - Gutenberg  text  number] + Gutenberg  text  number]

@prefix: [prefix  is  placed  just  after  table  of - contents] + contents]

@prefix_a: [prefix  is  placed  just  before  table  of  contents - -  not -

@prefix_b: + -  not +

@prefix_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  ] + a  document  ]

@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:) +a synonym for @toc:)

@level: newpage=3; breakpage=4 [paragraph  level, - used  by  latex  to  breakpages,  the  page  is  optional  eg.  in  newpage] + used  by  latex  to  breakpages,  the  page  is  optional  eg.  in  newpage]

@markup: information on the markup used, e.g. new=1,2,3; break=4; num_top=4 [or is newpage=1,2,3;  breakpage=4;  num_top=4] newpage and breakpage, heading level, @@ -883,17 +883,17 @@ page for both single and double column texts. num_top=4 [auto-number  docum  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] +breakpage=1;  num_top=1] see headings]

@bold: [regular  expression  of  words/phrases - to  be  made  bold] + to  be  made  bold]

@italics: [regular  expression  of  words/phrases  to  italicise]

@vocabulary: name of taxonomy/vocabulary/wordlist to use against document

@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. -

+urls of the home site, and the icon/logo for the document or site. +

@man: @@ -903,56 +903,56 @@ formats, and search; synopsis=sisu [-abcDdFHhIiMmNnopqRrSsTtUuVvwXxYyZz0-9] [filename/wildcard ] sisu [-Ddcv] [instruction] sisu [-CcFLSVvW] the man page category number (default 1) and special tags used in preparing man -

page headings +

page headings

@links: { SiSU }http://www.jus.uio.no/sisu/; { FSF }http://www.fsf.org

@promo: sisu, ruby, search_libre_docs, open_society [places  content  in  right  pane  in  html,  makes  use  of  commented  out  sample  in  document and  promo.yml, - commented  out  sample  in  document + commented  out  sample  in  document

-9. MARKUP OF SUBSTANTIVE TEXT +9. MARKUP OF SUBSTANTIVE TEXT

9.1 HEADING -

LEVELS +

LEVELS

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) +into another)

:A~ [heading  text] Top level heading [this  usually  has  similar  content  to  the  ] NOTE: the heading levels described here are in -0.38 notation, see heading +0.38 notation, see heading

:B~ [heading  text] Second level heading [this - is  a  heading  level  divider] + is  a  heading  level  divider]

:C~ [heading  text] Third level heading [this - is  a  heading  level  divider] + is  a  heading  level  divider]

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 +

form 1~my_filename_for_this_segment

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. -

+that would normally be marked 1.1 or 1.2 or 1.3 or 2.1 etc. in a document. +

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 -

+


  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)
-

9.2 FONT ATTRIBUTES -

markup example: -

+

9.2 FONT ATTRIBUTES +

markup example: +


  normal text !{emphasis}! *{bold text}* _{underscore}_ /{italics}/
   normal text
@@ -960,192 +960,192 @@ html segments are made)
   *{bold text}*
   _{underscore}_
   /{italics}/
-
+ 
   ^{superscript}^
   ,{subscript},
   +{inserted text}+
   -{strikethrough}-
-

resulting output: +

resulting output:

normal text emphasis bold text underscore italics <cite>citation</cite> ^superscript^  [subscript] <ins>inserted text</ins> <del>strikethrough</del> -

normal text -

-

bold text -

underscore -

italics -

<cite>citation</cite> +

normal text +

+

bold text +

underscore +

italics +

<cite>citation</cite>

- ^superscript^ -

[subscript] -

<ins>inserted text</ins> + ^superscript^ +

[subscript] +

<ins>inserted text</ins>

<del>strikethrough</del> -

9.3 INDENTATION AND BULLETS -

markup example: -

+

9.3 INDENTATION AND BULLETS +

markup example: +


  ordinary paragraph
   _1 indent paragraph one step
   _2 indent paragraph two steps
   _9 indent paragraph nine steps
-

-

resulting output: -

ordinary paragraph +

+

resulting output: +

ordinary paragraph

indent paragraph one step
- +

indent paragraph two steps
- +

indent paragraph nine steps
- -

markup example: -

+ +

markup example: +


  _* bullet text
   _1* bullet text, first indent
   _2* bullet text, two step indent
-

resulting output: -

* bullet text +

resulting output: +

* bullet text

* bullet text, first indent
- +

* bullet text, two step indent
- +

Numbered List (not to be confused with headings/titles, (document structure)) -

markup example: -

+

markup example: +


  # numbered list                numbered list 1., 2., 3, etc.
   _# numbered list numbered list indented a., b., c., d., etc.
-

9.4 FOOTNOTES / ENDNOTES +

9.4 FOOTNOTES / ENDNOTES

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. -

markup example: -

+or endnotes. +

markup example: +


  ~{ a footnote or endnote }~
-

resulting output: -

[^11] -

markup example: -

+

resulting output: +

[^11] +

markup example: +


  normal text~{ self contained endnote marker & endnote in one }~ continues
-

resulting output: -

normal text[^12] continues -

markup example: -

+

resulting output: +

normal text[^12] continues +

markup example: +


  normal text ~{* unnumbered asterisk footnote/endnote, insert multiple
 asterisks if required }~ continues
   normal text ~{** another unnumbered asterisk footnote/endnote }~ continues
-

resulting output: -

normal text [^*] continues +

resulting output: +

normal text [^*] continues

normal text [^**] continues -

-

markup example: -

+

+

markup example: +


  normal text ~[*  editors  notes,  numbered  asterisk  footnote/endnote  series
  ]~ continues
   normal text ~[+  editors  notes,  numbered  asterisk  footnote/endnote  series
  ]~ continues
-

resulting output: -

normal text [^*3] continues +

resulting output: +

normal text [^*3] continues

normal text [^+2] continues -

-

Alternative endnote pair notation for footnotes/endnotes: -

+

+

Alternative endnote pair notation for footnotes/endnotes: +


  % note the endnote marker
   normal text~^ continues
   ^~ endnote text following the paragraph in which the marker occurs
-

the standard and pair notation cannot be mixed in the same document +

the standard and pair notation cannot be mixed in the same document

-

9.5 LINKS -

9.5.1 NAKED URLS WITHIN TEXT, DEALING WITH URLS +

9.5 LINKS +

9.5.1 NAKED URLS WITHIN TEXT, DEALING WITH URLS

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). -

markup example: -

+is omitted). +

markup example: +


  normal text http://www.jus.uio.no/sisu continues
-

resulting output: +

resulting output:

normal text <http://www.jus.uio.no/sisu -> continues +> continues

An -

escaped url without decoration -

markup example: -

+

escaped url without decoration +

markup example: +


  normal text http://www.jus.uio.no/sisu continues
   deb http://www.jus.uio.no/sisu/archive unstable main non-free
-

resulting output: +

resulting output:

normal text http://www.jus.uio.no/sisu - continues + continues

deb

http://www.jus.uio.no/sisu/archive - unstable main non-free + unstable main non-free

where a code block is used there is neither decoration nor hyperlinking, code blocks are discussed -

later in this document -

resulting output: -

+

later in this document +

resulting output: +


  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
-

To link text or an image to a url the markup is as follows +

To link text or an image to a url the markup is as follows

markup example: -

+


  about { SiSU }http://url.org markup
-

9.5.2 LINKING TEXT -

resulting output: +

9.5.2 LINKING TEXT +

resulting output:

about SiSU <http://www.jus.uio.no/sisu/ > -

markup +

markup

A shortcut notation is available so the url link may also be provided -

automatically as a footnote -

markup example: -

+

automatically as a footnote +

markup example: +


  about {~^ SiSU }http://url.org markup
-

resulting output: +

resulting output:

about SiSU <http://www.jus.uio.no/sisu/ -> [^13] markup +> [^13] markup

-

9.5.3 LINKING IMAGES -

markup example: -

+

9.5.3 LINKING IMAGES +

markup example: +


      [ tux.png ]
   % various url linked images
@@ -1153,37 +1153,37 @@ is used there is neither decoration nor hyperlinking, code blocks are discussed
       [ GnuDebianLinuxRubyBetterWay.png ]
   {~^ ruby_logo.png
-

resulting output: -

[ tux.png ] -

tux.png 64x80 +

resulting output: +

[ tux.png ] +

tux.png 64x80

[  ruby_logo  (png  missing) - ]  [^14] -

GnuDebianLinuxRubyBetterWay.png 100x101 and Ruby + ]  [^14] +

GnuDebianLinuxRubyBetterWay.png 100x101 and Ruby

linked url footnote -

shortcut -

+

shortcut +


  {~^  [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
-

+


  text marker *~name

note at a heading level the same is automatically achieved by providing names to headings 1, 2 and 3 i.e. 2~[name] and 3~[name] or in the case of -auto-heading numbering, without further intervention. -

9.6 GROUPED TEXT +auto-heading numbering, without further intervention. +

9.6 GROUPED TEXT

9.6.1 -

TABLES -

Tables may be prepared in two either of two forms +

TABLES +

Tables may be prepared in two either of two forms

markup example: -

+


  table{ c3; 40; 30; 30;
   This is a table
@@ -1194,14 +1194,14 @@ auto-heading numbering, without further intervention.
   column three of row two, and so on
   }table
-

resulting output: +

resulting output:

 [table  omitted,  see  other  document  formats]
- +

a second form may be easier to work with in cases where there is not -

much information in each column -

markup example: [^15] -

+

much information in each column +

markup example: [^15] +


  !_ Table 3.1: Contributors to Wikipedia, January 2001 - June 2005
   {table~h 24; 12; 12; 12; 12; 12; 12;}
@@ -1213,38 +1213,38 @@ auto-heading numbering, without further intervention.
    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|
+  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|
+  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.
-

resulting output: +

resulting output:

Table 3.1: Contributors to Wikipedia, January 2001 -- June 2005 +- June 2005

 [table  omitted,  see  other  document  formats]
- +

* Contributed at least ten times; ** at least 5 times in last month; -*** more than 100 times in last month. -

9.6.2 POEM -

basic markup: -

+*** more than 100 times in last month. +

9.6.2 POEM +

basic markup: +


  poem{
     Your poem here
   }poem
   Each verse in a poem is given a separate object number.
-

markup example: -

+

markup example: +


  poem{
                       ’Fury said to a
                      mouse, That he
                    met in the
                  house,
-
+ 
                 both go to
                   law:  I will
                     prosecute
@@ -1269,13 +1269,13 @@ auto-heading numbering, without further intervention.
                 wasting
                our
                 breath.
-
+ 
                    judge, I’ll
                      be jury,
                            Said
                       cunning
                         old Fury:
-
+ 
                         try the
                            whole
                             cause,
@@ -1286,8 +1286,8 @@ auto-heading numbering, without further intervention.
                          death.
   }poem
-

resulting output: -

+

resulting output: +

’Fury said to a
mouse, That he
met in the
@@ -1332,25 +1332,25 @@ auto-heading numbering, without further intervention. you
to
death.
- -

9.6.3 GROUP -

basic markup: -

+ +

9.6.3 GROUP +

basic markup: +


  group{
     Your grouped text here
   }group
   A group is treated as an object and given a single object number.
-

markup example: -

+

markup example: +


  group{
                       ’Fury said to a
                      mouse, That he
                    met in the
                  house,
-
+ 
                 both go to
                   law:  I will
                     prosecute
@@ -1375,13 +1375,13 @@ auto-heading numbering, without further intervention.
                 wasting
                our
                 breath.
-
+ 
                    judge, I’ll
                      be jury,
                            Said
                       cunning
                         old Fury:
-
+ 
                         try the
                            whole
                             cause,
@@ -1392,8 +1392,8 @@ auto-heading numbering, without further intervention.
                          death.
   }group
-

resulting output: -

+

resulting output: +

’Fury said to a
mouse, That he
met in the
@@ -1438,25 +1438,25 @@ auto-heading numbering, without further intervention. you
to
death.
- -

9.6.4 CODE + +

9.6.4 CODE

Code tags are used to escape regular sisu markup, and have been used extensively within this document to provide examples of 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. +used in the same way as group or poem tags.

A code-block is treated as an object and given a single object number. [an more than 100 times in last month. option  to  number  each  line  of  code  may  be  considered  at more than -100 times in last month. some  later  time] +100 times in last month. some  later  time]

use of code tags instead of -poem compared, resulting output: -

+poem compared, resulting output: +


                      ’Fury said to a
                      mouse, That he
                    met in the
                  house,
-
+ 
                 both go to
                   law:  I will
                     prosecute
@@ -1481,13 +1481,13 @@ poem compared, resulting output:
                 wasting
                our
                 breath.
-
+ 
                    judge, I’ll
                      be jury,
                            Said
                       cunning
                         old Fury:
-
+ 
                         try the
                            whole
                             cause,
@@ -1497,7 +1497,59 @@ poem compared, resulting output:
                         to
                          death.
-

10. COMPOSITE DOCUMENTS MARKUP +

9.7 BOOK INDEX +

To make an index append to paragraph the book index term +relates to it, using an equal sign and curly braces. +

Currently two levels +are provided, a main term and if needed a sub-term. Sub-terms are separated +from the main term by a colon. +

+


+

    Paragraph containing main term and sub-term.
+    ={Main term:sub-term}
+
+

The index syntax starts on a new line, but there should not be an empty +line between paragraph and index markup. +

The structure of the resulting +index would be: +

+


+

    Main term, 1
+      sub-term, 1
+
+

Several terms may relate to a paragraph, they are separated by a semicolon. +If the term refers to more than one paragraph, indicate the number of paragraphs. + +

+


+

    Paragraph containing main term, second term and sub-term.
+    ={first term; second term: sub-term}
+
+

The structure of the resulting index would be: +

+


+

    First term, 1,
+    Second term, 1,
+      sub-term, 1
+
+

If multiple sub-terms appear under one paragraph, they are separated under +the main term heading from each other by a pipe symbol. +

+


+

    Paragraph containing main term, second term and sub-term.
+    ={Main term:sub-term+1|second sub-term
+    A paragraph that continues discussion of the first sub-term
+
+

The plus one in the example provided indicates the first sub-term spans +one additional paragraph. The logical structure of the resulting index would +be: +

+


+

    Main term, 1,
+      sub-term, 1-3,
+      second sub-term, 1,
+
+

10. COMPOSITE DOCUMENTS MARKUP

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, @@ -1511,11 +1563,11 @@ within a master document .sst regular markup file, or .ssi (insert

A secondary file of the composite document is built prior to processing -

with the same prefix and the suffix ._sst +

with the same prefix and the suffix ._sst

basic markup for importing a -

document into a master document -

+

document into a master document +


  << filename1.sst
   << filename2.ssi
@@ -1525,83 +1577,83 @@ 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.
 
-

+
 
 
 

 
  << filename.ssi
   <<{filename.ssi}
   % using textlink alternatives
   << |filename.ssi|@|^|
 

-
 MARKUP SYNTAX HISTORY
+
 MARKUP SYNTAX HISTORY  
 
 11. NOTES RELATED TO FILES-TYPES AND MARKUP SYNTAX
-
+ 
 
  0.38 is substantially current, depreciated 0.16 supported, though file
 
-
names were changed at 0.37
+
names were changed at 0.37 
 
  * sisu --query=[sisu  version  [0.38] or ’history]
 
-
  provides a short history of changes to SiSU markup
+
  provides a short history of changes to SiSU markup 
 
  0.57 (2007w34/4)
 SiSU 0.57 is the same as 0.42 with the introduction of some a shortcut to
 use the headers @title and @creator in the first heading [expanded  using
- the  and  @author:]
-

+ the  and  @author:] 
+
 
 
 

 
  :A~ @title by @author
 

 
  0.52 (2007w14/6) declared document type identifier at start of text/document:
 
 
    .B SiSU

- 0.52
-
  or, backward compatible using the comment marker:
+ 0.52 
+
  or, backward compatible using the comment marker: 
 
    %

- SiSU 0.38
+ SiSU 0.38 
 
  variations include ’ SiSU (text|master|insert) [version]’ and ’sisu-[version]’
 
-
  0.51 (2007w13/6) skins changed (simplified), markup unchanged
+
  0.51 (2007w13/6) skins changed (simplified), markup unchanged 
 
  0.42 (2006w27/4)
-* (asterisk) type endnotes, used e.g. in relation to author
+* (asterisk) type endnotes, used e.g. in relation to author 
 
  SiSU 0.42 is
 the same as 0.38 with the introduction of some additional endnote types,
 
 
  Introduces some variations on endnotes, in particular the use of the
 
-
asterisk
-

+
asterisk 
+
 
 
 

 
  ~{* for example for describing an author }~ and ~{** for describing a
 second author }~
 

-
  * for example for describing an author
+
  * for example for describing an author 
 
  ** for describing a second author
 
-
  and
-

+
  and 
+
 
 
 

 
  ~[*  my  note  ]~ or ~[+  another  note  ]~
 

-
  which numerically increments an asterisk and plus respectively
+
  which numerically increments an asterisk and plus respectively 
 
  *1 my
 
-
note +1 another note
+
note +1 another note 
 
  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)
+structure markup, :A,:B,:C,1,2,3 (maps to previous 1,2,3,4,5,6) 
 
  SiSU
 0.38 introduced alternative experimental header and heading/structure markers,
 
-

+
 
 
 

 
  @headername: and headers :A~ :B~ :C~ 1~ 2~ 3~
 

-
  as the equivalent of:
-

+
  as the equivalent of: 
+
 
 
 

 
  0~headername and headers 1~ 2~ 3~ 4~ 5~ 6~
 

 
  The internal document markup of SiSU 0.16 remains valid and standard Though
 
-
note that SiSU 0.37 introduced a new file naming convention
+
note that SiSU 0.37 introduced a new file naming convention 
 
  SiSU has in
 effect two sets of levels to be considered, using 0.38 notation A-C headings/levels,
 pre-ordinary paragraphs /pre-substantive text, and 1-3 headings/levels, levels
@@ -1617,45 +1669,45 @@ your face and likely to be understood fairly quickly); the substantive
 text follows levels 1,2,3 and it is ’nice’ to do most work in those levels
 
 
  0.37 (2006w09/7) introduced new file naming convention, .sst (text), .ssm
-(master), .ssi (insert), markup syntax unchanged
+(master), .ssi (insert), markup syntax unchanged 
 
  SiSU 0.37 introduced new
 file naming convention, using the file extensions .sst  .ssm and .ssi to replace
 .s1 .s2 .s3 .r1 .r2 .r3 and .si

-
-
  this is captured by the following file ’rename’ instruction:
-

+ 
+
  this is captured by the following file ’rename’ instruction: 
+
 
 
 

 
  rename ’s/.s[123]$/.sst/’ *.s{1,2,3}
   rename ’s/.r[123]$/.ssm/’ *.r{1,2,3}
   rename ’s/.si$/.ssi/’ *.si
 

-
  The internal document markup remains unchanged, from SiSU 0.16
+
  The internal document markup remains unchanged, from SiSU 0.16 
 
  0.35 (2005w52/3)
-sisupod, zipped content file introduced
+sisupod, zipped content file introduced 
 
  0.23 (2005w36/2) utf-8 for markup
 
-
file
+
file 
 
  0.22 (2005w35/3) image dimensions may be omitted if rmagick is available
 
-
to be relied upon
-
  0.20.4 (2005w33/4) header 0~links
+
to be relied upon 
+
  0.20.4 (2005w33/4) header 0~links 
 
  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
-
  SiSU 0.16 (0.15 development branch) introduced the use of
+
marker 
+
  SiSU 0.16 (0.15 development branch) introduced the use of 
 
  the
-header 0~ and headings/structure 1~ 2~ 3~ 4~ 5~ 6~
+header 0~ and headings/structure 1~ 2~ 3~ 4~ 5~ 6~ 
 
  in place of the 0.1
-header, heading/structure notation
+header, heading/structure notation 
 
  SiSU 0.1 headers and headings structure
-represented by header 0{~ and headings/structure 1{ 2{ 3{ 4{~ 5{ 6{
+represented by header 0{~ and headings/structure 1{ 2{ 3{ 4{~ 5{ 6{ 
 
 12.
-SISU FILETYPES
+SISU FILETYPES  
 
  SiSU has plaintext and binary filetypes, and can process
-either type of document.
-
 12.1 .SST .SSM .SSI MARKED UP PLAIN TEXT
+either type of document. 
+
 12.1 .SST .SSM .SSI MARKED UP PLAIN TEXT 
 
  SiSU documents
 are prepared as plain-text (utf-8) files with SiSU markup. They may make reference
 to and contain images (for example), which are stored in the directory
@@ -1664,259 +1716,259 @@ that may be distinguished by the file extension used: regular text .sst;
 master documents, composite documents that incorporate other text, which
 can be any regular text or text insert; and inserts the contents of which
 are like regular text except these are marked  .ssi and are not processed.

-
+ 
 
  SiSU processing can be done directly against a sisu documents; which
 may be located locally or on a remote server for which a url is provided.
 
-
  SiSU source markup can be shared with the command:
+
  SiSU source markup can be shared with the command: 
 
    sisu -s [filename]

-
-
 12.1.1 SISU TEXT - REGULAR FILES (.SST)
+ 
+
 12.1.1 SISU TEXT - REGULAR FILES (.SST) 
 
  The most common form of document
-in SiSU , see the section on SiSU markup.
+in SiSU , see the section on SiSU markup. 
 
  <http://www.jus.uio.no/sisu/sisu_markup
 >
 
 
  <http://www.jus.uio.no/sisu/sisu_manual
->
-
 12.1.2 SISU MASTER FILES (.SSM)
+> 
+
 12.1.2 SISU MASTER FILES (.SSM) 
 
  Composite
 documents which incorporate other SiSU documents which may be either regular
 SiSU text .sst which may be generated independently, or inserts prepared
 solely for the purpose of being incorporated into one or more master documents.
 
 
  The mechanism by which master files incorporate other documents is described
-as one of the headings under under SiSU markup in the SiSU manual.
+as one of the headings under under SiSU markup in the SiSU manual. 
 
  Note:
 Master documents may be prepared in a similar way to regular documents,
 and processing will occur normally if a .sst file is renamed .ssm without
 requiring any other documents; the .ssm marker flags that the document may
-contain other documents.
+contain other documents. 
 
  Note: a secondary file of the composite document
 is built prior to processing with the same prefix and the suffix ._sst [^16]
 
 
  <http://www.jus.uio.no/sisu/sisu_markup
->
+> 
 
  <http://www.jus.uio.no/sisu/sisu_manual
 >
 
-
 12.1.3 SISU INSERT FILES (.SSI)
+
 12.1.3 SISU INSERT FILES (.SSI) 
 
  Inserts are documents prepared solely for
 the purpose of being incorporated into one or more master documents. They
 resemble regular SiSU text files except they are ignored by the SiSU processor.
 Making a file a .ssi file is a quick and convenient way of flagging that
-it is not intended that the file should be processed on its own.
+it is not intended that the file should be processed on its own. 
 
 12.2 SISUPOD,
-ZIPPED BINARY CONTAINER (SISUPOD.ZIP, .SSP)
+ZIPPED BINARY CONTAINER (SISUPOD.ZIP, .SSP) 
 
  A sisupod is a zipped SiSU
 text file or set of SiSU text files and any associated images that they
-contain (this will be extended to include sound and multimedia-files)
-

+contain (this will be extended to include sound and multimedia-files) 
+
 
 SiSU plaintext files rely on a recognised directory structure to find contents
 such as images associated with documents, but all images for example for
 all documents contained in a directory are located in the sub-directory
 _sisu/image. Without the ability to create a sisupod it can be inconvenient
 to manually identify all other files associated with a document. A sisupod
 automatically bundles all associated files with the document that is turned
-into a pod.
+into a pod. 
 
  The structure of the sisupod is such that it may for example
 contain a single document and its associated images; a master document
 and its associated documents and anything else; or the zipped contents
-of a whole directory of prepared SiSU documents.
+of a whole directory of prepared SiSU documents. 
 
  The command to create
-a sisupod is:
+a sisupod is: 
 
    sisu -S [filename]

-
-
  Alternatively, make a pod of the contents of a whole directory:
-

+ 
+
  Alternatively, make a pod of the contents of a whole directory: 
+
   
 sisu -S

-
+ 
 
  SiSU processing can be done directly against a sisupod; which may be
-located locally or on a remote server for which a url is provided.
+located locally or on a remote server for which a url is provided. 
 
  <http://www.jus.uio.no/sisu/sisu_commands
 >
 
 
  <http://www.jus.uio.no/sisu/sisu_manual
->
+> 
 
 13. EXPERIMENTAL ALTERNATIVE INPUT
-REPRESENTATIONS
-
 13.1 ALTERNATIVE XML
+REPRESENTATIONS  
+
 13.1 ALTERNATIVE XML 
 
  SiSU offers alternative XML input
 representations of documents as a proof of concept, experimental feature.
 They are however not strictly maintained, and incomplete and should be
-handled with care.
+handled with care. 
 
  convert from sst to simple xml representations (sax,
-dom and node):
+dom and node): 
 
    sisu --to-sax [filename/wildcard] or sisu --to-sxs [filename/wildcard]

-
+ 
 
    sisu --to-dom [filename/wildcard] or sisu --to-sxd [filename/wildcard]

-
+ 
 
    sisu --to-node [filename/wildcard] or sisu --to-sxn [filename/wildcard]

-
-

+ 
+
 
 
  convert to sst from any sisu xml representation (sax, dom and node):
 
 
    sisu --from-xml2sst [filename/wildcard  [.sxs.xml,.sxd.xml,sxn.xml]]

-
-
  or the same:
+ 
+
  or the same: 
 
    sisu --from-sxml [filename/wildcard  [.sxs.xml,.sxd.xml,sxn.xml]]

-
-
 13.1.1 XML SAX REPRESENTATION
+ 
+
 13.1.1 XML SAX REPRESENTATION 
 
  To convert from sst to simple xml (sax)
-representation:
+representation: 
 
    sisu --to-sax [filename/wildcard] or sisu --to-sxs [filename/wildcard]

-
-
  To convert from any sisu xml representation back to sst
+ 
+
  To convert from any sisu xml representation back to sst 
 
    sisu --from-xml2sst
 [filename/wildcard  [.sxs.xml,.sxd.xml,sxn.xml]]

-
-
  or the same:
+ 
+
  or the same: 
 
    sisu --from-sxml [filename/wildcard  [.sxs.xml,.sxd.xml,sxn.xml]]

-
-
 13.1.2 XML DOM REPRESENTATION
+ 
+
 13.1.2 XML DOM REPRESENTATION 
 
  To convert from sst to simple xml (dom)
-representation:
+representation: 
 
    sisu --to-dom [filename/wildcard] or sisu --to-sxd [filename/wildcard]

-
-
  To convert from any sisu xml representation back to sst
+ 
+
  To convert from any sisu xml representation back to sst 
 
    sisu --from-xml2sst
 [filename/wildcard  [.sxs.xml,.sxd.xml,sxn.xml]]

-
-
  or the same:
+ 
+
  or the same: 
 
    sisu --from-sxml [filename/wildcard  [.sxs.xml,.sxd.xml,sxn.xml]]

-
-
 13.1.3 XML NODE REPRESENTATION
+ 
+
 13.1.3 XML NODE REPRESENTATION 
 
  To convert from sst to simple xml (node)
-representation:
+representation: 
 
    sisu --to-node [filename/wildcard] or sisu --to-sxn [filename/wildcard]

-
-
  To convert from any sisu xml representation back to sst
+ 
+
  To convert from any sisu xml representation back to sst 
 
    sisu --from-xml2sst
 [filename/wildcard  [.sxs.xml,.sxd.xml,sxn.xml]]

-
-
  or the same:
+ 
+
  or the same: 
 
    sisu --from-sxml [filename/wildcard  [.sxs.xml,.sxd.xml,sxn.xml]]

-
-
 14. CONFIGURATION
-
 14.1 DETERMINING THE CURRENT CONFIGURATION
+ 
+
 14. CONFIGURATION  
+
 14.1 DETERMINING THE CURRENT CONFIGURATION 
 
  Information
 on the current configuration of SiSU should be available with the help
-command:
+command: 
 
    sisu -v

-
-
  which is an alias for:
+ 
+
  which is an alias for: 
 
    sisu --help env

-
+ 
 
  Either of these should be executed from within a directory that contains
-sisu markup source documents.
-
 14.2 CONFIGURATION FILES (CONFIG.YML)
+sisu markup source documents. 
+
 14.2 CONFIGURATION FILES (CONFIG.YML) 
 
  SiSU
 configration parameters are adjusted in the configuration file, which can
 be used to override the defaults set. This includes such things as which
 directory interim processing should be done in and where the generated
-output should be placed.
+output should be placed. 
 
  The SiSU configuration file is a yaml file, which
-means indentation is significant.
+means indentation is significant. 
 
  SiSU resource configuration is determined
-by looking at the following files if they exist:
+by looking at the following files if they exist: 
 
    ./_sisu/sisurc.yml

-
+ 
 
    ~/.sisu/sisurc.yml

-
+ 
 
    /etc/sisu/sisurc.yml

-
-
  The search is in the order listed, and the first one found is used.
+ 
+
  The search is in the order listed, and the first one found is used. 
 

  In the absence of instructions in any of these it falls back to the internal
-program defaults.
+program defaults. 
 
  Configuration determines the output and processing directories
-and the database access details.
+and the database access details. 
 
  If SiSU is installed a sample sisurc.yml
 
-
may be found in /etc/sisu/sisurc.yml
-
 15. SKINS
+
may be found in /etc/sisu/sisurc.yml 
+
 15. SKINS  
 
  Skins modify the default
 appearance of document output on a document, directory, or site wide basis.
-Skins are looked for in the following locations:
+Skins are looked for in the following locations: 
 
    ./_sisu/skin

-
+ 
 
    ~/.sisu/skin

-
+ 
 
    /etc/sisu/skin

-
+ 
 
  Within the skin directory are the following the default sub-directories
-for document skins:
+for document skins: 
 
    ./skin/doc

-
+ 
 
    ./skin/dir

-
+ 
 
    ./skin/site

-
+ 
 
  A skin is placed in the appropriate directory and the file named skin_[name].rb
 
 
  The skin itself is a ruby file which modifies the default appearances
-set in the program.
-
 15.1 DOCUMENT SKIN
+set in the program. 
+
 15.1 DOCUMENT SKIN 
 
  Documents take on a document skin,
-if the header of the document specifies a skin to be used.
-

+if the header of the document specifies a skin to be used. 
+
 
 
 

 
  @skin: skin_united_nations
 

-
 15.2 DIRECTORY SKIN
+
 15.2 DIRECTORY SKIN 
 
  A directory may be mapped on to a particular skin,
 so all documents within that directory take on a particular appearance.
 If a skin exists in the skin/dir with the same name as the document directory,
 it will automatically be used for each of the documents in that directory,
 (except where a document specifies the use of another skin, in the skin/doc
-directory).
+directory). 
 
  A personal habit is to place all skins within the doc directory,
 and symbolic links as needed from the site, or dir directories as required.
 
-
 15.3 SITE SKIN
-
  A site skin, modifies the program default skin.
+
 15.3 SITE SKIN 
+
  A site skin, modifies the program default skin. 
 
 15.4 SAMPLE
 
-
SKINS
-
  With SiSU installed sample skins may be found in:
+
SKINS 
+
  With SiSU installed sample skins may be found in: 
 
    /etc/sisu/skin/doc
 and

    /usr/share/doc/sisu/sisu_markup_samples/dfsg/_sisu/skin/doc

-
+ 
 
  (or equivalent directory) and if sisu-markup-samples is installed also
-under:
+under: 
 
    /usr/share/doc/sisu/sisu_markup_samples/non-free/_sisu/skin/doc

-
+ 
 
  Samples of list.yml and promo.yml (which are used to create the right
-column list) may be found in:
+column list) may be found in: 
 
    /usr/share/doc/sisu/sisu_markup_samples/dfsg/_sisu/skin/yml
 (or equivalent

    directory)

-
-
 16. CSS - CASCADING STYLE SHEETS (FOR HTML, XHTML AND XML)
+ 
+
 16. CSS - CASCADING STYLE SHEETS (FOR HTML, XHTML AND XML)  
 
  CSS files
 to modify the appearance of SiSU html, XHTML or XML may be placed in the
 configuration directory:  ./_sisu/css; ~/.sisu/css or; /etc/sisu/css and
 these will be copied to the

- output directories with the command sisu -CC.
+ output directories with the command sisu -CC. 
 
  The basic CSS file for html
 output is html.css, placing a file of that name in directory _sisu/css or
 equivalent will result in the default file of that name being overwritten.
 
-
  HTML: html.css
-
  XML DOM: dom.css
-
  XML SAX: sax.css
-
  XHTML: xhtml.css
+
  HTML: html.css 
+
  XML DOM: dom.css 
+
  XML SAX: sax.css 
+
  XHTML: xhtml.css 
 

- The default homepage may use homepage.css or html.css
+ The default homepage may use homepage.css or html.css 
 
  Under consideration
 is to permit the placement of a CSS file with a different name in directory
 _sisu/css directory or equivalent, and change the default CSS file that
-is looked for in a skin.[^17]
-
 17. ORGANISING CONTENT
+is looked for in a skin.[^17] 
+
 17. ORGANISING CONTENT  
 
 17.1 DIRECTORY STRUCTURE
 
-
AND MAPPING
+
AND MAPPING 
 
  The output directory root can be set in the sisurc.yml file.
 Under the root, subdirectories are made for each directory in which a document
 set resides. If you have a directory named poems or conventions, that directory
@@ -1924,7 +1976,7 @@ will be created under the output directory root and the output for all
 documents contained in the directory of a particular name will be generated
 to subdirectories beneath that directory (poem or conventions). A document
 will be placed in a subdirectory of the same name as the document with
-the filetype identifier stripped (.sst .ssm)
+the filetype identifier stripped (.sst .ssm) 
 
  The last part of a directory
 path, representing the sub-directory in which a document set resides, is
 the directory name that will be used for the output directory. This has
@@ -1940,45 +1992,45 @@ named after each institution, and these would be output to the same output
 directory. Skins could be associated with each institution on a directory
 basis and resulting documents will take on the appropriate different appearance.
 
-
 17.2 ORGANISING CONTENT
-
 18. HOMEPAGES
+
 17.2 ORGANISING CONTENT 
+
 18. HOMEPAGES  
 
  SiSU is about the ability to auto-generate
 documents. Home pages are regarded as custom built items, and are not created
 by SiSU  SiSU has a default home page, which will not be appropriate for
 use with other sites, and the means to provide your own home page instead
-in one of two ways as part of a site’s configuration, these being:
+in one of two ways as part of a site’s configuration, these being: 
 
  1. through
 placing your home page and other custom built documents in the subdirectory
 _sisu/home/ (this probably being the easier and more convenient option)
 
-
  2. through providing what you want as the home page in a skin,
+
  2. through providing what you want as the home page in a skin, 
 
  Document
 sets are contained in directories, usually organised by site or subject.
 Each directory can/should have its own homepage. See the section on directory
-structure and organisation of content.
+structure and organisation of content. 
 
 18.1 HOME PAGE AND OTHER CUSTOM BUILT
 
-
PAGES IN A SUB-DIRECTORY
+
PAGES IN A SUB-DIRECTORY 
 
  Custom built pages, including the home page index.html
 may be placed within the configuration directory _sisu/home/ in any of
 the locations that is searched for the configuration directory, namely
 ./_sisu; ~/_sisu; /etc/sisu From there they are copied to the root of the
-output directory with the command:
+output directory with the command: 
 
    sisu -CC

-
-
 18.2 HOME PAGE WITHIN A SKIN
+ 
+
 18.2 HOME PAGE WITHIN A SKIN 
 
  Skins are described in a separate section,
 but basically are a file written in the programming language Ruby that
 may be provided to change the defaults that are provided with sisu with
-respect to individual documents, a directories contents or for a site.
+respect to individual documents, a directories contents or for a site. 
 

  If you wish to provide a homepage within a skin the skin should be in
 the directory _sisu/skin/dir and have the name of the directory for which
 it is to become the home page. Documents in the directory commercial_law
 would have the homepage modified in skin_commercial law.rb; or the directory
 
-
poems in skin_poems.rb
-

+
poems in skin_poems.rb 
+
 
 
 

 
    class Home
       def homepage
@@ -1994,20 +2046,20 @@ index.html
       end
     end
 

-
 19. MARKUP AND OUTPUT EXAMPLES
-
 19.1 MARKUP EXAMPLES
+
 19. MARKUP AND OUTPUT EXAMPLES  
+
 19.1 MARKUP EXAMPLES 
 
  Current markup examples
 and document output samples are provided at <http://www.jus.uio.no/sisu/SiSU/examples.html
 >
 
 
  Some markup with syntax highlighting may be found under <http://www.jus.uio.no/sisu/sample/syntax
 >
-but is not as up to date.
+but is not as up to date. 
 
  For some documents hardly any markup at all
 is required at all, other than a header, and an indication that the levels
-to be taken into account by the program in generating its output are.
+to be taken into account by the program in generating its output are. 
 
 20.
-SISU SEARCH - INTRODUCTION
+SISU SEARCH - INTRODUCTION  
 
  SiSU output can easily and conveniently be
 indexed by a number of standalone indexing tools, such as Lucene, Hyperestraier.
 
@@ -2015,28 +2067,28 @@ indexed by a number of standalone indexing tools, such as Lucene, Hyperestraier.
 the text object citation system is available hypothetically at least, for
 all forms of output, it is possible to search the sql database, and either
 read results from that database, or just as simply map the results to the
-html output, which has richer text markup.
+html output, which has richer text markup. 
 
  In addition to this SiSU has
 the ability to populate a relational sql type database with documents at
 an object level, with objects numbers that are shared across different
 output types, which make them searchable with that degree of granularity.
 Basically, your match criteria is met by these documents and at these locations
 within each document, which can be viewed within the database directly
-or in various output formats.
-
 21. SQL
+or in various output formats. 
+
 21. SQL  
 
 21.1 POPULATING SQL TYPE DATABASES
 
 
  SiSU feeds sisu markupd documents into sql type databases PostgreSQL[^18]
 and/or SQLite[^19] database together with information related to document
-structure.
+structure. 
 
  This is one of the more interesting output forms, as all the
 structural data of the documents are retained (though can be ignored by
 the user of the database should they so choose). All site texts/documents
-are (currently) streamed to four tables:
+are (currently) streamed to four tables: 
 
    * one containing semantic
 (and other) headers, including, title, author,

    subject, (the Dublin Core...);

-
+ 
 
    * another the substantive texts by individual

    along with structural information, each paragraph being identifiable
 by its

@@ -2044,25 +2096,25 @@ by its

    substantive text of each paragraph quite naturally being searchable
 (both in

    formatted and clean text versions for searching); and

-
+ 
 
    * a third containing endnotes cross-referenced back to the paragraph
 from

    which they are referenced (both in formatted and clean text versions
 for

    searching).

-
+ 
 
    * a fourth table with a one to one relation with the headers table
 contains

    full text versions of output, eg. pdf, html, xml, and ascii.

-
-
  There is of course the possibility to add further structures.
+ 
+
  There is of course the possibility to add further structures. 
 
  At this
 level SiSU loads a relational database with documents chunked into objects,
 their smallest logical structurally constituent parts, as text objects,
 with their object citation number and all other structural information
 needed to construct the document. Text is stored (at this text object level)
 with and without elementary markup tagging, the stripped version being
-so as to facilitate ease of searching.
+so as to facilitate ease of searching. 
 
  Being able to search a relational
 database at an object level with the SiSU citation system is an effective
 way of locating content generated by SiSU  object numbers, and all versions
@@ -2072,158 +2124,158 @@ output formats, with live links to the precise locations in the database
 or in html/xml documents; or, the structural information provided makes
 it possible to search the full contents of the database and have headings
 in which search content appears, or to search only headings etc. (as the
-Dublin Core is incorporated it is easy to make use of that as well).
+Dublin Core is incorporated it is easy to make use of that as well). 
 
 22.
-POSTGRESQL
-
 22.1 NAME
+POSTGRESQL  
+
 22.1 NAME 
 
  SiSU - Structured information, Serialized Units
-- a document publishing system, postgresql dependency package
+- a document publishing system, postgresql dependency package 
 
 22.2 DESCRIPTION
 
 
  Information related to using postgresql with sisu (and related to the
 sisu_postgresql dependency package, which is a dummy package to install
 dependencies needed for SiSU to populate a postgresql database, this being
-part of SiSU - man sisu).
-
 22.3 SYNOPSIS
+part of SiSU - man sisu). 
+
 22.3 SYNOPSIS 
 
    sisu -D [instruction] [filename/wildcard
  if  required]

-
+ 
 
    sisu -D --pg --[instruction] [filename/wildcard  if  required]

-
-
 22.4 COMMANDS
+ 
+
 22.4 COMMANDS 
 
  Mappings to two databases are provided by default, postgresql
 and sqlite, the same commands are used within sisu to construct and populate
 databases however -d (lowercase) denotes sqlite and -D (uppercase) denotes
-postgresql, alternatively --sqlite or --pgsql may be used
+postgresql, alternatively --sqlite or --pgsql may be used 
 
  -D or --pgsql may
-be used interchangeably.
-
 22.4.1 CREATE AND DESTROY DATABASE
-

+be used interchangeably. 
+
 22.4.1 CREATE AND DESTROY DATABASE 
+
 
 

 
 
--pgsql --createall
 

 
initial step, creates required relations (tables, indexes) in existing
 (postgresql) database (a database should be created manually and given
-the same name as working directory, as requested) (rb.dbi)
+the same name as working directory, as requested) (rb.dbi) 
 
 

 
 
sisu -D --createdb
 

 

-
creates database where no database existed before
+
creates database where no database existed before 
 
 

 
 
sisu -D --create 

 
creates
 
-
database tables where no database tables existed before
+
database tables where no database tables existed before 
 
 

 
 
sisu -D --Dropall
 

 
destroys database (including all its content)! kills data and drops tables,
 indexes and database associated with a given directory (and directories
-of the same name).
+of the same name). 
 
 

 
 
sisu -D --recreate 

 
destroys existing database and builds
 
-
a new empty database structure
+
a new empty database structure 
 
 

 

-22.4.2 IMPORT AND REMOVE DOCUMENTS
-

+22.4.2 IMPORT AND REMOVE DOCUMENTS 
+
 
 

 
 
sisu
 -D --import -v [filename/wildcard] 

 
populates database with the contents of
 the file. Imports documents(s) specified to a postgresql database (at an
-object level).
+object level). 
 
 

 
 
sisu -D --update -v [filename/wildcard] 

 
updates file contents
 
-
in database
+
in database 
 
 

 
 
sisu -D --remove -v [filename/wildcard] 

 
removes specified document
-from postgresql database.
+from postgresql database. 
 
 

 

-23. SQLITE
-
 23.1 NAME
+23. SQLITE  
+
 23.1 NAME 
 
  SiSU - Structured information,
-Serialized Units - a document publishing system.
-
 23.2 DESCRIPTION
+Serialized Units - a document publishing system. 
+
 23.2 DESCRIPTION 
 
  Information
 related to using sqlite with sisu (and related to the sisu_sqlite dependency
 package, which is a dummy package to install dependencies needed for SiSU
-to populate an sqlite database, this being part of SiSU - man sisu).
+to populate an sqlite database, this being part of SiSU - man sisu). 
 
 23.3
 
-
SYNOPSIS
+
SYNOPSIS 
 
    sisu -d [instruction] [filename/wildcard  if  required]

-
+ 
 
    sisu -d --(sqlite|pg) --[instruction] [filename/wildcard  if 

    required]

-
-
 23.4 COMMANDS
+ 
+
 23.4 COMMANDS 
 
  Mappings to two databases are provided by default, postgresql
 and sqlite, the same commands are used within sisu to construct and populate
 databases however -d (lowercase) denotes sqlite and -D (uppercase) denotes
-postgresql, alternatively --sqlite or --pgsql may be used
+postgresql, alternatively --sqlite or --pgsql may be used 
 
  -d or --sqlite may
-be used interchangeably.
-
 23.4.1 CREATE AND DESTROY DATABASE
-

+be used interchangeably. 
+
 23.4.1 CREATE AND DESTROY DATABASE 
+
 
 

 
 
--sqlite --createall
 

 
initial step, creates required relations (tables, indexes) in existing
 (sqlite) database (a database should be created manually and given the
-same name as working directory, as requested) (rb.dbi)
+same name as working directory, as requested) (rb.dbi) 
 
 

 
 
sisu -d --createdb
 

 

-
creates database where no database existed before
+
creates database where no database existed before 
 
 

 
 
sisu -d --create 

 
creates
 
-
database tables where no database tables existed before
+
database tables where no database tables existed before 
 
 

 
 
sisu -d --dropall
 

 
destroys database (including all its content)! kills data and drops tables,
 indexes and database associated with a given directory (and directories
-of the same name).
+of the same name). 
 
 

 
 
sisu -d --recreate 

 
destroys existing database and builds
 
-
a new empty database structure
+
a new empty database structure 
 
 

 

-23.4.2 IMPORT AND REMOVE DOCUMENTS
-

+23.4.2 IMPORT AND REMOVE DOCUMENTS 
+
 
 

 
 
sisu
 -d --import -v [filename/wildcard] 

 
populates database with the contents of
 the file. Imports documents(s) specified to an sqlite database (at an object
-level).
+level). 
 
 

 
 
sisu -d --update -v [filename/wildcard] 

@@ -2233,13 +2285,13 @@ level).
 
 
sisu -d --remove -v [filename/wildcard] 

 
removes specified document from sqlite
-database.
+database. 
 
 

 

-24. INTRODUCTION
+24. INTRODUCTION  
 
 24.1 SEARCH - DATABASE FRONTEND SAMPLE, UTILISING
 DATABASE AND SISU FEATURES, INCLUDING OBJECT CITATION NUMBERING (BACKEND
-CURRENTLY POSTGRESQL)
+CURRENTLY POSTGRESQL) 
 
  Sample search frontend <http://search.sisudoc.org
 >
 [^20] A small database and sample query front-end (search from) that makes
@@ -2250,24 +2302,24 @@ locations within each document the matches are found. These results are
 relevant across all outputs using object citation numbering, which includes
 html, XML, LaTeX, PDF and indeed the SQL database. You can then refer to
 one of the other outputs or in the SQL database expand the text within
-the matched objects (paragraphs) in the documents matched.
+the matched objects (paragraphs) in the documents matched. 
 
  Note you may
 set results either for documents matched and object number locations within
 each matched document meeting the search criteria; or display the names
 of the documents matched along with the objects (paragraphs) that meet
-the search criteria.[^22]
-

+the search criteria.[^22] 
+
 
 

 
 
sisu -F --webserv-webrick 

 
builds a cgi web search
 
-
frontend for the database created
+
frontend for the database created 
 
  The following is feedback on the setup
-on a machine provided by the help command:
+on a machine provided by the help command: 
 
    sisu --help sql

-
-

+ 
+
 
 
 

 
  Postgresql
     user:             ralph
@@ -2278,237 +2330,237 @@ on a machine provided by the help command:
     current db set:   /home/ralph/sisu_www/sisu/sisu_sqlite.db
     dbi connect       DBI:SQLite:/home/ralph/sisu_www/sisu/sisu_sqlite.db
 

-
  Note on databases built
+
  Note on databases built 
 
  By default, [unless  otherwise  specified] databases
 are built on a directory basis, from collections of documents within that
 directory. The name of the directory you choose to work from is used as
 the database name, i.e. if you are working in a directory called /home/ralph/ebook
 the database SiSU_ebook is used. [otherwise  a  manual  mapping  for  the  collection
- is
+ is 
 
 

 

-24.2 SEARCH FORM
-

+24.2 SEARCH FORM 
+
 
 

 
 
sisu -F 

 
generates a sample search form, which must
 
-
be copied to the web-server cgi directory
+
be copied to the web-server cgi directory 
 
 

 
 
sisu -F --webserv-webrick 

 
generates
 a sample search form for use with the webrick server, which must be copied
 
-
to the web-server cgi directory
+
to the web-server cgi directory 
 
 

 
 
sisu -Fv 

 
as above, and provides some information
 
-
on setting up hyperestraier
+
on setting up hyperestraier 
 
 

 
 
sisu -W 

 
starts the webrick server which should
 
-
be available wherever sisu is properly installed
+
be available wherever sisu is properly installed 
 
  The generated search
 
-
form must be copied manually to the webserver directory as instructed
+
form must be copied manually to the webserver directory as instructed 
 

 

 

-25. HYPERESTRAIER
-
  See the documentation for hyperestraier:
+25. HYPERESTRAIER  
+
  See the documentation for hyperestraier: 
 
    <http://hyperestraier.sourceforge.net/
 >

-
+ 
 
    /usr/share/doc/hyperestraier/index.html

-
+ 
 
    man estcmd

-
-
  on sisu_hyperestraier:
+ 
+
  on sisu_hyperestraier: 
 
    man sisu_hyperestraier

-
+ 
 
    /usr/share/doc/sisu/sisu_markup/sisu_hyperestraier/index.html

-
+ 
 
  NOTE: the examples that follow assume that sisu output is placed in
 
-
the directory /home/ralph/sisu_www
+
the directory /home/ralph/sisu_www 
 
  (A) to generate the index within the
-webserver directory to be indexed:
+webserver directory to be indexed: 
 
    estcmd gather -sd [index  name] [directory
  path  to  index]

-
+ 
 
  the following are examples that will need to be tailored according to
-your needs:
+your needs: 
 
    cd /home/ralph/sisu_www

-
+ 
 
    estcmd gather -sd casket /home/ralph/sisu_www

-
+ 
 
  you may use the ’find’ command together with ’egrep’ to limit indexing to
 particular document collection directories within the web server directory:
 
 
    find /home/ralph/sisu_www -type f | egrep

    ’/home/ralph/sisu_www/sisu/.+?.html$’ |estcmd gather -sd casket -

-
+ 
 
  Check which directories in the webserver/output directory (~/sisu_www
 or elsewhere depending on configuration) you wish to include in the search
-index.
+index. 
 
  As sisu duplicates output in multiple file formats, it it is probably
 preferable to limit the estraier index to html output, and as it may also
 be desirable to exclude files ’plain.txt’, ’toc.html’ and ’concordance.html’, as
-these duplicate information held in other html output e.g.
+these duplicate information held in other html output e.g. 
 
    find /home/ralph/sisu_www
 -type f | egrep

    ’/sisu_www/(sisu|bookmarks)/.+?.html$’ | egrep -v

    ’(doc|concordance).html$’ |estcmd gather -sd casket -

-
+ 
 
  from your current document preparation/markup directory, you would construct
-a rune along the following lines:
+a rune along the following lines: 
 
    find /home/ralph/sisu_www -type f
 | egrep ’/home/ralph/sisu_www/([specify 

    first  directory  for  inclusion]|[specify  second  directory  for 

    inclusion]|[another  directory  for  inclusion?  ...])/.+?.html$’ |

    egrep -v ’(doc|concordance).html$’ |estcmd gather -sd

    /home/ralph/sisu_www/casket -

-
-
  (B) to set up the search form
+ 
+
  (B) to set up the search form 
 
  (i) copy estseek.cgi to your cgi directory
-and set file permissions to 755:
+and set file permissions to 755: 
 
    sudo cp -vi /usr/lib/estraier/estseek.cgi
 /usr/lib/cgi-bin

-
+ 
 
    sudo chmod -v 755 /usr/lib/cgi-bin/estseek.cgi

-
+ 
 
    sudo cp -v /usr/share/hyperestraier/estseek.* /usr/lib/cgi-bin

-
+ 
 
    [see  estraier  documentation  for  paths]

-
+ 
 
  (ii) edit estseek.conf, with attention to the lines starting ’indexname:’
-and ’replace:’:
+and ’replace:’: 
 
    indexname: /home/ralph/sisu_www/casket

-
+ 
 
    replace: ^file:///home/ralph/sisu_www{{!}}http://localhost
 

-
+ 
 
    replace: /index.html?${{!}}/

-
-
  (C) to test using webrick, start webrick:
+ 
+
  (C) to test using webrick, start webrick: 
 
    sisu -W

-
+ 
 
  and try open the url: <http://localhost:8081/cgi-bin/estseek.cgi
->
+> 
 
 26. SISU_WEBRICK
-
-
 26.1 NAME
+ 
+
 26.1 NAME 
 
  SiSU - Structured information, Serialized Units - a document
 
-
publishing system
-
 26.2 SYNOPSIS
-
  sisu_webrick [port]
-
  or
+
publishing system 
+
 26.2 SYNOPSIS 
+
  sisu_webrick [port] 
+
  or 
 
  sisu -W [port]
 
-
 26.3 DESCRIPTION
+
 26.3 DESCRIPTION 
 
  sisu_webrick is part of SiSU (man sisu) sisu_webrick
 starts Ruby ’s Webrick web-server and points it to the directories to which
 SiSU output is written, providing a list of these directories (assuming
-SiSU is in use and they exist).
+SiSU is in use and they exist). 
 
  The default port for sisu_webrick is set
 to 8081, this may be modified in the yaml file: ~/.sisu/sisurc.yml a sample
 of which is provided as /etc/sisu/sisurc.yml (or in the equivalent directory
-on your system).
-
 26.4 SUMMARY OF MAN PAGE
+on your system). 
+
 26.4 SUMMARY OF MAN PAGE 
 
  sisu_webrick, may be started
 on it’s own with the command: sisu_webrick [port] or using the sisu command
-with the -W flag: sisu -W [port]
+with the -W flag: sisu -W [port] 
 
  where no port is given and settings are
 
-
unchanged the default port is 8081
+
unchanged the default port is 8081 
 
 26.5 DOCUMENT PROCESSING COMMAND FLAGS
 
 
  sisu -W [port] starts Ruby Webrick web-server, serving SiSU output directories,
 on the port provided, or if no port is provided and the defaults have not
 
-
been changed in ~/.sisu/sisurc.yaml then on port 8081
+
been changed in ~/.sisu/sisurc.yaml then on port 8081 
 
 26.6 FURTHER INFORMATION
 
 
  For more information on SiSU see: <http://www.jus.uio.no/sisu
->
+> 
 
  or man sisu
 
-
 26.7 AUTHOR
-
  Ralph Amissah ralph@amissah.com or ralph.amissah@gmail.com
+
 26.7 AUTHOR 
+
  Ralph Amissah ralph@amissah.com or ralph.amissah@gmail.com 
 

 
-
26.8 SEE ALSO
+
26.8 SEE ALSO 
 
    sisu(1)
 

-
+ 
 
    sisu_vim(7)
 

-
+ 
 
    sisu(8)
 

-
-
 27. REMOTE SOURCE DOCUMENTS
+ 
+
 27. REMOTE SOURCE DOCUMENTS  
 
  SiSU processing instructions can be run
 against remote source documents by providing the url of the documents against
 which the processing instructions are to be carried out. The remote SiSU
 documents can either be sisu marked up files in plaintext .sst or .ssm or;
-zipped sisu files, sisupod.zip or filename.ssp
+zipped sisu files, sisupod.zip or filename.ssp 
 
  .sst / .ssm - sisu text files
 
 
  SiSU can be run against source text files on a remote machine, provide
 the processing instruction and the url. The source file and any associated
-parts (such as images) will be downloaded and generated locally.
-

+parts (such as images) will be downloaded and generated locally. 
+
 
 
 

 
  sisu -3 http://[provide  url  to  valid  .sst  or  .ssm  file]
 

 
  Any of the source documents in the sisu examples page can be used in
 this way, see <http://www.jus.uio.no/sisu/SiSU/examples.html
 > and use the url
-for the desired document.
+for the desired document. 
 
  NOTE: to set up a remote machine to serve SiSU
 documents in this way, images should be in the directory relative to the
 
-
document source ../_sisu/image
-
  sisupod - zipped sisu files
+
document source ../_sisu/image 
+
  sisupod - zipped sisu files 
 
  A sisupod is
 the zipped content of a sisu marked up text or texts and any other associated
-parts to the document such as images.
+parts to the document such as images. 
 
  SiSU can be run against a sisupod
 on a (local or) remote machine, provide the processing instruction and
 the url, the sisupod will be downloaded and the documents it contains generated
-locally.
-

+locally. 
+
 
 
 

 
  sisu -3 http://[provide  url  to  valid  sisupod.zip  or  .ssp  file]
 

 
  Any of the source documents in the sisu examples page can be used in
 this way, see <http://www.jus.uio.no/sisu/SiSU/examples.html
 > and use the url
-for the desired document.
-
 REMOTE DOCUMENT OUTPUT
-
 28. REMOTE OUTPUT
-

+for the desired document. 
+
 REMOTE DOCUMENT OUTPUT  
+
 28. REMOTE OUTPUT  
+
 
 Once properly configured SiSU output can be automatically posted once generated
-to a designated remote machine using either rsync, or scp.
+to a designated remote machine using either rsync, or scp. 
 
  In order to
 do this some ssh authentication agent and keychain or similar tool will
 need to be configured. Once that is done the placement on a remote host
 can be done seamlessly with the -r (for scp) or -R (for rsync) flag, which
-may be used in conjunction with other processing flags, e.g.
-

+may be used in conjunction with other processing flags, e.g. 
+
 
 
 

 
  sisu -3R sisu_remote.sst
 

-
 28.1 COMMANDS
-

+
 28.1 COMMANDS 
+
 
 

 
 
-R [filename/wildcard] 

@@ -2517,7 +2569,7 @@ host using rsync. This requires that sisurc.yml has been provided with informati
 on hostname and username, and that you have your different if -R is used
 with other flags from if used alone. Alone the rsync --delete parameter is
 sent, useful for cleaning the remote directory (when -R is used together
-with other flags, it is not). Also see -r
+with other flags, it is not). Also see -r 
 
 
 
 
-r [filename/wildcard] 

@@ -2525,45 +2577,45 @@ with other flags, it is not). Also see -r
 output files to remote host using scp. This requires that sisurc.yml has
 been provided with information on hostname and username, and that you have
 
-
your
+
your 
 
 
 

-28.2 CONFIGURATION
+28.2 CONFIGURATION 
 
  [expand  on  the  setting  up  of  an  ssh-agent  /  keychain]
 
-
 29. REMOTE SERVERS
+
 29. REMOTE SERVERS  
 
  As SiSU is generally operated using the command line,
 and works within a Unix type environment, SiSU the program and all documents
 can just as easily be on a remote server, to which you are logged on using
 a terminal, and commands and operations would be pretty much the same as
-they would be on your local machine.
+they would be on your local machine. 
 
 30. QUICKSTART - GETTING STARTED HOWTO
-
-
 30.1 INSTALLATION
+ 
+
 30.1 INSTALLATION 
 
  Installation is currently most straightforward and
 tested on the Debian platform, as there are packages for the installation
-of sisu and all requirements for what it does.
+of sisu and all requirements for what it does. 
 
 30.1.1 DEBIAN INSTALLATION
 
 
  SiSU is available directly from the Debian Sid and testing archives (and
 possibly Ubuntu), assuming your /etc/apt/sources.list is set accordingly:
 
-

+
 
 
 

 
    aptitude update
     aptitude install sisu-complete
 

 
  The following /etc/apt/sources.list setting permits the download of additional
-markup samples:
-

+markup samples: 
+
 
 
 

 
  #/etc/apt/sources.list
     deb http://ftp.fi.debian.org/debian/ unstable main non-free contrib
     deb-src http://ftp.fi.debian.org/debian/ unstable main non-free contrib
   d
 

-
  The aptitude commands become:
-

+
  The aptitude commands become: 
+
 
 
 

 
    aptitude update
     aptitude install sisu-complete sisu-markup-samples
@@ -2572,308 +2624,308 @@ markup samples:
 
 
they will be available by adding the following to your /etc/apt/sources.list
 
-

+
 
 
 

 
  #/etc/apt/sources.list
     deb http://www.jus.uio.no/sisu/archive unstable main non-free
     deb-src http://www.jus.uio.no/sisu/archive unstable main non-free
 

-
  repeat the aptitude commands
-

+
  repeat the aptitude commands 
+
 
 
 

 
    aptitude update
     aptitude install sisu-complete sisu-markup-samples
 

 
  Note however that it is not necessary to install sisu-complete if not
 all components of sisu are to be used. Installing just the package sisu
-will provide basic functionality.
-
 30.1.2 RPM INSTALLATION
+will provide basic functionality. 
+
 30.1.2 RPM INSTALLATION 
 
  RPMs are provided
 though untested, they are prepared by running alien against the source
-package, and against the debs.
-
  They may be downloaded from:
+package, and against the debs. 
+
  They may be downloaded from: 
 
    <http://www.jus.uio.no/sisu/SiSU/download.html#rpm
 >

-
-
  as root type:
+ 
+
  as root type: 
 
    rpm -i [rpm  package  name]

-
-
 30.1.3 INSTALLATION FROM SOURCE
+ 
+
 30.1.3 INSTALLATION FROM SOURCE 
 
  To install SiSU from source check information
-at:
+at: 
 
    <http://www.jus.uio.no/sisu/SiSU/download.html#current
 >

-
-
  * download the source package
-
  * Unpack the source
+ 
+
  * download the source package 
+
  * Unpack the source 
 
  Two alternative
 modes of installation from source are provided, setup.rb (by Minero Aoki)
 and a rant(by Stefan Lang) built install file, in either case: the first
-steps are the same, download and unpack the source file:
+steps are the same, download and unpack the source file: 
 
  For basic use
 SiSU is only dependent on the programming language in which it is written
 Ruby , and SiSU will be able to generate html, various XMLs, including
 ODF (and will also produce LaTeX). Dependencies required for further actions,
 though it relies on the installation of additional dependencies which the
 source tarball does not take care of, for things like using a database
-(postgresql or sqlite)[^23] or converting LaTeX to pdf.
-
  setup.rb
+(postgresql or sqlite)[^23] or converting LaTeX to pdf. 
+
  setup.rb 
 
  This
 is a standard ruby installer, using setup.rb is a three step process. In
-the root directory of the unpacked SiSU as root type:
-

+the root directory of the unpacked SiSU as root type: 
+
 
 
 

 
      ruby setup.rb config
       ruby setup.rb setup
       #[and  as  root:]
       ruby setup.rb install
 

-
  further information on setup.rb is available from:
+
  further information on setup.rb is available from: 
 
    <http://i.loveruby.net/en/projects/setup/
 >

-
+ 
 
    <http://i.loveruby.net/en/projects/setup/doc/usage.html
 >

-
-
  
-
  The root directory of the unpacked SiSU as root type:
+ 
+
   
+
  The root directory of the unpacked SiSU as root type: 
 
    ruby install
 base

-
-
  or for a more complete installation:
+ 
+
  or for a more complete installation: 
 
    ruby install

-
-
  or
+ 
+
  or 
 
    ruby install base

-
+ 
 
  This makes use of Rant (by Stefan Lang) and the provided Rantfile. It
 has been configured to do post installation setup setup configuration and
 generation of first test file. Note however, that additional external package
-dependencies, such as tetex-extra are not taken care of for you.
+dependencies, such as tetex-extra are not taken care of for you. 
 
  Further
 
-
information on
+
information on 
 
    <http://make.rubyforge.org/
 >

-
+ 
 
    <http://rubyforge.org/frs/?group_id=615
 >

-
-
  For a list of alternative actions you may type:
+ 
+
  For a list of alternative actions you may type: 
 
    ruby install help

-
+ 
 
    ruby install -T

-
-
 30.2 TESTING SISU, GENERATING OUTPUT
+ 
+
 30.2 TESTING SISU, GENERATING OUTPUT 
 
  To check which version of sisu
-is installed:
-
  sisu -v
+is installed: 
+
  sisu -v 
 
  Depending on your mode of installation one or
-a number of markup sample files may be found either in the directory:
+a number of markup sample files may be found either in the directory: 
 

-
-
  or
-

-
  change directory to the appropriate one:
+  
+
  or 
+
   
+
  change directory to the appropriate one: 
 
  cd /usr/share/doc/sisu/sisu_markup_samples/dfsg
 
-
 30.2.1 BASIC TEXT, PLAINTEXT, HTML, XML, ODF
+
 30.2.1 BASIC TEXT, PLAINTEXT, HTML, XML, ODF 
 
  Having moved to the directory
 that contains the markup samples (see instructions above if necessary),
 
-
choose a file and run sisu against it
+
choose a file and run sisu against it 
 
  sisu -NhwoabxXyv free_as_in_freedom.rms_and_free_software.sam_williams.sst
 
 
  this will generate html including a concordance file, opendocument text
 format, plaintext, XHTML and various forms of XML, and OpenDocument text
 
-
 30.2.2 LATEX / PDF
+
 30.2.2 LATEX / PDF 
 
  Assuming a LaTeX engine such as tetex or texlive is
 installed with the required modules (done automatically on selection of
-sisu-pdf in Debian )
+sisu-pdf in Debian ) 
 
  Having moved to the directory that contains the markup
 samples (see instructions above if necessary), choose a file and run sisu
 
-
against it
+
against it 
 
  sisu -pv free_as_in_freedom.rms_and_free_software.sam_williams.sst
 
-
  sisu -3 free_as_in_freedom.rms_and_free_software.sam_williams.sst
+
  sisu -3 free_as_in_freedom.rms_and_free_software.sam_williams.sst 
 
  should
 generate most available output formats: html including a concordance file,
 opendocument text format, plaintext, XHTML and various forms of XML, and
 
-
OpenDocument text and pdf
+
OpenDocument text and pdf 
 
 30.2.3 RELATIONAL DATABASE - POSTGRESQL, SQLITE
 
 
  Relational databases need some setting up - you must have permission to
-create the database and write to it when you run sisu.
+create the database and write to it when you run sisu. 
 
  Assuming you have
 
-
the database installed and the requisite permissions
+
the database installed and the requisite permissions 
 
  sisu --sqlite --recreate
 
 
  sisu --sqlite -v --import free_as_in_freedom.rms_and_free_software.sam_williams.sst
 
-
  sisu --pgsql --recreate
+
  sisu --pgsql --recreate 
 
  sisu --pgsql -v --import free_as_in_freedom.rms_and_free_software.sam_williams.sst
 
-
 30.3 GETTING HELP
-
 30.3.1 THE MAN PAGES
-
  Type:
+
 30.3 GETTING HELP 
+
 30.3.1 THE MAN PAGES 
+
  Type: 
 
    man sisu

-
+ 
 
  The man pages are also available online, though not always kept as up
-to date as within the package itself:
+to date as within the package itself: 
 
  * sisu.1 <http://www.jus.uio.no/sisu/man/sisu.1
 >
-[^24]
+[^24] 
 
  * sisu.8 <http://www.jus.uio.no/sisu/man/sisu.8
-> [^25]
+> [^25] 
 
  * man directory
 <http://www.jus.uio.no/sisu/man
-> [^26]
-
 30.3.2 BUILT IN HELP
-
  sisu --help
+> [^26] 
+
 30.3.2 BUILT IN HELP 
+
  sisu --help 
 
  sisu
 
 
-
 
-
-
help --env
-
  sisu --help --commands
-
  sisu --help --markup
-
 30.3.3 THE HOME PAGE
-

+
help --env 
+
  sisu --help --commands 
+
  sisu --help --markup 
+
 30.3.3 THE HOME PAGE 
+
 
 <http://www.jus.uio.no/sisu
->
+> 
 
  <http://www.jus.uio.no/sisu/SiSU
->
+> 
 
 30.4 MARKUP SAMPLES
 
-
  A number of markup samples (along with output) are available off:
+
  A number of markup samples (along with output) are available off: 
 
  <http://www.jus.uio.no/sisu/SiSU/examples.html
 >
 
-
  Additional markup samples are packaged separately in the file:
-
  *
-

+
  Additional markup samples are packaged separately in the file: 
+
  * 
+
 
 On Debian they are available in non-free[^27] to include them it is necessary
 to include non-free in your /etc/apt/source.list or obtain them from the
-sisu home site.
-
 31. EDITOR FILES, SYNTAX HIGHLIGHTING
+sisu home site. 
+
 31. EDITOR FILES, SYNTAX HIGHLIGHTING  
 
  The directory:
 
 
    ./data/sisu/conf/editor-syntax-etc/

-
+ 
 
    /usr/share/sisu/conf/editor-syntax-etc

-
-
  contains rudimentary sisu syntax highlighting files for:
+ 
+
  contains rudimentary sisu syntax highlighting files for: 
 
  * (g)vim
 <http://www.vim.org
->
+> 
 
    package: sisu-vim

-
-
  status: largely done
+ 
+
  status: largely done 
 
    there is a vim syntax highlighting and folds
 component

-
+ 
 
  * gedit <http://www.gnome.org/projects/gedit
->
+> 
 
  * gobby <http://gobby.0x539.de/
 >
 
 
    file: sisu.lang

-
-
  place in:
+ 
+
  place in: 
 
    /usr/share/gtksourceview-1.0/language-specs

-
-
  or
+ 
+
  or 
 
    ~/.gnome2/gtksourceview-1.0/language-specs

-
+ 
 
    status: very basic syntax highlighting

-
+ 
 
    comments: this editor features display line wrap and is used by Goby!

-
+ 
 
  * nano <http://www.nano-editor.org
->
+> 
 
    file: nanorc

-
-
  save as:
+ 
+
  save as: 
 
    ~/.nanorc

-
+ 
 
    status: basic syntax highlighting

-
+ 
 
    comments: assumes dark background; no display line-wrap; does line
 breaks

-
+ 
 
  * diakonos (an editor written in ruby) <http://purepistos.net/diakonos
 >
 
-
  file: diakonos.conf
-
  save as:
+
  file: diakonos.conf 
+
  save as: 
 
    ~/.diakonos/diakonos.conf

-
-
  includes:
+ 
+
  includes: 
 
    status: basic syntax highlighting

-
-
  comments: assumes dark background; no display line-wrap
+ 
+
  comments: assumes dark background; no display line-wrap 
 
  * kate & kwrite
 <http://kate.kde.org
->
+> 
 
    file: sisu.xml

-
+ 
 
    place in:

-
+ 
 
      /usr/share/apps/katepart/syntax

-
+ 
 
    or

-
+ 
 
      ~/.kde/share/apps/katepart/syntax

-
+ 
 
    [settings::configure  kate::{highlighting,filetypes}]

-
+ 
 
    [tools::highlighting::{markup,scripts}::  .B  SiSU  ]

-
+ 
 
  * nedit <http://www.nedit.org
->
+> 
 
    file: sisu_nedit.pats

-
+ 
 
    nedit -import sisu_nedit.pats

-
+ 
 
    status: a very clumsy first attempt [not  really  done]

-
+ 
 
    comments: this editor features display line wrap

-
+ 
 
  * emacs <http://www.gnu.org/software/emacs/emacs.html
->
+> 
 
    files: sisu-mode.el

-
+ 
 
    to file ~/.emacs add the following 2 lines:

-
+ 
 
      (add-to-list ’load-path

-
+ 
 
      (require ’sisu-mode.el)

-
+ 
 
    [not  done  /  not  yet  included]

-
+ 
 
  * vim & gvim <http://www.vim.org
->
+> 
 
    files:

-
+ 
 
    package is the most comprehensive sisu syntax highlighting and editor

    environment provided to date (is for vim/ gvim, and is separate from
 the

    contents of this directory)

-
+ 
 
    status: this includes: syntax highlighting; vim folds; some error
 checking

-
+ 
 
    comments: this editor features display line wrap

-
-
  NOTE:
+ 
+
  NOTE: 
 
  [  .B  SiSU  parses  files  with  long  lines  or  line  breaks, but,  display
  linewrap  (without  line-breaks)  is  a  convenient editor  feature  to  have  for
- sisu  markup]
-
 32. HOW DOES SISU WORK?
+ sisu  markup] 
+
 32. HOW DOES SISU WORK?  
 
  SiSU markup is fairly minimalistic,
 it consists of: a (largely optional) document header, made up of information
 about the document (such as when it was published, who authored it, and
@@ -2891,12 +2943,12 @@ considerable flexibility in representing documents different ways and for
 different purposes (e.g. search, document layout, publishing, content certification,
 concordance etc.), and makes it possible to take advantage of some of the
 strengths of established ways of representing documents, (or indeed to
-create new ones).
-
 33. SUMMARY OF FEATURES
+create new ones). 
+
 33. SUMMARY OF FEATURES  
 
  * sparse/minimal markup (clean
 utf-8 source texts). Documents are prepared in a single UTF-8 file using a
 minimalistic mnemonic syntax. Typical literature, documents like headers
-are optional.
+are optional. 
 
  * markup is easily readable/parsable by the human eye, (basic
 markup is simpler and more sparse than the most basic HTML), [this  may
  also  be  converted  to  XML  representations  of  the  same  input/source  document].
@@ -2910,36 +2962,36 @@ may also contain processing instructions. SiSU markup is primarily an abs
 of document structure and document metadata to permit taking advantage
 of the basic strengths of existing alternative practical standard ways
 of representing documents [be  that  paper  publication,  sql  search  etc.] (html,
-xml, odf, latex, pdf, sql)
+xml, odf, latex, pdf, sql) 
 
  * for output produces reasonably elegant output
 of established industry and institutionally accepted open standard formats.[3]
 takes advantage of the different strengths of various standard formats
 for representing documents, amongst the output formats currently supported
-are:
+are: 
 
    * html - both as a single scrollable text and a segmented document

-
+ 
 
    * xhtml

-
+ 
 
    * XML - both in sax and dom style xml structures for further development
 as

    required

-
+ 
 
    * ODF - open document format, the iso standard for document storage

-
+ 
 
    * LaTeX - used to generate pdf

-
+ 
 
    * pdf (via LaTeX)

-
+ 
 
    * sql - population of an sql database, (at the same object level that
 is

    used to cite text within a document)

-
+ 
 
  Also produces: concordance files; document content certificates (md5
 or sha256 digests of headings, paragraphs, images etc.) and html manifests
 (and sitemaps of content). (b) takes advantage of the strengths implicit
 in these very different output types, (e.g. PDFs produced using typesetting
 of LaTeX, databases populated with documents at an individual object/paragraph
-level, making possible granular search (and related possibilities))
+level, making possible granular search (and related possibilities)) 
 
  *
 ensuring content can be cited in a meaningful way regardless of selected
 output format. Online publishing (and publishing in multiple document formats)
@@ -2950,23 +3002,23 @@ the text within a document, (which can be utilized for citation and by
 search engines). The outputs share a common numbering system that is meaningful
 (to man and machine) across all digital outputs whether paper, screen,
 or database oriented, (pdf, HTML, xml, sqlite, postgresql), this numbering
-system can be used to reference content.
+system can be used to reference content. 
 
  * Granular search within documents.
 SQL databases are populated at an object level (roughly headings, paragraphs,
 verse, tables) and become searchable with that degree of granularity, the
 output information provides the object/paragraph numbers which are relevant
 across all generated outputs; it is also possible to look at just the matching
 paragraphs of the documents in the database; [output  indexing  also  work
- well  with  search  indexing tools  like  hyperestraier].
+ well  with  search  indexing tools  like  hyperestraier]. 
 
  * long term maintainability
 of document collections in a world of changing formats, having a very sparsely
 marked-up source document base. there is a considerable degree of future-proofing,
 output representations are upgradeable (open document text) module in 2006
 and in future html5 output sometime in future, without modification of
 
-
existing prepared texts
+
existing prepared texts 
 
  * SQL search aside, documents are generated as
-required and static once generated.
+required and static once generated. 
 
  * documents produced are static files,
 and may be batch processed, this needs to be done only once but may be
 repeated for various reasons as desired (updated content, addition of new
@@ -2974,7 +3026,7 @@ output formats, updated technology document presentations/representations)
 
 
  * document source (plaintext utf-8) if shared on the net may be used as
 
-
input and processed locally to produce the different document outputs
+
input and processed locally to produce the different document outputs 
 

  * document source may be bundled together (automatically) with associated
 documents (multiple language versions or master document with inclusions)
@@ -2987,232 +3039,232 @@ and images and sent as a zip file called a sisupod, if shared on the net
 
  * for basic document generation, the only software dependency is Ruby
 , and a few standard Unix tools (this covers plaintext, HTML, XML, ODF,
 LaTeX). To use a database you of course need that, and to convert the LaTeX
-generated to pdf, a latex processor like tetex or texlive.
+generated to pdf, a latex processor like tetex or texlive. 
 
  * as a developers
 
-
tool it is flexible and extensible
+
tool it is flexible and extensible 
 
  Syntax highlighting for SiSU markup
-is available for a number of text editors.
+is available for a number of text editors. 
 
  SiSU is less about document
 layout than about finding a way with little markup to be able to construct
 an abstract representation of a document that makes it possible to produce
 multiple representations of it which may be rather different from each
 other and used for different purposes, whether layout and publishing, or
 
-
search of content
+
search of content 
 
  i.e. to be able to take advantage from this minimal preparation
 starting point of some of the strengths of rather different established
 ways of representing documents for different purposes, whether for search
 (relational database, or indexed flat files generated for that purpose
 whether of complete documents, or say of files made up of objects), online
-viewing (e.g. html, xml, pdf), or paper publication (e.g. pdf)...
+viewing (e.g. html, xml, pdf), or paper publication (e.g. pdf)... 
 
  the solution
 arrived at is by extracting structural information about the document (about
 headings within the document) and by tracking objects (which are serialized
 and also given hash values) in the manner described. It makes possible representations
 that are quite different from those offered at present. For example objects
 could be saved individually and identified by their hashes, with an index
-of how the objects relate to each other to form a document.
+of how the objects relate to each other to form a document. 
 
 34. HELP SOURCES
-
+ 
 
  For a summary of alternative ways to get help on SiSU try one of the
-following:
-
  man page
+following: 
+
  man page 
 
    man sisu_help

-
-
  man2html
+ 
+
  man2html 
 
    <http://www.jus.uio.no/sisu/man/sisu_help.1.html
 >

-
-
  sisu generated output - links to html
+ 
+
  sisu generated output - links to html 
 
    <http://sisudoc.org/sisu/sisu_help/index.html
 >

-
-
  help sources lists
+ 
+
  help sources lists 
 
  Alternative sources for this help sources page
-listed here:
+listed here: 
 
    man sisu_help_sources

-
+ 
 
    <http://sisudoc.org/sisu/sisu_help_sources/index.html
 >

-
-
 34.1 MAN PAGES
-
 34.1.1 MAN
+ 
+
 34.1 MAN PAGES 
+
 34.1.1 MAN 
 
    man sisu

-
+ 
 
    man 7 sisu_complete

-
+ 
 
    man 7 sisu_pdf

-
+ 
 
    man 7 sisu_postgresql

-
+ 
 
    man 7 sisu_sqlite

-
+ 
 
    man sisu_termsheet

-
+ 
 
    man sisu_webrick

-
-
 34.2 SISU GENERATED OUTPUT - LINKS TO HTML
+ 
+
 34.2 SISU GENERATED OUTPUT - LINKS TO HTML 
 
  Note SiSU documentation is
 prepared in SiSU and output is available in multiple formats including
 amongst others html, pdf, and odf which may be also be accessed via the
-html pages[^28]
-
 34.2.1 WWW.SISUDOC.ORG
+html pages[^28] 
+
 34.2.1 WWW.SISUDOC.ORG 
 
  <http://sisudoc.org/sisu/sisu_manual/index.html
 >
 
 
    <http://sisudoc.org/sisu/sisu_manual/index.html
 >

-
+ 
 
    <http://sisudoc.org/sisu/sisu_commands/index.html
 >

-
+ 
 
    <http://sisudoc.org/sisu/sisu_complete/index.html
 >

-
+ 
 
    <http://sisudoc.org/sisu/sisu_configuration/index.html
 >

-
+ 
 
    <http://sisudoc.org/sisu/sisu_description/index.html
 >

-
+ 
 
    <http://sisudoc.org/sisu/sisu_examples/index.html
 >

-
+ 
 
    <http://sisudoc.org/sisu/sisu_faq/index.html
 >

-
+ 
 
    <http://sisudoc.org/sisu/sisu_filetypes/index.html
 >

-
+ 
 
    <http://sisudoc.org/sisu/sisu_help/index.html
 >

-
+ 
 
    <http://sisudoc.org/sisu/sisu_help_sources/index.html
 >

-
+ 
 
    <http://sisudoc.org/sisu/sisu_howto/index.html
 >

-
+ 
 
    <http://sisudoc.org/sisu/sisu_introduction/index.html
 >

-
+ 
 
    <http://sisudoc.org/sisu/sisu_manual/index.html
 >

-
+ 
 
    <http://sisudoc.org/sisu/sisu_markup/index.html
 >

-
+ 
 
    <http://sisudoc.org/sisu/sisu_output_overview/index.html
 >

-
+ 
 
    <http://sisudoc.org/sisu/sisu_pdf/index.html
 >

-
+ 
 
    <http://sisudoc.org/sisu/sisu_postgresql/index.html
 >

-
+ 
 
    <http://sisudoc.org/sisu/sisu_quickstart/index.html
 >

-
+ 
 
    <http://sisudoc.org/sisu/sisu_remote/index.html
 >

-
+ 
 
    <http://sisudoc.org/sisu/sisu_search/index.html
 >

-
+ 
 
    <http://sisudoc.org/sisu/sisu_skin/index.html
 >

-
+ 
 
    <http://sisudoc.org/sisu/sisu_sqlite/index.html
 >

-
+ 
 
    <http://sisudoc.org/sisu/sisu_syntax_highlighting/index.html
 >

-
+ 
 
    <http://sisudoc.org/sisu/sisu_vim/index.html
 >

-
+ 
 
    <http://sisudoc.org/sisu/sisu_webrick/index.html
 >

-
-
 34.3 MAN2HTML
-
 34.3.1 LOCALLY INSTALLED
+ 
+
 34.3 MAN2HTML 
+
 34.3.1 LOCALLY INSTALLED 
 
  <file:///usr/share/doc/sisu/html/sisu.1.html>
 
-
  <file:///usr/share/doc/sisu/html/sisu_help.1.html>
+
  <file:///usr/share/doc/sisu/html/sisu_help.1.html> 
 
  <file:///usr/share/doc/sisu/html/sisu_help_sources.1.html>
 
 
    /usr/share/doc/sisu/html/sisu.1.html

-
+ 
 
    /usr/share/doc/sisu/html/sisu_pdf.7.html

-
+ 
 
    /usr/share/doc/sisu/html/sisu_postgresql.7.html

-
+ 
 
    /usr/share/doc/sisu/html/sisu_sqlite.7.html

-
+ 
 
    /usr/share/doc/sisu/html/sisu_webrick.1.html

-
-
 34.3.2 WWW.JUS.UIO.NO/SISU
+ 
+
 34.3.2 WWW.JUS.UIO.NO/SISU 
 
  <http://www.jus.uio.no/sisu/man/sisu.1.html
->
+> 
 
    <http://www.jus.uio.no/sisu/man/sisu.1.html
 >

-
+ 
 
    <http://www.jus.uio.no/sisu/man/sisu_complete.7.html
 >

-
+ 
 
    <http://www.jus.uio.no/sisu/man/sisu_pdf.7.html
 >

-
+ 
 
    <http://www.jus.uio.no/sisu/man/sisu_postgresql.7.html
 >

-
+ 
 
    <http://www.jus.uio.no/sisu/man/sisu_sqlite.7.html
 >

-
+ 
 
    <http://www.jus.uio.no/sisu/man/sisu_webrick.1.html
 >

-
-
 DOCUMENT INFORMATION (METADATA)
-
 METADATA
+ 
+
 DOCUMENT INFORMATION (METADATA)  
+
 METADATA  
 
  Document Manifest @ <http://sisudoc.org/sisu_manual/sisu/sisu_manifest.html
 >
 
-
  Dublin Core (DC)
+
  Dublin Core (DC) 
 
  DC tags included with this document are provided here.
 
-
 DC Title: SiSU - Manual
-
 DC Creator: Ralph Amissah
-
 DC Rights: 3
+
 DC Title: SiSU - Manual 
+
 DC Creator: Ralph Amissah 
+
 DC Rights: 3 
 
  DC Type:
 
-
information
-
  DC Date created: 2002-08-28
-
  DC Date issued: 2002-08-28
+
information 
+
  DC Date created: 2002-08-28 
+
  DC Date issued: 2002-08-28 
 
  DC
-Date available: 2002-08-28
-
  DC Date modified: 2008-05-22
+Date available: 2002-08-28 
+
  DC Date modified: 2008-05-22 
 
  DC Date: 2008-05-22
 
-
  Version Information
-
  Sourcefile: sisu.ssm.sst
+
  Version Information 
+
  Sourcefile: sisu.ssm.sst 
 
  Filetype: SiSU text insert
 
-
0.67
+
0.67 
 
  Sourcefile Digest, MD5(sisu.ssm.sst)= 7fbab3b7c0fd0ed2e128585c2982c5c8
 
 
  Skin_Digest: MD5(skin_sisu_manual.rb)= 072b2584bedea82ea8a416587b9fa244
 
-
  Generated
+
  Generated 
 
  Document (metaverse) last generated: Mon Jul 21 02:54:34
 
 
-
-
0400 2008
-
  Generated by: SiSU 0.68.0 of 2008w29/1 (2008-07-21)
+
0400 2008 
+
  Generated by: SiSU 0.68.0 of 2008w29/1 (2008-07-21) 
 
  Ruby version:
-ruby 1.8.7 (2008-06-20 patchlevel 22)  [i486-linux]
-

+ruby 1.8.7 (2008-06-20 patchlevel 22)  [i486-linux] 
+
 
 
    
 .
  1. objects include: headings,
 paragraphs, verse, tables, images, but not footnotes/endnotes which are
@@ -3291,7 +3343,7 @@ being added in future. 
    2. .
  2. < http://www.gigalaw.com/articles/ghosh-2000-01-p1.html }~ The current, privately owned software environment, GPL-proponents say, leads to monopoly abuse and stagnation. Strong companies suck all the oxygen out of the marketplace for rival competitors and innovative startups.
 
@@ -221,7 +226,7 @@ If the last two decades have brought dramatic changes to the software marketplac
 
 The crowd is filled with visitors who share Stallman's fashion and grooming tastes. Many come bearing laptop computers and cellular modems, all the better to record and transmit Stallman's words to a waiting Internet audience. The gender ratio is roughly 15 males to 1 female, and 1 of the 7 or 8 females in the room comes in bearing a stuffed penguin, the official Linux mascot, while another carries a stuffed teddy bear.
 
-{free_as_in_freedom_01_rms.png 381x321 "Richard Stallman, circa 2000. 'I decided I would develop a free software operating system or die trying ... of old age of course.' Photo courtesy of http://www.stallman.org " }http://www.free-culture.cc/
+{free_as_in_freedom_01_rms.png 381x321 "Richard Stallman, circa 2000. 'I decided I would develop a free software operating system or die trying ... of old age of course.' Photo courtesy of http://www.stallman.org " }http://en.wikipedia.org/wiki/Richard_stallman
 
 Agitated, Stallman leaves his post at the front of the room and takes a seat in a front-row chair, tapping a few commands into an already-opened laptop. For the next 10 minutes Stallman is oblivious to the growing number of students, professors, and fans circulating in front of him at the foot of the auditorium stage.
 
@@ -338,6 +343,7 @@ Seth Breidbart, a fellow Columbia Science Honors Program alumnus, offers bolster
 "It's hard to describe," Breidbart says. "It wasn't like he was unapproachable. He was just very intense. [He was] very knowledgeable but also very hardheaded in some ways."
 
 Such descriptions give rise to speculation: are judgment-laden adjectives like "intense" and "hardheaded" simply a way to describe traits that today might be categorized under juvenile behavioral disorder? A December, 2001, Wired magazine article titled "The Geek Syndrome" paints the portrait of several scientifically gifted children diagnosed with high-functioning autism or Asperger Syndrome. In many ways, the parental recollections recorded in the Wired article are eerily similar to the ones offered by Lippman. Even Stallman has indulged in psychiatric revisionism from time to time. During a 2000 profile for the Toronto Star, Stallman described himself to an interviewer as "borderline autistic,"~{ See Judy Steed, Toronto Star, BUSINESS, (October 9, 2000): C03.
    His vision of free software and social cooperation stands in stark contrast to the isolated nature of his private life. A Glenn Gould-like eccentric, the Canadian pianist was similarly brilliant, articulate, and lonely. Stallman considers himself afflicted, to some degree, by autism: a condition that, he says, makes it difficult for him to interact with people. }~ a description that goes a long way toward explaining a lifelong tendency toward social and emotional isolation and the equally lifelong effort to overcome it.
+={Asperger Syndrome+1;autism+5}
 
 Such speculation benefits from the fast and loose nature of most so-called " behavioral disorders" nowadays, of course. As Steve Silberman, author of " The Geek Syndrome," notes, American psychiatrists have only recently come to accept Asperger Syndrome as a valid umbrella term covering a wide set of behavioral traits. The traits range from poor motor skills and poor socialization to high intelligence and an almost obsessive affinity for numbers, computers, and ordered systems.~{ See Steve Silberman, "The Geek Syndrome," Wired (December, 2001).
     http://www.wired.com/wired/archive/9.12/aspergers_pr.html }~ Reflecting on the broad nature of this umbrella, Stallman says its possible that, if born 40 years later, he might have merited just such a diagnosis. Then again, so would many of his computer-world colleagues.
 
@@ -376,6 +382,7 @@ For all the agony it produced, adolescence would have a encouraging effect on St
 Outside the home, Stallman saved the jokes for the adults who tended to indulge his gifted nature. One of the first was a summer-camp counselor who handed Stallman a print-out manual for the IBM 7094 computer during his 12th year. To a preteenager fascinated with numbers and science, the gift was a godsend.~{ Stallman, an atheist, would probably quibble with this description. Suffice it to say, it was something Stallman welcomed. See previous note 1: "As soon as I heard about computers, I wanted to see one and play with one." }~ By the end of summer, Stallman was writing out paper programs according to the 7094's internal specifications, anxiously anticipating getting a chance to try them out on a real machine.
 
 With the first personal computer still a decade away, Stallman would be forced to wait a few years before getting access to his first computer. His first chance finally came during his junior year of high school. Hired on at the IBM New York Scientific Center, a now-defunct research facility in downtown Manhattan, Stallman spent the summer after high-school graduation writing his first program, a pre-processor for the 7094 written in the programming language PL/I. "I first wrote it in PL/I, then started over in assembler language when the PL/I program was too big to fit in the computer," he recalls.
+={assembler language}
 
 After that job at the IBM Scientific Center, Stallman had held a laboratory-assistant position in the biology department at Rockefeller University. Although he was already moving toward a career in math or physics, Stallman's analytical mind impressed the lab director enough that a few years after Stallman departed for college, Lippman received an unexpected phone call. "It was the professor at Rockefeller," Lippman says. "He wanted to know how Richard was doing. He was surprised to learn that he was working in computers. He'd always thought Richard had a great future ahead of him as a biologist."
 
@@ -393,7 +400,7 @@ By fall, Stallman was back within the mainstream population of New York City hig
 
 By the end of his first semester at Brandeis, things were falling into place. A 96 in English wiped away much of the stigma of the 60 earned 2 years before. For good measure, Stallman backed it up with top marks in American History, Advanced Placement Calculus, and Microbiology. The crowning touch was a perfect 100 in Physics. Though still a social outcast, Stallman finished his 11 months at Brandeis as the fourth-ranked student in a class of 789.
 
-{free_as_in_freedom_02_rms_snr_year_report.png 381x286 "Stallman's senior-year transcript at Louis D. Brandeis H.S., November, 1969. Note turnaround in English class performance. 'He was forced to kowtow to a certain degree,' says his mother, 'but he did it.'" }http://www.free-culture.cc/
+{free_as_in_freedom_02_rms_snr_year_report.png 381x286 "Stallman's senior-year transcript at Louis D. Brandeis H.S., November, 1969. Note turnaround in English class performance. 'He was forced to kowtow to a certain degree,' says his mother, 'but he did it.'" }http://en.wikipedia.org/wiki/Richard_stallman
 
 Outside the classroom, Stallman pursued his studies with even more diligence, rushing off to fulfill his laboratory-assistant duties at Rockefeller University during the week and dodging the Vietnam protesters on his way to Saturday school at Columbia. It was there, while the rest of the Science Honors Program students sat around discussing their college choices, that Stallman finally took a moment to participate in the preclass bull session.
 
@@ -494,12 +501,14 @@ For Stallman, the first taste of real computer programming at the IBM New York S
 Taking the manuals home, Stallman would examine machine specifications, compare them with other machines he already knew, and concoct a trial program, which he would then bring back to the lab along with the borrowed manual. Although some labs balked at the notion of a strange kid coming off the street and working on the lab machinery, most recognized competence when they saw it and let Stallman run the programs he had created.
 
 One day, near the end of freshman year, Stallman heard about a special laboratory near MIT. The laboratory was located on the ninth floor an off-campus building in Tech Square, the newly built facility dedicated to advanced research. According to the rumors, the lab itself was dedicated to the cutting-edge science of artificial intelligence and boasted the cutting-edge machines and software programs to match.
+={artificial intelligence}
 
 Intrigued, Stallman decided to pay a visit.
 
 The trip was short, about 2 miles on foot, 10 minutes by train, but as Stallman would soon find out, MIT and Harvard can feel like opposite poles of the same planet. With its maze-like tangle of interconnected office buildings, the Institute's campus offered an aesthetic yin to Harvard's spacious colonial-village yang. The same could be said for the student body, a geeky collection of ex-high school misfits known more for its predilection for pranks than its politically powerful alumni.
 
 The yin-yang relationship extended to the AI Lab as well. Unlike Harvard computer labs, there was no grad-student gatekeeper, no clipboard waiting list for terminal access, no explicit atmosphere of "look but don't touch." Instead, Stallman found only a collection of open terminals and robotic arms, presumably the artifacts of some A.I. experiment.
+={AI Lab (Artificial Intelligence Laboratory)+40}
 
 Although the rumors said anybody could sit down at the terminals, Stallman decided to stick with the original plan. When he encountered a lab employee, he asked if the lab had any spare manuals it could loan to an inquisitive student. "They had some, but a lot of things weren't documented," Stallman recalls. "They were hackers after all."
 
@@ -511,9 +520,10 @@ To get a taste of "bureaucratic and stuffy," Stallman need only visit the comput
 
 Stallman quickly learned that the AI Lab's first-come, first-served policy owed much to the efforts of a vigilant few. Many were holdovers from the days of Project MAC, the Department of Defense-funded research program that had given birth to the first time-share operating systems. A few were already legends in the computing world. There was Richard Greenblatt, the lab's in-house Lisp expert and author of MacHack, the computer chess program that had once humbled A.I. critic Hubert Dreyfus. There was Gerald Sussman, original author of the robotic block-stacking program HACKER. And there was Bill Gosper, the in-house math whiz already in the midst of an 18-month hacking bender triggered by the philosophical implications of the computer game LIFE.~{ See Steven Levy, Hackers (Penguin USA [paperback], 1984): 144.
    Levy devotes about five pages to describing Gosper's fascination with LIFE, a math-based software game first created by British mathematician John Conway. I heartily recommend this book as a supplement, perhaps even a prerequisite, to this one. }~
 
-Members of the tight-knit group called themselves " hackers." Over time, they extended the "hacker" description to Stallman as well. In the process of doing so, they inculcated Stallman in the ethical traditions of the "hacker ethic ." To be a hacker meant more than just writing programs, Stallman learned. It meant writing the best possible programs. It meant sitting at a terminal for 36 hours straight if that's what it took to write the best possible programs. Most importantly, it meant having access to the best possible machines and the most useful information at all times. Hackers spoke openly about changing the world through software, and Stallman learned the instinctual hacker disdain for any obstacle that prevented a hacker from fulfilling this noble cause. Chief among these obstacles were poor software, academic bureaucracy, and selfish behavior.
+Members of the tight-knit group called themselves "hackers." Over time, they extended the "hacker" description to Stallman as well. In the process of doing so, they inculcated Stallman in the ethical traditions of the "hacker ethic ." To be a hacker meant more than just writing programs, Stallman learned. It meant writing the best possible programs. It meant sitting at a terminal for 36 hours straight if that's what it took to write the best possible programs. Most importantly, it meant having access to the best possible machines and the most useful information at all times. Hackers spoke openly about changing the world through software, and Stallman learned the instinctual hacker disdain for any obstacle that prevented a hacker from fulfilling this noble cause. Chief among these obstacles were poor software, academic bureaucracy, and selfish behavior.
 
-Stallman also learned the lore, stories of how hackers, when presented with an obstacle, had circumvented it in creative ways. Stallman learned about " lock hacking," the art of breaking into professors' offices to "liberate" sequestered terminals. Unlike their pampered Harvard counterparts, MIT faculty members knew better than to treat the AI Lab's terminal as private property. If a faculty member made the mistake of locking away a terminal for the night, hackers were quick to correct the error. Hackers were equally quick to send a message if the mistake repeated itself. "I was actually shown a cart with a heavy cylinder of metal on it that had been used to break down the door of one professor's office,"~{ Gerald Sussman, an MIT faculty member and hacker whose work at the AI Lab predates Stallman's, disputes this memory. According to Sussman, the hackers never broke any doors to retrieve terminals. }~ Stallman says.
+Stallman also learned the lore, stories of how hackers, when presented with an obstacle, had circumvented it in creative ways. Stallman learned about "lock hacking," the art of breaking into professors' offices to "liberate" sequestered terminals. Unlike their pampered Harvard counterparts, MIT faculty members knew better than to treat the AI Lab's terminal as private property. If a faculty member made the mistake of locking away a terminal for the night, hackers were quick to correct the error. Hackers were equally quick to send a message if the mistake repeated itself. "I was actually shown a cart with a heavy cylinder of metal on it that had been used to break down the door of one professor's office,"~{ Gerald Sussman, an MIT faculty member and hacker whose work at the AI Lab predates Stallman's, disputes this memory. According to Sussman, the hackers never broke any doors to retrieve terminals. }~ Stallman says.
+={AI Lab (Artificial Intelligence Laboratory):lock hacking at+31}
 
 Such methods, while lacking in subtlety, served a purpose. Although professors and administrators outnumbered hackers two-to-one inside the AI Lab, the hacker ethic prevailed. Indeed, by the time of Stallman's arrival at the AI Lab, hackers and the AI Lab administration had coevolved into something of a symbiotic relationship. In exchange for fixing the machines and keeping the software up and running, hackers earned the right to work on favorite pet projects. Often, the pet projects revolved around improving the machines and software programs even further. Like teenage hot-rodders, most hackers viewed tinkering with machines as its own form of entertainment.
 
@@ -596,6 +606,7 @@ To call the Stallman gaze intense is an understatement. Stallman's eyes don't ju
 Maybe that's why most writers, when describing Stallman, tend to go for the religious angle. In a 1998 Salon.com article titled "The Saint of Free Software," Andrew Leonard describes Stallman's green eyes as "radiating the power of an Old Testament prophet."~{ See Andrew Leonard, "The Saint of Free Software," Salon.com (August 1998).
     http://www.salon.com/21st/feature/1998/08/cov_31feature.html }~ A 1999 Wired magazine article describes the Stallman beard as "Rasputin-like,"~{ See Leander Kahney, "Linux's Forgotten Man," Wired News (March 5, 1999).
     http://www.wired.com/news/print/0,1294,18291,00.html }~ while a London Guardian profile describes the Stallman smile as the smile of "a disciple seeing Jesus."~{ See "Programmer on moral high ground; Free software is a moral issue for Richard Stallman believes in freedom and free software." London Guardian (November 6, 1999).
    These are just a small sampling of the religious comparisons. To date, the most extreme comparison has to go to Linus Torvalds, who, in his autobiography-see Linus Torvalds and David Diamond, Just For Fun: The Story of an Accidentaly Revolutionary (HarperCollins Publishers, Inc., 2001): 58-writes "Richard Stallman is the God of Free Software."
    Honorable mention goes to Larry Lessig, who, in a footnote description of Stallman in his book-see Larry Lessig, The Future of Ideas (Random House, 2001): 270-likens Stallman to Moses:
    _1 ... as with Moses, it was another leader, Linus Torvalds, who finally carried the movement into the promised land by facilitating the development of the final part of the OS puzzle. Like Moses, too, Stallman is both respected and reviled by allies within the movement. He is [an] unforgiving, and hence for many inspiring, leader of a critically important aspect of modern culture. I have deep respect for the principle and commitment of this extraordinary individual, though I also have great respect for those who are courageous enough to question his thinking and then sustain his wrath.
    In a final interview with Stallman, I asked him his thoughts about the religious comparisons. "Some people do compare me with an Old Testament prophent, and the reason is Old Testament prophets said certain social practices were wrong. They wouldn't compromise on moral issues. They couldn't be bought off, and they were usually treated with contempt." }~
 
 Such analogies serve a purpose, but they ultimately fall short. That's because they fail to take into account the vulnerable side of the Stallman persona. Watch the Stallman gaze for an extended period of time, and you will begin to notice a subtle change. What appears at first to be an attempt to intimidate or hypnotize reveals itself upon second and third viewing as a frustrated attempt to build and maintain contact. If, as Stallman himself has suspected from time to time, his personality is the product of autism or Asperger Syndrome, his eyes certainly confirm the diagnosis. Even at their most high-beam level of intensity, they have a tendency to grow cloudy and distant, like the eyes of a wounded animal preparing to give up the ghost.
+={Asperger Syndrome;autism}
 
 My own first encounter with the legendary Stallman gaze dates back to the March, 1999, LinuxWorld Convention and Expo in San Jose, California. Billed as a "coming out party" for the Linux software community, the convention also stands out as the event that reintroduced Stallman to the technology media. Determined to push for his proper share of credit, Stallman used the event to instruct spectators and reporters alike on the history of the GNU Project and the project's overt political objectives.
 
@@ -616,6 +627,7 @@ Maybe that's why, when LinuxWorld follows up its first two shows with a third Li
 My second encounter with Stallman and his trademark gaze comes shortly after that third LinuxWorld show. Hearing that Stallman is going to be in Silicon Valley, I set up a lunch interview in Palo Alto, California. The meeting place seems ironic, not only because of the recent no-show but also because of the overall backdrop. Outside of Redmond, Washington, few cities offer a more direct testament to the economic value of proprietary software. Curious to see how Stallman, a man who has spent the better part of his life railing against our culture's predilection toward greed and selfishness, is coping in a city where even garage-sized bungalows run in the half-million-dollar price range, I make the drive down from Oakland.
 
 I follow the directions Stallman has given me, until I reach the headquarters of Art.net, a nonprofit "virtual artists collective." Located in a hedge-shrouded house in the northern corner of the city, the Art.net headquarters are refreshingly run-down. Suddenly, the idea of Stallman lurking in the heart of Silicon Valley doesn't seem so strange after all.
+={Art.net}
 
 I find Stallman sitting in a darkened room, tapping away on his gray laptop computer. He looks up as soon as I enter the room, giving me a full blast of his 200-watt gaze. When he offers a soothing "Hello," I offer a return greeting. Before the words come out, however, his eyes have already shifted back to the laptop screen.
 
@@ -780,6 +792,7 @@ The waiter, uncomprehending or fooled by the look of the bill, smiles and scurri
 1~ Chapter 6 - The Emacs Commune
 
 The AI Lab of the 1970s was by all accounts a special place. Cutting-edge projects and top-flight researchers gave it an esteemed position in the world of computer science. The internal hacker culture and its anarchic policies lent a rebellious mystique as well. Only later, when many of the lab's scientists and software superstars had departed, would hackers fully realize the unique and ephemeral world they had once inhabited.
+={AI Lab (Artificial Intelligence Laboratory)+17}
 
 "It was a bit like the Garden of Eden," says Stallman, summing up the lab and its software-sharing ethos in a 1998 Forbes article. "It hadn't occurred to us not to cooperate."~{ See Josh McHugh, "For the Love of Hacking," Forbes (August 10, 1998).
     http://www.forbes.com/forbes/1998/0810/6203094a.html }~
 
@@ -874,6 +887,7 @@ Although Stallman had been powerless to head off Reid's sale, he did possess the
 Over time, Emacs became a sales tool for the hacker ethic. The flexibility Stallman and built into the software not only encouraged collaboration, it demanded it. Users who didn't keep abreast of the latest developments in Emacs evolution or didn't contribute their contributions back to Stallman ran the risk of missing out on the latest breakthroughs. And the breakthroughs were many. Twenty years later, users had modified Emacs for so many different uses-using it as a spreadsheet, calculator, database, and web browser-that later Emacs developers adopted an overflowing sink to represent its versatile functionality. "That's the idea that we wanted to convey," says Stallman. "The amount of stuff it has contained within it is both wonderful and awful at the same time."
 
 Stallman's AI Lab contemporaries are more charitable. Hal Abelson, an MIT grad student who worked with Stallman during the 1970s and would later assist Stallman as a charter boardmember of the Free Software Foundation, describes Emacs as "an absolutely brilliant creation." In giving programmers a way to add new software libraries and features without messing up the system, Abelson says, Stallman paved the way for future large-scale collaborative software projects. "Its structure was robust enough that you'd have people all over the world who were loosely collaborating [and] contributing to it," Abelson says. "I don't know if that had been done before."~{ In writing this chapter, I've elected to focus more on the social significance of Emacs than the software significance. To read more about the software side, I recommend Stallman's 1979 memo. I particularly recommend the section titled "Research Through Development of Installed Tools" (#SEC27). Not only is it accessible to the nontechnical reader, it also sheds light on how closely intertwined Stallman's political philosophies are with his software-design philosophies. A sample excerpt follows:
    _1 EMACS could not have been reached by a process of careful design, because such processes arrive only at goals which are visible at the outset, and whose desirability is established on the bottom line at the outset. Neither I nor anyone else visualized an extensible editor until I had made one, nor appreciated its value until he had experienced it. EMACS exists because I felt free to make individually useful small improvements on a path whose end was not in sight. }~
+={Abelson, Hal}
 
 Guy Steele expresses similar admiration. Currently a research scientist for Sun Microsystems, he remembers Stallman primarily as a "brilliant programmer with the ability to generate large quantities of relatively bug-free code." Although their personalities didn't exactly mesh, Steele and Stallman collaborated long enough for Steele to get a glimpse of Stallman's intense coding style. He recalls a notable episode in the late 1970s when the two programmers banded together to write the editor's "pretty print" feature. Originally conceived by Steele, pretty print was another keystroke-triggerd feature that reformatted Emacs' source code so that it was both more readable and took up less space, further bolstering the program's WYSIWIG qualities. The feature was strategic enough to attract Stallman's active interest, and it wasn't long before Steele wrote that he and Stallman were planning an improved version.
 
@@ -898,10 +912,13 @@ Anticipating a skeptical response on some readers' part, the author made sure to
 _1 I am Richard Stallman, inventor of the original much-imitated EMACS editor, now at the Artificial Intelligence Lab at MIT. I have worked extensively on compilers, editors, debuggers, command interpreters, the Incompatible Timesharing System and the Lisp Machine operating system. I pioneered terminal-independent display support in ITS. In addition I have implemented one crashproof file system and two window systems for Lisp machines. ^44^
 
 As fate would have it, Stallman's fanciful GNU Project missed its Thanksgiving launch date. By January, 1984, however, Stallman made good on his promise and fully immersed himself in the world of Unix software development. For a software architect raised on ITS, it was like designing suburban shopping malls instead of Moorish palaces. Even so, building a Unix-like operating system had its hidden advantages. ITS had been powerful, but it also possessed an Achilles' heel: MIT hackers had designed it to take specific advantage of the DEC-built PDP line. When AI Lab administrators elected to phase out the lab's powerful PDP-10 machine in the early 1980s, the operating system that hackers once likened to a vibrant city became an instant ghost town. Unix, on the other hand, was designed for mobility and long-term survival. Originally developed by junior scientists at AT&T, the program had slipped out under corporate-management radar, finding a happy home in the cash-strapped world of academic computer systems. With fewer resources than their MIT brethren, Unix developers had customized the software to ride atop a motley assortment of hardware systems: everything from the 16-bit PDP-11-a machine considered fit for only small tasks by most AI Lab hackers-to 32-bit mainframes such as the VAX 11/780. By 1983, a few companies, most notably Sun Microsystems, were even going so far as to develop a new generation of microcomputers, dubbed "workstations," to take advantage of the increasingly ubiquitous operating system.
+={AT&T}
 
 To facilitate this process, the developers in charge of designing the dominant Unix strains made sure to keep an extra layer of abstraction between the software and the machine. Instead of tailoring the operating system to take advantage of a specific machine's resources-as the AI Lab hackers had done with ITS and the PDP-10-Unix developers favored a more generic, off-the-rack approach. Focusing more on the interlocking standards and specifications that held the operating system's many subcomponents together, rather than the actual components themselves, they created a system that could be quickly modified to suit the tastes of any machine. If a user quibbled with a certain portion, the standards made it possible to pull out an individual subcomponent and either fix it or replace it with something better. Simply put, what the Unix approach lacked in terms of style or aesthetics, it more than made up for in terms of flexibility and economy, hence its rapid adoption.~{ See Marshall Kirk McKusick, "Twenty Years of Berkeley Unix," Open Sources (O'Reilly & Associates, Inc., 1999): 38. }~
+={abstraction:designing Unix}
 
 Stallman's decision to start developing the GNU system was triggered by the end of the ITS system that the AI Lab hackers had nurtured for so long. The demise of ITS had been a traumatic blow to Stallman. Coming on the heels of the Xerox laser printer episode, it offered further evidence that the AI Lab hacker culture was losing its immunity to business practices in the outside world.
+={AI Lab (Artificial Intelligence Laboratory):ITS demise+3}
 
 Like the software code that composed it, the roots of ITS' demise stretched way back. Defense spending, long a major font for computer-science research, had dried up during the post-Vietnam years. In a desperate quest for new funds, laboratories and universities turned to the private sector. In the case of the AI Lab, winning over private investors was an easy sell. Home to some of the most ambitious computer-science projects of the post-war era, the lab became a quick incubator of technology. Indeed, by 1980, most of the lab's staff, including many hackers, were dividing its time between Institute and commercial projects.
 
@@ -922,6 +939,7 @@ Cadging passwords and deliberately crashing the system in order to glean evidenc
 "There has been another attempt to seize power," Stallman wrote. "So far, the aristocratic forces have been defeated." To protect his identity, Stallman signed the message "Radio Free OZ."
 
 The disguise was a thin one at best. By 1982, Stallman's aversion to passwords and secrecy had become so well known that users outside the AI Laboratory were using his account as a stepping stone to the ARPAnet, the research-funded computer network that would serve as a foundation for today's Internet. One such "tourist" during the early 1980s was Don Hopkins, a California programmer who learned through the hacking grapevine that all an outsider needed to do to gain access to MIT's vaunted ITS system was to log in under the initials RMS and enter the same three-letter monogram when the system requested a password.
+={ARPAnet+2}
 
 "I'm eternally grateful that MIT let me and many other people use their computers for free," says Hopkins. "It meant a lot to many people."
 
@@ -930,12 +948,16 @@ This so-called "tourist" policy, which had been openly tolerated by MIT manageme
 "[When] passwords first appeared at the MIT AI Lab I [decided] to follow my belief that there should be no passwords," Stallman would later say. "Because I don't believe that it's really desirable to have security on a computer, I shouldn't be willing to help uphold the security regime." ^46^
 
 Stallman's refusal to bow before the great and powerful Oz symbolized the growing tension between hackers and AI Lab management during the early 1980s. This tension paled in comparison to the conflict that raged within the hacker community itself. By the time the KL-10 arrived, the hacker community had already divided into two camps. The first centered around a software company called Symbolics, Inc. The second centered around Symbolics chief rival, Lisp Machines, Inc. (LMI). Both companies were in a race to market the Lisp Machine, a device built to take full advantage of the Lisp programming language.
+={Symbolics+15}
 
 Created by artificial-intelligence research pioneer John McCarthy, a MIT artificial-intelligence researcher during the late 1950s, Lisp is an elegant language well-suited for programs charged with heavy-duty sorting and processing. The language's name is a shortened version of LISt Processing. Following McCarthy's departure to the Stanford Artificial Intelligence Laboratory, MIT hackers refined the language into a local dialect dubbed MACLISP. The "MAC" stood for Project MAC, the DARPA-funded research project that gave birth to the AI Lab and the Laboratory for Computer Science. Led by AI Lab arch-hacker Richard Greenblatt, AI Lab programmers during the 1970s built up an entire Lisp-based operating system, dubbed the Lisp Machine operating system. By 1980, the Lisp Machine project had generated two commercial spin-offs. Symbolics was headed by Russell Noftsker, a former AI Lab administrator, and Lisp Machines, Inc., was headed by Greenblatt.
 
 The Lisp Machine software was hacker-built, meaning it was owned by MIT but available for anyone to copy as per hacker custom. Such a system limited the marketing advantage of any company hoping to license the software from MIT and market it as unique. To secure an advantage, and to bolster the aspects of the operating system that customers might consider attractive, the companies recruited various AI Lab hackers and set them working on various components of the Lisp Machine operating system outside the auspices of the AI Lab.
 
 The most aggressive in this strategy was Symbolics. By the end of 1980, the company had hired 14 AI Lab staffers as part-time consultants to develop its version of the Lisp Machine. Apart from Stallman, the rest signed on to help LMI.~{ See H. P. Newquist, The Brain Makers: Genius, Ego, and Greed in the Quest for Machines that Think (Sams Publishing, 1994): 172. }~
+={AI Lab (Artificial Intelligence Laboratory):Symbolics and+10}
+
+% Symbolics AI Lab longer range marked
 
 At first, Stallman accepted both companies' attempt to commercialize the Lisp machine, even though it meant more work for him. Both licensed the Lisp Machine OS source code from MIT, and it was Stallman's job to update the lab's own Lisp Machine to keep pace with the latest innovations. Although Symbolics' license with MIT gave Stallman the right to review, but not copy, Symbolics' source code, Stallman says a "gentleman's agreement" between Symbolics management and the AI Lab made it possible to borrow attractive snippets in traditional hacker fashion.
 
@@ -968,6 +990,7 @@ Stallman would have little opportunity to mourn. The Lisp Machine, despite all t
 Riding atop this microprocessor wave were hundreds-thousands-of commercial software programs, each protected by a patchwork of user licenses and nondisclosure agreements that made it impossible for hackers to review or share source code. The licenses were crude and ill-fitting, but by 1983 they had become strong enough to satisfy the courts and scare away would-be interlopers. Software, once a form of garnish most hardware companies gave away to make their expensive computer systems more flavorful, was quickly becoming the main dish. In their increasing hunger for new games and features, users were putting aside the traditional demand to review the recipe after every meal.
 
 Nowhere was this state of affairs more evident than in the realm of personal computer systems. Companies such as Apple Computer and Commodore were minting fresh millionaires selling machines with built-in operating systems. Unaware of the hacker culture and its distaste for binary-only software, many of these users saw little need to protest when these companies failed to attach the accompanying source-code files. A few anarchic adherents of the hacker ethic helped propel that ethic into this new marketplace, but for the most part, the marketplace rewarded the programmers speedy enough to write new programs and savvy enough to copyright them as legally protected works.
+={Apple Computers}
 
 One of the most notorious of these programmers was Bill Gates, a Harvard dropout two years Stallman's junior. Although Stallman didn't know it at the time, seven years before sending out his message to the n et.unix-wizards newsgroup, Gates, a budding entrepreneur and general partner with the Albuquerque-based software firm Micro-Soft, later spelled as Microsoft, had sent out his own open letter to the software-developer community. Written in response to the PC users copying Micro-Soft's software programs, Gates' " Open Letter to Hobbyists" had excoriated the notion of communal software development.
 
@@ -1032,6 +1055,7 @@ Forced to watch his work sink into the mire while his erstwhile employer struggl
 1~ Chapter 8 - St. Ignucius
 
 The Maui High Performance Computing Center is located in a single-story building in the dusty red hills just above the town of Kihei. Framed by million-dollar views and the multimillion dollar real estate of the Silversword Golf Course, the center seems like the ultimate scientific boondoggle. Far from the boxy, sterile confines of Tech Square or even the sprawling research metropolises of Argonne, Illinois and Los Alamos, New Mexico, the MHPCC seems like the kind of place where scientists spend more time on their tans than their post-doctoral research projects.
+={Argonne (Illinois)}
 
 The image is only half true. Although researchers at the MHPCC do take advantage of the local recreational opportunities, they also take their work seriously. According to Top500.org, a web site that tracks the most powerful supercomputers in the world, the IBM SP Power3 supercomputer housed within the MHPCC clocks in at 837 billion floating-point operations per second, making it one of 25 most powerful computers in the world. Co-owned and operated by the University of Hawaii and the U.S. Air Force, the machine divides its computer cycles between the number crunching tasks associated with military logistics and high-temperature physics research.
 
@@ -1093,7 +1117,7 @@ As if to drive home this message, Stallman punctuates his speech with an unusual
 
 "I am St. Ignucius of the Church of Emacs," says Stallman, raising his right hand in mock-blessing. "I bless your computer, my child."
 
-{free_as_in_freedom_03_rms_st_ignucius.png 188x209 "Stallman dressed as St. Ignucius. Photo by Wouter van Oortmerssen." }http://www.free-culture.cc/
+{free_as_in_freedom_03_rms_st_ignucius.png 188x209 "Stallman dressed as St. Ignucius. Photo by Wouter van Oortmerssen." }http://en.wikipedia.org/wiki/Richard_stallman
 
 The laughter turns into full-blown applause after a few seconds. As audience members clap, the computer disk on Stallman's head catches the glare of an overhead light, eliciting a perfect halo effect. In the blink of an eye, Stallman goes from awkward haole to Russian religious icon.
 
@@ -1221,12 +1245,14 @@ The German sociologist Max Weber once proposed that all great religions are buil
 While not religious per se, the GNU GPL certainly qualifies as an interesting example of this "routinization" process at work in the modern, decentralized world of software development. Since its unveiling, programmers and companies who have otherwise expressed little loyalty or allegiance to Stallman have willingly accepted the GPL bargain at face value. A few have even accepted the GPL as a preemptive protective mechanism for their own software programs. Even those who reject the GPL contract as too compulsory, still credit it as influential.
 
 One hacker falling into this latter group was Keith Bostic, a University of California employee at the time of the GPL 1.0 release. Bostic's department, the Computer Systems Research Group (SRG), had been involved in Unix development since the late 1970s and was responsible for many key parts of Unix, including the TCP/IP networking protocol, the cornerstone of modern Internet communications. By the late 1980s, AT&T, the original owner of the Unix brand name, began to focus on commercializing Unix and began looking to the Berkeley Software Distribution, or BSD, the academic version of Unix developed by Bostic and his Berkeley peers, as a key source of commercial technology.
+={AT&T+1}
 
 Although the Berkeley BSD source code was shared among researchers and commercial programmers with a source-code license, this commercialization presented a problem. The Berkeley code was intermixed with proprietary AT&T code. As a result, Berkeley distributions were available only to institutions that already had a Unix source license from AT&T. As AT&T raised its license fees, this arrangement, which had at first seemed innocuous, became increasingly burdensome.
 
 Hired in 1986, Bostic had taken on the personal project of porting BSD over to the Digital Equipment Corporation's PDP-11 computer. It was during this period, Bostic says, that he came into close interaction with Stallman during Stallman's occasional forays out to the west coast. "I remember vividly arguing copyright with Stallman while he sat at borrowed workstations at CSRG," says Bostic. "We'd go to dinner afterward and continue arguing about copyright over dinner."
 
 The arguments eventually took hold, although not in the way Stallman would have liked. In June, 1989, Berkeley separated its networking code from the rest of the AT&T-owned operating system and distributed it under a University of California license. The contract terms were liberal. All a licensee had to do was give credit to the university in advertisements touting derivative programs.~{ The University of California's "obnoxious advertising clause" would later prove to be a problem. Looking for a less restrictive alternative to the GPL, some hackers used the University of California, replacing "University of California" with the name of their own instution. The result: free software programs that borrowed from dozens of other programs would have to cite dozens of institutions in advertisements. In 1999, after a decade of lobbying on Stallman's part, the University of California agreed to drop this clause.
    See "The BSD License Problem" at http://www.gnu.org/philosophy/bsd.html. }~ In contrast to the GPL, proprietary offshoots were permissible. Only one problem hampered the license's rapid adoption: the BSD Networking release wasn't a complete operating system. People could study the code, but it could only be run in conjunction with other proprietary-licensed code.
+={AT&T+1}
 
 Over the next few years, Bostic and other University of California employees worked to replace the missing components and turn BSD into a complete, freely redistributable operating system. Although delayed by a legal challenge from Unix Systems Laboratories-the AT&T spin-off that retained ownership of the Unix brand name-the effort would finally bear fruit in the early 1990s. Even before then, however, many of the Berkeley utilities would make their way into Stallman's GNU Project.
 
@@ -1269,6 +1295,7 @@ According to Stallman, improving software programs was secondary to building the
 Nevertheless, as GNU tools made their mark in the late 1980s, Stallman's AI Lab-honed reputation for design fastidiousness soon became legendary throughout the entire software-development community.
 
 Jeremy Allison, a Sun user during the late 1980s and programmer destined to run his own free software project, Samba, in the 1990s, recalls that reputation with a laugh. During the late 1980s, Allison began using Emacs. Inspired by the program's community-development model, Allison says he sent in a snippet of source code only to have it rejected by Stallman.
+={Allison, Jeramy+1}
 
 "It was like the Onion headline," Allison says. "`Child's prayers to God answered: No.'"
 
@@ -1276,7 +1303,8 @@ Stallman's growing stature as a software programmer, however, was balanced by hi
 
 A review of GNU Project "GNUsletters" of the late 1980s reflects the management tension. In January, 1987, Stallman announced to the world that the GNU Project was working to overhaul TRIX, a Unix kernel developed at MIT. A year later, in February of 1988, the GNU Project announced that it had shifted its attentions to Mach, a lightweight "micro-kernel" developed at Carnegie Mellon. All told, however, official GNU Project kernel development wouldn't commence until 1990.~{ See "HURD History."
     http://www.gnu.org/software/hurd/history.html }~
 
-The delays in kernel development were just one of many concerns weighing on Stallman during this period. In 1989, Lotus Development Corporation filed suit against rival software company, Paperback Software International, for copying menu commands in Lotus' popular 1-2-3 Spreadsheet program. Lotus' suit, coupled with the Apple -Microsoft "look and feel" battle, provided a troublesome backdrop for the GNU Project. Although both suits fell outside the scope of the GNU Project, both revolved around operating systems and software applications developed for the personal computer, not Unix-compatible hardware systems-they threatened to impose a chilling effect on the entire culture of software development. Determined to do something, Stallman recruited a few programmer friends and composed a magazine ad blasting the lawsuits. He then followed up the ad by helping to organize a group to protest the corporations filing the suit. Calling itself the League of Programming Freedom, the group held protests outside the offices of Lotus, Inc. and the Boston courtroom hosting the Lotus trial.
+The delays in kernel development were just one of many concerns weighing on Stallman during this period. In 1989, Lotus Development Corporation filed suit against rival software company, Paperback Software International, for copying menu commands in Lotus' popular 1-2-3 Spreadsheet program. Lotus' suit, coupled with the Apple-Microsoft "look and feel" battle, provided a troublesome backdrop for the GNU Project. Although both suits fell outside the scope of the GNU Project, both revolved around operating systems and software applications developed for the personal computer, not Unix-compatible hardware systems-they threatened to impose a chilling effect on the entire culture of software development. Determined to do something, Stallman recruited a few programmer friends and composed a magazine ad blasting the lawsuits. He then followed up the ad by helping to organize a group to protest the corporations filing the suit. Calling itself the League of Programming Freedom, the group held protests outside the offices of Lotus, Inc. and the Boston courtroom hosting the Lotus trial.
+={Apple Computers}
 
 The protests were notable.~{ According to a League of Programming Freedom Press, the protests were notable for featuring the first hexadecimal protest chant:
    1-2-3-4, toss the lawyers out the door;
    5-6-7-8, innovate don't litigate;
    9-A-B-C, 1-2-3 is not for me;
    D-E-F-O, look and feel have got to go
     http://lpf.ai.mit.edu/Links/prep.ai.mit.edu/demo.final.release }~ They document the evolving nature of software industry. Applications had quietly replaced operating systems as the primary corporate battleground. In its unfulfilled quest to build a free software operating system, the GNU Project seemed hopelessly behind the times. Indeed, the very fact that Stallman had felt it necessary to put together an entirely new group dedicated to battling the "look and feel" lawsuits reinforced that obsolescence in the eyes of some observers.
 
@@ -1469,6 +1497,7 @@ Summarized Raymond, "I think Linus's cleverest and most consequential hack was n
 In summarizing the secrets of Torvalds' managerial success, Raymond himself had pulled off a coup. One of the audience members at the Linux Kongress was Tim O'Reilly, publisher of O'Reilly & Associates, a company specializing in software manuals and software-related books (and the publisher of this book). After hearing Raymond's Kongress speech, O'Reilly promptly invited Raymond to deliver it again at the company's inaugural Perl Conference later that year in Monterey, California.
 
 Although the conference was supposed to focus on Perl, a scripting language created by Unix hacker Larry Wall, O'Reilly assured Raymond that the conference would address other free software technologies. Given the growing commercial interest in Linux and Apache, a popular free software web server, O'Reilly hoped to use the event to publicize the role of free software in creating the entire infrastructure of the Internet. From web-friendly languages such as Perl and Python to back-room programs such as BIND (the Berkeley Internet Naming Daemon), a software tool that lets users replace arcane IP numbers with the easy-to-remember domain-name addresses (e.g., amazon.com), and sendmail, the most popular mail program on the Internet, free software had become an emergent phenomenon. Like a colony of ants creating a beautiful nest one grain of sand at a time, the only thing missing was the communal self-awareness. O'Reilly saw Raymond's speech as a good way to inspire that self-awareness, to drive home the point that free software development didn't start and end with the GNU Project. Programming languages, such as Perl and Python, and Internet software, such as BIND, sendmail, and Apache, demonstrated that free software was already ubiquitous and influential. He also assured Raymond an even warmer reception than the one at Linux Kongress.
+={Apache web server}
 
 O'Reilly was right. "This time, I got the standing ovation before the speech," says Raymond, laughing.
 
@@ -1477,8 +1506,10 @@ As predicted, the audience was stocked not only with hackers, but with other peo
 Intrigued by Raymond's speech and anxious to win back lost market share, Netscape executives took the message back to corporate headquarters. A few months later, in January, 1998, the company announced its plan to publish the source code of its flagship Navigator web browser in the hopes of enlisting hacker support in future development.
 
 When Netscape CEO Jim Barksdale cited Raymond's "Cathedral and the Bazaar" essay as a major influence upon the company's decision, the company instantly elevated Raymond to the level of hacker celebrity. Determined not to squander the opportunity, Raymond traveled west to deliver interviews, advise Netscape executives, and take part in the eventual party celebrating the publication of Netscape Navigator's source code. The code name for Navigator's source code was "Mozilla": a reference both to the program's gargantuan size-30 million lines of code-and to its heritage. Developed as a proprietary offshoot of Mosaic, the web browser created by Marc Andreessen at the University of Illinois, Mozilla was proof, yet again, that when it came to building new programs, most programmers preferred to borrow on older, modifiable programs.
+={Andreessen, Marc}
 
 While in California, Raymond also managed to squeeze in a visit to VA Research, a Santa Clara-based company selling workstations with the GNU/Linux operating system preinstalled. Convened by Raymond, the meeting was small. The invite list included VA founder Larry Augustin, a few VA employees, and Christine Peterson, president of the Foresight Institute, a Silicon Valley think tank specializing in nanotechnology.
+={Augustin, Larry}
 
 "The meeting's agenda boiled down to one item: how to take advantage of Netscape's decision so that other companies might follow suit?" Raymond doesn't recall the conversation that took place, but he does remember the first complaint addressed. Despite the best efforts of Stallman and other hackers to remind people that the word "free" in free software stood for freedom and not price, the message still wasn't getting through. Most business executives, upon hearing the term for the first time, interpreted the word as synonymous with "zero cost," tuning out any follow up messages in short order. Until hackers found a way to get past this cognitive dissonance, the free software movement faced an uphill climb, even after Netscape.
 
@@ -1519,6 +1550,7 @@ Summing up his position at the 1999 LinuxWorld Convention and Expo, an event bil
 "Because we've shown how much we can do, we don't have to be desperate to work with companies or compromise our goals," Stallman said during a panel discussion. "Let them offer and we'll accept. We don't have to change what we're doing to get them to help us. You can take a single step towards a goal, then another and then more and more and you'll actually reach your goal. Or, you can take a half measure that means you don't ever take another step and you'll never get there."
 
 Even before the LinuxWorld show, however, Stallman was showing an increased willingness to alienate his more conciliatory peers. A few months after the Freeware Summit, O'Reilly hosted its second annual Perl Conference. This time around, Stallman was in attendance. During a panel discussion lauding IBM's decision to employ the free software Apache web server in its commercial offerings, Stallman, taking advantage of an audience microphone, disrupted the proceedings with a tirade against panelist John Ousterhout, creator of the Tcl scripting language. Stallman branded Ousterhout a "parasite" on the free software community for marketing a proprietary version of Tcl via Ousterhout's startup company, Scriptics. "I don't think Scriptics is necessary for the continued existence of Tcl," Stallman said to hisses from the fellow audience members. ^98^
+={Apache web server}
 
 "It was a pretty ugly scene," recalls Prime Time Freeware's Rich Morin. "John's done some pretty respectable things: Tcl, Tk, Sprite. He's a real contributor."
 
@@ -1530,6 +1562,7 @@ http://www.opensource.org/docs/definition.html }~
 Perens would later resign from the OSI, expressing regret that the organization had set itself up in opposition to Stallman and the FSF. Still, looking back on the need for a free software definition outside the Free Software Foundation's auspices, Perens understands why other hackers might still feel the need for distance. "I really like and admire Richard," says Perens. "I do think Richard would do his job better if Richard had more balance. That includes going away from free software for a couple of months."
 
 Stallman's monomaniacal energies would do little to counteract the public-relations momentum of open source proponents. In August of 1998, when chip-maker Intel purchased a stake in GNU/Linux vendor Red Hat, an accompanying New York Times article described the company as the product of a movement "known alternatively as free software and open source."~{ See Amy Harmon, "For Sale: Free Operating System," New York Times (September 28, 1998).
     http://www.nytimes.com/library/tech/98/09/biztech/articles/28linux.html }~ Six months later, a John Markoff article on Apple Computer was proclaiming the company's adoption of the "open source" Apache server in the article headline.~{ See John Markoff, "Apple Adopts `Open Source' for its Server Computers," New York Times (March 17, 1999).
     http://www.nytimes.com/library/tech/99/03/biztech/articles/17apple.html }~
+={Apache web server;Apple Computers:open source software and}
 
 Such momentum would coincide with the growing momentum of companies that actively embraced the "open source" term. By August of 1999, Red Hat, a company that now eagerly billed itself as "open source," was selling shares on Nasdaq. In December, VA Linux-formerly VA Research-was floating its own IPO to historical effect. Opening at $30 per share, the company's stock price exploded past the $300 mark in initial trading only to settle back down to the $239 level. Shareholders lucky enough to get in at the bottom and stay until the end experienced a 698% increase in paper wealth, a Nasdaq record.
 
@@ -1702,6 +1735,7 @@ Moglen says that moment, more than any other, drove home the elemental simplicit
 Writing the biography of a living person is a bit like producing a play. The drama in front of the curtain often pales in comparison to the drama backstage.
 
 In The Autobiography of Malcolm X, Alex Haley gives readers a rare glimpse of that backstage drama. Stepping out of the ghostwriter role, Haley delivers the book's epilogue in his own voice. The epilogue explains how a freelance reporter originally dismissed as a "tool" and "spy" by the Nation of Islam spokesperson managed to work through personal and political barriers to get Malcolm X's life story on paper.
+={Autobiography of Malcolm X, The (Haley)+1}
 
 While I hesitate to compare this book with The Autobiography of Malcolm X, I do owe a debt of gratitude to Haley for his candid epilogue. Over the last 12 months, it has served as a sort of instruction manual on how to deal with a biographical subject who has built an entire career on being disagreeable. From the outset, I envisioned closing this biography with a similar epilogue, both as an homage to Haley and as a way to let readers know how this book came to be.
 
@@ -1775,6 +1809,7 @@ I made a few more suggestions with little effect. About the only thing I could g
 Before I signed off, Stallman suggested I tell the publisher that I'd promised Stallman that the work would be free. I told Stallman I couldn't agree to that statement but that I did view the book as unfinishable without his cooperation. Seemingly satisfied, Stallman hung up with his usual sign-off line: "Happy hacking."
 
 Henning and I met with Tracy the next day. Tracy said her company was willing to publish copyable excerpts in a unencrypted format but would limit the excerpts to 500 words. Henning informed her that this wouldn't be enough for me to get around my ethical obligation to Stallman. Tracy mentioned her own company's contractual obligation to online vendors such as Amazon.com. Even if the company decided to open up its e-book content this one time, it faced the risk of its partners calling it a breach of contract. Barring a change of heart in the executive suite or on the part of Stallman, the decision was up to me. I could use the interviews and go against my earlier agreement with Stallman, or I could plead journalistic ethics and back out of the verbal agreement to do the book.
+={Amazon.com}
 
 Following the meeting, my agent and I relocated to a pub on Third Ave. I used his cell phone to call Stallman, leaving a message when nobody answered. Henning left for a moment, giving me time to collect my thoughts. When he returned, he was holding up the cell phone.
 
@@ -1870,7 +1905,7 @@ Afterwards, when the dinner was complete and Sarah had departed, Stallman seemed
 
 Before parting, Stallman handed me his "pleasure card," a business card listing Stallman's address, phone number, and favorite pastimes ("sharing good books, good food and exotic music and dance") so that I might set up a final interview.
 
-{free_as_in_freedom_04_rms_pleasure_card.png 355x207 "Stallman's 'pleasure' card, handed to me the night of our dinner." }http://www.free-culture.cc/
+{free_as_in_freedom_04_rms_pleasure_card.png 355x207 "Stallman's 'pleasure' card, handed to me the night of our dinner." }http://en.wikipedia.org/wiki/Richard_stallman
 
 The next day, over another meal of dim sum, Stallman seemed even more lovestruck than the night before. Recalling his debates with Currier House dorm maters over the benefits and drawbacks of an immortality serum, Stallman expressed hope that scientists might some day come up with the key to immortality. "Now that I'm finally starting to have happiness in my life, I want to have more," he said.
 
@@ -1898,7 +1933,8 @@ A similar situation surrounds the terms "free software" and "open source." Again
 
 To understand the full meaning of the word " hacker," it helps to examine the word's etymology over the years.
 
-The New Hacker Dictionary, an online compendium of software-programmer jargon, officially lists nine different connotations of the word "hack" and a similar number for "hacker." Then again, the same publication also includes an accompanying essay that quotes Phil Agre, an MIT hacker who warns readers not to be fooled by the word's perceived flexibility. "Hack has only one meaning," argues Agre. "An extremely subtle and profound one which defies articulation."
+/{The New Hacker Dictionary}/, an online compendium of software-programmer jargon, officially lists nine different connotations of the word "hack" and a similar number for "hacker." Then again, the same publication also includes an accompanying essay that quotes Phil Agre, an MIT hacker who warns readers not to be fooled by the word's perceived flexibility. "Hack has only one meaning," argues Agre. "An extremely subtle and profound one which defies articulation."
+={Agre, Phil}
 
 Regardless of the width or narrowness of the definition, most modern hackers trace the word back to MIT, where the term bubbled up as popular item of student jargon in the early 1950s. In 1990 the MIT Museum put together a journal documenting the hacking phenomenon. According to the journal, students who attended the institute during the fifties used the word "hack" the way a modern student might use the word "goof." Hanging a jalopy out a dormitory window was a "hack," but anything harsh or malicious-e.g., egging a rival dorm's windows or defacing a campus statue-fell outside the bounds. Implicit within the definition of "hack" was a spirit of harmless, creative fun.
 
@@ -1921,6 +1957,7 @@ It is a testament to the original computer hackers' prodigious skill that later
 As the definition tightened, "computer" hacking acquired additional semantic overtones. To be a hacker, a person had to do more than write interesting software; a person had to belong to the hacker "culture" and honor its traditions the same way a medieval wine maker might pledge membership to a vintners' guild. The social structure wasn't as rigidly outlined as that of a guild, but hackers at elite institutions such as MIT, Stanford, and Carnegie Mellon began to speak openly of a "hacker ethic": the yet-unwritten rules that governed a hacker's day-to-day behavior. In the 1984 book Hackers, author Steven Levy, after much research and consultation, codified the hacker ethic as five core hacker tenets.
 
 In many ways, the core tenets listed by Levy continue to define the culture of computer hacking. Still, the guild-like image of the hacker community was undermined by the overwhelmingly populist bias of the software industry. By the early 1980s, computers were popping up everywhere, and programmers who once would have had to travel to top-rank institutions or businesses just to gain access to a machine suddenly had the ability to rub elbows with major-league hackers via the ARPAnet. The more these programmers rubbed elbows, the more they began to appropriate the anarchic philosophies of the hacker culture in places like MIT. Lost within the cultural transfer, however, was the native MIT cultural taboo against malicious behavior. As younger programmers began employing their computer skills to harmful ends-creating and disseminating computer viruses, breaking into military computer systems, deliberately causing machines such as MIT Oz, a popular ARPAnet gateway, to crash-the term "hacker" acquired a punk, nihilistic edge. When police and businesses began tracing computer-related crimes back to a few renegade programmers who cited convenient portions of the hacking ethic in defense of their activities, the word "hacker" began appearing in newspapers and magazine stories in a negative light. Although books like Hackers did much to document the original spirit of exploration that gave rise to the hacking culture, for most news reporters, "computer hacker" became a synonym for "electronic burglar."
+={ARPAnet}
 
 Although hackers have railed against this perceived misusage for nearly two decades, the term's rebellious connotations dating back to the 1950s make it hard to discern the 15-year-old writing software programs that circumvent modern encryption programs from the 1960s college student, picking locks and battering down doors to gain access to the lone, office computer terminal. One person's creative subversion of authority is another person's security headache, after all. Even so, the central taboo against malicious or deliberately harmful behavior remains strong enough that most hackers prefer to use the term " cracker"-i.e., a person who deliberately cracks a computer security system to steal or vandalize data-to describe the subset of hackers who apply their computing skills maliciously.
 
diff --git a/data/doc/sisu/sisu_markup_samples/sisu_manual/sisu_markup.sst b/data/doc/sisu/sisu_markup_samples/sisu_manual/sisu_markup.sst
index 32659adf..09a8f427 100644
--- a/data/doc/sisu/sisu_markup_samples/sisu_manual/sisu_markup.sst
+++ b/data/doc/sisu/sisu_markup_samples/sisu_manual/sisu_markup.sst
@@ -39,7 +39,7 @@
 { SiSU help }http://www.jus.uio.no/sisu/sisu_manual/sisu_help/
 { SiSU help sources }http://www.jus.uio.no/sisu/sisu_manual/sisu_help_sources/
 
-% @prefix: 
+% @prefix:
 
 :A~? @title @creator
 
@@ -1057,6 +1057,70 @@ code{
 
 }code
 
+2~ Book index
+
+To make an index append to paragraph the book index term relates to it, using an equal sign and curly braces.
+
+Currently two levels are provided, a main term and if needed a sub-term. Sub-terms are separated from the main term by a colon.
+
+code{
+
+  Paragraph containing main term and sub-term.
+  ={Main term:sub-term}
+
+}code
+
+The index syntax starts on a new line, but there should not be an empty line between paragraph and index markup.
+
+The structure of the resulting index would be:
+
+code{
+
+  Main term, 1
+    sub-term, 1
+
+}code
+
+Several terms may relate to a paragraph, they are separated by a semicolon. If the term refers to more than one paragraph, indicate the number of paragraphs.
+
+code{
+
+  Paragraph containing main term, second term and sub-term.
+  ={first term; second term: sub-term}
+
+}code
+
+The structure of the resulting index would be:
+
+code{
+
+  First term, 1,
+  Second term, 1,
+    sub-term, 1
+
+}code
+
+If multiple sub-terms appear under one paragraph, they are separated under the main term heading from each other by a pipe symbol.
+
+code{
+
+  Paragraph containing main term, second term and sub-term.
+  ={Main term:sub-term+1|second sub-term
+
+  A paragraph that continues discussion of the first sub-term
+
+}code
+
+The plus one in the example provided indicates the first sub-term spans one additional paragraph. The logical structure of the resulting index would be:
+
+code{
+
+  Main term, 1,
+    sub-term, 1-3,
+    second sub-term, 1,
+
+}code
+
 1~ Composite documents markup
 
 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 *{.ssm}* Within this document you would provide information on the other documents that should be included within the text. These may be other documents that would be processed in a regular way, or markup bits prepared only for inclusion within a master document *{.sst}* regular markup file, or *{.ssi}* (insert/information) A secondary file of the composite document is built prior to processing with the same prefix and the suffix *{._sst}*
@@ -1143,7 +1207,7 @@ and
 
 code{
 
-~[* my note ]~ or ~[+ another note ]~ 
+~[* my note ]~ or ~[+ another note ]~
 
 }code
 
-- 
cgit v1.2.3