sisu-0.68.0 proposed

* middle layer document representation changed, (accounting for substantial patch)
* texpdf multiple document sizes as specified in config
* numerous small fixes
[should on the whole be easier to maintain]

1 files changed, 637 insertions, 443 deletions

diff --git a/man/man1/sisu.1 b/man/man1/sisu.1
index 59acec9f..fe745b87 100644
--- a/man/man1/sisu.1
+++ b/man/man1/sisu.1
@@ -1,4 +1,4 @@
-.TH "sisu" "1" "2008-05-22" "0.67.0" "SiSU"
+.TH "sisu" "1" "2008-07-21" "0.68.0" "SiSU"
 .SH NAME
 sisu \- documents: markup, structuring, publishing in multiple standard formats, and search
 .SH SYNOPSIS
@@ -179,14 +179,14 @@ content prepared in
 \- Structured information, Serialized Units \- a document publishing system
 
 .BR
-sisu \ [ \ \-abcDdFHhIiMmNnopqRrSsTtUuVvwXxYyZz0\-9 \ ] \ [ \ filename/ \
-wildcard \ ]
+sisu [ \ \-abcDdFHhIiMmNnopqRrSsTtUuVvwXxYyZz0\-9 \ ] [ \ filename/ \ wildcard
+\ ]
 
 .BR
-sisu \ [ \ \-Ddcv \ ] \ [ \ instruction \ ]
+sisu [ \ \-Ddcv \ ] [ \ instruction \ ]
 
 .BR
-sisu \ [ \ \-CcFLSVvW \ ]
+sisu [ \ \-CcFLSVvW \ ]
 
 .BR
 Note: commands should be issued from within the directory that contains the
@@ -208,20 +208,20 @@ structure information. For more see: <http://www.jus.uio.no/sisu>
 2.3 DOCUMENT PROCESSING COMMAND FLAGS
 
 .TP
-.B \ \-a \ \ [filename/wildcard]
+.B \-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 \ [ \
-\-A \ for \ equivalent \ dos \ (linefeed) \ output \ file] \ [see \ \-e \ for \
+are omitted), has footnotes at end of each paragraph that contains them [ \ \-A
+\ for \ equivalent \ dos \ (linefeed) \ 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)
 
 .TP
-.B \ \-b \ \ [filename/wildcard]
+.B \-b [filename/wildcard]
 produces xhtml/XML output for browser viewing (sax parsing).
 
 .TP
-.B \ \-C \ \ [\-\-init\-site]
+.B \-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
@@ -230,40 +230,37 @@ update, existing shared output config files such as css and dtd files are
 updated if this modifier is used.
 
 .TP
-.B \ \-CC
-\ 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). \ 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. \
+.B \-CC
+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). 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.
 
 .TP
-.B \ \-c \ \ [filename/wildcard]
+.B \-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 output will be without colour).
 
 .TP
-.B \ \-D \ \ [instruction] \ [filename]
+.B \-D [instruction] [filename]
 database postgresql ( \-\-pgsql may be used instead) possible instructions,
-include: \-\-createdb; \-\-create; \-\-dropall; \-\-import \ [filename];
-\-\-update \ [filename]; \-\-remove \ [filename]; see database section below.
+include: \-\-createdb; \-\-create; \-\-dropall; \-\-import [filename];
+\-\-update [filename]; \-\-remove [filename]; see database section below.
 
 .TP
-.B \ \-d \ \ [\-\-db\-[database \ type \ (sqlite|pg)]] \-\-[instruction] \
-[filename]
+.B \-d [\-\-db\-[database \ type \ (sqlite|pg)]] \-\-[instruction] [filename]
 database type default set to sqlite, (for which \-\-sqlite may be used
 instead) or to specify another database \-\-db\-[pgsql, \ sqlite] (however see
 \-D) possible instructions include: \-\-createdb; \-\-create; \-\-dropall;
-\-\-import \ [filename]; \-\-update \ [filename]; \-\-remove \ [filename]; see
+\-\-import [filename]; \-\-update [filename]; \-\-remove [filename]; see
 database section below.
 
 .TP
-.B \ \-F \ \ [\-\-webserv=webrick]
+.B \-F [\-\-webserv=webrick]
 generate examples of (naive) cgi search form for sqlite and pgsql depends on
 your already having used sisu to populate an sqlite and/or pgsql database, (the
 sqlite version scans the output directories for existing sisu_sqlite databases,
@@ -277,71 +274,71 @@ that they be copied to the cgi\-bin directory). \-Fv (in addition to the above)
 provides some information on setting up hyperestraier for sisu
 
 .TP
-.B \ \-H \ \ [filename/wildcard]
+.B \-H [filename/wildcard]
 produces html without link suffixes (.html \.pdf etc.) (\"Hide\"). Requires
-an appropriately configured web server. \ [behaviour \ switched \ after \ 0.35
-\ see \ \-h].
+an appropriately configured web server. [behaviour \ switched \ after \ 0.35 \
+see \ \-h].
 
 .TP
-.B \ \-h \ \ [filename/wildcard]
+.B \-h [filename/wildcard]
 produces html (with hardlinks i.e. with name suffixes in links/local urls).
 html, with internal document links that include the document suffix, i.e.
 whether it is \.html or \.pdf (required for browsing directly off a file
-system, and works with most web servers). \ [behaviour \ switched \ after \
-0.35 \ see \ \-H].
+system, and works with most web servers). [behaviour \ switched \ after \ 0.35
+\ see \ \-H].
 
 .TP
-.B \ \-I \ \ [filename/wildcard]
+.B \-I [filename/wildcard]
 produces texinfo and info file, (view with pinfo).
 
 .TP
-.B \ \-i \ \ [filename/wildcard]
+.B \-i [filename/wildcard]
 produces man page of file, not suitable for all outputs.
 
 .TP
-.B \ \-L
-\ prints \ license \ information. \
+.B \-L
+prints license information.
 
 .TP
-.B \ \-M \ \ [filename/wildcard/url]
+.B \-M [filename/wildcard/url]
 maintenance mode files created for processing preserved and their locations
 indicated. (also see \-V)
 
 .TP
-.B \ \-m \ \ [filename/wildcard/url]
+.B \-m [filename/wildcard/url]
 assumed for most other flags, creates new meta\-markup file, (the metaverse )
 that is used in all subsequent processing of other output. This step is assumed
 for most processing flags. To skip it see \-n
 
 .TP
-.B \ \-N \ \ [filename/wildcard/url]
+.B \-N [filename/wildcard/url]
 document digest or document content certificate ( DCC ) as md5 digest tree of
 the document: the digest for the document, and digests for each object
 contained within the document (together with information on software versions
 that produced it) (digest.txt). \-NV for verbose digest output to screen.
 
 .TP
-.B \ \-n \ \ [filename/wildcard/url]
+.B \-n [filename/wildcard/url]
 skip meta\-markup (building of \"metaverse\"), this skips the equivalent of
 \-m which is otherwise assumed by most processing flags.
 
 .TP
-.B \ \-o \ \ [filename/wildcard/url]
+.B \-o [filename/wildcard/url]
 output basic document in opendocument file format (opendocument.odt).
 
 .TP
-.B \ \-p \ \ [filename/wildcard]
+.B \-p [filename/wildcard]
 produces LaTeX pdf (portrait.pdf & landscape.pdf). Default paper size is set
 in config file, or document header, or provided with additional command line
 parameter, e.g. \-\-papersize\-a4 preset sizes include: \'A4\', U.S. \'letter\'
 and \'legal\' and book sizes \'A5\' and \'B5\' (system defaults to A4).
 
 .TP
-.B \ \-q \ \ [filename/wildcard]
+.B \-q [filename/wildcard]
 quiet less output to screen.
 
 .TP
-.B \ \-R \ \ [filename/wildcard]
+.B \-R [filename/wildcard]
 copies sisu output files to remote host using rsync. This requires that
 sisurc.yml has been provided with information on hostname and username, and
 that you have your \"keys\" and ssh agent in place. Note the behavior of rsync
@@ -350,22 +347,21 @@ different if \-R is used with other flags from if used alone. Alone the rsync
 \-R is used together with other flags, it is not). Also see \-r
 
 .TP
-.B \ \-r \ \ [filename/wildcard]
+.B \-r [filename/wildcard]
 copies sisu output files to remote host using scp. This requires that
 sisurc.yml has been provided with information on hostname and username, and
 that you have your \"keys\" and ssh agent in place. Also see \-R
 
 .TP
-.B \ \-S
-\ produces \ a \ sisupod \ a \ zipped \ sisu \ directory \ of \ markup \
-files \ including \ sisu \ markup \ source \ files \ and \ the \ directories \
-local \ configuration \ file, \ images \ and \ skins. \ Note: \ this \ only \
-includes \ the \ configuration \ files \ or \ skins \ contained \ in \ \./_sisu
-\ not \ those \ in \ ~/.sisu \ \-S \ \ [filename/wildcard] option. Note: (this
+.B \-S
+produces a sisupod a zipped sisu directory of markup files including sisu
+markup source files and the directories local configuration file, images and
+skins. Note: this only includes the configuration files or skins contained in
+ \./_sisu not those in ~/.sisu \-S [filename/wildcard] option. Note: (this
 option is tested only with zsh).
 
 .TP
-.B \ \-S \ \ [filename/wildcard]
+.B \-S [filename/wildcard]
 produces a zipped file of the prepared document specified along with
 associated images, by default named sisupod.zip they may alternatively be named
 with the filename extension \.ssp This provides a quick way of gathering the
@@ -382,19 +378,18 @@ that file that are not your own are treated as untrusted. The directory
 structure of the unzipped file is understood by sisu, and sisu commands can be
 run within it. Note: if you wish to send multiple files, it quickly becomes
 more space efficient to zip the sisu markup directory, rather than the
-individual files for sending). See the \-S option without \
-[filename/wildcard].
+individual files for sending). See the \-S option without [filename/wildcard].
 
 .TP
