From c5e3e37e66ac980c2a9a458bfdc7455e831ad1ab Mon Sep 17 00:00:00 2001 From: Ralph Amissah Date: Sat, 29 Sep 2007 16:00:32 +0100 Subject: start preparing sisu-auto-generated man pages for 0.60 release --- data/doc/sisu/html/sisu.1.html | 1570 ++++++++++++++--------------- data/doc/sisu/html/sisu_complete.7.html | 16 +- data/doc/sisu/html/sisu_pdf.7.html | 16 +- data/doc/sisu/html/sisu_postgresql.7.html | 16 +- data/doc/sisu/html/sisu_sqlite.7.html | 16 +- data/doc/sisu/html/sisu_vim.7.html | 68 +- data/doc/sisu/html/sisu_webrick.1.html | 94 +- lib/sisu/v0/manpage.rb | 4 +- man/man1/sisu.1 | 1535 +++++++++++++--------------- man/man1/sisu_webrick.1 | 12 +- man/man7/sisu_vim.7 | 10 +- 11 files changed, 1597 insertions(+), 1760 deletions(-) diff --git a/data/doc/sisu/html/sisu.1.html b/data/doc/sisu/html/sisu.1.html index 93840b9f..54d04145 100644 --- a/data/doc/sisu/html/sisu.1.html +++ b/data/doc/sisu/html/sisu.1.html @@ -7,69 +7,74 @@ Table of Contents

-SISU - MANUAL, RALPH AMISSAH + +

Name

+sisu - documents: markup, structuring, publishing in multiple standard +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? - -

SiSU is a system for document markup, publishing (in multiple open standard -formats) and search -

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

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

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 several standard -output formats which share a common (text object) numbering system for -citation of content within a document (that also has implications for search). -The sisu engine works with an abstraction of the document’s structure and -content from which it is possible to generate different forms of representation -of the document. Significantly SiSU markup is more sparse 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. 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. -

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 desired output subsequently -generated by running the sisu engine against document source. Output representations -if updated (in the sisu engine) can be generated by re-running the engine -against the prepared source. Using SiSU markup applied to a document, 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 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 -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. -

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[^4] the -different forms of output requested. -

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 SiSU to represent the document +

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

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

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 +several standard output formats which share a common (text object) numbering +system for citation of content within a document (that also has implications +for search). The sisu engine works with an abstraction of the document’s +structure and content from which it is possible to generate different forms +of representation of the document. Significantly SiSU markup is more sparse +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. +

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 +desired output subsequently generated by running the sisu engine against +document source. Output representations if updated (in the sisu engine) +can be generated by re-running the engine against the prepared source. Using +SiSU markup applied to a document, SiSU 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 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. +

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

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 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 publishing, changing a browser’s +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 to cite text in a manner that @@ -83,280 +88,44 @@ formats today and what guarantee you have that old proprietary formats will remain (or can be read without proprietary software/equipment) in 15 years time, or the way the way in which html has evolved over its relatively short span of existence. SiSU provides the flexibility of outputing documents -in multiple non-proprietary open formats including html, pdf[^7] and the -ISO standard ODF.[^8] Whilst SiSU relies on software, the markup is uncomplicated +in multiple non-proprietary open formats including html, pdf[^5] and the +ISO standard ODF.[^6] Whilst 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 easily converted to other formats, which means documents prepared in SiSU can be migrated to other document formats. Further security is provided by the fact that the software itself, 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 +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. Another challenge is to keep up with a moving target. 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). -

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

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

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

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

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

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

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

2. 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 granting what rights) and any processing instructions; -and markup within the substantive text of the document, which is related -to document structure and typeface. 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). -

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

* 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 simpler converted  to  XML  representations  of  the - same  input/source -

* 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. SiSU markup is primarily -an abstraction 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 browser  viewing,  paper  publication, - sql  search  etc.] (html, 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: -

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

* -ensuring content can be cited in a meaningful way regardless of selected -output format. Online publishing (and publishing in multiple document formats) -lacks a useful way of citing text internally within documents (important -to academics generally and to lawyers) as page numbers are meaningless -across browsers and formats. sisu seeks to provide a common way of pinpoint -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. -

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

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

* SQL search aside, documents are generated as -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 -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 -

- * document source may be bundled together (automatically) with associated -documents (multiple language versions or master document with inclusions) -and images and sent as a zip file called a sisupod, if shared on the net - -

these too may be processed locally to produce the desired document outputs - -

* generated document outputs may automatically be posted to remote sites. - -

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

* as a developers - -

tool it is flexible and extensible -

Syntax highlighting for SiSU markup -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 -

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

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

4. HELP -

4.1 - -

SISU MANUAL -

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

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

and (from SiSU 0.59 onwards) installed locally at: -

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

or equivalent directory -

Within the SiSU tarball at: -

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

4.2 SISU MAN PAGES -

If SiSU is installed on your system usual man commands -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: -

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

Once installed, directory equivalent to: -

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

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

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

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

The SiSU man pages can be viewed online at:[^9] -

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

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

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

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

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

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

4.3 SISU BUILT-IN INTERACTIVE HELP -

This is particularly useful when current -installation information is obtained as the interactive help is able to -provide information on your sisu configuration and setup. -

sisu --help
- -

sisu --help  [subject]
- -

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

sisu -V  [same  as  above  command]
- -

sisu --help commands
- -

sisu --help markup
- -

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

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

4.4 HELP SOURCES -

For lists of alternative help sources, -see: -

man page -

man sisu_help_sources
- -

man2html -

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

sisu generated html -

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

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

<http://www.jus.uio.no/sisu/sisu_manual/sisu_help_sources/index.html ->
- -

5. COMMANDS SUMMARY -

5.1 SYNOPSIS +

2. +COMMANDS SUMMARY +

2.1 SYNOPSIS

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

sisu  [  -abcDdFHhIiMmNnopqRrSsTtUuVvwXxYyZz0-9 @@ -366,14 +135,14 @@ Units - a document publishing system

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

5.2 DESCRIPTION +

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

5.3 DOCUMENT +

2.3 DOCUMENT

PROCESSING COMMAND FLAGS

@@ -382,41 +151,42 @@ XML, info, and SQL (PostgreSQL and SQLite), which share numbered text objects

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

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

-
 -C   [--init-site]
-
configure/initialise shared output -directory files initialize shared output directory (config 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. +
 -C   [--init-site] +
+
configure/initialise shared output directory files initialize shared output +directory (config 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.

 -CC
-
 configure/initialise  shared  output  directory  files  initialize -shared  output  directory  (config  files  such  as  css  and  dtd 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. -such  as  css  and  dtd  files  are  updated +
 configure/initialise  shared  output + directory  files  initialize shared  output  directory  (config  files  such  as + css  and  dtd and search is  used).  The  equivalent  of:  -C  --init-site and search +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 and search if  -CC  is  used. such  as  css  and + dtd  files  are  updated and search

 -c   [filename/wildcard]
-
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 +
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).

@@ -471,14 +241,19 @@ with most web servers).  [behaviour  switched  after
produces texinfo and info file, (view with pinfo).

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

+
 -L
-
 prints  license  information. - +
 prints  license + information.

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

 -m   [filename/wildcard/url] @@ -664,7 +439,7 @@ directory.  for  the  time being]

-6. COMMAND LINE MODIFIERS +3. COMMAND LINE MODIFIERS

@@ -690,7 +465,7 @@ in margins of html or LaTeX/pdf output.

-7. DATABASE COMMANDS +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 @@ -732,7 +507,7 @@ specified data to postgresql db (rb.dbi)  [  -dv  --update  

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

-8. SHORTCUTS, +5. SHORTCUTS, SHORTHAND FOR MULTIPLE FLAGS

@@ -785,30 +560,116 @@ changed/configured in the sisurc.yml file):

verbose output

-8.0.1 COMMAND LINE WITH FLAGS - BATCH PROCESSING +5.0.1 COMMAND LINE WITH FLAGS - BATCH PROCESSING

In the data directory 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. -

9. INTRODUCTION TO SISU MARKUP[^15] -

9.1 SUMMARY -

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

All paragraphs are separated -by an empty line. +

6. HELP +

6.1 SISU MANUAL +

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

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

and (from SiSU 0.59 onwards) installed locally at: +

/usr/share/doc/sisu/sisu_manual/
+ +

or equivalent directory +

Within the SiSU tarball at: +

./data/doc/sisu/sisu_manual/
+ +

6.2 SISU MAN PAGES +

If SiSU is installed on your system usual man commands +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: +

./data/doc/sisu/sisu_manual/
+ +

Once installed, directory equivalent to: +

/usr/share/doc/sisu/sisu_manual/
+ +

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

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

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

6.3 SISU BUILT-IN INTERACTIVE HELP +

This is particularly useful for +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 and search
+ 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). +

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 +

For lists of alternative help sources, +see: +

man page +

man sisu_help_sources
+ +

man2html +

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

sisu generated html +

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

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

<http://www.jus.uio.no/sisu/sisu_manual/sisu_help_sources/index.html +>
+ +

7. INTRODUCTION TO SISU MARKUP[^9] +

7.1 SUMMARY +

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

All paragraphs are separated by an empty +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) -

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

* heading -levels defines document structure
+

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

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

* heading levels defines +document structure

* text basic attributes, italics, bold etc.
@@ -825,8 +686,8 @@ as code

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

markup or sisu --help markup -

9.2 MARKUP EXAMPLES -

9.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/2.html @@ -843,15 +704,15 @@ for viewing: <http://www.j

an alternative presentation of markup syntax: <http://www.jus.uio.no/sisu/sample/on_markup.txt > -

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

10. MARKUP OF HEADERS - -

Headers consist of semantic meta-data about a document, which can be used +

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.

Note: the first line of a document may include @@ -862,7 +723,7 @@ in a line of text) followed by a space and the comment: 


  % this would be a comment
-

10.1 SAMPLE HEADER +

8.1 SAMPLE HEADER

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

@@ -903,7 +764,7 @@ 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 -

10.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 @@ -1023,17 +884,29 @@ see headings]

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

@links: -{ SiSU }http://www.jus.uio.no/sisu/; +

+

+ +
 @man: + 8;
+
 name=sisu  -  documents:  markup,  structuring,  publishing  in multiple  standard + formats,  and  search;  synopsis=sisu  in [-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 +

@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 list.yml  and  promo.yml,  commented  out  sample  in  document -sample: and  promo.yml,  commented  out  sample  in  document free_as_in_freedom.richard_stallman_crusade_for_free_software.sam_williams.sst] -

11. MARKUP OF SUBSTANTIVE TEXT -

11.1 HEADING LEVELS + +

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

+
+9. MARKUP OF SUBSTANTIVE TEXT +

9.1 HEADING 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 @@ -1066,7 +939,7 @@ marked 1.1.1 or 1.1.2 or 1.2.1 or 2.1.1 etc. in a document text, and may be further subdivided (this is the level on which by default html segments are made) -

11.2 FONT ATTRIBUTES +

9.2 FONT ATTRIBUTES

markup example:


@@ -1098,7 +971,7 @@ html segments are made)

<ins>inserted text</ins>

<del>strikethrough</del> -

11.3 INDENTATION AND BULLETS +

9.3 INDENTATION AND BULLETS

markup example:


@@ -1136,7 +1009,7 @@ html segments are made) 

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

11.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 @@ -1147,14 +1020,14 @@ or endnotes. 

  ~{ a footnote or endnote }~

resulting output: -

[^17] +

[^11]

markup example: 


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

resulting output: -

normal text[^18] continues +

normal text[^12] continues

markup example:


@@ -1189,8 +1062,8 @@ asterisks if required }~ continues

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

-

11.5 LINKS -

11.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 @@ -1238,7 +1111,7 @@ is used there is neither decoration nor hyperlinking, code blocks are discussed 


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

11.5.2 LINKING TEXT +

9.5.2 LINKING TEXT

resulting output:

about SiSU <http://www.jus.uio.no/sisu/ > @@ -1254,10 +1127,10 @@ is used there is neither decoration nor hyperlinking, code blocks are discussed

resulting output:

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

-

11.5.3 LINKING IMAGES +

9.5.3 LINKING IMAGES

markup example:


@@ -1271,7 +1144,7 @@ is used there is neither decoration nor hyperlinking, code blocks are discussed

[ tux.png ]

tux.png 64x80

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

GnuDebianLinuxRubyBetterWay.png 100x101 and Ruby

linked url footnote @@ -1290,13 +1163,13 @@ endnote providing the url for the text location used in the hyperlink

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

11.6 GROUPED TEXT -

+

9.6 GROUPED TEXT +

9.6.1 -

11.6.1 TABLES +

TABLES

Tables may be prepared in two either of two forms -

markup -example: +

