start preparing sisu-auto-generated man pages for 0.60 release

3 files changed, 701 insertions, 804 deletions

diff --git a/man/man1/sisu.1 b/man/man1/sisu.1
index 11c5dc72..8cbb0056 100644
--- a/man/man1/sisu.1
+++ b/man/man1/sisu.1
@@ -1,4 +1,12 @@
-.TH "sisu" "1" "2007-08-30" "0.59.1" "SiSU"
+.TH "sisu" "1" "2007-09-29" "0.59.1" "SiSU"
+.SH NAME
+sisu \- documents: markup, structuring, publishing in multiple standard formats, and search
+.SH SYNOPSIS
+sisu [\-abcDdFHhIiMmNnopqRrSsTtUuVvwXxYyZz0\-9] [filename/wildcard ]
+.BR
+sisu [\-Ddcv] [instruction]
+.BR
+sisu [\-CcFLSVvW]
 .SH
 SISU \- MANUAL,
 RALPH AMISSAH
@@ -14,24 +22,21 @@ WHAT IS SISU?
 
 .BR
 .B SiSU
-is a system for document markup, publishing (in multiple open standard
-formats) and search
-
-.BR
-.B SiSU
-[^1] is a[^2] framework for document structuring, publishing and search,
-comprising of (a) a lightweight document 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 that (can) share a common numbering system for the
-citation of text within a document.
+is a framework for document structuring, publishing (in multiple open
+standard formats) and search, comprising of: (a) a lightweight document
+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.
 
 .BR
 .B SiSU
-is developed under an open source, software libre license (GPL3). It has been
-developed in the context of coping with large document sets with evolving
-markup related technologies, for which you want multiple output formats, a
-common mechanism for cross\-output\-format citation, and search.
+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.
 
 .BR
 .B SiSU
@@ -50,10 +55,7 @@ landscape and portrait pdfs, Open Document Format (ODF), all of which can be
 added to and updated.
 .B 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. Results of objects
-(primarily paragraphs and headings) can be viewed directly in the database, or
-just the object numbers shown \- your search criteria is met in these documents
-and at these locations within each document.
+that searches can be made with that degree of granularity.
 
 .BR
 Source document preparation and output generation is a two step process: (i)
@@ -64,9 +66,10 @@ generated by re\-running the engine against the prepared source. Using
 .B SiSU
 markup applied to a document,
 .B SiSU
-custom builds various standard open output formats including plain text,
-HTML, XHTML, XML, OpenDocument, LaTeX or PDF files, and populate an SQL
-database with objects[^3] (equating generally to paragraph\-sized chunks) so
+custom builds (to take advantage of the strengths of different ways of
+representing documents) various standard open output formats including plain
+text, HTML, XHTML, XML, OpenDocument, LaTeX or PDF files, and populate an SQL
+database with objects[^1] (equating generally to paragraph\-sized chunks) so
 searches may be performed and matches returned with that degree of granularity
 ( e.g. your search criteria is met by these documents and at these locations
 within each document). Document output formats share a common object numbering
@@ -81,19 +84,20 @@ 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[^4]
+where used. The rest is automatic, sisu from this information custom builds[^2]
 the different forms of output requested.
 
 .BR
 .B SiSU
 works with an abstraction of the document based on its structure which is
-comprised of its frame[^5] and the objects[^6] it contains, which enables
+comprised of its structure (or frame)[^3] and the objects[^4] it contains,
+which enables
 .B SiSU
 to represent the document in many different ways, and to take advantage of
 the strengths of different ways of presenting documents. The objects are
 numbered, and these numbers can be used to provide a common base for citing
 material within a document across the different output format types. This is
-significant as page numbers are not suited to the digital age, in web
+significant as page numbers are not well suited to the digital age, in web
 publishing, changing a browser\'s default font or using a different browser
 means that text appears on different pages; and in publishing in different
 formats, html, landscape and portrait pdf etc. again page numbers are of no use
@@ -111,7 +115,7 @@ time, or the way the way in which html has evolved over its relatively short
 span of existence.
 .B SiSU
 provides the flexibility of outputing documents in multiple non\-proprietary
-open formats including html, pdf[^7] and the ISO standard ODF.[^8] Whilst
+open formats including html, pdf[^5] and the ISO standard ODF.[^6] Whilst
 .B SiSU
 relies on software, the markup is uncomplicated and minimalistic which
 guarantees that future engines can be written to run against it. It is also
@@ -122,15 +126,16 @@ the fact that the software itself,
 .B SiSU
 is available under GPL3 a licence that guarantees that the source code will
 always be open, and free as in libre which means that that code base can be
-used updated and further developed as required under the terms of its license.
+used, updated and further developed as required under the terms of its license.
 Another challenge is to keep up with a moving target.
 .B SiSU
 permits new forms of output to be added as they become important, (Open
-Document Format text was added in 2006), 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).
+Document Format text was added in 2006 when it became an ISO standard for
+office applications 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).
 
 .BR
 The document formats are written to the file\-system and available for indexing
@@ -163,362 +168,11 @@ content prepared in
 <http://www.jus.uio.no/sisu>
 
 .SH
-2. HOW DOES SISU WORK?
-.BR
-
+2. COMMANDS SUMMARY
 .BR
-.B 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 granting what rights) and any processing
-instructions; and markup within the substantive text of the document, which is
-related to document structure and typeface.
-.B SiSU
-must be able to discern the structure of a document, (text headings and their
-levels in relation to each other), either from information provided in the
-document header or from markup within the text (or from a combination of both).
-Processing is done against an abstraction of the document comprising of
-information on the document\'s structure and its objects,[2] which the program
-serializes (providing the object numbers) and which are assigned hash sum
-values based on their content. This abstraction of information about document
-structure, objects, (and hash sums), provides 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).
 
 .SH
-3. SUMMARY OF FEATURES
-.BR
-
-.BR
-* 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 \"War and Peace\" require almost no markup, and most of the
-headers are optional.
-
-.BR
-* 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].
-
-.BR
-* markup defines document structure (this may be done once in a header
-pattern\-match description, or for heading levels individually); basic text
-attributes (bold, italics, underscore, strike\-through etc.) as required; and
-semantic information related to the document (header information, extended
-beyond the Dublin core and easily further extended as required); the headers
-may also contain processing instructions.