-.B \ \-s \ \ [filename/wildcard]
+.B \-s [filename/wildcard]
 copies sisu markup file to output directory.
 
 .TP
-.B \ \-t \ \ [filename/wildcard \ (*.termsheet.rb)]
+.B \-t [filename/wildcard \ (*.termsheet.rb)]
 standard form document builder, preprocessing feature
 
 .TP
-.B \ \-U \ \ [filename/wildcard]
+.B \-U [filename/wildcard]
 prints url output list/map for the available processing flags options and
 resulting files that could be requested, (can be used to get a list of
 processing options in relation to a file, together with information on the
@@ -404,77 +399,76 @@ provides webrick url mappings where appropriate, but these can be switched to
 file system paths in sisurc.yml
 
 .TP
-.B \ \-u \ \ [filename/wildcard]
+.B \-u [filename/wildcard]
 provides url mapping of output files for the flags requested for processing,
 also see \-U
 
 .TP
-.B \ \-V
-\ on \ its \ own, \ provides
-.B \ SiSU
-\ version \ and \ environment \ information \ (sisu \ \-\-help \ env) \
+.B \-V
+on its own, provides
+.B SiSU
+version and environment information (sisu \-\-help env)
 
 .TP
-.B \ \-V \ \ [filename/wildcard]
+.B \-V [filename/wildcard]
 even more verbose than the \-v flag. (also see \-M)
 
 .TP
-.B \ \-v
-\ on \ its \ own, \ provides
-.B \ SiSU
-\ version \ information \
+.B \-v
+on its own, provides
+.B SiSU
+version information
 
 .TP
-.B \ \-v \ \ [filename/wildcard]
+.B \-v [filename/wildcard]
 provides verbose output of what is being built, where it is being built (and
 error messages if any), as with \-u flag provides a url mapping of files
 created for each of the processing flag requests. See also \-V
 
 .TP
-.B \ \-W
-\ starts \ ruby\'s \ webrick \ webserver \ points \ at \ sisu \ output \
-directories, \ the \ default \ port \ is \ set \ to \ 8081 \ and \ can \ be \
-changed \ in \ the \ resource \ configuration \ files. \ \ [tip: \ the \
-webrick \ server \ requires \ link \ suffixes, \ so \ html \ output \ should \
-be \ created \ using \ the \ \-h \ option \ rather \ than \ \-H; \ also, \ note
-\ \-F \ webrick \ ].
+.B \-W
+starts ruby\'s webrick webserver points at sisu output directories, the
+default port is set to 8081 and can be changed in the resource configuration
+files. [tip: \ the \ webrick \ server \ requires \ link \ suffixes, \ so \ html
+\ output \ should \ be \ created \ using \ the \ \-h \ option \ rather \ than \
+\-H; \ also, \ note \ \-F \ webrick \ ].
 
 .TP
-.B \ \-w \ \ [filename/wildcard]
+.B \-w [filename/wildcard]
 produces concordance (wordmap) a rudimentary index of all the words in a
 document. (Concordance files are not generated for documents of over 260,000
 words unless this limit is increased in the file sisurc.yml)
 
 .TP
-.B \ \-X \ \ [filename/wildcard]
+.B \-X [filename/wildcard]
 produces XML output with deep document structure, in the nature of dom.
 
 .TP
-.B \ \-x \ \ [filename/wildcard]
+.B \-x [filename/wildcard]
 produces XML output shallow structure (sax parsing).
 
 .TP
-.B \ \-Y \ \ [filename/wildcard]
+.B \-Y [filename/wildcard]
 produces a short sitemap entry for the document, based on html output and the
 sisu_manifest. \-\-sitemaps generates/updates the sitemap index of existing
-sitemaps. (Experimental, \ [g,y,m \ announcement \ this \ week])
+sitemaps. (Experimental, [g,y,m \ announcement \ this \ week])
 
 .TP
-.B \ \-y \ \ [filename/wildcard]
+.B \-y [filename/wildcard]
 produces an html summary of output generated (hyperlinked to content) and
 document specific metadata (sisu_manifest.html). This step is assumed for most
 processing flags.
 
 .TP
-.B \ \-Z \ \ [filename/wildcard]
+.B \-Z [filename/wildcard]
 Zap, if used with other processing flags deletes output files of the type
 about to be processed, prior to processing. If \-Z is used as the lone
 processing related flag (or in conjunction with a combination of \-[mMvVq]),
 will remove the related document output directory.
 
 .TP
-.B \ \-z \ \ [filename/wildcard]
-produces php (zend) \ [this \ feature \ is \ disabled \ for \ the \ time \
+.B \-z [filename/wildcard]
+produces php (zend) [this \ feature \ is \ disabled \ for \ the \ time \
 being]
 
 .SH
@@ -482,25 +476,22 @@ being]
 .BR
 
 .TP
-.B \ \-\-no\-ocn
-\ \ [with \ \-h \ \-H \ or \ \-p] switches off object citation numbering.
-Produce output without identifying numbers in margins of html or LaTeX/pdf
-output.
+.B \-\-no\-ocn
+[with \ \-h \ \-H \ or \ \-p] switches off object citation numbering. Produce
+output without identifying numbers in margins of html or LaTeX/pdf output.
 
 .TP
-.B \ \-\-no\-annotate
-\ strips \ output \ text \ of \ editor \ endnotes[^*1] denoted by asterisk or
-dagger/plus sign
+.B \-\-no\-annotate
+strips output text of editor endnotes[^*1] denoted by asterisk or dagger/plus
+sign
 
 .TP
-.B \ \-\-no\-asterisk
-\ strips \ output \ text \ of \ editor \ endnotes[^*2] denoted by asterisk
-sign
+.B \-\-no\-asterisk
+strips output text of editor endnotes[^*2] denoted by asterisk sign
 
 .TP
-.B \ \-\-no\-dagger
-\ strips \ output \ text \ of \ editor \ endnotes[^+1] denoted by dagger/plus
-sign
+.B \-\-no\-dagger
+strips output text of editor endnotes[^+1] denoted by dagger/plus sign
 
 .SH
 4. DATABASE COMMANDS
@@ -514,36 +505,35 @@ dbi \- database interface
 \-d is modifiable with \-\-db=[database \ type \ (pgsql \ or \ sqlite)]
 
 .TP
-.B \ \-Dv \ \-\-createall
-\ initial \ step, \ creates \ required \ relations \ (tables, \ indexes) \ in
-\ existing \ postgresql \ database \ (a \ database \ should \ be \ created \
-manually \ and \ given \ the \ same \ name \ as \ working \ directory, \ as \
-requested) \ (rb.dbi) \ \ [ \ \-dv \ \-\-createall \ sqlite \ equivalent] it
-may be necessary to run sisu \-Dv \-\-createdb initially NOTE: at the present
-time for postgresql it may be necessary to manually create the database. The
-command would be \'createdb \ [database \ name]\' where database name would be
-SiSU_[present \ working \ directory \ name \ (without \ path)]. Please use only
-alphanumerics and underscores.
+.B \-Dv \-\-createall
+initial step, creates required relations (tables, indexes) in existing
+postgresql database (a database should be created manually and given the same
+name as working directory, as requested) (rb.dbi) [ \ \-dv \ \-\-createall \
+sqlite \ equivalent] it may be necessary to run sisu \-Dv \-\-createdb
+initially NOTE: at the present time for postgresql it may be necessary to
+manually create the database. The command would be \'createdb [database \
+name]\' where database name would be SiSU_[present \ working \ directory \ name
+\ (without \ path)]. Please use only alphanumerics and underscores.
 
 .TP
-.B \ \-Dv \ \-\-import
-\ \ [filename/wildcard] imports data specified to postgresql db (rb.dbi) \ [
-\ \-dv \ \-\-import \ sqlite \ equivalent]
+.B \-Dv \-\-import
+[filename/wildcard] imports data specified to postgresql db (rb.dbi) [ \ \-dv
+\ \-\-import \ sqlite \ equivalent]
 
 .TP
-.B \ \-Dv \ \-\-update
-\ \ [filename/wildcard] updates/imports specified data to postgresql db
-(rb.dbi) \ [ \ \-dv \ \-\-update \ sqlite \ equivalent]
+.B \-Dv \-\-update
+[filename/wildcard] updates/imports specified data to postgresql db (rb.dbi)
+[ \ \-dv \ \-\-update \ sqlite \ equivalent]
 
 .TP
-.B \ \-D \ \-\-remove
-\ \ [filename/wildcard] removes specified data to postgresql db (rb.dbi) \ [
-\ \-d \ \-\-remove \ sqlite \ equivalent]
+.B \-D \-\-remove
+[filename/wildcard] removes specified data to postgresql db (rb.dbi) [ \ \-d
+\ \-\-remove \ sqlite \ equivalent]
 
 .TP
-.B \ \-D \ \-\-dropall
-\ kills \ data\" \ and \ drops \ (postgresql \ or \ sqlite) \ db, \ tables \
-& \ indexes \ \ [ \ \-d \ \-\-dropall \ sqlite \ equivalent]
+.B \-D \-\-dropall
+kills data\" and drops (postgresql or sqlite) db, tables & indexes [ \ \-d \
+\-\-dropall \ sqlite \ equivalent]
 
 .BR
 The v in e.g. \-Dv is for verbose output.
@@ -553,7 +543,7 @@ The v in e.g. \-Dv is for verbose output.
 .BR
 
 .TP
-.B \ \-\-update \ \ [filename/wildcard]
+.B \-\-update [filename/wildcard]
 Checks existing file output and runs the flags required to update this
 output. This means that if only html and pdf output was requested on previous
 runs, only the \-hp files will be applied, and only these will be generated
@@ -561,37 +551,37 @@ this time, together with the summary. This can be very convenient, if you offer
 different outputs of different files, and just want to do the same again.
 
 .TP