markup example: + 


  table{ c3; 40; 30; 30;
@@ -1314,7 +1187,7 @@ example:
 
  a second form may be easier to work with in cases where there is not
 
 
much information in each column 
-
  markup example: [^21] 
+
  markup example: [^15] 
 
 
 
 

 
  !_ Table 3.1: Contributors to Wikipedia, January 2001 - June 2005
@@ -1341,7 +1214,7 @@ example:
  
 
  * Contributed at least ten times; ** at least 5 times in last month;
 *** more than 100 times in last month. 
-
 11.6.2 POEM 
+
 9.6.2 POEM 
 
  basic markup: 
 
 
 
 

@@ -1491,7 +1364,7 @@ example:
                        death.

  

 
-
 11.6.3 GROUP 
+
 9.6.3 GROUP 
 
  basic markup: 
 
 
 
 

@@ -1641,7 +1514,7 @@ example:
                        death.

  

 
-
 11.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
@@ -1699,7 +1572,7 @@ poem compared, resulting output:
                         to
                          death.
 

-
 12. COMPOSITE DOCUMENTS MARKUP  
+
 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,
@@ -1740,13 +1613,24 @@ of documents under consideration, and occasionally supported have been.
   << <url:filename.ssi>

MARKUP SYNTAX HISTORY -

13. NOTES RELATED TO FILES-TYPES AND MARKUP SYNTAX +

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 -

0.52 (2007w14/6) declared document type identifier -at start of text/document: +

names were changed at 0.37 +

* sisu --query=[sisu  version   [0.38] or ’history] + +

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 contents  of  the  headers  @title:  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: @@ -1757,12 +1641,75 @@ at start of text/document:

0.51 (2007w13/6) skins changed (simplified), markup unchanged

0.42 (2006w27/4) * (asterisk) type endnotes, used e.g. in relation to author -

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

0.37 (2006w09/7) introduced new file naming convention, -.sst (text), .ssm (master), .ssi (insert), markup syntax unchanged +

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 +

+


+

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

* for example for describing an author +

** for describing a second author + +

and +

+


+

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

which numerically increments an asterisk and plus respectively +

*1 my + +

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

SiSU +0.38 introduced alternative experimental header and heading/structure markers, + +

+


+

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

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 +

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 +which are followed by ordinary text. This may be conceptualised as levels +A,B,C, 1,2,3, and using such letter number notation, in effect: A must +exist, optional B and C may follow in sequence (not strict) 1 must exist, +optional 2 and 3 may follow in sequence i.e. there are two independent heading +level sequences A,B,C and 1,2,3 (using the 0.16 standard notation 1,2,3 +and 4,5,6) on the positive side: the 0.38 A,B,C,1,2,3 alternative makes +explicit an aspect of structuring documents in SiSU that is not otherwise +obvious to the newcomer (though it appears more complicated, is more in +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 +

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

+


+

  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

0.35 (2005w52/3) sisupod, zipped content file introduced

0.23 (2005w36/2) utf-8 for markup @@ -1777,27 +1724,34 @@ 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 -

14. SISU FILETYPES -

SiSU has plaintext and binary filetypes, and -can process either type of document. -

14.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 beneath them _sisu/image. SiSU plaintext markup -files are of three types 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 0.16 (0.15 development branch) introduced the use of +

the +header 0~ and headings/structure 1~ 2~ 3~ 4~ 5~ 6~ +

in place of the 0.1 +header, heading/structure notation +

SiSU 0.1 headers and headings structure +represented by header 0{~ and headings/structure 1{ 2{ 3{ 4{~ 5{ 6{ +

12. +SISU FILETYPES +

SiSU has plaintext and binary filetypes, and can process +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 +beneath them _sisu/image. SiSU plaintext markup files are of three types +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 -s  [filename]
-

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

<http://www.jus.uio.no/sisu/sisu_markup @@ -1805,7 +1759,7 @@ in SiSU , see the section on SiSU markup.

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

14.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 @@ -1819,20 +1773,20 @@ 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.

Note: a secondary file of the composite document -is built prior to processing with the same prefix and the suffix ._sst  [^22] +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 > -

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

14.2 SISUPOD, +

12.2 SISUPOD, 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 @@ -1864,9 +1818,9 @@ located locally or on a remote server for which a url is provided.

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

15. EXPERIMENTAL ALTERNATIVE INPUT +

13. EXPERIMENTAL ALTERNATIVE INPUT REPRESENTATIONS -

15.1 ALTERNATIVE XML +

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 @@ -1889,7 +1843,7 @@ dom and node):

or the same:

sisu --from-sxml  [filename/wildcard   [.sxs.xml,.sxd.xml,sxn.xml]]
-

15.1.1 XML SAX REPRESENTATION +

13.1.1 XML SAX REPRESENTATION

To convert from sst to simple xml (sax) representation:

sisu --to-sax  [filename/wildcard] or sisu --to-sxs
@@ -1902,7 +1856,7 @@ representation:

or the same:

sisu --from-sxml  [filename/wildcard   [.sxs.xml,.sxd.xml,sxn.xml]]
-

15.1.2 XML DOM REPRESENTATION +

13.1.2 XML DOM REPRESENTATION

To convert from sst to simple xml (dom) representation:

sisu --to-dom  [filename/wildcard] or sisu --to-sxd
@@ -1915,7 +1869,7 @@ representation:

or the same:

sisu --from-sxml  [filename/wildcard   [.sxs.xml,.sxd.xml,sxn.xml]]
-

15.1.3 XML NODE REPRESENTATION +

13.1.3 XML NODE REPRESENTATION

To convert from sst to simple xml (node) representation:

sisu --to-node  [filename/wildcard] or sisu --to-sxn
@@ -1928,8 +1882,8 @@ representation:

or the same:

sisu --from-sxml  [filename/wildcard   [.sxs.xml,.sxd.xml,sxn.xml]]
-

16. CONFIGURATION -

16.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: @@ -1940,7 +1894,7 @@ command:

Either of these should be executed from within a directory that contains sisu markup source documents. -

16.2 CONFIGURATION FILES (CONFIG.YML) +

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 @@ -1965,7 +1919,7 @@ and the database access details.

If SiSU is installed a sample sisurc.yml

may be found in /etc/sisu/sisurc.yml -

17. SKINS +

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: @@ -1987,14 +1941,14 @@ for document skins:

The skin itself is a ruby file which modifies the default appearances set in the program. -

17.1 DOCUMENT SKIN +

15.1 DOCUMENT SKIN

Documents take on a document skin, if the header of the document specifies a skin to be used. 


  @skin: skin_united_nations
-

17.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, @@ -2004,9 +1958,9 @@ 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. -

17.3 SITE SKIN +

15.3 SITE SKIN

A site skin, modifies the program default skin. -

17.4 SAMPLE +

15.4 SAMPLE

SKINS

With SiSU installed sample skins may be found in: @@ -2024,80 +1978,80 @@ column list) may be found in: (or equivalent
directory)
-

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

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. +configuration directory: ./_sisu/css; ~/.sisu/css or; /etc/sisu/css and +these will be copied to the
+ 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 +

XML SAX: sax.css

XHTML: xhtml.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.[^23] -

19. ORGANISING -CONTENT -

19.1 DIRECTORY STRUCTURE 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 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 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 implications for the organisation of document -collections as it could make sense to place documents of a particular subject, -or type within a directory identifying them. This grouping as suggested -could be by subject (sales_law, english_literature); or just as conveniently -by some other classification (X University). The mapping means it is also -possible to place in the same output directory documents that are for organisational -purposes kept separately, for example documents on a given subject of two -different institutions may be kept in two different directories of the -same name, under a directory 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. -

19.2 ORGANISING CONTENT -

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

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

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

20.1 HOME PAGE AND OTHER CUSTOM BUILT 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: +

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

17.1 DIRECTORY STRUCTURE + +

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 +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 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 +implications for the organisation of document collections as it could make +sense to place documents of a particular subject, or type within a directory +identifying them. This grouping as suggested could be by subject (sales_law, +english_literature); or just as conveniently by some other classification +(X University). The mapping means it is also possible to place in the same +output directory documents that are for organisational purposes kept separately, +for example documents on a given subject of two different institutions +may be kept in two different directories of the same name, under a directory +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 +

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

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, +

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

18.1 HOME PAGE AND OTHER CUSTOM BUILT + +

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:

sisu -CC
-

20.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 @@ -2125,8 +2079,8 @@ index.html end end -

21. MARKUP AND OUTPUT EXAMPLES -

21.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/2.html > @@ -2137,7 +2091,7 @@ 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. -

22. +

20. SISU SEARCH - INTRODUCTION

SiSU output can easily and conveniently be indexed by a number of standalone indexing tools, such as Lucene, Hyperestraier. @@ -2154,11 +2108,11 @@ 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. -

23. SQL -

23.1 POPULATING SQL TYPE DATABASES +

21. SQL +

21.1 POPULATING SQL TYPE DATABASES -

SiSU feeds sisu markupd documents into sql type databases PostgreSQL[^24] -and/or SQLite[^25] database together with information related to document +

SiSU feeds sisu markupd documents into sql type databases PostgreSQL[^18] +and/or SQLite[^19] database together with information related to document 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 @@ -2204,31 +2158,31 @@ 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). -

24. +

22. POSTGRESQL -

24.1 NAME +

22.1 NAME

SiSU - Structured information, Serialized Units - a document publishing system, postgresql dependency package -

24.2 DESCRIPTION +

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

24.3 SYNOPSIS +

22.3 SYNOPSIS

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

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

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

-D or --pgsql may be used interchangeably. -

24.4.1 CREATE AND DESTROY DATABASE +

22.4.1 CREATE AND DESTROY DATABASE

@@ -2263,7 +2217,7 @@ and  drops  tables,  indexes  and  database  assoc

 database  and  builds  a  new  empty  database  structure

-24.4.2 IMPORT AND REMOVE +22.4.2 IMPORT AND REMOVE

DOCUMENTS

@@ -2286,31 +2240,31 @@ database (at an object level). specified document from postgresql database.

-25. SQLITE -

25.1 NAME +23. SQLITE +

23.1 NAME

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

25.2 DESCRIPTION +

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

25.3 SYNOPSIS +

23.3 SYNOPSIS

sisu -d  [instruction]  [filename/wildcard  if  required]

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

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

-d or --sqlite may be used interchangeably. -

25.4.1 CREATE AND DESTROY DATABASE +

23.4.1 CREATE AND DESTROY DATABASE

@@ -2344,7 +2298,7 @@ be used interchangeably.

 existing  database  and  builds  a  new  empty  database  structure

-25.4.2 IMPORT +23.4.2 IMPORT

AND REMOVE DOCUMENTS

@@ -2367,15 +2321,15 @@ database (at an object level). specified document from sqlite database.

-26. INTRODUCTION -

26.1 SEARCH - +24. INTRODUCTION +

24.1 SEARCH - DATABASE FRONTEND SAMPLE, UTILISING DATABASE AND SISU FEATURES, INCLUDING OBJECT CITATION NUMBERING (BACKEND CURRENTLY POSTGRESQL)

Sample search frontend <http://search.sisudoc.org ->  [^26] A small database and sample query +>  [^20] A small database and sample query front-end (search from) that makes use of the citation system, object citation -numbering to demonstrates functionality.[^27] +numbering to demonstrates functionality.[^21]

SiSU can provide information on which documents are matched and at what locations within each document the matches are found. These results are relevant across all outputs using @@ -2386,7 +2340,7 @@ 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.[^28] +objects (paragraphs) that meet the search criteria.[^22]

@@ -2419,7 +2373,7 @@ the database SiSU_ebook is used.  [otherwise  a  manual  map  is

-26.2 SEARCH FORM +24.2 SEARCH FORM

@@ -2449,7 +2403,7 @@ the database SiSU_ebook is used.  [otherwise  a  manual  map

-27. HYPERESTRAIER +25. HYPERESTRAIER

See the documentation for hyperestraier:

<http://hyperestraier.sourceforge.net/ >
@@ -2530,18 +2484,18 @@ and ’replace:’:

and try open the url: <http://localhost:8081/cgi-bin/estseek.cgi > -

28. SISU_WEBRICK +

26. SISU_WEBRICK -

28.1 NAME +

26.1 NAME

SiSU - Structured information, Serialized Units - a document

publishing system -

28.2 SYNOPSIS +

26.2 SYNOPSIS

sisu_webrick  [port]

or

sisu -W  [port] -

28.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 @@ -2550,30 +2504,30 @@ starts Ruby ’s Webrick web-server and points it to the directories 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). -

28.4 SUMMARY OF MAN PAGE +

26.4 SUMMARY OF MAN PAGE

sisu_webrick, may be started on it’s own with the command: sisu_webrick or using the sisu command with the -W flag: sisu -W  [port]

where no port is given and settings are unchanged

the default port is 8081 -

28.5 DOCUMENT PROCESSING COMMAND FLAGS +

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 -

28.6 FURTHER INFORMATION +

26.6 FURTHER INFORMATION

For more information on SiSU see: <http://www.jus.uio.no/sisu >

or man sisu -

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

-

28.8 SEE ALSO +

26.8 SEE ALSO

sisu(1)
@@ -2583,7 +2537,7 @@ on the port provided, or if no port is provided and the defaults have not

sisu(8)
-

29. 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 @@ -2623,7 +2577,7 @@ this way, see <http://www.ju > and use the url for the desired document.

REMOTE DOCUMENT OUTPUT -

30. REMOTE 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. @@ -2636,7 +2590,7 @@ in conjunction with other processing flags, e.g. 


  sisu -3R sisu_remote.sst
-

30.1 COMMANDS +

28.1 COMMANDS

@@ -2657,22 +2611,22 @@ been provided with information on hostname and username, and that you have

your

-30.2 CONFIGURATION +28.2 CONFIGURATION

[expand  on  the  setting  up  of  an  ssh-agent  /  keychain] -

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

32. QUICKSTART - GETTING STARTED HOWTO +

30. QUICKSTART - GETTING STARTED HOWTO -

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

32.1.1 DEBIAN INSTALLATION +

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: @@ -2716,7 +2670,7 @@ 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. -

32.1.2 RPM INSTALLATION +

30.1.2 RPM INSTALLATION

RPMs are provided though untested, they are prepared by running alien against the source package, and against the debs. @@ -2727,7 +2681,7 @@ package, and against the debs.

as root type:

rpm -i  [rpm  package  name]
-

32.1.3 INSTALLATION FROM SOURCE +

30.1.3 INSTALLATION FROM SOURCE

To install SiSU from source check information at:

<http://www.jus.uio.no/sisu/SiSU/download.html#current @@ -2745,7 +2699,7 @@ steps are the same, download and unpack the source file: 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)[^29] or converting LaTeX to pdf. +(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 @@ -2793,7 +2747,7 @@ dependencies, such as tetex-extra are not taken care of for you.

ruby install -T
-

32.2 TESTING SISU, GENERATING OUTPUT +

30.2 TESTING SISU, GENERATING OUTPUT

To check which version of sisu is installed:

sisu -v @@ -2806,7 +2760,7 @@ a number of markup sample files may be found either in the directory:

change directory to the appropriate one:

cd /usr/share/doc/sisu/sisu_markup_samples/dfsg -

32.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), @@ -2816,7 +2770,7 @@ that contains the markup samples (see instructions above if necessary),

this will generate html including a concordance file, opendocument text format, plaintext, XHTML and various forms of XML, and OpenDocument text -

32.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 ) @@ -2832,7 +2786,7 @@ 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 -

32.2.3 RELATIONAL DATABASE - POSTGRESQL, SQLITE +

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. @@ -2846,8 +2800,8 @@ create the database and write to it when you run sisu.

sisu --pgsql --recreate

sisu --pgsql -v --import free_as_in_freedom.rms_and_free_software.sam_williams.sst -

32.3 GETTING HELP -

32.3.1 THE MAN PAGES +

30.3 GETTING HELP +

30.3.1 THE MAN PAGES

Type:

man sisu
@@ -2855,13 +2809,13 @@ create the database and write to it when you run sisu. to date as within the package itself:

* sisu.1 <http://www.jus.uio.no/sisu/man/sisu.1 > - [^30] + [^24]

* sisu.8 <http://www.jus.uio.no/sisu/man/sisu.8 ->  [^31] +>  [^25]

* man directory <http://www.jus.uio.no/sisu/man ->  [^32] -

32.3.2 BUILT IN HELP +>  [^26] +

30.3.2 BUILT IN HELP

sisu --help

sisu @@ -2870,13 +2824,13 @@ to date as within the package itself:

help --env

sisu --help --commands

sisu --help --markup -

32.3.3 THE HOME PAGE +

30.3.3 THE HOME PAGE

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

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

32.4 MARKUP SAMPLES +

30.4 MARKUP SAMPLES

A number of markup samples (along with output) are available off:

<http://www.jus.uio.no/sisu/SiSU/2.html @@ -2885,10 +2839,10 @@ to date as within the package itself:

Additional markup samples are packaged separately in the file:

*

-On Debian they are available in non-free[^33] to include them it is necessary +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. -

33. EDITOR FILES, SYNTAX HIGHLIGHTING +

31. EDITOR FILES, SYNTAX HIGHLIGHTING

The directory:

./data/sisu/conf/editor-syntax-etc/
@@ -3002,9 +2956,151 @@ checking

[  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] -

34. HELP SOURCES -

For a summary of alternative ways to get -help on SiSU try one of the following: +

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 +granting what rights) and any processing instructions; and markup within +the substantive text of the document, which is related to document structure +and typeface. 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). +

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

* 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 simpler converted  to  XML  representations  of  the  same  input/source + +

* 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. SiSU markup is primarily an abstraction +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 browser  viewing,  paper  publication, + sql  search  etc.] (html, 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: +

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

* +ensuring content can be cited in a meaningful way regardless of selected +output format. Online publishing (and publishing in multiple document formats) +lacks a useful way of citing text internally within documents (important +to academics generally and to lawyers) as page numbers are meaningless +across browsers and formats. sisu seeks to provide a common way of pinpoint +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. +

* 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]. +

* 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 +

* SQL search aside, documents are generated as +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 +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 +

+ * document source may be bundled together (automatically) with associated +documents (multiple language versions or master document with inclusions) +and images and sent as a zip file called a sisupod, if shared on the net + +

these too may be processed locally to produce the desired document outputs + +

* generated document outputs may automatically be posted to remote sites. + +

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

* as a developers + +

tool it is flexible and extensible +

Syntax highlighting for SiSU markup +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 +

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

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

34. HELP SOURCES + +

For a summary of alternative ways to get help on SiSU try one of the +following:

man page

man sisu_help
@@ -3042,45 +3138,15 @@ listed here:

34.1.1 MAN

man sisu
-

man sisu_commands
-

man 7 sisu_complete
-

man sisu_configuration
- -

man 8 sisu_faq
- -

man sisu_filetypes
- -

man sisu_help
- -

man sisu_help_sources
- -

man 8 sisu_howto
- -

man sisu_introduction
- -

man sisu_markup
- -

man sisu_output_overview
-

man 7 sisu_pdf

man 7 sisu_postgresql
-

man 8 sisu_quickstart
- -

man 8 sisu_remote
- -

man 8 sisu_search
- -

man sisu_skin
-

man 7 sisu_sqlite
-

man 8 sisu_syntax_highlighting
- -

man 7 sisu_vim
+

man sisu_termsheet

man sisu_webrick
@@ -3088,7 +3154,7 @@ listed here:

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[^34] +html pages[^28]

34.2.1 LOCALLY INSTALLED

<file:///usr/share/doc/sisu/sisu_manual/sisu_manual/index.html> @@ -3097,51 +3163,15 @@ html pages[^34]

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

/usr/share/doc/sisu/sisu_manual/sisu_pdf/index.html

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

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

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

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

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

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

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

/usr/share/doc/sisu/sisu_manual/sisu_vim/index.html
+

/usr/share/doc/sisu/sisu_manual/sisu_termsheet/index.html

/usr/share/doc/sisu/sisu_manual/sisu_webrick/index.html
@@ -3303,52 +3333,24 @@ html pages[^34]

<http://www.jus.uio.no/sisu/sisu_manual/sisu_webrick/index.html >
-

34.2.4 MAN2HTML -

34.2.5 LOCALLY INSTALLED -

<file:///usr/share/doc/sisu/html/sisu_manual.1.html> +

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_sources.1.html>

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

/usr/share/doc/sisu/html/sisu_commands.1.html
- -

/usr/share/doc/sisu/html/sisu_complete.7.html
- -

/usr/share/doc/sisu/html/sisu_configuration.1.html
- -

/usr/share/doc/sisu/html/sisu_faq.8.html
- -

/usr/share/doc/sisu/html/sisu_help.1.html
- -

/usr/share/doc/sisu/html/sisu_help_sources.1.html
- -

/usr/share/doc/sisu/html/sisu_howto.8.html
- -

/usr/share/doc/sisu/html/sisu_markup.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_quickstart.8.html
- -

/usr/share/doc/sisu/html/sisu_remote.8.html
- -

/usr/share/doc/sisu/html/sisu_search.8.html
- -

/usr/share/doc/sisu/html/sisu_skin.1.html
-

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

/usr/share/doc/sisu/html/sisu_syntax_highlighting.8.html
- -

/usr/share/doc/sisu/html/sisu_vim.7.html
-

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

34.2.6 WWW.SISUDOC.ORG +

34.3.2 WWW.SISUDOC.ORG

<http:///sisudoc.org/man/sisu_manual.1.html >

<http:///sisudoc.org/man/sisu_help.1.html @@ -3359,129 +3361,50 @@ html pages[^34]

<http://sisudoc.org/man/sisu.1.html >
-

<http://sisudoc.org/man/sisu_commands.1.html ->
-

<http://sisudoc.org/man/sisu_complete.7.html >
-

<http://sisudoc.org/man/sisu_configuration.1.html ->
- -

<http://sisudoc.org/man/sisu_faq.8.html ->
- -

<http://sisudoc.org/man/sisu_help.1.html ->
- -

<http://sisudoc.org/man/sisu_help_sources.1.html ->
- -

<http://sisudoc.org/man/sisu_howto.8.html ->
- -

<http://sisudoc.org/man/sisu_markup.1.html ->
-

<http://sisudoc.org/man/sisu_pdf.7.html >

<http://sisudoc.org/man/sisu_postgresql.7.html >
-

<http://sisudoc.org/man/sisu_quickstart.8.html ->
- -

<http://sisudoc.org/man/sisu_remote.8.html ->
- -

<http://sisudoc.org/man/sisu_search.8.html ->
- -

<http://sisudoc.org/man/sisu_skin.1.html ->
-

<http://sisudoc.org/man/sisu_sqlite.7.html >
-

<http://sisudoc.org/man/sisu_syntax_highlighting.8.html ->
- -

<http://sisudoc.org/man/sisu_vim.7.html ->
-

<http://sisudoc.org/man/sisu_webrick.1.html >
-

34.2.7 WWW.JUS.UIO.NO/SISU -

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

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

34.3.3 WWW.JUS.UIO.NO/SISU +

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

<http://www.jus.uio.no/sisu/man/sisu_help_sources.1.html +

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

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

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

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

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

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

<http://www.jus.uio.no/sisu/man/sisu_faq.8.html ->
- -

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

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

<http://www.jus.uio.no/sisu/man/sisu_howto.8.html ->
- -

<http://www.jus.uio.no/sisu/man/sisu_markup.1.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_quickstart.8.html ->
- -

<http://www.jus.uio.no/sisu/man/sisu_remote.8.html ->
- -

<http://www.jus.uio.no/sisu/man/sisu_search.8.html ->
- -

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

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

<http://www.jus.uio.no/sisu/man/sisu_syntax_highlighting.8.html ->
- -

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

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

DOCUMENT INFORMATION (METADATA)

METADATA -

Document Manifest @ <http://www.jus.uio.no/sisu/sisu_manual/sisu/sisu_manifest.html +

Document Manifest @ <http://sisudoc.org/sisu_manual/sisu/sisu_manifest.html >

Dublin Core (DC) @@ -3497,55 +3420,39 @@ Type: information

DC Date issued: 2002-08-28

DC Date available: 2002-08-28 -

DC Date modified: 2007-08-30 -

DC Date: 2007-08-30 +

DC Date modified: 2007-09-29 +

DC Date: 2007-09-29

Version Information

Sourcefile: sisu._sst

Filetype: SiSU text insert

0.58 -

Sourcefile Digest, MD5(sisu._sst)= 4c33c586109800b635ffe667a0cf217f +

Sourcefile Digest, MD5(sisu._sst)= 5f973d9b8e96b9f3fabc280e9d0a18e0

Skin_Digest: MD5(/home/ralph/grotto/theatre/dbld/sisu-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)=

20fc43cf3eb6590bc3399a1aef65c5a9

Generated

Document (metaverse) last -generated: Mon Sep 24 15:36:12 +0100 2007 -

Generated by: SiSU 0.59.0 of -2007w38/0 (2007-09-23) +generated: Sat Sep 29 15:46:29 +0100 2007 +

Generated by: SiSU 0.59.1 of +2007w39/2 (2007-09-25)

Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36)  [i486-linux]

    -.
  1. .B SiSU
    - information Structuring Universe Units also chosen for the meaning of -the Finnish term "sisu".
    -
    2. .
  2. Unix command line oriented
    3. .
  3. objects include: headings, paragraphs, verse, -tables, images, but not footnotes/endnotes which are numbered separately -and tied to the object from which they are referenced.
    4. .
  4. i.e. the html, pdf, -odf outputs are each built individually and optimised for that form of -presentation, rather than for example the html being a saved version of -the odf, or the pdf being a saved version of the html.
    5. .
  5. the different heading -levels
    6. .
  6. units of text, primarily paragraphs and headings, also any tables, -poems, code-blocks
    7. .
  7. Specification submitted by Adobe to ISO to become a full -open ISO specification <http://www.linux-watch.com/news/NS7542722606.html ->
    -
    8. .
  8. ISO/IEC 26300:2006
    9. .
  9. generated from source using rman <http://polyglotman.sourceforge.net/rman.html ->
    - With regard to
    - SiSU man pages the formatting generated for markup syntax is not quite -right, for that you might prefer the links under: <http://www.jus.uio.no/sample ->
    -
    10. .
  10. <http://www.jus.uio.no/sisu/man/ ->
    11. .
  11. <http://www.jus.uio.no/sisu/man/sisu.1.html ->
    12. .
  12. <http://www.jus.uio.no/sisu/man/sisu.8.html -> -
    13. .
  13. <http://www.jus.uio.no/sisu/man/sisu_examples.1.html ->
    14. .
  14. <http://www.jus.uio.no/sisu/man/sisu_webrick.1.html -> - +.
  15. objects include: headings, paragraphs, verse, tables, images, +but not footnotes/endnotes which are numbered separately and tied to the +object from which they are referenced.
    16. .
  16. i.e. the html, pdf, odf outputs are +each built individually and optimised for that form of presentation, rather +than for example the html being a saved version of the odf, or the pdf +being a saved version of the html.
    17. .
  17. the different heading levels
    18. .
  18. units of +text, primarily paragraphs and headings, also any tables, poems, code-blocks +
    19. .
  19. Specification submitted by Adobe to ISO to become a full open ISO specification + <http://www.linux-watch.com/news/NS7542722606.html +>
    +
    20. .
  20. ISO/IEC 26300:2006
    *1.
    square brackets
    @@ -3554,29 +3461,33 @@ right, for that you might prefer the links under: <http://www.jus.uio.no/sisu/man/ +>
    21. .
  21. <http://www.jus.uio.no/sisu/man/sisu.1.html +>
    22. .
  22. From +sometime after SiSU 0.58 it should be possible to describe SiSU markup using +SiSU, which though not an original design goal is useful.
    23. .
  23. files should be +prepared using UTF-8 character encoding
    24. .
  24. a footnote or endnote
    25. .
  25. self contained +endnote marker & endnote in one
    *.
    -
    unnumbered asterisk footnote/endnote, insert multiple -asterisks if required
    +
    unnumbered asterisk footnote/endnote, +insert multiple asterisks if required
    **.
    -
    another unnumbered asterisk footnote/endnote
    +
    another unnumbered asterisk footnote/endnote +
    -
    *3. -
    +
    *3.
    editors notes, numbered asterisk footnote/endnote series
    +2.
    -
    editors notes, -numbered asterisk footnote/endnote series
    26. .
  26. <http://www.jus.uio.no/sisu/ ->
    27. .
  27. <http://www.ruby-lang.org/en/ +
    editors +notes, numbered asterisk footnote/endnote series
    28. .
  28. <http://www.jus.uio.no/sisu/ > -
    29. .
  29. Table from the Wealth of Networks by Yochai Benkler <http://www.jus.uio.no/sisu/the_wealth_of_networks.yochai_benkler +
    30. .
  30. <http://www.ruby-lang.org/en/ +>
    31. .
  31. Table from the Wealth of Networks by Yochai Benkler + <http://www.jus.uio.no/sisu/the_wealth_of_networks.yochai_benkler >
    32. .
  32. .ssc (for composite) is under consideration but ._sst makes clear that this is not a regular file to be worked on, and thus less likely that people @@ -3644,15 +3555,15 @@ distributable are not freely changeable.
    33. .
  33. named index.html or mo
-
* Generated by: SiSU 0.59.0 of 2007w38/0 (2007-09-23)
+
* Generated by: SiSU 0.59.1 of 2007w39/2 (2007-09-25)
* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux]
-
* Last Generated on: Mon Sep 24 -15:36:29 +0100 2007
+
* Last Generated on: Sat Sep 29 +15:46:29 +0100 2007
* SiSU http://www.jus.uio.no/sisu @@ -3660,5 +3571,12 @@ distributable are not freely changeable. .
  • named index.html or mo

    + +

    +Table of Contents

    +

    diff --git a/data/doc/sisu/html/sisu_complete.7.html b/data/doc/sisu/html/sisu_complete.7.html index 5f2d4713..c44da5a2 100644 --- a/data/doc/sisu/html/sisu_complete.7.html +++ b/data/doc/sisu/html/sisu_complete.7.html @@ -47,7 +47,7 @@ on SiSU see:

    DOCUMENT INFORMATION (METADATA)

    METADATA -

    Document Manifest @ <http://www.jus.uio.no/sisu/sisu_manual/sisu_complete/sisu_manifest.html +

    Document Manifest @ <http://sisudoc.org/sisu_manual/sisu_complete/sisu_manifest.html >

    Dublin Core (DC) @@ -75,14 +75,14 @@ Date: 2007-09-16

    SiSU text 0.58

    Sourcefile Digest, MD5(sisu_complete.sst)= 0974a5dfc0c6bc648ac21c688177bec0 -

    Skin_Digest: MD5(/home/ralph/grotto/theatre/dbld/sisu-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +

    Skin_Digest: MD5(/home/ralph/grotto/theatre/dbld/builds/sisu/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)=

    20fc43cf3eb6590bc3399a1aef65c5a9

    Generated

    Document (metaverse) last -generated: Mon Sep 24 15:36:18 +0100 2007 -

    Generated by: SiSU 0.59.0 of -2007w38/0 (2007-09-23) +generated: Wed Sep 26 08:58:59 +0100 2007 +

    Generated by: SiSU 0.59.1 of +2007w39/2 (2007-09-25)

    Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36)  [i486-linux]

    @@ -120,15 +120,15 @@ generated: Mon Sep 24 15:36:18 +0100 2007

    • -
    * Generated by: SiSU 0.59.0 of 2007w38/0 (2007-09-23)
    +
    * Generated by: SiSU 0.59.1 of 2007w39/2 (2007-09-25)
    * Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux]
    -
    * Last Generated on: Mon Sep 24 -15:36:32 +0100 2007
    +
    * Last Generated on: Wed Sep 26 +08:59:04 +0100 2007
    * SiSU http://www.jus.uio.no/sisu diff --git a/data/doc/sisu/html/sisu_pdf.7.html b/data/doc/sisu/html/sisu_pdf.7.html index 16d2279b..b8751d3b 100644 --- a/data/doc/sisu/html/sisu_pdf.7.html +++ b/data/doc/sisu/html/sisu_pdf.7.html @@ -69,7 +69,7 @@ US_legal

    DOCUMENT INFORMATION (METADATA)

    METADATA -

    Document Manifest @ <http://www.jus.uio.no/sisu/sisu_manual/sisu_pdf/sisu_manifest.html +

    Document Manifest @ <http://sisudoc.org/sisu_manual/sisu_pdf/sisu_manifest.html >

    Dublin Core (DC) @@ -94,14 +94,14 @@ Type: information

    Sourcefile Digest, MD5(sisu_pdf.sst)= 63bca4cff790aa5ca87bea788c520076 -

    Skin_Digest: MD5(/home/ralph/grotto/theatre/dbld/sisu-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +

    Skin_Digest: MD5(/home/ralph/grotto/theatre/dbld/builds/sisu/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)=

    20fc43cf3eb6590bc3399a1aef65c5a9

    Generated

    Document (metaverse) last -generated: Mon Sep 24 15:36:19 +0100 2007 -

    Generated by: SiSU 0.59.0 of -2007w38/0 (2007-09-23) +generated: Wed Sep 26 08:59:00 +0100 2007 +

    Generated by: SiSU 0.59.1 of +2007w39/2 (2007-09-25)

    Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36)  [i486-linux]

    @@ -139,15 +139,15 @@ generated: Mon Sep 24 15:36:19 +0100 2007

    -
    * Generated by: SiSU 0.59.0 of 2007w38/0 (2007-09-23)
    +
    * Generated by: SiSU 0.59.1 of 2007w39/2 (2007-09-25)
    * Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux]
    -
    * Last Generated on: Mon Sep 24 -15:36:32 +0100 2007
    +
    * Last Generated on: Wed Sep 26 +08:59:05 +0100 2007
    * SiSU http://www.jus.uio.no/sisu diff --git a/data/doc/sisu/html/sisu_postgresql.7.html b/data/doc/sisu/html/sisu_postgresql.7.html index 97f6cd7b..85f3c78b 100644 --- a/data/doc/sisu/html/sisu_postgresql.7.html +++ b/data/doc/sisu/html/sisu_postgresql.7.html @@ -94,7 +94,7 @@ specified document from postgresql database. DOCUMENT INFORMATION (METADATA)

    METADATA -

    Document Manifest @ <http://www.jus.uio.no/sisu/sisu_manual/sisu_postgresql/sisu_manifest.html +

    Document Manifest @ <http://sisudoc.org/sisu_manual/sisu_postgresql/sisu_manifest.html >

    Dublin Core (DC) @@ -120,14 +120,14 @@ Type: information

    text 0.58

    Sourcefile Digest, MD5(sisu_postgresql.sst)= 5f9ca1acb186a64f8e924876892dc25e -

    Skin_Digest: MD5(/home/ralph/grotto/theatre/dbld/sisu-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +

    Skin_Digest: MD5(/home/ralph/grotto/theatre/dbld/builds/sisu/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)=

    20fc43cf3eb6590bc3399a1aef65c5a9

    Generated

    Document (metaverse) last -generated: Mon Sep 24 15:36:18 +0100 2007 -

    Generated by: SiSU 0.59.0 of -2007w38/0 (2007-09-23) +generated: Wed Sep 26 08:59:00 +0100 2007 +

    Generated by: SiSU 0.59.1 of +2007w39/2 (2007-09-25)

    Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36)  [i486-linux]

    @@ -165,15 +165,15 @@ generated: Mon Sep 24 15:36:18 +0100 2007

    -
    * Generated by: SiSU 0.59.0 of 2007w38/0 (2007-09-23)
    +
    * Generated by: SiSU 0.59.1 of 2007w39/2 (2007-09-25)
    * Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux]
    -
    * Last Generated on: Mon Sep 24 -15:36:32 +0100 2007
    +
    * Last Generated on: Wed Sep 26 +08:59:04 +0100 2007
    * SiSU http://www.jus.uio.no/sisu diff --git a/data/doc/sisu/html/sisu_sqlite.7.html b/data/doc/sisu/html/sisu_sqlite.7.html index 036d10e8..a456c0b5 100644 --- a/data/doc/sisu/html/sisu_sqlite.7.html +++ b/data/doc/sisu/html/sisu_sqlite.7.html @@ -95,7 +95,7 @@ specified document from sqlite database. DOCUMENT INFORMATION (METADATA)

    METADATA -

    Document Manifest @ <http://www.jus.uio.no/sisu/sisu_manual/sisu_sqlite/sisu_manifest.html +

    Document Manifest @ <http://sisudoc.org/sisu_manual/sisu_sqlite/sisu_manifest.html >

    Dublin Core (DC) @@ -121,14 +121,14 @@ Type: information

    0.58

    Sourcefile Digest, MD5(sisu_sqlite.sst)= 2ffb869c7c41615ca4ec83d8bd70470d -

    Skin_Digest: MD5(/home/ralph/grotto/theatre/dbld/sisu-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +

    Skin_Digest: MD5(/home/ralph/grotto/theatre/dbld/builds/sisu/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)=

    20fc43cf3eb6590bc3399a1aef65c5a9

    Generated

    Document (metaverse) last -generated: Mon Sep 24 15:36:18 +0100 2007 -

    Generated by: SiSU 0.59.0 of -2007w38/0 (2007-09-23) +generated: Wed Sep 26 08:59:00 +0100 2007 +

    Generated by: SiSU 0.59.1 of +2007w39/2 (2007-09-25)

    Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36)  [i486-linux]

    @@ -166,15 +166,15 @@ generated: Mon Sep 24 15:36:18 +0100 2007

    -
    * Generated by: SiSU 0.59.0 of 2007w38/0 (2007-09-23)
    +
    * Generated by: SiSU 0.59.1 of 2007w39/2 (2007-09-25)
    * Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux]
    -
    * Last Generated on: Mon Sep 24 -15:36:32 +0100 2007
    +
    * Last Generated on: Wed Sep 26 +08:59:05 +0100 2007
    * SiSU http://www.jus.uio.no/sisu diff --git a/data/doc/sisu/html/sisu_vim.7.html b/data/doc/sisu/html/sisu_vim.7.html index b607fdb3..c9ea62bb 100644 --- a/data/doc/sisu/html/sisu_vim.7.html +++ b/data/doc/sisu/html/sisu_vim.7.html @@ -7,13 +7,16 @@ Table of Contents

    -SISU - VIM, RALPH AMISSAH + +

    Name

    +man page "name/whatis" information not provided, set in header @man: +name=[whatis information] SISU - VIM, RALPH AMISSAH

    SISU VIM -

    1. SISU VIM +

    1. SISU +VIM

    Synopsis -

    SiSU has -syntax highlighting for a number of editors including vim which are documented -under: +

    SiSU has syntax highlighting for a number of editors +including vim which are documented under:

    man sisu_syntax_highlighting

    /usr/share/doc/sisu/sisu_manual/sisu_syntax_highlighting/index.html
    @@ -52,41 +55,40 @@ of Vim).

    DOCUMENT INFORMATION (METADATA)

    METADATA

    Document Manifest -@ <http://www.jus.uio.no/sisu/sisu_manual/sisu_vim/sisu_manifest.html +@ <http://sisudoc.org/sisu_manual/sisu_vim/sisu_manifest.html > -

    Dublin -Core (DC) +

    Dublin Core +(DC)

    DC tags included with this document are provided here. -

    DC -Title: SiSU - Vim +

    DC Title: +SiSU - Vim

    DC Creator: Ralph Amissah -

    DC Rights: Copyright (C) -Ralph Amissah 2007, part of SiSU documentation, License GPL 3 -

    DC Type: +

    DC Rights: Copyright (C) Ralph +Amissah 2007, part of SiSU documentation, License GPL 3 +

    DC Type: information -

    information

    DC Date created: 2002-11-12

    DC Date issued: 2002-11-12 -

    DC -Date available: 2002-11-12 +

    DC Date available: + +

    2002-11-12

    DC Date modified: 2007-09-16 -

    DC Date: 2007-09-16 +

    DC Date: 2007-09-16 +

    Version Information -

    Version Information

    Sourcefile: sisu_vim.sst -

    Filetype: SiSU text insert - -

    0.58 -

    Sourcefile Digest, MD5(sisu_vim.sst)= a3db74eebef04815aa234d3c3b17f375 - -

    Skin_Digest: MD5(/home/ralph/grotto/theatre/dbld/sisu-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +

    Filetype: SiSU text insert 0.58 +

    Sourcefile +Digest, MD5(sisu_vim.sst)= a3db74eebef04815aa234d3c3b17f375 +

    Skin_Digest: +MD5(/home/ralph/grotto/theatre/dbld/sisu-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)=

    20fc43cf3eb6590bc3399a1aef65c5a9

    Generated

    Document (metaverse) last -generated: Mon Sep 24 15:36:19 +0100 2007 -

    Generated by: SiSU 0.59.0 of -2007w38/0 (2007-09-23) +generated: Sat Sep 29 13:20:58 +0100 2007 +

    Generated by: SiSU 0.59.1 of +2007w39/2 (2007-09-25)

    Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36)  [i486-linux]

    @@ -124,15 +126,15 @@ generated: Mon Sep 24 15:36:19 +0100 2007

    -
    * Generated by: SiSU 0.59.0 of 2007w38/0 (2007-09-23)
    +
    * Generated by: SiSU 0.59.1 of 2007w39/2 (2007-09-25)
    * Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux]
    -
    * Last Generated on: Mon Sep 24 -15:36:32 +0100 2007
    +
    * Last Generated on: Sat Sep 29 +13:21:02 +0100 2007
    * SiSU http://www.jus.uio.no/sisu @@ -140,5 +142,11 @@ generated: Mon Sep 24 15:36:19 +0100 2007

    + +

    +Table of Contents

    +

    diff --git a/data/doc/sisu/html/sisu_webrick.1.html b/data/doc/sisu/html/sisu_webrick.1.html index e25650a4..8a51ea32 100644 --- a/data/doc/sisu/html/sisu_webrick.1.html +++ b/data/doc/sisu/html/sisu_webrick.1.html @@ -7,52 +7,57 @@ Table of Contents

    -SISU - SISU_WEBRICK, RALPH AMISSAH -

    SISU WEBRICK -

    1. SISU_WEBRICK -

    1.1 -

    NAME -

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

    Name

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

    system +

    Synopsis

    +sisu -W SISU - SISU_WEBRICK, RALPH AMISSAH +

    SISU WEBRICK +

    1. SISU_WEBRICK + +

    1.1 NAME +

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

    publishing system

    1.2 SYNOPSIS

    sisu_webrick  [port]

    or -

    sisu -W  [port] -

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

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

    sisu -W  [port] + +

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

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

    1.4 SUMMARY OF MAN PAGE -

    sisu_webrick, may be started on it’s own with -the command: sisu_webrick or using the sisu command with the -W flag: sisu --W  [port] -

    where no port is given and settings are unchanged the default +

    sisu_webrick, may be started +on it’s own with the command: sisu_webrick or using the sisu command with +the -W flag: sisu -W  [port] +

    where no port is given and settings are unchanged -

    port is 8081 +

    the default port is 8081

    1.5 DOCUMENT PROCESSING COMMAND FLAGS -

    sisu -W  [port] starts -Ruby Webrick web-server, serving SiSU output directories, on the port provided, +

    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 -

    or if no port is provided and the defaults have not been changed in ~/.sisu/sisurc.yaml +

    been changed in ~/.sisu/sisurc.yaml then on port 8081 +

    1.6 FURTHER INFORMATION -

    then on port 8081 -

    1.6 FURTHER INFORMATION -

    For more information on SiSU -see: <http://www.jus.uio.no/sisu +

    For more information on SiSU see: <http://www.jus.uio.no/sisu > -

    or man sisu +

    or man sisu +

    1.7 AUTHOR -

    Ralph Amissah <ralph@amissah.com> -or <ralph.amissah@gmail.com> -

    1.8 SEE ALSO +

    Ralph Amissah ralph@amissah.com or ralph.amissah@gmail.com +

    1.8 + +

    SEE ALSO

    sisu(1)
    @@ -64,7 +69,7 @@ or <ralph.amissah@gmail.com>

    DOCUMENT INFORMATION (METADATA)

    METADATA -

    Document Manifest @ <http://www.jus.uio.no/sisu/sisu_manual/sisu_webrick/sisu_manifest.html +

    Document Manifest @ <http://sisudoc.org/sisu_manual/sisu_webrick/sisu_manifest.html >

    Dublin Core (DC) @@ -90,15 +95,15 @@ Date: 2007-09-16

    Filetype:

    SiSU text 0.58 -

    Sourcefile Digest, MD5(sisu_webrick.sst)= 2ed989fa51df49e85d1161f4a4afc897 +

    Sourcefile Digest, MD5(sisu_webrick.sst)= 11fb0494766a9b6d3ce091bf41241973

    Skin_Digest: MD5(/etc/sisu/skin/doc/skin_sisu.rb)= c4b3c21ba1ed0d491bfe14cd0fcd075e

    Generated -

    Document (metaverse) last generated: Mon Sep 24 15:36:15 +

    Document (metaverse) last generated: Sat Sep 29 15:49:36

    +0100 2007 -

    Generated by: SiSU 0.59.0 of 2007w38/0 (2007-09-23) +

    Generated by: SiSU 0.59.1 of 2007w39/2 (2007-09-25)

    Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36)  [i486-linux]

    @@ -137,15 +142,15 @@ document:

    -
    * Generated by: SiSU 0.59.0 of 2007w38/0 (2007-09-23)
    +
    * Generated by: SiSU 0.59.1 of 2007w39/2 (2007-09-25)
    * Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux]
    -
    * Last Generated on: Mon Sep 24 -15:36:31 +0100 2007
    +
    * Last Generated on: Sat Sep 29 +15:49:36 +0100 2007
    * SiSU http://www.jus.uio.no/sisu @@ -153,5 +158,12 @@ document:

    + +

    +Table of Contents

    +

    diff --git a/lib/sisu/v0/manpage.rb b/lib/sisu/v0/manpage.rb index 768fbc48..304bcda1 100644 --- a/lib/sisu/v0/manpage.rb +++ b/lib/sisu/v0/manpage.rb @@ -269,7 +269,9 @@ WOK util=SiSU_text_utils::Wrap.new(paragraph,78,m*2) else util=SiSU_text_utils::Wrap.new(paragraph,78,0) end - util.line_wrap + w=util.line_wrap + w.gsub!(/^(\\\.)/,' \1') + w end if lv times=wrapped.length 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 .SH -2. HOW DOES SISU WORK? +2. COMMANDS SUMMARY .BR -.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. -.B SiSU -markup is primarily an abstraction 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 \ -browser \ viewing, \ paper \ publication, \ sql \ search \ etc.] (html, xml, -odf, latex, pdf, sql) - -.BR -* 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: - -.BR - * html \- both as a single scrollable text and a segmented document - -.BR - * xhtml - -.BR - * XML \- both in sax and dom style xml structures for further development as - required - -.BR - * ODF \- open document format, the iso standard for document storage - -.BR - * LaTeX \- used to generate pdf - -.BR - * pdf (via LaTeX) - -.BR - * sql \- population of an sql database, (at the same object level that is - used to cite text within a document) - -.BR -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)) - -.BR -* ensuring content can be cited in a meaningful way regardless of selected -output format. Online publishing (and publishing in multiple document formats) -lacks a useful way of citing text internally within documents (important to -academics generally and to lawyers) as page numbers are meaningless across -browsers and formats. sisu seeks to provide a common way of pinpoint 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. - -.BR -* 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]. - -.BR -* 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\", and new document formats may be added. e.g. addition of odf -(open document text) module in 2006 and in future html5 output sometime in -future, without modification of existing prepared texts - -.BR -* SQL search aside, documents are generated as required and static once -generated. - -.BR -* 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 output formats, updated technology document -presentations/representations) - -.BR -* document source (plaintext utf\-8) if shared on the net may be used as input -and processed locally to produce the different document outputs - -.BR -* document source may be bundled together (automatically) with associated -documents (multiple language versions or master document with inclusions) and -images and sent as a zip file called a sisupod, if shared on the net these too -may be processed locally to produce the desired document outputs - -.BR -* generated document outputs may automatically be posted to remote sites. - -.BR -* for basic document generation, the only software dependency is -.B 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. - -.BR -* as a developers tool it is flexible and extensible - -.BR -Syntax highlighting for -.B SiSU -markup is available for a number of text editors. - -.BR -.B 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 - -.BR -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)... - -.BR -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. - -.SH -4. HELP -.BR - -.SH -4.1 SISU MANUAL - -.BR -The most up to date information on sisu should be contained in the sisu_manual, -available at: - -.BR - - -.BR -and (from -.B SiSU -0.59 onwards) installed locally at: - -.BR - /usr/share/doc/sisu/sisu_manual/ - -.BR -or equivalent directory - -.BR -Within the -.B SiSU -tarball at: - -.BR - \./data/doc/sisu/sisu_manual/ - -.SH -4.2 SISU MAN PAGES - -.BR -If -.B SiSU -is installed on your system usual man commands should be available, try: - -.BR - man sisu - -.BR - man sisu_markup - -.BR - man sisu_commands - -.BR -Most -.B 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 -.B SiSU -tarball at: - -.BR - \./data/doc/sisu/sisu_manual/ - -.BR -Once installed, directory equivalent to: - -.BR - /usr/share/doc/sisu/sisu_manual/ - -.BR -Available man pages are converted back to html using man2html: - -.BR - /usr/share/doc/sisu/html/ - -.BR - \./data/doc/sisu/html/ - -.BR -The -.B SiSU -man pages can be viewed online at:[^9] - -.BR -An online version of the sisu man page is available here: - -.BR -* various sisu man pages \ [^10] - -.BR -* sisu.1 \ [^11] - -.BR -* sisu.8 \ [^12] - -.BR -* sisu_examples.1 \ [^13] - -.BR -* sisu_webrick.1 \ [^14] - -.SH -4.3 SISU BUILT\-IN INTERACTIVE HELP - -.BR -This is particularly useful when current installation information is obtained -as the interactive help is able to provide information on your sisu -configuration and setup. - -.BR - sisu \-\-help - -.BR - sisu \-\-help \ [subject] - -.BR - sisu \-\-help env \ [for \ feedback \ on \ the \ way \ your \ system \ is \ - setup \ with \ regard \ to \ sisu] - -.BR - sisu \-V \ [same \ as \ above \ command] - -.BR - sisu \-\-help commands - -.BR - sisu \-\-help markup - -.BR -Apart from real\-time information on your current configuration the -.B 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). - -.BR -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. - -.SH -4.4 HELP SOURCES - -.BR -For lists of alternative help sources, see: - -.BR -.B man page - -.BR - man sisu_help_sources - -.BR -.B man2html - -.BR - /usr/share/doc/sisu/sisu_manual/sisu_help_sources/index.html - -.BR -.B sisu generated html - -.BR - /usr/share/doc/sisu/html/sisu_help_sources/index.html - -.BR - - -.BR - - -.SH -5. COMMANDS SUMMARY -.BR - -.SH -5.1 SYNOPSIS +2.1 SYNOPSIS .BR .B SiSU @@ -539,7 +193,7 @@ Note: commands should be issued from within the directory that contains the marked up files, cd to markup directory. .SH -5.2 DESCRIPTION +2.2 DESCRIPTION .BR .B SiSU @@ -551,7 +205,7 @@ numbered text objects (\"object citation numbering\") and the same document structure information. For more see: .SH -5.3 DOCUMENT PROCESSING COMMAND FLAGS +2.3 DOCUMENT PROCESSING COMMAND FLAGS .TP .B \ \-a \ \ [filename/wildcard] @@ -640,6 +294,10 @@ system, and works with most web servers). \ [behaviour \ switched \ after \ .B \ \-I \ \ [filename/wildcard] produces texinfo and info file, (view with pinfo). +.TP +.B \ \-i \ \ [filename/wildcard] +produces man page of file, not suitable for all outputs. + .TP .B \ \-L \ prints \ license \ information. \ @@ -820,7 +478,7 @@ produces php (zend) \ [this \ feature \ is \ disabled \ for \ the \ time \ being] .SH -6. COMMAND LINE MODIFIERS +3. COMMAND LINE MODIFIERS .BR .TP @@ -845,7 +503,7 @@ sign sign .SH -7. DATABASE COMMANDS +4. DATABASE COMMANDS .BR .BR @@ -891,7 +549,7 @@ alphanumerics and underscores. The v in e.g. \-Dv is for verbose output. .SH -8. SHORTCUTS, SHORTHAND FOR MULTIPLE FLAGS +5. SHORTCUTS, SHORTHAND FOR MULTIPLE FLAGS .BR .TP @@ -940,7 +598,7 @@ wildcard] consider \-u for appended url info or \-v for verbose output .SH -8.0.1 COMMAND LINE WITH FLAGS \- BATCH PROCESSING +5.0.1 COMMAND LINE WITH FLAGS \- BATCH PROCESSING .BR In the data directory run sisu \-mh filename or wildcard eg. \"sisu \-h @@ -948,20 +606,175 @@ cisg.sst\" or \"sisu \-h *.{sst,ssm}\" to produce html version of all documents. .BR -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. +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. + +.SH +6. HELP +.BR + +.SH +6.1 SISU MANUAL + +.BR +The most up to date information on sisu should be contained in the sisu_manual, +available at: + +.BR + + +.BR +and (from +.B SiSU +0.59 onwards) installed locally at: + +.BR + /usr/share/doc/sisu/sisu_manual/ + +.BR +or equivalent directory + +.BR +Within the +.B SiSU +tarball at: + +.BR + \./data/doc/sisu/sisu_manual/ + +.SH +6.2 SISU MAN PAGES + +.BR +If +.B SiSU +is installed on your system usual man commands should be available, try: + +.BR + man sisu + +.BR + man sisu_markup + +.BR + man sisu_commands + +.BR +Most +.B 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 +.B SiSU +tarball at: + +.BR + \./data/doc/sisu/sisu_manual/ + +.BR +Once installed, directory equivalent to: + +.BR + /usr/share/doc/sisu/sisu_manual/ + +.BR +Available man pages are converted back to html using man2html: + +.BR + /usr/share/doc/sisu/html/ + +.BR + \./data/doc/sisu/html/ + +.BR +An online version of the sisu man page is available here: + +.BR +* various sisu man pages \ [^7] + +.BR +* sisu.1 \ [^8] + +.SH +6.3 SISU BUILT\-IN INTERACTIVE HELP + +.BR +This is particularly useful for getting the current sisu setup/environment +information: + +.BR + sisu \-\-help + +.BR + sisu \-\-help \ [subject] + +.BR + sisu \-\-help commands + +.BR + sisu \-\-help markup + +.BR + sisu \-\-help env \ [for \ feedback \ on \ the \ way \ your \ system \ is \ + setup \ with \ regard \ to \ sisu] + +.BR + sisu \-V \ [environment \ information, \ same \ as \ above \ command] + +.BR + sisu (on its own provides version and some help information) + +.BR +Apart from real\-time information on your current configuration the +.B 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). + +.BR +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. + +.SH +6.4 HELP SOURCES + +.BR +For lists of alternative help sources, see: + +.BR +.B man page + +.BR + man sisu_help_sources + +.BR +.B man2html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_help_sources/index.html + +.BR +.B sisu generated html + +.BR + /usr/share/doc/sisu/html/sisu_help_sources/index.html + +.BR + + +.BR + .SH -9. INTRODUCTION TO SISU MARKUP[^15] +7. INTRODUCTION TO SISU MARKUP[^9] .BR .SH -9.1 SUMMARY +7.1 SUMMARY .BR .B SiSU -source documents are plaintext (UTF\-8)[^16] files +source documents are plaintext (UTF\-8)[^10] files .BR All paragraphs are separated by an empty line. @@ -1003,10 +816,10 @@ Some interactive help on markup is available, by typing sisu and selecting markup or sisu \-\-help markup .SH -9.2 MARKUP EXAMPLES +7.2 MARKUP EXAMPLES .SH -9.2.1 ONLINE +7.2.1 ONLINE .BR Online markup examples are available together with the respective outputs @@ -1027,7 +840,7 @@ an alternative presentation of markup syntax: .SH -9.2.2 INSTALLED +7.2.2 INSTALLED .BR With @@ -1038,7 +851,7 @@ sisu\-markup\-samples is installed also under: /usr/share/doc/sisu/sisu_markup_samples/non\-free .SH -10. MARKUP OF HEADERS +8. MARKUP OF HEADERS .BR .BR @@ -1058,7 +871,7 @@ a space and the comment: .fi .SH -10.1 SAMPLE HEADER +8.1 SAMPLE HEADER .BR This current document has a header similar to this one (without the comments): @@ -1093,7 +906,7 @@ This current document has a header similar to this one (without the comments): .fi .SH -10.2 AVAILABLE HEADERS +8.2 AVAILABLE HEADERS .BR Header tags appear at the beginning of a document and provide meta information @@ -1319,6 +1132,16 @@ 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. +.TP +.B \ @man: \ 8; +\ name=sisu \ \- \ documents: \ markup, \ structuring, \ publishing \ in \ +multiple \ standard \ 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 + .BR .B @links: { @@ -1335,11 +1158,11 @@ sample: \ free_as_in_freedom.richard_stallman_crusade_for_free_software.sam_williams.sst] .SH -11. MARKUP OF SUBSTANTIVE TEXT +9. MARKUP OF SUBSTANTIVE TEXT .BR .SH -11.1 HEADING LEVELS +9.1 HEADING LEVELS .BR Heading levels are :A~ ,:B~ ,:C~ ,1~ ,2~ ,3~ \... :A \- :C being part / section @@ -1388,7 +1211,7 @@ normally be marked 1.1.1 or 1.1.2 or 1.2.1 or 2.1.1 etc. in a document .fi .SH -11.2 FONT ATTRIBUTES +9.2 FONT ATTRIBUTES .BR .B markup example: @@ -1450,7 +1273,7 @@ normal text strikethrough .SH -11.3 INDENTATION AND BULLETS +9.3 INDENTATION AND BULLETS .BR .B markup example: @@ -1513,7 +1336,7 @@ Numbered List (not to be confused with headings/titles, (document structure)) .fi .SH -11.4 FOOTNOTES / ENDNOTES +9.4 FOOTNOTES / ENDNOTES .BR Footnotes and endnotes not distinguished in markup. They are automatically @@ -1532,7 +1355,7 @@ document output selected will have either footnotes or endnotes. .B resulting output: .BR -[^17] +[^11] .BR .B markup example: @@ -1546,7 +1369,7 @@ document output selected will have either footnotes or endnotes. .B resulting output: .BR -normal text[^18] continues +normal text[^12] continues .BR .B markup example: @@ -1599,10 +1422,10 @@ normal text \ [^+2] continues the standard and pair notation cannot be mixed in the same document .SH -11.5 LINKS +9.5 LINKS .SH -11.5.1 NAKED URLS WITHIN TEXT, DEALING WITH URLS +9.5.1 NAKED URLS WITHIN TEXT, DEALING WITH URLS .BR urls are found within text and marked up automatically. A url within text is @@ -1671,7 +1494,7 @@ To link text or an image to a url the markup is as follows .fi .SH -11.5.2 LINKING TEXT +9.5.2 LINKING TEXT .BR .B resulting output: @@ -1695,10 +1518,10 @@ automatically as a footnote .B resulting output: .BR -about SiSU \ [^19] markup +about SiSU \ [^13] markup .SH -11.5.3 LINKING IMAGES +9.5.3 LINKING IMAGES .BR .B markup example: @@ -1722,7 +1545,7 @@ about SiSU \ [^19] markup tux.png 64x80 \"Gnu/Linux \- a better way\" .BR -[ \ ruby_logo \ (png \ missing) \ ] \ [^20] +[ \ ruby_logo \ (png \ missing) \ ] \ [^14] .BR GnuDebianLinuxRubyBetterWay.png 100x101 \"Way Better \- with Gnu/Linux, Debian @@ -1749,10 +1572,10 @@ to headings 1, 2 and 3 i.e. 2~[name] and 3~[name] or in the case of auto\-heading numbering, without further intervention. .SH -11.6 GROUPED TEXT +9.6 GROUPED TEXT .SH -11.6.1 TABLES +9.6.1 TABLES .BR Tables may be prepared in two either of two forms @@ -1783,7 +1606,7 @@ information in each column .BR .B markup example: -[^21] +[^15] .nf @@ -1811,7 +1634,7 @@ information in each column than 100 times in last month. .SH -11.6.2 POEM +9.6.2 POEM .BR .B basic markup: @@ -1971,7 +1794,7 @@ than 100 times in last month. .P .SH -11.6.3 GROUP +9.6.3 GROUP .BR .B basic markup: @@ -2131,7 +1954,7 @@ than 100 times in last month. .P .SH -11.6.4 CODE +9.6.4 CODE .BR Code tags are used to escape regular sisu markup, and have been used @@ -2197,7 +2020,7 @@ some \ later \ time] .fi .SH -12. COMPOSITE DOCUMENTS MARKUP +10. COMPOSITE DOCUMENTS MARKUP .BR .BR @@ -2252,13 +2075,34 @@ MARKUP SYNTAX HISTORY .BR .SH -13. NOTES RELATED TO FILES\-TYPES AND MARKUP SYNTAX +11. NOTES RELATED TO FILES\-TYPES AND MARKUP SYNTAX .BR .BR 0.38 is substantially current, depreciated 0.16 supported, though file names were changed at 0.37 +.BR +* sisu \-\-query=[sisu \ version \ \ [0.38] or \'history] + +.BR +provides a short history of changes to +.B SiSU +markup + +.BR +.B 0.57 +(2007w34/4) +.B 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 \ +contents \ of \ the \ headers \ @title: \ and \ @author:] + + +.nf + :A~ @title by @author +.fi + .BR .B 0.52 (2007w14/6) declared document type identifier at start of text/document: @@ -2288,17 +2132,112 @@ variations include \' .B 0.42 (2006w27/4) * (asterisk) type endnotes, used e.g. in relation to author +.BR +.B SiSU +0.42 is the same as 0.38 with the introduction of some additional endnote +types, + +.BR +Introduces some variations on endnotes, in particular the use of the asterisk + + +.nf + ~{* for example for describing an author }~ and ~{** for describing a second author }~ +.fi + +.BR +* for example for describing an author + +.BR +** for describing a second author + +.BR +and + + +.nf + ~[* \ my \ note \ ]~ or ~[+ \ another \ note \ ]~ +.fi + +.BR +which numerically increments an asterisk and plus respectively + +.BR +*1 my note +1 another note + .BR .B 0.38 (2006w15/7) introduced new/alternative notation for headers, e.g. @title: (instead of 0~title), and accompanying document structure markup, :A,:B,:C,1,2,3 (maps to previous 1,2,3,4,5,6) +.BR +.B SiSU +0.38 introduced alternative experimental header and heading/structure +markers, + + +.nf + @headername: and headers :A~ :B~ :C~ 1~ 2~ 3~ +.fi + +.BR +as the equivalent of: + + +.nf + 0~headername and headers 1~ 2~ 3~ 4~ 5~ 6~ +.fi + +.BR +The internal document markup of +.B SiSU +0.16 remains valid and standard Though note that +.B SiSU +0.37 introduced a new file naming convention + +.BR +.B 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 which are followed by ordinary text. This may be +conceptualised as levels A,B,C, 1,2,3, and using such letter number notation, +in effect: A must exist, optional B and C may follow in sequence (not strict) 1 +must exist, optional 2 and 3 may follow in sequence i.e. there are two +independent heading level sequences A,B,C and 1,2,3 (using the 0.16 standard +notation 1,2,3 and 4,5,6) on the positive side: the 0.38 A,B,C,1,2,3 +alternative makes explicit an aspect of structuring documents in +.B SiSU +that is not otherwise obvious to the newcomer (though it appears more +complicated, is more in 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 + .BR .B 0.37 (2006w09/7) introduced new file naming convention, \.sst (text), \.ssm (master), \.ssi (insert), markup syntax unchanged +.BR +.B 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 + +.BR +this is captured by the following file \'rename\' instruction: + + +.nf + rename \'s/\.s[123]$/\.sst/\' *.s{1,2,3} + rename \'s/\.r[123]$/\.ssm/\' *.r{1,2,3} + rename \'s/\.si$/\.ssi/\' *.si +.fi + +.BR +The internal document markup remains unchanged, from +.B SiSU +0.16 + .BR .B 0.35 (2005w52/3) sisupod, zipped content file introduced @@ -2322,8 +2261,23 @@ relied upon 0~title type, and headings \ [1\-6]~ introduced, also percentage sign (%) at start of a text line as comment marker +.BR +.B SiSU +0.16 (0.15 development branch) introduced the use of + +.BR +the header 0~ and headings/structure 1~ 2~ 3~ 4~ 5~ 6~ + +.BR +in place of the 0.1 header, heading/structure notation + +.BR +.B SiSU +0.1 headers and headings structure represented by header 0{~ and +headings/structure 1{ 2{ 3{ 4{~ 5{ 6{ + .SH -14. SISU FILETYPES +12. SISU FILETYPES .BR .BR @@ -2331,7 +2285,7 @@ start of a text line as comment marker has plaintext and binary filetypes, and can process either type of document. .SH -14.1 \.SST \.SSM \.SSI MARKED UP PLAIN TEXT +12.1 \.SST \.SSM \.SSI MARKED UP PLAIN TEXT .BR .B SiSU @@ -2344,7 +2298,7 @@ plaintext markup files are of three types 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. + \.ssi and are not processed. .BR .B SiSU @@ -2359,7 +2313,7 @@ source markup can be shared with the command: sisu \-s \ [filename] .SH -14.1.1 SISU TEXT \- REGULAR FILES (.SST) +12.1.1 SISU TEXT \- REGULAR FILES (.SST) .BR The most common form of document in @@ -2375,7 +2329,7 @@ markup. .SH -14.1.2 SISU MASTER FILES (.SSM) +12.1.2 SISU MASTER FILES (.SSM) .BR Composite documents which incorporate other @@ -2401,7 +2355,7 @@ contain other documents. .BR Note: a secondary file of the composite document is built prior to processing -with the same prefix and the suffix \._sst \ [^22] +with the same prefix and the suffix \._sst \ [^16] .BR @@ -2410,7 +2364,7 @@ with the same prefix and the suffix \._sst \ [^22] .SH -14.1.3 SISU INSERT FILES (.SSI) +12.1.3 SISU INSERT FILES (.SSI) .BR Inserts are documents prepared solely for the purpose of being incorporated @@ -2422,7 +2376,7 @@ 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. .SH -14.2 SISUPOD, ZIPPED BINARY CONTAINER (SISUPOD.ZIP, \.SSP) +12.2 SISUPOD, ZIPPED BINARY CONTAINER (SISUPOD.ZIP, \.SSP) .BR A sisupod is a zipped @@ -2474,11 +2428,11 @@ locally or on a remote server for which a url is provided. .SH -15. EXPERIMENTAL ALTERNATIVE INPUT REPRESENTATIONS +13. EXPERIMENTAL ALTERNATIVE INPUT REPRESENTATIONS .BR .SH -15.1 ALTERNATIVE XML +13.1 ALTERNATIVE XML .BR .B SiSU @@ -2514,7 +2468,7 @@ or the same: sisu \-\-from\-sxml \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]] .SH -15.1.1 XML SAX REPRESENTATION +13.1.1 XML SAX REPRESENTATION .BR To convert from sst to simple xml (sax) representation: @@ -2536,7 +2490,7 @@ or the same: sisu \-\-from\-sxml \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]] .SH -15.1.2 XML DOM REPRESENTATION +13.1.2 XML DOM REPRESENTATION .BR To convert from sst to simple xml (dom) representation: @@ -2558,7 +2512,7 @@ or the same: sisu \-\-from\-sxml \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]] .SH -15.1.3 XML NODE REPRESENTATION +13.1.3 XML NODE REPRESENTATION .BR To convert from sst to simple xml (node) representation: @@ -2580,11 +2534,11 @@ or the same: sisu \-\-from\-sxml \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]] .SH -16. CONFIGURATION +14. CONFIGURATION .BR .SH -16.1 DETERMINING THE CURRENT CONFIGURATION +14.1 DETERMINING THE CURRENT CONFIGURATION .BR Information on the current configuration of @@ -2605,7 +2559,7 @@ Either of these should be executed from within a directory that contains sisu markup source documents. .SH -16.2 CONFIGURATION FILES (CONFIG.YML) +14.2 CONFIGURATION FILES (CONFIG.YML) .BR .B SiSU @@ -2650,7 +2604,7 @@ If is installed a sample sisurc.yml may be found in /etc/sisu/sisurc.yml .SH -17. SKINS +15. SKINS .BR .BR @@ -2687,7 +2641,7 @@ The skin itself is a ruby file which modifies the default appearances set in the program. .SH -17.1 DOCUMENT SKIN +15.1 DOCUMENT SKIN .BR Documents take on a document skin, if the header of the document specifies a @@ -2699,7 +2653,7 @@ skin to be used. .fi .SH -17.2 DIRECTORY SKIN +15.2 DIRECTORY SKIN .BR A directory may be mapped on to a particular skin, so all documents within that @@ -2713,13 +2667,13 @@ 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. .SH -17.3 SITE SKIN +15.3 SITE SKIN .BR A site skin, modifies the program default skin. .SH -17.4 SAMPLE SKINS +15.4 SAMPLE SKINS .BR With @@ -2745,14 +2699,14 @@ list) may be found in: directory) .SH -18. CSS \- CASCADING STYLE SHEETS (FOR HTML, XHTML AND XML) +16. CSS \- CASCADING STYLE SHEETS (FOR HTML, XHTML AND XML) .BR .BR CSS files to modify the appearance of .B 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 + \./_sisu/css; ~/.sisu/css or; /etc/sisu/css and these will be copied to the output directories with the command sisu \-CC. .BR @@ -2778,14 +2732,14 @@ The default homepage may use homepage.css or html.css .BR 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.[^23] +file that is looked for in a skin.[^17] .SH -19. ORGANISING CONTENT +17. ORGANISING CONTENT .BR .SH -19.1 DIRECTORY STRUCTURE AND MAPPING +17.1 DIRECTORY STRUCTURE AND MAPPING .BR The output directory root can be set in the sisurc.yml file. Under the root, @@ -2814,10 +2768,10 @@ directory basis and resulting documents will take on the appropriate different appearance. .SH -19.2 ORGANISING CONTENT +17.2 ORGANISING CONTENT .SH -20. HOMEPAGES +18. HOMEPAGES .BR .BR @@ -2845,7 +2799,7 @@ subject. Each directory can/should have its own homepage. See the section on directory structure and organisation of content. .SH -20.1 HOME PAGE AND OTHER CUSTOM BUILT PAGES IN A SUB\-DIRECTORY +18.1 HOME PAGE AND OTHER CUSTOM BUILT PAGES IN A SUB\-DIRECTORY .BR Custom built pages, including the home page index.html may be placed within the @@ -2857,7 +2811,7 @@ they are copied to the root of the output directory with the command: sisu \-CC .SH -20.2 HOME PAGE WITHIN A SKIN +18.2 HOME PAGE WITHIN A SKIN .BR Skins are described in a separate section, but basically are a file written in @@ -2890,11 +2844,11 @@ skin_poems.rb .fi .SH -21. MARKUP AND OUTPUT EXAMPLES +19. MARKUP AND OUTPUT EXAMPLES .BR .SH -21.1 MARKUP EXAMPLES +19.1 MARKUP EXAMPLES .BR Current markup examples and document output samples are provided at @@ -2910,7 +2864,7 @@ header, and an indication that the levels to be taken into account by the program in generating its output are. .SH -22. SISU SEARCH \- INTRODUCTION +20. SISU SEARCH \- INTRODUCTION .BR .BR @@ -2936,16 +2890,16 @@ each document, which can be viewed within the database directly or in various output formats. .SH -23. SQL +21. SQL .BR .SH -23.1 POPULATING SQL TYPE DATABASES +21.1 POPULATING SQL TYPE DATABASES .BR .B SiSU -feeds sisu markupd documents into sql type databases PostgreSQL[^24] and/or -SQLite[^25] database together with information related to document structure. +feeds sisu markupd documents into sql type databases PostgreSQL[^18] and/or +SQLite[^19] database together with information related to document structure. .BR This is one of the more interesting output forms, as all the structural data of @@ -3002,11 +2956,11 @@ headings etc. (as the Dublin Core is incorporated it is easy to make use of that as well). .SH -24. POSTGRESQL +22. POSTGRESQL .BR .SH -24.1 NAME +22.1 NAME .BR .B SiSU @@ -3014,7 +2968,7 @@ that as well). postgresql dependency package .SH -24.2 DESCRIPTION +22.2 DESCRIPTION .BR Information related to using postgresql with sisu (and related to the @@ -3026,7 +2980,7 @@ to populate a postgresql database, this being part of \- man sisu). .SH -24.3 SYNOPSIS +22.3 SYNOPSIS .BR sisu \-D \ [instruction] \ [filename/wildcard \ if \ required] @@ -3035,7 +2989,7 @@ to populate a postgresql database, this being part of sisu \-D \-\-pg \-\-[instruction] \ [filename/wildcard \ if \ required] .SH -24.4 COMMANDS +22.4 COMMANDS .BR Mappings to two databases are provided by default, postgresql and sqlite, the @@ -3048,7 +3002,7 @@ alternatively \-\-sqlite or \-\-pgsql may be used may be used interchangeably. .SH -24.4.1 CREATE AND DESTROY DATABASE +22.4.1 CREATE AND DESTROY DATABASE .TP .B \ \-\-pgsql \ \-\-createall @@ -3078,7 +3032,7 @@ given \ directory \ (and \ directories \ of \ the \ same \ name). \ \ structure \ .SH -24.4.2 IMPORT AND REMOVE DOCUMENTS +22.4.2 IMPORT AND REMOVE DOCUMENTS .TP .B \ sisu \ \-D \ \-\-import \ \-v \ \ [filename/wildcard] @@ -3094,18 +3048,18 @@ updates file contents in database removes specified document from postgresql database. .SH -25. SQLITE +23. SQLITE .BR .SH -25.1 NAME +23.1 NAME .BR .B SiSU \- Structured information, Serialized Units \- a document publishing system. .SH -25.2 DESCRIPTION +23.2 DESCRIPTION .BR Information related to using sqlite with sisu (and related to the sisu_sqlite @@ -3116,7 +3070,7 @@ to populate an sqlite database, this being part of \- man sisu). .SH -25.3 SYNOPSIS +23.3 SYNOPSIS .BR sisu \-d \ [instruction] \ [filename/wildcard \ if \ required] @@ -3126,7 +3080,7 @@ to populate an sqlite database, this being part of required] .SH -25.4 COMMANDS +23.4 COMMANDS .BR Mappings to two databases are provided by default, postgresql and sqlite, the @@ -3139,7 +3093,7 @@ alternatively \-\-sqlite or \-\-pgsql may be used may be used interchangeably. .SH -25.4.1 CREATE AND DESTROY DATABASE +23.4.1 CREATE AND DESTROY DATABASE .TP .B \ \-\-sqlite \ \-\-createall @@ -3169,7 +3123,7 @@ given \ directory \ (and \ directories \ of \ the \ same \ name). \ \ structure \ .SH -25.4.2 IMPORT AND REMOVE DOCUMENTS +23.4.2 IMPORT AND REMOVE DOCUMENTS .TP .B \ sisu \ \-d \ \-\-import \ \-v \ \ [filename/wildcard] @@ -3185,18 +3139,18 @@ updates file contents in database removes specified document from sqlite database. .SH -26. INTRODUCTION +24. INTRODUCTION .BR .SH -26.1 SEARCH \- DATABASE FRONTEND SAMPLE, UTILISING DATABASE AND SISU FEATURES, +24.1 SEARCH \- DATABASE FRONTEND SAMPLE, UTILISING DATABASE AND SISU FEATURES, INCLUDING OBJECT CITATION NUMBERING (BACKEND CURRENTLY POSTGRESQL) .BR -Sample search frontend \ [^26] A small database and +Sample search frontend \ [^20] A small database and sample query front\-end (search from) that makes use of the citation system, .I object citation numbering -to demonstrates functionality.[^27] +to demonstrates functionality.[^21] .BR .B SiSU @@ -3211,7 +3165,7 @@ 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.[^28] +meet the search criteria.[^22] .TP .B \ sisu \ \-F \ \-\-webserv\-webrick @@ -3249,7 +3203,7 @@ is used. \ [otherwise \ a \ manual \ mapping \ for \ the \ collection \ is \ necessary] .SH -26.2 SEARCH FORM +24.2 SEARCH FORM .TP .B \ sisu \ \-F @@ -3277,7 +3231,7 @@ The generated search form must be copied manually to the webserver directory as instructed .SH -27. HYPERESTRAIER +25. HYPERESTRAIER .BR .BR @@ -3397,18 +3351,18 @@ rune along the following lines: and try open the url: .SH -28. SISU_WEBRICK +26. SISU_WEBRICK .BR .SH -28.1 NAME +26.1 NAME .BR .B SiSU \- Structured information, Serialized Units \- a document publishing system .SH -28.2 SYNOPSIS +26.2 SYNOPSIS .BR sisu_webrick \ [port] @@ -3420,7 +3374,7 @@ or sisu \-W \ [port] .SH -28.3 DESCRIPTION +26.3 DESCRIPTION .BR sisu_webrick is part of @@ -3439,7 +3393,7 @@ yaml file: ~/.sisu/sisurc.yml a sample of which is provided as /etc/sisu/sisurc.yml (or in the equivalent directory on your system). .SH -28.4 SUMMARY OF MAN PAGE +26.4 SUMMARY OF MAN PAGE .BR sisu_webrick, may be started on it\'s own with the command: sisu_webrick \ @@ -3449,7 +3403,7 @@ sisu_webrick, may be started on it\'s own with the command: sisu_webrick \ where no port is given and settings are unchanged the default port is 8081 .SH -28.5 DOCUMENT PROCESSING COMMAND FLAGS +26.5 DOCUMENT PROCESSING COMMAND FLAGS .BR sisu \-W \ [port] starts @@ -3460,7 +3414,7 @@ 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 .SH -28.6 FURTHER INFORMATION +26.6 FURTHER INFORMATION .BR For more information on @@ -3471,13 +3425,13 @@ see: or man sisu .SH -28.7 AUTHOR +26.7 AUTHOR .BR Ralph Amissah ralph@amissah.com or ralph.amissah@gmail.com .SH -28.8 SEE ALSO +26.8 SEE ALSO .BR sisu(1) @@ -3489,7 +3443,7 @@ Ralph Amissah ralph@amissah.com or ralph.amissah@gmail.com sisu(8) .SH -29. REMOTE SOURCE DOCUMENTS +27. REMOTE SOURCE DOCUMENTS .BR .BR @@ -3554,7 +3508,7 @@ REMOTE DOCUMENT OUTPUT .BR .SH -30. REMOTE OUTPUT +28. REMOTE OUTPUT .BR .BR @@ -3575,7 +3529,7 @@ may be used in conjunction with other processing flags, e.g. .fi .SH -30.1 COMMANDS +28.1 COMMANDS .TP .B \ \-R \ \ [filename/wildcard] @@ -3593,13 +3547,13 @@ sisurc.yml has been provided with information on hostname and username, and that you have your \"keys\" and ssh agent in place. Also see \-R .SH -30.2 CONFIGURATION +28.2 CONFIGURATION .BR [expand \ on \ the \ setting \ up \ of \ an \ ssh\-agent \ / \ keychain] .SH -31. REMOTE SERVERS +29. REMOTE SERVERS .BR .BR @@ -3613,11 +3567,11 @@ 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. .SH -32. QUICKSTART \- GETTING STARTED HOWTO +30. QUICKSTART \- GETTING STARTED HOWTO .BR .SH -32.1 INSTALLATION +30.1 INSTALLATION .BR Installation is currently most straightforward and tested on the @@ -3626,7 +3580,7 @@ platform, as there are packages for the installation of sisu and all requirements for what it does. .SH -32.1.1 DEBIAN INSTALLATION +30.1.1 DEBIAN INSTALLATION .BR .B SiSU @@ -3692,7 +3646,7 @@ components of sisu are to be used. Installing just the package sisu will provide basic functionality. .SH -32.1.2 RPM INSTALLATION +30.1.2 RPM INSTALLATION .BR RPMs are provided though untested, they are prepared by running alien against @@ -3711,7 +3665,7 @@ as root type: rpm \-i \ [rpm \ package \ name] .SH -32.1.3 INSTALLATION FROM SOURCE +30.1.3 INSTALLATION FROM SOURCE .BR To install @@ -3742,7 +3696,7 @@ is only dependent on the programming language in which it is written 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)[^29] or +take care of, for things like using a database (postgresql or sqlite)[^23] or converting LaTeX to pdf. .BR @@ -3820,7 +3774,7 @@ For a list of alternative actions you may type: ruby install \-T .SH -32.2 TESTING SISU, GENERATING OUTPUT +30.2 TESTING SISU, GENERATING OUTPUT .BR To check which version of sisu is installed: @@ -3848,7 +3802,7 @@ change directory to the appropriate one: cd /usr/share/doc/sisu/sisu_markup_samples/dfsg .SH -32.2.1 BASIC TEXT, PLAINTEXT, HTML, XML, ODF +30.2.1 BASIC TEXT, PLAINTEXT, HTML, XML, ODF .BR Having moved to the directory that contains the markup samples (see @@ -3862,7 +3816,7 @@ this will generate html including a concordance file, opendocument text format, plaintext, XHTML and various forms of XML, and OpenDocument text .SH -32.2.2 LATEX / PDF +30.2.2 LATEX / PDF .BR Assuming a LaTeX engine such as tetex or texlive is installed with the required @@ -3886,7 +3840,7 @@ file, opendocument text format, plaintext, XHTML and various forms of XML, and OpenDocument text and pdf .SH -32.2.3 RELATIONAL DATABASE \- POSTGRESQL, SQLITE +30.2.3 RELATIONAL DATABASE \- POSTGRESQL, SQLITE .BR Relational databases need some setting up \- you must have permission to create @@ -3910,10 +3864,10 @@ sisu \-\-pgsql \-v \-\-import free_as_in_freedom.rms_and_free_software.sam_williams.sst .SH -32.3 GETTING HELP +30.3 GETTING HELP .SH -32.3.1 THE MAN PAGES +30.3.1 THE MAN PAGES .BR Type: @@ -3926,16 +3880,16 @@ The man pages are also available online, though not always kept as up to date as within the package itself: .BR -* sisu.1 \ [^30] +* sisu.1 \ [^24] .BR -* sisu.8 \ [^31] +* sisu.8 \ [^25] .BR -* man directory \ [^32] +* man directory \ [^26] .SH -32.3.2 BUILT IN HELP +30.3.2 BUILT IN HELP .BR sisu \-\-help @@ -3950,7 +3904,7 @@ sisu \-\-help \-\-commands sisu \-\-help \-\-markup .SH -32.3.3 THE HOME PAGE +30.3.3 THE HOME PAGE .BR @@ -3959,7 +3913,7 @@ sisu \-\-help \-\-markup .SH -32.4 MARKUP SAMPLES +30.4 MARKUP SAMPLES .BR A number of markup samples (along with output) are available off: @@ -3976,12 +3930,12 @@ Additional markup samples are packaged separately in the file: .BR On .B Debian -they are available in non\-free[^33] to include them it is necessary to +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. .SH -33. EDITOR FILES, SYNTAX HIGHLIGHTING +31. EDITOR FILES, SYNTAX HIGHLIGHTING .BR .BR @@ -4140,25 +4094,209 @@ comments: assumes dark background; no display line\-wrap files: .BR - 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) + 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) + +.BR + status: this includes: syntax highlighting; vim folds; some error checking + +.BR + comments: this editor features display line wrap + +.BR +NOTE: + +.BR +[ +.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] + +.SH +32. HOW DOES SISU WORK? +.BR + +.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 +33. 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. +.B SiSU +markup is primarily an abstraction 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 \ +browser \ viewing, \ paper \ publication, \ sql \ search \ etc.] (html, xml, +odf, latex, pdf, sql) + +.BR +* 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: + +.BR + * html \- both as a single scrollable text and a segmented document + +.BR + * xhtml + +.BR + * XML \- both in sax and dom style xml structures for further development as + required + +.BR + * ODF \- open document format, the iso standard for document storage + +.BR + * LaTeX \- used to generate pdf + +.BR + * pdf (via LaTeX) + +.BR + * sql \- population of an sql database, (at the same object level that is + used to cite text within a document) + +.BR +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)) + +.BR +* ensuring content can be cited in a meaningful way regardless of selected +output format. Online publishing (and publishing in multiple document formats) +lacks a useful way of citing text internally within documents (important to +academics generally and to lawyers) as page numbers are meaningless across +browsers and formats. sisu seeks to provide a common way of pinpoint 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. + +.BR +* 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]. + +.BR +* 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\", and new document formats may be added. e.g. addition of odf +(open document text) module in 2006 and in future html5 output sometime in +future, without modification of existing prepared texts + +.BR +* SQL search aside, documents are generated as required and static once +generated. + +.BR +* 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 output formats, updated technology document +presentations/representations) + +.BR +* document source (plaintext utf\-8) if shared on the net may be used as input +and processed locally to produce the different document outputs + +.BR +* document source may be bundled together (automatically) with associated +documents (multiple language versions or master document with inclusions) and +images and sent as a zip file called a sisupod, if shared on the net these too +may be processed locally to produce the desired document outputs + +.BR +* generated document outputs may automatically be posted to remote sites. + +.BR +* for basic document generation, the only software dependency is +.B 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. + +.BR +* as a developers tool it is flexible and extensible .BR - status: this includes: syntax highlighting; vim folds; some error checking +Syntax highlighting for +.B SiSU +markup is available for a number of text editors. .BR - comments: this editor features display line wrap +.B 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 .BR -NOTE: +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)... .BR -[ -.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] +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. .SH 34. HELP SOURCES @@ -4226,65 +4364,20 @@ Alternative sources for this help sources page listed here: .BR man sisu -.BR - man sisu_commands - .BR man 7 sisu_complete -.BR - man sisu_configuration - -.BR - man 8 sisu_faq - -.BR - man sisu_filetypes - -.BR - man sisu_help - -.BR - man sisu_help_sources - -.BR - man 8 sisu_howto - -.BR - man sisu_introduction - -.BR - man sisu_markup - -.BR - man sisu_output_overview - .BR man 7 sisu_pdf .BR man 7 sisu_postgresql -.BR - man 8 sisu_quickstart - -.BR - man 8 sisu_remote - -.BR - man 8 sisu_search - -.BR - man sisu_skin - .BR man 7 sisu_sqlite .BR - man 8 sisu_syntax_highlighting - -.BR - man 7 sisu_vim + man sisu_termsheet .BR man sisu_webrick @@ -4298,7 +4391,7 @@ Note documentation is prepared in .B 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[^34] +pdf, and odf which may be also be accessed via the html pages[^28] .SH 34.2.1 LOCALLY INSTALLED @@ -4315,74 +4408,20 @@ pdf, and odf which may be also be accessed via the html pages[^34] .BR /usr/share/doc/sisu/sisu_manual/sisu/index.html -.BR - /usr/share/doc/sisu/sisu_manual/sisu_commands/index.html - .BR /usr/share/doc/sisu/sisu_manual/sisu_complete/index.html -.BR - /usr/share/doc/sisu/sisu_manual/sisu_configuration/index.html - -.BR - /usr/share/doc/sisu/sisu_manual/sisu_description/index.html - -.BR - /usr/share/doc/sisu/sisu_manual/sisu_examples/index.html - -.BR - /usr/share/doc/sisu/sisu_manual/sisu_faq/index.html - -.BR - /usr/share/doc/sisu/sisu_manual/sisu_filetypes/index.html - -.BR - /usr/share/doc/sisu/sisu_manual/sisu_help/index.html - -.BR - /usr/share/doc/sisu/sisu_manual/sisu_help_sources/index.html - -.BR - /usr/share/doc/sisu/sisu_manual/sisu_howto/index.html - -.BR - /usr/share/doc/sisu/sisu_manual/sisu_introduction/index.html - -.BR - /usr/share/doc/sisu/sisu_manual/sisu_manual/index.html - -.BR - /usr/share/doc/sisu/sisu_manual/sisu_markup/index.html - -.BR - /usr/share/doc/sisu/sisu_manual/sisu_output_overview/index.html - .BR /usr/share/doc/sisu/sisu_manual/sisu_pdf/index.html .BR /usr/share/doc/sisu/sisu_manual/sisu_postgresql/index.html -.BR - /usr/share/doc/sisu/sisu_manual/sisu_quickstart/index.html - -.BR - /usr/share/doc/sisu/sisu_manual/sisu_remote/index.html - -.BR - /usr/share/doc/sisu/sisu_manual/sisu_search/index.html - -.BR - /usr/share/doc/sisu/sisu_manual/sisu_skin/index.html - .BR /usr/share/doc/sisu/sisu_manual/sisu_sqlite/index.html .BR - /usr/share/doc/sisu/sisu_manual/sisu_syntax_highlighting/index.html - -.BR - /usr/share/doc/sisu/sisu_manual/sisu_vim/index.html + /usr/share/doc/sisu/sisu_manual/sisu_termsheet/index.html .BR /usr/share/doc/sisu/sisu_manual/sisu_webrick/index.html @@ -4550,13 +4589,13 @@ pdf, and odf which may be also be accessed via the html pages[^34] .SH -34.2.4 MAN2HTML +34.3 MAN2HTML .SH -34.2.5 LOCALLY INSTALLED +34.3.1 LOCALLY INSTALLED .BR - + .BR @@ -4567,62 +4606,20 @@ pdf, and odf which may be also be accessed via the html pages[^34] .BR /usr/share/doc/sisu/html/sisu.1.html -.BR - /usr/share/doc/sisu/html/sisu_commands.1.html - -.BR - /usr/share/doc/sisu/html/sisu_complete.7.html - -.BR - /usr/share/doc/sisu/html/sisu_configuration.1.html - -.BR - /usr/share/doc/sisu/html/sisu_faq.8.html - -.BR - /usr/share/doc/sisu/html/sisu_help.1.html - -.BR - /usr/share/doc/sisu/html/sisu_help_sources.1.html - -.BR - /usr/share/doc/sisu/html/sisu_howto.8.html - -.BR - /usr/share/doc/sisu/html/sisu_markup.1.html - .BR /usr/share/doc/sisu/html/sisu_pdf.7.html .BR /usr/share/doc/sisu/html/sisu_postgresql.7.html -.BR - /usr/share/doc/sisu/html/sisu_quickstart.8.html - -.BR - /usr/share/doc/sisu/html/sisu_remote.8.html - -.BR - /usr/share/doc/sisu/html/sisu_search.8.html - -.BR - /usr/share/doc/sisu/html/sisu_skin.1.html - .BR /usr/share/doc/sisu/html/sisu_sqlite.7.html -.BR - /usr/share/doc/sisu/html/sisu_syntax_highlighting.8.html - -.BR - /usr/share/doc/sisu/html/sisu_vim.7.html - .BR /usr/share/doc/sisu/html/sisu_webrick.1.html .SH -34.2.6 WWW.SISUDOC.ORG +34.3.2 WWW.SISUDOC.ORG .BR @@ -4636,65 +4633,26 @@ pdf, and odf which may be also be accessed via the html pages[^34] .BR -.BR - - .BR -.BR - - -.BR - - -.BR - - -.BR - - -.BR - - -.BR - - .BR .BR -.BR - - -.BR - - -.BR - - -.BR - - .BR -.BR - - -.BR - - .BR .SH -34.2.7 WWW.JUS.UIO.NO/SISU +34.3.3 WWW.JUS.UIO.NO/SISU .BR - + .BR @@ -4705,57 +4663,18 @@ pdf, and odf which may be also be accessed via the html pages[^34] .BR -.BR - - .BR -.BR - - -.BR - - -.BR - - -.BR - - -.BR - - -.BR - - .BR .BR -.BR - - -.BR - - -.BR - - -.BR - - .BR -.BR - - -.BR - - .BR @@ -4768,8 +4687,7 @@ METADATA .BR .BR -Document Manifest @ - +Document Manifest @ .BR .B Dublin Core @@ -4809,11 +4727,11 @@ DC Date available: .BR DC Date modified: -.I 2007\-08\-30 +.I 2007\-09\-29 .BR DC Date: -.I 2007\-08\-30 +.I 2007\-09\-29 .BR .B Version Information @@ -4828,11 +4746,11 @@ Filetype: .BR Sourcefile Digest, MD5(sisu._sst)= -.I 104416276094558eeb6bd0320281ae0d +.I 5f973d9b8e96b9f3fabc280e9d0a18e0 .BR Skin_Digest: -MD5(/home/ralph/grotto/theatre/dbld/builds/sisu/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= .I 20fc43cf3eb6590bc3399a1aef65c5a9 .BR @@ -4840,7 +4758,7 @@ MD5(/home/ralph/grotto/theatre/dbld/builds/sisu/sisu/data/doc/sisu/sisu_markup_s .BR Document (metaverse) last generated: -.I Tue Sep 25 02:54:41 +0100 2007 +.I Sat Sep 29 15:46:29 +0100 2007 .BR Generated by: @@ -4854,63 +4772,30 @@ Ruby version: .TP .BI 1. -\" \.B SiSU -information Structuring Universe\" or \"Structured information, Serialized -Units\". - also chosen for the meaning of the Finnish term "sisu". -.TP -.BI 2. -Unix command line oriented -.TP -.BI 3. objects include: headings, paragraphs, verse, tables, images, but not footnotes/endnotes which are numbered separately and tied to the object from which they are referenced. .TP -.BI 4. +.BI 2. i.e. the html, pdf, odf outputs are each built individually and optimised for that form of presentation, rather than for example the html being a saved version of the odf, or the pdf being a saved version of the html. .TP -.BI 5. +.BI 3. the different heading levels .TP -.BI 6. +.BI 4. units of text, primarily paragraphs and headings, also any tables, poems, code-blocks .TP -.BI 7. +.BI 5. Specification submitted by Adobe to ISO to become a full open ISO specification .TP -.BI 8. +.BI 6. ISO/IEC 26300:2006 .TP -.BI 9. -generated from source using rman - - With regard to -.B SiSU -man pages the formatting generated for markup syntax is not quite right, for -that you might prefer the links under: - -.TP -.BI 10. - -.TP -.BI 11. - -.TP -.BI 12. - -.TP -.BI 13. - -.TP -.BI 14. - -.TP .BI *1. square brackets .TP @@ -4920,17 +4805,23 @@ square brackets .BI +1. square brackets .TP -.BI 15. +.BI 7. + +.TP +.BI 8. + +.TP +.BI 9. From sometime after SiSU 0.58 it should be possible to describe SiSU markup using SiSU, which though not an original design goal is useful. .TP -.BI 16. +.BI 10. files should be prepared using UTF-8 character encoding .TP -.BI 17. +.BI 11. a footnote or endnote .TP -.BI 18. +.BI 12. self contained endnote marker & endnote in one .TP .BI *. @@ -4945,47 +4836,47 @@ editors notes, numbered asterisk footnote/endnote series .BI +2. editors notes, numbered asterisk footnote/endnote series .TP -.BI 19. +.BI 13. .TP -.BI 20. +.BI 14. .TP -.BI 21. +.BI 15. Table from the Wealth of Networks by Yochai Benkler .TP -.BI 22. +.BI 16. \.ssc (for composite) is under consideration but \._sst makes clear that this is not a regular file to be worked on, and thus less likely that people will have \"accidents\", working on a \.ssc file that is overwritten by subsequent processing. It may be however that when the resulting file is shared \.ssc is an appropriate suffix to use. .TP -.BI 23. +.BI 17. \.B SiSU has worked this way in the past, though this was dropped as it was thought the complexity outweighed the flexibility, however, the balance was rather fine and this behaviour could be reinstated. .TP -.BI 24. +.BI 18. .TP -.BI 25. +.BI 19. .TP -.BI 26. +.BI 20. .TP -.BI 27. +.BI 21. (which could be extended further with current back-end). As regards scaling of the database, it is as scalable as the database (here Postgresql) and hardware allow. .TP -.BI 28. +.BI 22. of this feature when demonstrated to an IBM software innovations evaluator in 2004 he said to paraphrase: this could be of interest to us. We have large document management systems, you can search hundreds of thousands of documents @@ -4993,25 +4884,25 @@ and we can tell you which documents meet your search criteria, but there is no way we can tell you without opening each document where within each your matches are found. .TP -.BI 29. +.BI 23. There is nothing to stop MySQL support being added in future. .TP -.BI 30. +.BI 24. .TP -.BI 31. +.BI 25. .TP -.BI 32. +.BI 26. .TP -.BI 33. +.BI 27. the \.B Debian Free Software guidelines require that everything distributed within \.B Debian can be changed - and the documents are authors\' works that while freely distributable are not freely changeable. .TP -.BI 34. +.BI 28. named index.html or more extensively through sisu_manifest.html .TP @@ -5034,6 +4925,6 @@ at: .TP * Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] .TP -* Last Generated on: Tue Sep 25 02:54:48 +0100 2007 +* Last Generated on: Sat Sep 29 15:46:29 +0100 2007 .TP * SiSU http://www.jus.uio.no/sisu diff --git a/man/man1/sisu_webrick.1 b/man/man1/sisu_webrick.1 index 6d8cc219..a1677f1c 100644 --- a/man/man1/sisu_webrick.1 +++ b/man/man1/sisu_webrick.1 @@ -1,4 +1,8 @@ .TH "sisu_webrick" "1" "2007-09-16" "0.59.1" "SiSU" +.SH NAME +sisu \- documents: structuring, publishing in multiple formats, and search +.SH SYNOPSIS +sisu \-W .SH SISU \- SISU_WEBRICK, RALPH AMISSAH @@ -110,7 +114,7 @@ METADATA .BR Document Manifest @ - + .BR .B Dublin Core @@ -169,7 +173,7 @@ Filetype: .BR Sourcefile Digest, MD5(sisu_webrick.sst)= -.I 3d9a36a867ddc771d75083c5a7eea2bc +.I 11fb0494766a9b6d3ce091bf41241973 .BR Skin_Digest: MD5(/etc/sisu/skin/doc/skin_sisu.rb)= @@ -180,7 +184,7 @@ Skin_Digest: MD5(/etc/sisu/skin/doc/skin_sisu.rb)= .BR Document (metaverse) last generated: -.I Tue Sep 25 02:54:44 +0100 2007 +.I Sat Sep 29 15:49:36 +0100 2007 .BR Generated by: @@ -213,6 +217,6 @@ at: .TP * Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] .TP -* Last Generated on: Tue Sep 25 02:54:51 +0100 2007 +* Last Generated on: Sat Sep 29 15:49:36 +0100 2007 .TP * SiSU http://www.jus.uio.no/sisu diff --git a/man/man7/sisu_vim.7 b/man/man7/sisu_vim.7 index 5a7c9c3f..553e8fd6 100644 --- a/man/man7/sisu_vim.7 +++ b/man/man7/sisu_vim.7 @@ -1,4 +1,6 @@ .TH "sisu_vim" "1" "2007-09-16" "0.59.1" "SiSU" +.SH NAME +man page "name/whatis" information not provided, set in header @man: name=[whatis information] .SH SISU \- VIM, RALPH AMISSAH @@ -87,7 +89,7 @@ METADATA .BR Document Manifest @ - + .BR .B Dublin Core @@ -150,7 +152,7 @@ Sourcefile Digest, MD5(sisu_vim.sst)= .BR Skin_Digest: -MD5(/home/ralph/grotto/theatre/dbld/builds/sisu/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= .I 20fc43cf3eb6590bc3399a1aef65c5a9 .BR @@ -158,7 +160,7 @@ MD5(/home/ralph/grotto/theatre/dbld/builds/sisu/sisu/data/doc/sisu/sisu_markup_s .BR Document (metaverse) last generated: -.I Tue Sep 25 02:54:48 +0100 2007 +.I Sat Sep 29 13:20:58 +0100 2007 .BR Generated by: @@ -191,6 +193,6 @@ at: .TP * Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] .TP -* Last Generated on: Tue Sep 25 02:54:52 +0100 2007 +* Last Generated on: Sat Sep 29 13:21:02 +0100 2007 .TP * SiSU http://www.jus.uio.no/sisu -- cgit v1.2.3