-.B \ \-0 \ to \ \-5 \ \ [filename \ or \ wildcard]
+.B \-0 to \-5 [filename \ or \ wildcard]
 Default shorthand mappings (note that the defaults can be changed/configured
 in the sisurc.yml file):
 
 .TP
-.B \ \-0
-\ \-mNhwpAobxXyYv \ \ [this \ is \ the \ default \ action \ run \ when \ no \
-options \ are \ give, \ i.e. \ on \ \'sisu \ \ [filename]\']
+.B \-0
+\-mNhwpAobxXyYv [this \ is \ the \ default \ action \ run \ when \ no \
+options \ are \ give, \ i.e. \ on \ \'sisu \ [filename]\']
 
 .TP
-.B \ \-1
-\ \-mNHwpy \
+.B \-1
+\-mNHwpy
 
 .TP
-.B \ \-2
-\ \-mNHwpaoy \
+.B \-2
+\-mNHwpaoy
 
 .TP
-.B \ \-3
-\ \-mNhwpAobxXyY \
+.B \-3
+\-mNhwpAobxXyY
 
 .TP
-.B \ \-4
-\ \-mNhwpAobxXDyY \ \-\-import \
+.B \-4
+\-mNhwpAobxXDyY \-\-import
 
 .TP
-.B \ \-5
-\ \-mNhwpAobxXDyY \ \-\-update \
+.B \-5
+\-mNhwpAobxXDyY \-\-update
 
 .BR
-add \-v for verbose mode and \-c for color, e.g. sisu \-2vc \ [filename \ or \
+add \-v for verbose mode and \-c for color, e.g. sisu \-2vc [filename \ or \
 wildcard]
 
 .BR
@@ -630,7 +620,7 @@ The manual can be generated from source, found respectively, either within the
 tarball or installed locally at:
 
 .BR
-  \./data/doc/sisu/sisu_markup_samples/sisu_manual/
+  ./data/doc/sisu/sisu_markup_samples/sisu_manual/
 
 .BR
   /usr/share/doc/sisu/sisu_markup_samples/sisu_manual/
@@ -667,7 +657,7 @@ the sisu manual, the sources files for which are located within the
 tarball at:
 
 .BR
-  \./data/doc/sisu/sisu_manual/
+  ./data/doc/sisu/sisu_manual/
 
 .BR
 Once installed, directory equivalent to:
@@ -682,16 +672,16 @@ Available man pages are converted back to html using man2html:
   /usr/share/doc/sisu/html/
 
 .BR
-  \./data/doc/sisu/html/
+  ./data/doc/sisu/html/
 
 .BR
 An online version of the sisu man page is available here:
 
 .BR
-* various sisu man pages <http://www.jus.uio.no/sisu/man/> \ [^7]
+* various sisu man pages <http://www.jus.uio.no/sisu/man/> [^7]
 
 .BR
-* sisu.1 <http://www.jus.uio.no/sisu/man/sisu.1.html> \ [^8]
+* sisu.1 <http://www.jus.uio.no/sisu/man/sisu.1.html> [^8]
 
 .SH
 6.3 SISU BUILT\-IN INTERACTIVE HELP
@@ -704,7 +694,7 @@ information:
   sisu \-\-help
 
 .BR
-  sisu \-\-help \ [subject]
+  sisu \-\-help [subject]
 
 .BR
     sisu \-\-help commands
@@ -713,11 +703,11 @@ information:
     sisu \-\-help markup
 
 .BR
-    sisu \-\-help env \ [for \ feedback \ on \ the \ way \ your \ system \ is \
+    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]
+  sisu \-V [environment \ information, \ same \ as \ above \ command]
 
 .BR
   sisu (on its own provides version and some help information)
@@ -814,7 +804,7 @@ markup or sisu \-\-help markup
 To check the markup in a file:
 
 .BR
-  sisu \-\-identify \ [filename].sst
+  sisu \-\-identify [filename].sst
 
 .BR
 For brief descriptive summary of markup history
@@ -945,12 +935,12 @@ This is a sample header
 
 .BR
 .B % SiSU 0.38
-\ [declared \ file\-type \ identifier \ with \ markup \ version]
+[declared \ file\-type \ identifier \ with \ markup \ version]
+
 
 .BR
 .B @title:
-\ [title \ text] This is the title of the document and used as such, this
-header is the only one that is
+ \ [title \ text] This is the title of the document and used as such, this header is the only one that is
 .I mandatory
 
 .BR
@@ -959,7 +949,7 @@ The Subtitle if any
 
 .BR
 .B @creator:
-\ [or \ @author:] Name of Author
+[or \ @author:] Name of Author
 
 .BR
 .B @subject:
@@ -988,8 +978,9 @@ The Subtitle if any
 
 .BR
 .B @date: 2000\-08\-27
-\ [ \ also \ @date.created: \ @date.issued: \ @date.available: \ @date.valid:
-\ @date.modified: \ ]
+[ \ also \ @date.created: \ @date.issued: \ @date.available: \ @date.valid: \
+@date.modified: \ ]
+
 
 .BR
 .B @type: article
@@ -1005,13 +996,13 @@ The Subtitle if any
 
 .BR
 .B @language:
-\ [or \ @language.document:] \ [country \ code \ for \ language \ if \
-available, \ or \ language, \ English, \ en \ is \ the \ default \ setting] (en
-\- English, fr \- French, de \- German, it \- Italian, es \- Spanish, pt \-
+[or \ @language.document:] [country \ code \ for \ language \ if \ available,
+\ or \ language, \ English, \ en \ is \ the \ default \ setting] (en \-
+English, fr \- French, de \- German, it \- Italian, es \- Spanish, pt \-
 Portuguese, sv \- Swedish, da \- Danish, fi \- Finnish, no \- Norwegian, is \-
 Icelandic, nl \- Dutch, et \- Estonian, hu \- Hungarian, pl \- Polish, ro \-
 Romanian, ru \- Russian, el \- Greek, uk \- Ukranian, tr \- Turkish, sk \-
-Slovak, sl \- Slovenian, hr \- Croatian, cs \- Czech, bg \- Bul garian ) \
+Slovak, sl \- Slovenian, hr \- Croatian, cs \- Czech, bg \- Bul garian )
 [however, \ encodings \ are \ not \ available \ for \ all \ of \ the \
 languages \ listed.]
 
@@ -1040,16 +1031,16 @@ public domain, copyleft, creative commons variant, etc.
 .BR
 .B @keywords:
 text document generation processing management latex pdf structured xml
-citation \ [your \ keywords \ here, \ used \ for \ example \ by \ rss \ feeds,
-\ and \ in \ sql \ searches]
+citation [your \ keywords \ here, \ used \ for \ example \ by \ rss \ feeds, \
+and \ in \ sql \ searches]
 
 .BR
 .B @abstract:
-\ [paper \ abstract, \ placed \ after \ table \ of \ contents]
+[paper \ abstract, \ placed \ after \ table \ of \ contents]
 
 .BR
 .B @comment:
-\ [...]
+[...]
 
 .BR
 .B @catalogue:
@@ -1058,27 +1049,27 @@ classification]; isbn=[ISBN]; pg=[Project \ Gutenberg \ text \ number]
 
 .BR
 .B @classify_loc:
-\ [Library \ of \ Congress \ classification]
+[Library \ of \ Congress \ classification]
 
 .BR
 .B @classify_dewey:
-\ [Dewey \ classification]
+[Dewey \ classification]
 
 .BR
 .B @classify_isbn:
-\ [ISBN]
+[ISBN]
 
 .BR
 .B @classify_pg:
-\ [Project \ Gutenberg \ text \ number]
+[Project \ Gutenberg \ text \ number]
 
 .BR
 .B @prefix:
-\ [prefix \ is \ placed \ just \ after \ table \ of \ contents]
+[prefix \ is \ placed \ just \ after \ table \ of \ contents]
 
 .BR
 .B @prefix_a:
-\ [prefix \ is \ placed \ just \ before \ table \ of \ contents \ \- \ not \
+[prefix \ is \ placed \ just \ before \ table \ of \ contents \ \- \ not \
 implemented]
 
 .BR
@@ -1086,8 +1077,8 @@ implemented]
 
 .BR
 .B @rcs:
-$Id: sisu_markup.sst,v 1.2 2007/09/08 17:12:47 ralph Exp $ \ [used \ by \ rcs
-\ or \ cvs \ to \ embed \ version \ (revision \ control) \ information \ into \
+$Id: sisu_markup.sst,v 1.2 2007/09/08 17:12:47 ralph Exp $ [used \ by \ rcs \
+or \ cvs \ to \ embed \ version \ (revision \ control) \ information \ into \
 document, \ rcs \ or \ cvs \ can \ usefully \ provide \ a \ history \ of \
 updates \ to \ a \ document \ ]
 
@@ -1104,35 +1095,35 @@ for @toc:)
 .BR
 .B @level:
 newpage=3; breakpage=4
-\ [paragraph \ level, \ used \ by \ latex \ to \ breakpages, \ the \ page \
-is \ optional \ eg. \ in \ newpage]
+[paragraph \ level, \ used \ by \ latex \ to \ breakpages, \ the \ page \ is
+\ optional \ eg. \ in \ newpage]
 
 .BR
 .B @markup:
-information on the markup used, e.g. new=1,2,3; break=4; num_top=4 \ [or \
+information on the markup used, e.g. new=1,2,3; break=4; num_top=4 [or \
 newpage=1,2,3; \ breakpage=4; \ num_top=4] newpage and breakpage, heading
 level, used by LaTeX to breakpages. breakpage: starts on a new page in single
 column text and on a new column in double column text; newpage: starts on a new
 page for both single and double column texts.
-num_top=4 \ [auto\-number \ document, \ starting \ at \ level \ 4. \ the \
+num_top=4 [auto\-number \ document, \ starting \ at \ level \ 4. \ the \
 default \ is \ to \ provide \ 3 \ levels, \ as \ in \ 1 \ level \ 4, \ 1.1 \
 level \ 5, \ 1.1.1 \ level \ 6, \ markup \ to \ be \ merged \ within \ level]
-num_extract \ [take \ numbering \ of \ headings \ provided \ (manually \ in \
+num_extract [take \ numbering \ of \ headings \ provided \ (manually \ in \
 marked \ up \ source \ document), \ and \ use \ for \ numbering \ of \
 segments. \ Available \ where \ a \ clear \ numbering \ structure \ is \
 provided \ within \ document, \ without \ the \ repetition \ of \ a \ number \
-in \ a \ header.] \ [In \ 0.38 \ notation, \ you \ would \ map \ to \ the \
+in \ a \ header.] [In \ 0.38 \ notation, \ you \ would \ map \ to \ the \
 equivalent \ levels, \ the \ examples \ provided \ would \ map \ to \ the \
-following \ new=A,B,C; \ break=1; \ num_top=1 \ \ [or \ newpage=A,B,C; \
+following \ new=A,B,C; \ break=1; \ num_top=1 \ [or \ newpage=A,B,C; \
 breakpage=1; \ num_top=1] see headings]
 
 .BR
 .B @bold:
-\ [regular \ expression \ of \ words/phrases \ to \ be \ made \ bold]
+[regular \ expression \ of \ words/phrases \ to \ be \ made \ bold]
 
 .BR
 .B @italics:
-\ [regular \ expression \ of \ words/phrases \ to \ italicise]
+[regular \ expression \ of \ words/phrases \ to \ italicise]
 
 .BR
 .B @vocabulary:
@@ -1146,12 +1137,13 @@ 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]
+.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
 
@@ -1165,7 +1157,7 @@ man page headings
 .BR
 .B @promo:
 sisu, ruby, search_libre_docs, open_society
-\ [places \ content \ in \ right \ pane \ in \ html, \ makes \ use \ of \
+[places \ content \ in \ right \ pane \ in \ html, \ makes \ use \ of \
 list.yml \ and \ promo.yml, \ commented \ out \ sample \ in \ document \
 sample: \
 free_as_in_freedom.richard_stallman_crusade_for_free_software.sam_williams.sst]
@@ -1185,21 +1177,21 @@ level 1 heading (used where a stand\-alone document may be imported into
 another)
 
 .BR
-.B :A~ \ [heading \ text]
-Top level heading \ [this \ usually \ has \ similar \ content \ to \ the \
+.B :A~ [heading \ text]
+Top level heading [this \ usually \ has \ similar \ content \ to \ the \
 title \ @title: \ ] NOTE: the heading levels described here are in 0.38
 notation, see heading
 
 .BR
-.B :B~ \ [heading \ text]
-Second level heading \ [this \ is \ a \ heading \ level \ divider]
+.B :B~ [heading \ text]
+Second level heading [this \ is \ a \ heading \ level \ divider]
 
 .BR
-.B :C~ \ [heading \ text]
-Third level heading \ [this \ is \ a \ heading \ level \ divider]
+.B :C~ [heading \ text]
+Third level heading [this \ is \ a \ heading \ level \ divider]
 
 .BR
-.B 1~ \ [heading \ text]
+.B 1~ [heading \ text]
 Top level heading preceding substantive text of document or sub\-heading 2,
 the heading level that would normally be marked 1. or 2. or 3. etc. in a
 document, and the level on which sisu by default would break html output into
@@ -1207,19 +1199,20 @@ named segments, names are provided automatically if none are given (a number),
 otherwise takes the form 1~my_filename_for_this_segment
 
 .BR
-.B 2~ \ [heading \ text]
+.B 2~ [heading \ text]
 Second level heading preceding substantive text of document or sub\-heading
 3, the heading level that would normally be marked 1.1 or 1.2 or 1.3 or 2.1
 etc. in a document.
 
 .BR
-.B 3~ \ [heading \ text]
+.B 3~ [heading \ text]
 Third level heading preceding substantive text of document, that would
 normally be marked 1.1.1 or 1.1.2 or 1.2.1 or 2.1.1 etc. in a document
 
 
 .nf
   1~filename level 1 heading,
+.BR
   % the primary division such as Chapter that is followed by substantive text, and may be further subdivided (this is the level on which by default html segments are made)
 .fi
 
@@ -1232,15 +1225,25 @@ normally be marked 1.1.1 or 1.1.2 or 1.2.1 or 2.1.1 etc. in a document
 
 .nf
   normal text !{emphasis}! *{bold text}* _{underscore}_ /{italics}/ \"{citation}\" ^{superscript}^ ,{subscript}, +{inserted text}+
+.BR
   normal text
+.BR
   !{emphasis}!
+.BR
   *{bold text}*
+.BR
   _{underscore}_
+.BR
   /{italics}/
+.BR
   \"{citation}\"
+.BR
   ^{superscript}^
+.BR
   ,{subscript},
+.BR
   +{inserted text}+
+.BR
   \-{strikethrough}\-
 .fi
 
@@ -1248,7 +1251,8 @@ normally be marked 1.1.1 or 1.1.2 or 1.2.1 or 2.1.1 etc. in a document
 .B resulting output:
 
 .BR
-normal text <em>emphasis</em>
+normal text
+.B emphasis
 .B bold text
 .I underscore
 .I italics
@@ -1258,8 +1262,6 @@ normal text <em>emphasis</em>
 .BR
 normal text
 
-.BR
-<em>emphasis</em>
 
 .BR
 .B bold text
@@ -1294,12 +1296,15 @@ normal text
 
 .nf
   ordinary paragraph
+.BR
   _1 indent paragraph one step
+.BR
   _2 indent paragraph two steps
+.BR
   _9 indent paragraph nine steps
 .fi
 
-.BR
+
 .B resulting output:
 
 .BR
@@ -1319,8 +1324,10 @@ ordinary paragraph
 
 
 .nf
-  * bullet text
+  _* bullet text
+.BR
   _1* bullet text, first indent
+.BR
   _2* bullet text, two step indent
 .fi
 
@@ -1345,6 +1352,7 @@ Numbered List (not to be confused with headings/titles, (document structure))
 
 .nf
   # numbered list                numbered list 1., 2., 3, etc.
+.BR
   _# numbered list numbered list indented a., b., c., d., etc.
 .fi
 
@@ -1390,6 +1398,7 @@ normal text[^12] continues
 
 .nf
   normal text ~{* unnumbered asterisk footnote/endnote, insert multiple asterisks if required }~ continues
+.BR
   normal text ~{** another unnumbered asterisk footnote/endnote }~ continues
 .fi
 
@@ -1397,10 +1406,11 @@ normal text[^12] continues
 .B resulting output:
 
 .BR
-normal text \ [^*] continues
+normal text [^*] continues
 
 .BR
-normal text \ [^**] continues
+normal text [^**] continues
+
 
 .BR
 .B markup example:
@@ -1408,6 +1418,7 @@ normal text \ [^**] continues
 
 .nf
   normal text ~[* \ editors \ notes, \ numbered \ asterisk \ footnote/endnote \ series \ ]~ continues
+.BR
   normal text ~[+ \ editors \ notes, \ numbered \ asterisk \ footnote/endnote \ series \ ]~ continues
 .fi
 
@@ -1415,19 +1426,21 @@ normal text \ [^**] continues
 .B resulting output:
 
 .BR
-normal text \ [^*3] continues
+normal text [^*3] continues
 
 .BR
-normal text \ [^+2] continues
+normal text [^+2] continues
+
 
 .BR
 .B Alternative endnote pair notation for footnotes/endnotes:
 
 
 .nf
-.nf
   % note the endnote marker \"~^\"
+.BR
   normal text~^ continues
+.BR
   ^~ endnote text following the paragraph in which the marker occurs
 .fi
 
@@ -1470,6 +1483,7 @@ An escaped url without decoration
 
 .nf
   normal text http://www.jus.uio.no/sisu continues
+.BR
   deb http://www.jus.uio.no/sisu/archive unstable main non\-free
 .fi
 
@@ -1492,6 +1506,7 @@ blocks are discussed later in this document
 
 .nf
   deb http://www.jus.uio.no/sisu/archive unstable main non\-free
+.BR
   deb\-src http://www.jus.uio.no/sisu/archive unstable main non\-free
 .fi
 
@@ -1531,7 +1546,7 @@ automatically as a footnote
 .B resulting output:
 
 .BR
-about SiSU <http://www.jus.uio.no/sisu/> \ [^13] markup
+about SiSU <http://www.jus.uio.no/sisu/> [^13] markup
 
 .SH
 9.5.3 LINKING IMAGES
@@ -1541,11 +1556,19 @@ about SiSU <http://www.jus.uio.no/sisu/> \ [^13] markup
 
 
 .nf
-     [ tux.png ]
+     \ [ tux.png ]
+.BR
   % various url linked images
-     [ tux.png ]
-     [ GnuDebianLinuxRubyBetterWay.png ]
+.BR
+     \ [ tux.png ]
+.BR
+.BR
+     \ [ GnuDebianLinuxRubyBetterWay.png ]
+.BR
+.BR
   {~^ ruby_logo.png \"Ruby\" }http://www.ruby\-lang.org/en/
+.BR
+.BR
 .fi
 
 .BR
@@ -1570,7 +1593,10 @@ and Ruby\" <http://www.jus.uio.no/sisu/>
 
 .nf
   {~^ \ [text \ to \ link] }http://url.org
+.BR
+.BR
   % maps to: { \ [text \ to \ link] }http://url.org ~{ http://url.org }~
+.BR
   % which produces hyper\-linked text within a document/paragraph, with an endnote providing the url for the text location used in the hyperlink
 .fi
 
@@ -1599,12 +1625,19 @@ Tables may be prepared in two either of two forms
 
 .nf
   table{ c3; 40; 30; 30;
+.BR
   This is a table
+.BR
   this would become column two of row one
+.BR
   column three of row one is here
+.BR
   And here begins another row
+.BR
   column two of row two
+.BR
   column three of row two, and so on
+.BR
   }table
 .fi
 
@@ -1624,13 +1657,21 @@ information in each column
 
 .nf
   !_ Table 3.1: Contributors to Wikipedia, January 2001 \- June 2005
+.BR
   {table~h 24; 12; 12; 12; 12; 12; 12;}
+.BR
                                   |Jan. 2001|Jan. 2002|Jan. 2003|Jan. 2004|July 2004|June 2006
+.BR
   Contributors*                   |       10|      472|    2,188|    9,653|   25,011|   48,721
+.BR
   Active contributors**           |        9|      212|      846|    3,228|    8,442|   16,945
+.BR
   Very active contributors***     |        0|       31|      190|      692|    1,639|    3,016
+.BR
   No. of English language articles|       25|   16,000|  101,000|  190,000|  320,000|  630,000
+.BR
   No. of articles, all languages  |       25|   19,000|  138,000|  490,000|  862,000|1,600,000
+.BR
   \\* Contributed at least ten times; \\** at least 5 times in last month; \\*\** more than 100 times in last month.
 .fi
 
@@ -1655,8 +1696,11 @@ than 100 times in last month.
 
 .nf
   poem{
+.BR
     Your poem here
+.BR
   }poem
+.BR
   Each verse in a poem is given a separate object number.
 .fi
 
@@ -1666,50 +1710,95 @@ than 100 times in last month.
 
 .nf
   poem{
+.BR
                       \'Fury said to a
+.BR
                      mouse, That he
+.BR
                    met in the
+.BR
                  house,
+.BR
               \"Let us
+.BR
                 both go to
+.BR
                   law:  I will
+.BR
                     prosecute
+.BR
                       YOU.  \-\-Come,
+.BR
                          I\'ll take no
+.BR
                           denial; We
+.BR
                        must have a
+.BR
                    trial:  For
+.BR
                 really this
+.BR
              morning I\'ve
+.BR
             nothing
+.BR
            to do.\"
+.BR
              Said the
+.BR
                mouse to the
+.BR
                  cur, \"Such
+.BR
                    a trial,
+.BR
                      dear Sir,
+.BR
                            With
+.BR
                        no jury
+.BR
                     or judge,
+.BR
                   would be
+.BR
                 wasting
+.BR
                our
+.BR
                 breath.\"
+.BR
                  \"I\'ll be
+.BR
                    judge, I\'ll
+.BR
                      be jury,\"
+.BR
                            Said
+.BR
                       cunning
+.BR
                         old Fury:
+.BR
                        \"I\'ll
+.BR
                         try the
+.BR
                            whole
+.BR
                             cause,
+.BR
                                and
+.BR
                           condemn
+.BR
                          you
+.BR
                         to
+.BR
                          death.\"\'
+.BR
   }poem
 .fi
 
@@ -1718,93 +1807,93 @@ than 100 times in last month.
 
 
                     \'Fury said to a
-.P
+.BR
                    mouse, That he
-.P
+.BR
                  met in the
-.P
+.BR
                house,
-.P
+.BR
             \"Let us
-.P
+.BR
               both go to
-.P
+.BR
                 law:  I will
-.P
+.BR
                   prosecute
-.P
+.BR
                     YOU.  \-\-Come,
-.P
+.BR
                        I\'ll take no
-.P
+.BR
                         denial; We
-.P
+.BR
                      must have a
-.P
+.BR
                  trial:  For
-.P
+.BR
               really this
-.P
+.BR
            morning I\'ve
-.P
+.BR
           nothing
-.P
+.BR
          to do.\"
-.P
+.BR
            Said the
-.P
+.BR
              mouse to the
-.P
+.BR
                cur, \"Such
-.P
+.BR
                  a trial,
-.P
+.BR
                    dear Sir,
-.P
+.BR
                          With
-.P
+.BR
                      no jury
-.P
+.BR
                   or judge,
-.P
+.BR
                 would be
-.P
+.BR
               wasting
-.P
+.BR
              our
-.P
+.BR
               breath.\"
-.P
+.BR
                \"I\'ll be
-.P
+.BR
                  judge, I\'ll
-.P
+.BR
                    be jury,\"
-.P
+.BR
                          Said
-.P
+.BR
                     cunning
-.P
+.BR
                       old Fury:
-.P
+.BR
                      \"I\'ll
-.P
+.BR
                       try the
-.P
+.BR
                          whole
-.P
+.BR
                           cause,
-.P
+.BR
                              and
-.P
+.BR
                         condemn
-.P
+.BR
                        you
-.P
+.BR
                       to
-.P
+.BR
                        death.\"\'
-.P
+.BR
 
 .SH
 9.6.3 GROUP
@@ -1815,8 +1904,11 @@ than 100 times in last month.
 
 .nf
   group{
+.BR
     Your grouped text here
+.BR
   }group
+.BR
   A group is treated as an object and given a single object number.
 .fi
 
@@ -1826,50 +1918,95 @@ than 100 times in last month.
 
 .nf
   group{
+.BR
                       \'Fury said to a
+.BR
                      mouse, That he
+.BR
                    met in the
+.BR
                  house,
+.BR
               \"Let us
+.BR
                 both go to
+.BR
                   law:  I will
+.BR
                     prosecute
+.BR
                       YOU.  \-\-Come,
+.BR
                          I\'ll take no
+.BR
                           denial; We
+.BR
                        must have a
+.BR
                    trial:  For
+.BR
                 really this
+.BR
              morning I\'ve
+.BR
             nothing
+.BR
            to do.\"
+.BR
              Said the
+.BR
                mouse to the
+.BR
                  cur, \"Such
+.BR
                    a trial,
+.BR
                      dear Sir,
+.BR
                            With
+.BR
                        no jury
+.BR
                     or judge,
+.BR
                   would be
+.BR
                 wasting
+.BR
                our
+.BR
                 breath.\"
+.BR
                  \"I\'ll be
+.BR
                    judge, I\'ll
+.BR
                      be jury,\"
+.BR
                            Said
+.BR
                       cunning
+.BR
                         old Fury:
+.BR
                        \"I\'ll
+.BR
                         try the
+.BR
                            whole
+.BR
                             cause,
+.BR
                                and
+.BR
                           condemn
+.BR
                          you
+.BR
                         to
+.BR
                          death.\"\'
+.BR
   }group
 .fi
 
@@ -1878,93 +2015,93 @@ than 100 times in last month.
 
 
                     \'Fury said to a
-.P
+.BR
                    mouse, That he
-.P
+.BR
                  met in the
-.P
+.BR
                house,
-.P
+.BR
             \"Let us
-.P
+.BR
               both go to
-.P
+.BR
                 law:  I will
-.P
+.BR
                   prosecute
-.P
+.BR
                     YOU.  \-\-Come,
-.P
+.BR
                        I\'ll take no
-.P
+.BR
                         denial; We
-.P
+.BR
                      must have a
-.P
+.BR
                  trial:  For
-.P
+.BR
               really this
-.P
+.BR
            morning I\'ve
-.P
+.BR
           nothing
-.P
+.BR
          to do.\"
-.P
+.BR
            Said the
-.P
+.BR
              mouse to the
-.P
+.BR
                cur, \"Such
-.P
+.BR
                  a trial,
-.P
+.BR
                    dear Sir,
-.P
+.BR
                          With
-.P
+.BR
                      no jury
-.P
+.BR
                   or judge,
-.P
+.BR
                 would be
-.P
+.BR
               wasting
-.P
+.BR
              our
-.P
+.BR
               breath.\"
-.P
+.BR
                \"I\'ll be
-.P
+.BR
                  judge, I\'ll
-.P
+.BR
                    be jury,\"
-.P
+.BR
                          Said
-.P
+.BR
                     cunning
-.P
+.BR
                       old Fury:
-.P
+.BR
                      \"I\'ll
-.P
+.BR
                       try the
-.P
+.BR
                          whole
-.P
+.BR
                           cause,
-.P
+.BR
                              and
-.P
+.BR
                         condemn
-.P
+.BR
                        you
-.P
+.BR
                       to
-.P
+.BR
                        death.\"\'
-.P
+.BR
 
 .SH
 9.6.4 CODE
@@ -1977,7 +2114,7 @@ markup. You cannot however use code tags to escape code tags. They are
 however used in the same way as group or poem tags.
 
 .BR
-A code\-block is treated as an object and given a single object number. \ [an \
+A code\-block is treated as an object and given a single object number. [an \
 option \ to \ number \ each \ line \ of \ code \ may \ be \ considered \ at \
 some \ later \ time]
 
@@ -1987,48 +2124,91 @@ some \ later \ time]
 
 .nf
                       \'Fury said to a
+.BR
                      mouse, That he
+.BR
                    met in the
+.BR
                  house,
+.BR
               \"Let us
+.BR
                 both go to
+.BR
                   law:  I will
+.BR
                     prosecute
+.BR
                       YOU.  \-\-Come,
+.BR
                          I\'ll take no
+.BR
                           denial; We
+.BR
                        must have a
+.BR
                    trial:  For
+.BR
                 really this
+.BR
              morning I\'ve
+.BR
             nothing
+.BR
            to do.\"
+.BR
              Said the
+.BR
                mouse to the
+.BR
                  cur, \"Such
+.BR
                    a trial,
+.BR
                      dear Sir,
+.BR
                            With
+.BR
                        no jury
+.BR
                     or judge,
+.BR
                   would be
+.BR
                 wasting
+.BR
                our
+.BR
                 breath.\"
+.BR
                  \"I\'ll be
+.BR
                    judge, I\'ll
+.BR
                      be jury,\"
+.BR
                            Said
+.BR
                       cunning
+.BR
                         old Fury:
+.BR
                        \"I\'ll
+.BR
                         try the
+.BR
                            whole
+.BR
                             cause,
+.BR
                                and
+.BR
                           condemn
+.BR
                          you
+.BR
                         to
+.BR
                          death.\"\'
 .fi
 
@@ -2061,6 +2241,7 @@ basic markup for importing a document into a master document
 
 .nf
   << filename1.sst
+.BR
   << filename2.ssi
 .fi
 
@@ -2073,8 +2254,11 @@ documents under consideration, and occasionally supported have been.
 
 .nf
   << filename.ssi
+.BR
   <<{filename.ssi}
+.BR
   % using textlink alternatives
+.BR
   << |filename.ssi|@|^|
 .fi
 
@@ -2091,7 +2275,7 @@ MARKUP SYNTAX HISTORY
 were changed at 0.37
 
 .BR
-* sisu \-\-query=[sisu \ version \ \ [0.38] or \'history]
+* sisu \-\-query=[sisu \ version \ [0.38] or \'history]
 
 .BR
 provides a short history of changes to
@@ -2103,7 +2287,7 @@ markup
 (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 \
+headers @title and @creator in the first heading [expanded \ using \ the \
 contents \ of \ the \ headers \ @title: \ and \ @author:]
 
 
@@ -2130,7 +2314,7 @@ or, backward compatible using the comment marker:
 .BR
 variations include \'
 .B SiSU
-(text|master|insert) \ [version]\' and \'sisu\-[version]\'
+(text|master|insert) [version]\' and \'sisu\-[version]\'
 
 .BR
 .B 0.51
@@ -2237,7 +2421,9 @@ this is captured by the following file \'rename\' instruction:
 
 .nf
   rename \'s/\.s[123]$/\.sst/\' *.s{1,2,3}
+.BR
   rename \'s/\.r[123]$/\.ssm/\' *.r{1,2,3}
+.BR
   rename \'s/\.si$/\.ssi/\' *.si
 .fi
 
@@ -2266,7 +2452,7 @@ relied upon
 .BR
 .B 0.16
 (2005w25/2) substantial changes introduced to make markup cleaner, header
-0~title type, and headings \ [1\-6]~ introduced, also percentage sign (%) at
+0~title type, and headings [1\-6]~ introduced, also percentage sign (%) at
 start of a text line as comment marker
 
 .BR
@@ -2318,7 +2504,7 @@ located locally or on a remote server for which a url is provided.
 source markup can be shared with the command:
 
 .BR
-  sisu \-s \ [filename]
+  sisu \-s [filename]
 
 .SH
 12.1.1 SISU TEXT \- REGULAR FILES (.SST)
@@ -2363,7 +2549,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 \ [^16]
+with the same prefix and the suffix \._sst [^16]
 
 .BR
 <http://www.jus.uio.no/sisu/sisu_markup>
@@ -2416,7 +2602,7 @@ documents.
 The command to create a sisupod is:
 
 .BR
-  sisu \-S \ [filename]
+  sisu \-S [filename]
 
 .BR
 Alternatively, make a pod of the contents of a whole directory:
@@ -2452,28 +2638,26 @@ incomplete and should be handled with care.
 .B convert from sst to simple xml representations (sax, dom and node):
 
 .BR
-  sisu \-\-to\-sax \ [filename/wildcard] or sisu \-\-to\-sxs \
-  [filename/wildcard]
+  sisu \-\-to\-sax [filename/wildcard] or sisu \-\-to\-sxs [filename/wildcard]
 
 .BR
-  sisu \-\-to\-dom \ [filename/wildcard] or sisu \-\-to\-sxd \
-  [filename/wildcard]
+  sisu \-\-to\-dom [filename/wildcard] or sisu \-\-to\-sxd [filename/wildcard]
 
 .BR
-  sisu \-\-to\-node \ [filename/wildcard] or sisu \-\-to\-sxn \
-  [filename/wildcard]
+  sisu \-\-to\-node [filename/wildcard] or sisu \-\-to\-sxn [filename/wildcard]
+
 
 .BR
 .B convert to sst from any sisu xml representation (sax, dom and node):
 
 .BR
-  sisu \-\-from\-xml2sst \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]]
+  sisu \-\-from\-xml2sst [filename/wildcard \ [.sxs.xml,.sxd.xml,sxn.xml]]
 
 .BR
 or the same:
 
 .BR
-  sisu \-\-from\-sxml \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]]
+  sisu \-\-from\-sxml [filename/wildcard \ [.sxs.xml,.sxd.xml,sxn.xml]]
 
 .SH
 13.1.1 XML SAX REPRESENTATION
@@ -2482,20 +2666,19 @@ or the same:
 To convert from sst to simple xml (sax) representation:
 
 .BR
-  sisu \-\-to\-sax \ [filename/wildcard] or sisu \-\-to\-sxs \
-  [filename/wildcard]
+  sisu \-\-to\-sax [filename/wildcard] or sisu \-\-to\-sxs [filename/wildcard]
 
 .BR
 To convert from any sisu xml representation back to sst
 
 .BR
-  sisu \-\-from\-xml2sst \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]]
+  sisu \-\-from\-xml2sst [filename/wildcard \ [.sxs.xml,.sxd.xml,sxn.xml]]
 
 .BR
 or the same:
 
 .BR
-  sisu \-\-from\-sxml \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]]
+  sisu \-\-from\-sxml [filename/wildcard \ [.sxs.xml,.sxd.xml,sxn.xml]]
 
 .SH
 13.1.2 XML DOM REPRESENTATION
@@ -2504,20 +2687,19 @@ or the same:
 To convert from sst to simple xml (dom) representation:
 
 .BR
-  sisu \-\-to\-dom \ [filename/wildcard] or sisu \-\-to\-sxd \
-  [filename/wildcard]
+  sisu \-\-to\-dom [filename/wildcard] or sisu \-\-to\-sxd [filename/wildcard]
 
 .BR
 To convert from any sisu xml representation back to sst
 
 .BR
-  sisu \-\-from\-xml2sst \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]]
+  sisu \-\-from\-xml2sst [filename/wildcard \ [.sxs.xml,.sxd.xml,sxn.xml]]
 
 .BR
 or the same:
 
 .BR
-  sisu \-\-from\-sxml \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]]
+  sisu \-\-from\-sxml [filename/wildcard \ [.sxs.xml,.sxd.xml,sxn.xml]]
 
 .SH
 13.1.3 XML NODE REPRESENTATION
@@ -2526,20 +2708,19 @@ or the same:
 To convert from sst to simple xml (node) representation:
 
 .BR
-  sisu \-\-to\-node \ [filename/wildcard] or sisu \-\-to\-sxn \
-  [filename/wildcard]
+  sisu \-\-to\-node [filename/wildcard] or sisu \-\-to\-sxn [filename/wildcard]
 
 .BR
 To convert from any sisu xml representation back to sst
 
 .BR
-  sisu \-\-from\-xml2sst \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]]
+  sisu \-\-from\-xml2sst [filename/wildcard \ [.sxs.xml,.sxd.xml,sxn.xml]]
 
 .BR
 or the same:
 
 .BR
-  sisu \-\-from\-sxml \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]]
+  sisu \-\-from\-sxml [filename/wildcard \ [.sxs.xml,.sxd.xml,sxn.xml]]
 
 .SH
 14. CONFIGURATION
@@ -2587,7 +2768,7 @@ resource configuration is determined by looking at the following files if
 they exist:
 
 .BR
-  \./_sisu/sisurc.yml
+  ./_sisu/sisurc.yml
 
 .BR
   ~/.sisu/sisurc.yml
@@ -2620,7 +2801,7 @@ Skins modify the default appearance of document output on a document,
 directory, or site wide basis. Skins are looked for in the following locations:
 
 .BR
-  \./_sisu/skin
+  ./_sisu/skin
 
 .BR
   ~/.sisu/skin
@@ -2633,13 +2814,13 @@ directory, or site wide basis. Skins are looked for in the following locations:
 are the following the default sub\-directories for document skins:
 
 .BR
-  \./skin/doc
+  ./skin/doc
 
 .BR
-  \./skin/dir
+  ./skin/dir
 
 .BR
-  \./skin/site
+  ./skin/site
 
 .BR
 A skin is placed in the appropriate directory and the file named skin_[name].rb
@@ -2838,16 +3019,27 @@ skin_poems.rb
 
 .nf
     class Home
+.BR
       def homepage
+.BR
         # place the html content of your homepage here, this will become index.html
+.BR
         <<HOME <html>
+.BR
   <head></head>
+.BR
   <doc>
+.BR
   <p>this is my new homepage.</p>
+.BR
   </doc>
+.BR
   </html>
+.BR
   HOME
+.BR
       end
+.BR
     end
 .fi
 
@@ -2991,10 +3183,10 @@ to populate a postgresql database, this being part of
 22.3 SYNOPSIS
 
 .BR
-  sisu \-D \ [instruction] \ [filename/wildcard \ if \ required]
+  sisu \-D [instruction] [filename/wildcard \ if \ required]
 
 .BR
-  sisu \-D \-\-pg \-\-[instruction] \ [filename/wildcard \ if \ required]
+  sisu \-D \-\-pg \-\-[instruction] [filename/wildcard \ if \ required]
 
 .SH
 22.4 COMMANDS
@@ -3013,46 +3205,43 @@ may be used interchangeably.
 22.4.1 CREATE AND DESTROY DATABASE
 
 .TP
-.B \ \-\-pgsql \ \-\-createall
-\ initial \ step, \ creates \ required \ relations \ (tables, \ indexes) \ in
-\ existing \ (postgresql) \ database \ (a \ database \ should \ be \ created \
-manually \ and \ given \ the \ same \ name \ as \ working \ directory, \ as \
-requested) \ (rb.dbi) \
+.B \-\-pgsql \-\-createall
+initial step, creates required relations (tables, indexes) in existing
+(postgresql) database (a database should be created manually and given the same
+name as working directory, as requested) (rb.dbi)
 
 .TP
-.B \ sisu \ \-D \ \-\-createdb
-\ creates \ database \ where \ no \ database \ existed \ before \
+.B sisu \-D \-\-createdb
+creates database where no database existed before
 
 .TP
-.B \ sisu \ \-D \ \-\-create
-\ creates \ database \ tables \ where \ no \ database \ tables \ existed \
-before \
+.B sisu \-D \-\-create
+creates database tables where no database tables existed before
 
 .TP
-.B \ sisu \ \-D \ \-\-Dropall
-\ destroys \ database \ (including \ all \ its \ content)! \ kills \ data \
-and \ drops \ tables, \ indexes \ and \ database \ associated \ with \ a \
-given \ directory \ (and \ directories \ of \ the \ same \ name). \
+.B sisu \-D \-\-Dropall
+destroys database (including all its content)! kills data and drops tables,
+indexes and database associated with a given directory (and directories of the
+same name).
 
 .TP
-.B \ sisu \ \-D \ \-\-recreate
-\ destroys \ existing \ database \ and \ builds \ a \ new \ empty \ database
-\ structure \
+.B sisu \-D \-\-recreate
+destroys existing database and builds a new empty database structure
 
 .SH
 22.4.2 IMPORT AND REMOVE DOCUMENTS
 
 .TP
-.B \ sisu \ \-D \ \-\-import \ \-v \ \ [filename/wildcard]
+.B sisu \-D \-\-import \-v [filename/wildcard]
 populates database with the contents of the file. Imports documents(s)
 specified to a postgresql database (at an object level).
 
 .TP
-.B \ sisu \ \-D \ \-\-update \ \-v \ \ [filename/wildcard]
+.B sisu \-D \-\-update \-v [filename/wildcard]
 updates file contents in database
 
 .TP
-.B \ sisu \ \-D \ \-\-remove \ \-v \ \ [filename/wildcard]
+.B sisu \-D \-\-remove \-v [filename/wildcard]
 removes specified document from postgresql database.
 
 .SH
@@ -3081,10 +3270,10 @@ to populate an sqlite database, this being part of
 23.3 SYNOPSIS
 
 .BR
-  sisu \-d \ [instruction] \ [filename/wildcard \ if \ required]
+  sisu \-d [instruction] [filename/wildcard \ if \ required]
 
 .BR
-  sisu \-d \-\-(sqlite|pg) \-\-[instruction] \ [filename/wildcard \ if \
+  sisu \-d \-\-(sqlite|pg) \-\-[instruction] [filename/wildcard \ if \
   required]
 
 .SH
@@ -3104,46 +3293,43 @@ may be used interchangeably.
 23.4.1 CREATE AND DESTROY DATABASE
 
 .TP
-.B \ \-\-sqlite \ \-\-createall
-\ initial \ step, \ creates \ required \ relations \ (tables, \ indexes) \ in
-\ existing \ (sqlite) \ database \ (a \ database \ should \ be \ created \
-manually \ and \ given \ the \ same \ name \ as \ working \ directory, \ as \
-requested) \ (rb.dbi) \
+.B \-\-sqlite \-\-createall
+initial step, creates required relations (tables, indexes) in existing
+(sqlite) database (a database should be created manually and given the same
+name as working directory, as requested) (rb.dbi)
 
 .TP
-.B \ sisu \ \-d \ \-\-createdb
-\ creates \ database \ where \ no \ database \ existed \ before \
+.B sisu \-d \-\-createdb
+creates database where no database existed before
 
 .TP
-.B \ sisu \ \-d \ \-\-create
-\ creates \ database \ tables \ where \ no \ database \ tables \ existed \
-before \
+.B sisu \-d \-\-create
+creates database tables where no database tables existed before
 
 .TP
-.B \ sisu \ \-d \ \-\-dropall
-\ destroys \ database \ (including \ all \ its \ content)! \ kills \ data \
-and \ drops \ tables, \ indexes \ and \ database \ associated \ with \ a \
-given \ directory \ (and \ directories \ of \ the \ same \ name). \
+.B sisu \-d \-\-dropall
+destroys database (including all its content)! kills data and drops tables,
+indexes and database associated with a given directory (and directories of the
+same name).
 
 .TP
-.B \ sisu \ \-d \ \-\-recreate
-\ destroys \ existing \ database \ and \ builds \ a \ new \ empty \ database
-\ structure \
+.B sisu \-d \-\-recreate
+destroys existing database and builds a new empty database structure
 
 .SH
 23.4.2 IMPORT AND REMOVE DOCUMENTS
 
 .TP
-.B \ sisu \ \-d \ \-\-import \ \-v \ \ [filename/wildcard]
+.B sisu \-d \-\-import \-v [filename/wildcard]
 populates database with the contents of the file. Imports documents(s)
 specified to an sqlite database (at an object level).
 
 .TP
-.B \ sisu \ \-d \ \-\-update \ \-v \ \ [filename/wildcard]
+.B sisu \-d \-\-update \-v [filename/wildcard]
 updates file contents in database
 
 .TP
-.B \ sisu \ \-d \ \-\-remove \ \-v \ \ [filename/wildcard]
+.B sisu \-d \-\-remove \-v [filename/wildcard]
 removes specified document from sqlite database.
 
 .SH
@@ -3155,7 +3341,7 @@ removes specified document from sqlite database.
 INCLUDING OBJECT CITATION NUMBERING (BACKEND CURRENTLY POSTGRESQL)
 
 .BR
-Sample search frontend <http://search.sisudoc.org> \ [^20] A small database and
+Sample search frontend <http://search.sisudoc.org> [^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.[^21]
@@ -3176,9 +3362,8 @@ the names of the documents matched along with the objects (paragraphs) that
 meet the search criteria.[^22]
 
 .TP
-.B \ sisu \ \-F \ \-\-webserv\-webrick
-\ builds \ a \ cgi \ web \ search \ frontend \ for \ the \ database \ created
-\
+.B sisu \-F \-\-webserv\-webrick
+builds a cgi web search frontend for the database created
 
 .BR
 The following is feedback on the setup on a machine provided by the help
@@ -3190,12 +3375,19 @@ command:
 
 .nf
   Postgresql
+.BR
     user:             ralph
+.BR
     current db set:   SiSU_sisu
+.BR
     port:             5432
+.BR
     dbi connect:      DBI:Pg:database=SiSU_sisu;port=5432
+.BR
   sqlite
+.BR
     current db set:   /home/ralph/sisu_www/sisu/sisu_sqlite.db
+.BR
     dbi connect       DBI:SQLite:/home/ralph/sisu_www/sisu/sisu_sqlite.db
 .fi
 
@@ -3203,36 +3395,34 @@ command:
 Note on databases built
 
 .BR
-By default, \ [unless \ otherwise \ specified] databases are built on a
-directory basis, from collections of documents within that directory. The name
-of the directory you choose to work from is used as the database name, i.e. if
-you are working in a directory called /home/ralph/ebook the database SiSU_ebook
-is used. \ [otherwise \ a \ manual \ mapping \ for \ the \ collection \ is \
+By default, [unless \ otherwise \ specified] databases are built on a directory
+basis, from collections of documents within that directory. The name of the
+directory you choose to work from is used as the database name, i.e. if you are
+working in a directory called /home/ralph/ebook the database SiSU_ebook is
+used. [otherwise \ a \ manual \ mapping \ for \ the \ collection \ is \
 necessary]
 
 .SH
 24.2 SEARCH FORM
 
 .TP
-.B \ sisu \ \-F
-\ generates \ a \ sample \ search \ form, \ which \ must \ be \ copied \ to \
-the \ web\-server \ cgi \ directory \
+.B sisu \-F
+generates a sample search form, which must be copied to the web\-server cgi
+directory
 
 .TP
-.B \ sisu \ \-F \ \-\-webserv\-webrick
-\ generates \ a \ sample \ search \ form \ for \ use \ with \ the \ webrick \
-server, \ which \ must \ be \ copied \ to \ the \ web\-server \ cgi \ directory
-\
+.B sisu \-F \-\-webserv\-webrick
+generates a sample search form for use with the webrick server, which must be
+copied to the web\-server cgi directory
 
 .TP
-.B \ sisu \ \-Fv
-\ as \ above, \ and \ provides \ some \ information \ on \ setting \ up \
-hyperestraier \
+.B sisu \-Fv
+as above, and provides some information on setting up hyperestraier
 
 .TP
-.B \ sisu \ \-W
-\ starts \ the \ webrick \ server \ which \ should \ be \ available \
-wherever \ sisu \ is \ properly \ installed \
+.B sisu \-W
+starts the webrick server which should be available wherever sisu is properly
+installed
 
 .BR
 The generated search form must be copied manually to the webserver directory as
@@ -3271,7 +3461,7 @@ directory /home/ralph/sisu_www
 (A) to generate the index within the webserver directory to be indexed:
 
 .BR
-  estcmd gather \-sd \ [index \ name] \ [directory \ path \ to \ index]
+  estcmd gather \-sd [index \ name] [directory \ path \ to \ index]
 
 .BR
 the following are examples that will need to be tailored according to your
@@ -3334,7 +3524,7 @@ rune along the following lines:
   sudo cp \-v /usr/share/hyperestraier/estseek.* /usr/lib/cgi\-bin
 
 .BR
-  \ [see \ estraier \ documentation \ for \ paths]
+  [see \ estraier \ documentation \ for \ paths]
 
 .BR
 (ii) edit estseek.conf, with attention to the lines starting \'indexname:\' and
@@ -3373,13 +3563,13 @@ and try open the url: <http://localhost:8081/cgi\-bin/estseek.cgi>
 26.2 SYNOPSIS
 
 .BR
-sisu_webrick \ [port]
+sisu_webrick [port]
 
 .BR
 or
 
 .BR
-sisu \-W \ [port]
+sisu \-W [port]
 
 .SH
 26.3 DESCRIPTION
@@ -3404,8 +3594,8 @@ yaml file: ~/.sisu/sisurc.yml a sample of which is provided as
 26.4 SUMMARY OF MAN PAGE
 
 .BR
-sisu_webrick, may be started on it\'s own with the command: sisu_webrick \
-[port] or using the sisu command with the \-W flag: sisu \-W \ [port]
+sisu_webrick, may be started on it\'s own with the command: sisu_webrick [port]
+or using the sisu command with the \-W flag: sisu \-W [port]
 
 .BR
 where no port is given and settings are unchanged the default port is 8081
@@ -3414,7 +3604,7 @@ where no port is given and settings are unchanged the default port is 8081
 26.5 DOCUMENT PROCESSING COMMAND FLAGS
 
 .BR
-sisu \-W \ [port] starts
+sisu \-W [port] starts
 .B Ruby
 Webrick web\-server, serving
 .B SiSU
@@ -3540,7 +3730,7 @@ may be used in conjunction with other processing flags, e.g.
 28.1 COMMANDS
 
 .TP
-.B \ \-R \ \ [filename/wildcard]
+.B \-R [filename/wildcard]
 copies sisu output files to remote host using rsync. This requires that
 sisurc.yml has been provided with information on hostname and username, and
 that you have your \"keys\" and ssh agent in place. Note the behavior of rsync
@@ -3549,7 +3739,7 @@ different if \-R is used with other flags from if used alone. Alone the rsync
 \-R is used together with other flags, it is not). Also see \-r
 
 .TP
-.B \ \-r \ \ [filename/wildcard]
+.B \-r [filename/wildcard]
 copies sisu output files to remote host using scp. This requires that
 sisurc.yml has been provided with information on hostname and username, and
 that you have your \"keys\" and ssh agent in place. Also see \-R
@@ -3600,6 +3790,7 @@ Sid and testing archives (and possibly Ubuntu), assuming your
 
 .nf
     aptitude update
+.BR
     aptitude install sisu\-complete
 .fi
 
@@ -3610,8 +3801,11 @@ markup samples:
 
 .nf
   #/etc/apt/sources.list
+.BR
     deb http://ftp.fi.debian.org/debian/ unstable main non\-free contrib
+.BR
     deb\-src http://ftp.fi.debian.org/debian/ unstable main non\-free contrib
+.BR
   d
 .fi
 
@@ -3621,6 +3815,7 @@ The aptitude commands become:
 
 .nf
     aptitude update
+.BR
     aptitude install sisu\-complete sisu\-markup\-samples
 .fi
 
@@ -3635,7 +3830,9 @@ archives, they will be available by adding the following to your
 
 .nf
   #/etc/apt/sources.list
+.BR
     deb http://www.jus.uio.no/sisu/archive unstable main non\-free
+.BR
     deb\-src http://www.jus.uio.no/sisu/archive unstable main non\-free
 .fi
 
@@ -3645,6 +3842,7 @@ repeat the aptitude commands
 
 .nf
     aptitude update
+.BR
     aptitude install sisu\-complete sisu\-markup\-samples
 .fi
 
@@ -3670,7 +3868,7 @@ They may be downloaded from:
 as root type:
 
 .BR
-  rpm \-i \ [rpm \ package \ name]
+  rpm \-i [rpm \ package \ name]
 
 .SH
 30.1.3 INSTALLATION FROM SOURCE
@@ -3719,8 +3917,11 @@ as root type:
 
 .nf
       ruby setup.rb config
+.BR
       ruby setup.rb setup
+.BR
       #[and \ as \ root:]
+.BR
       ruby setup.rb install
 .fi
 
@@ -3888,13 +4089,13 @@ The man pages are also available online, though not always kept as up to date
 as within the package itself:
 
 .BR
-* sisu.1 <http://www.jus.uio.no/sisu/man/sisu.1> \ [^24]
+* sisu.1 <http://www.jus.uio.no/sisu/man/sisu.1> [^24]
 
 .BR
-* sisu.8 <http://www.jus.uio.no/sisu/man/sisu.8> \ [^25]
+* sisu.8 <http://www.jus.uio.no/sisu/man/sisu.8> [^25]
 
 .BR
-* man directory <http://www.jus.uio.no/sisu/man> \ [^26]
+* man directory <http://www.jus.uio.no/sisu/man> [^26]
 
 .SH
 30.3.2 BUILT IN HELP
@@ -4055,12 +4256,10 @@ comments: assumes dark background; no display line\-wrap
     ~/.kde/share/apps/katepart/syntax
 
 .BR
-  \ [settings::configure \ kate::{highlighting,filetypes}]
+  [settings::configure \ kate::{highlighting,filetypes}]
 
 .BR
-  \ [tools::highlighting::{markup,scripts}::
-.B \ SiSU
-]
+  [tools::highlighting::{markup,scripts}:: \ .B \ SiSU \ ]
 
 .BR
 * nedit <http://www.nedit.org>
@@ -4072,7 +4271,7 @@ comments: assumes dark background; no display line\-wrap
   nedit \-import sisu_nedit.pats
 
 .BR
-  status: a very clumsy first attempt \ [not \ really \ done]
+  status: a very clumsy first attempt [not \ really \ done]
 
 .BR
   comments: this editor features display line wrap
@@ -4093,7 +4292,7 @@ comments: assumes dark background; no display line\-wrap
     (require \'sisu\-mode.el)
 
 .BR
-  \ [not \ done \ / \ not \ yet \ included]
+  [not \ done \ / \ not \ yet \ included]
 
 .BR
 * vim & gvim <http://www.vim.org>
@@ -4116,11 +4315,9 @@ comments: assumes dark background; no display line\-wrap
 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]
+[ \ .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?
@@ -4159,9 +4356,8 @@ 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].
+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
@@ -4173,7 +4369,7 @@ 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 \
+alternative practical standard ways of representing documents [be \ that \
 browser \ viewing, \ paper \ publication, \ sql \ search \ etc.] (html, xml,
 odf, latex, pdf, sql)
 
@@ -4232,8 +4428,8 @@ 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].
+database; [output \ indexing \ also \ work \ well \ with \ search \ indexing \
+tools \ like \ hyperestraier].
 
 .BR
 * long term maintainability of document collections in a world of changing
@@ -4536,17 +4732,13 @@ Document Manifest @ <http://sisudoc.org/sisu_manual/sisu/sisu_manifest.html>
 .BR
 .I DC tags included with this document are provided here.
 
-.BR
 DC Title:
 .I SiSU \- Manual
 
-.BR
 DC Creator:
 .I Ralph Amissah
 
-.BR
 DC Rights:
-.I Copyright (C) Ralph Amissah 2008, part of SiSU documentation, License GPL
 3
 
 .BR
@@ -4586,7 +4778,7 @@ Filetype:
 
 .BR
 Sourcefile Digest, MD5(sisu.ssm.sst)=
-.I 7568e6bc171256672e0820a333b37459
+.I 7fbab3b7c0fd0ed2e128585c2982c5c8
 
 .BR
 Skin_Digest: MD5(skin_sisu_manual.rb)=
@@ -4597,17 +4789,17 @@ Skin_Digest: MD5(skin_sisu_manual.rb)=
 
 .BR
 Document (metaverse) last generated:
-.I Thu May 22 21:53:23 \-0400 2008
+.I Mon Jul 21 02:54:34 \-0400 2008
 
 .BR
 Generated by:
 .I SiSU
-.I 0.67.0
-of 2008w20/4 (2008\-05\-22)
+.I 0.68.0
+of 2008w29/1 (2008\-07\-21)
 
 .BR
 Ruby version:
-.I ruby 1.8.6 (2008\-03\-03 patchlevel 114) \ [i486\-linux]
+.I  ruby 1.8.7 (2008\-06\-20 patchlevel 22) \ [i486\-linux]
 
 .TP
 .BI 1.
@@ -4630,7 +4822,7 @@ code-blocks
 .BI 5.
 Specification submitted by Adobe to ISO to become a full open ISO
 specification
- <http://www.linux-watch.com/news/NS7542722606.html>
+<http://www.linux-watch.com/news/NS7542722606.html>
 .TP
 .BI 6.
 ISO/IEC 26300:2006
@@ -4683,7 +4875,7 @@ editors notes, numbered asterisk footnote/endnote series
 .TP
 .BI 15.
 Table from the Wealth of Networks by Yochai Benkler
- <http://www.jus.uio.no/sisu/the_wealth_of_networks.yochai_benkler>
+<http://www.jus.uio.no/sisu/the_wealth_of_networks.yochai_benkler>
 .TP
 .BI 16.
 \.ssc (for composite) is under consideration but \._sst makes clear that this
@@ -4700,12 +4892,12 @@ and this behaviour could be reinstated.
 .TP
 .BI 18.
 <http://www.postgresql.org/>
- <http://advocacy.postgresql.org/>
- <http://en.wikipedia.org/wiki/Postgresql>
+<http://advocacy.postgresql.org/>
+<http://en.wikipedia.org/wiki/Postgresql>
 .TP
 .BI 19.
 <http://www.hwaci.com/sw/sqlite/>
- <http://en.wikipedia.org/wiki/Sqlite>
+<http://en.wikipedia.org/wiki/Sqlite>
 .TP
 .BI 20.
 <http://search.sisudoc.org>
@@ -4736,9 +4928,11 @@ There is nothing to stop MySQL support being added in future.
 <http://www.jus.uio.no/sisu/man>
 .TP
 .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
+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 28.
@@ -4758,10 +4952,10 @@ pdf: <http://www.jus.uio.no/sisu/sisu/landscape.pdf>
 at: <http://www.jus.uio.no/sisu>
 .TP
 .TP
-* Generated by: SiSU 0.67.0 of 2008w20/4 (2008-05-22)
+* Generated by: SiSU 0.68.0 of 2008w29/1 (2008-07-21)
 .TP
-* Ruby version: ruby 1.8.6 (2008-03-03 patchlevel 114) [i486-linux]
+* Ruby version: ruby 1.8.7 (2008-06-20 patchlevel 22) [i486-linux]
 .TP
-* Last Generated on: Thu May 22 21:53:23 -0400 2008
+* Last Generated on: Mon Jul 21 02:54:35 -0400 2008
 .TP
 * SiSU http://www.jus.uio.no/sisu