Merge branch 'upstream' into debian/sid

1 files changed, 368 insertions, 0 deletions

diff --git a/man/man1/sisu_configuration.1 b/man/man1/sisu_configuration.1
new file mode 100644
index 00000000..8dcb0560
--- /dev/null
+++ b/man/man1/sisu_configuration.1
@@ -0,0 +1,368 @@
+.TH "sisu_configuration" "1" "2007-08-30" "0.58.3" "SiSU"
+.SH
+SISU \- CONFIGURATION \ [0.58],
+RALPH AMISSAH
+.BR
+
+.SH
+CONFIGURATION OF ENVIRONMENT
+.BR
+
+.SH
+1. CONFIGURATION
+.BR
+
+.SH
+1.1 DETERMINING THE CURRENT CONFIGURATION
+
+.BR
+Information on the current configuration of
+.B SiSU
+should be available with the help command:
+
+.BR
+  sisu \-v
+
+.BR
+which is an alias for:
+
+.BR
+  sisu \-\-help env
+
+.BR
+Either of these should be executed from within a directory that contains sisu
+markup source documents.
+
+.SH
+1.2 CONFIGURATION FILES (CONFIG.YML)
+
+.BR
+.B SiSU
+configration parameters are adjusted in the configuration file, which can be
+used to override the defaults set. This includes such things as which directory
+interim processing should be done in and where the generated output should be
+placed.
+
+.BR
+The
+.B SiSU
+configuration file is a yaml file, which means indentation is significant.
+
+.BR
+.B SiSU
+resource configuration is determined by looking at the following files if
+they exist:
+
+.BR
+  ./_sisu/sisurc.yml
+
+.BR
+  ~/.sisu/sisurc.yml
+
+.BR
+  /etc/sisu/sisurc.yml
+
+.BR
+The search is in the order listed, and the first one found is used.
+
+.BR
+In the absence of instructions in any of these it falls back to the internal
+program defaults.
+
+.BR
+Configuration determines the output and processing directories and the database
+access details.
+
+.BR
+If
+.B SiSU
+is installed a sample sisurc.yml may be found in /etc/sisu/sisurc.yml
+
+.SH
+CONFIGURATION OF DOCUMENTS
+.BR
+
+.SH
+2. SKINS
+.BR
+
+.BR
+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
+
+.BR
+  ~/.sisu/skin
+
+.BR
+  /etc/sisu/skin
+
+.BR
+.B Within the skin directory
+are the following the default sub\-directories for document skins:
+
+.BR
+  ./skin/doc
+
+.BR
+  ./skin/dir
+
+.BR
+  ./skin/site
+
+.BR
+A skin is placed in the appropriate directory and the file named skin_[name].rb
+
+.BR
+The skin itself is a ruby file which modifies the default appearances set in
+the program.
+
+.SH
+2.1 DOCUMENT SKIN
+
+.BR
+Documents take on a document skin, if the header of the document specifies a
+skin to be used.
+
+
+.nf
+  @skin: skin_united_nations
+.fi
+
+.SH
+2.2 DIRECTORY SKIN
+
+.BR
+A directory may be mapped on to a particular skin, so all documents within that
+directory take on a particular appearance. If a skin exists in the skin/dir
+with the same name as the document directory, it will automatically be used for
+each of the documents in that directory, (except where a document specifies the
+use of another skin, in the skin/doc directory).
+
+.BR
+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
+2.3 SITE SKIN
+
+.BR
+A site skin, modifies the program default skin.
+
+.SH
+2.4 SAMPLE SKINS
+
+.BR
+With
+.B SiSU
+installed sample skins may be found in:
+
+.BR
+  /etc/sisu/skin/doc and
+  /usr/share/doc/sisu/sisu_markup_samples/dfsg/_sisu/skin/doc
+
+.BR
+(or equivalent directory) and if sisu\-markup\-samples is installed also under:
+
+.BR
+  /usr/share/doc/sisu/sisu_markup_samples/non\-free/_sisu/skin/doc
+
+.BR
+Samples of list.yml and promo.yml (which are used to create the right column
+list) may be found in:
+
+.BR
+  /usr/share/doc/sisu/sisu_markup_samples/dfsg/_sisu/skin/yml (or equivalent
+  directory)
+
+.SH
+3. HOMEPAGES
+.BR
+
+.BR
+.B SiSU
+is about the ability to auto\-generate documents. Home pages are regarded as
+custom built items, and are not created by
+.B SiSU
+. More accurately,
+.B 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:
+
+.BR
+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)
+
+.BR
+2. through providing what you want as the home page in a skin,
+
+.BR
+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.
+
+.SH
+3.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
+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:
+
+.BR
+  sisu \-CC
+
+.SH
+3.2 HOME PAGE WITHIN A SKIN
+
+.BR
+Skins are described in a separate section, but basically are a file written in
+the programming language
+.B Ruby
+that may be provided to change the defaults that are provided with sisu with
+respect to individual documents, a directories contents or for a site.
+
+.BR
+If you wish to provide a homepage within a skin the skin should be in the
+directory _sisu/skin/dir and have the name of the directory for which it is to
+become the home page. Documents in the directory commercial_law would have the
+homepage modified in skin_commercial law.rb; or the directory poems in
+skin_poems.rb
+
+
+.nf
+    class Home
+      def homepage
+        # place the html content of your homepage here, this will become index.html
+        <<HOME <html>
+  <head></head>
+  <doc>
+  <p>this is my new homepage.</p>
+  </doc>
+  </html>
+  HOME
+      end
+    end
+.fi
+
+.SH
+DOCUMENT INFORMATION (METADATA)
+.BR
+
+.SH
+METADATA
+.BR
+
+.BR
+Document Manifest @
+<http://www.jus.uio.no/sisu/sisu_manual/sisu_configuration/sisu_manifest.html>
+
+.BR
+.B Dublin Core
+(DC)
+
+.BR
+.I DC tags included with this document are provided here.
+
+.BR
+DC Title:
+.I SiSU \- Configuration \ [0.58]
+
+.BR
+DC Creator:
+.I Ralph Amissah
+
+.BR
+DC Rights:
+.I Ralph Amissah
+
+.BR
+DC Type:
+.I information
+
+.BR
+DC Date created:
+.I 2002\-08\-28
+
+.BR
+DC Date issued:
+.I 2002\-08\-28
+
+.BR
+DC Date available:
+.I 2007\-08\-28
+
+.BR
+DC Date modified:
+.I 2007\-08\-30
+
+.BR
+DC Date:
+.I 2007\-08\-30
+
+.BR
+.B Version Information
+
+.BR
+Sourcefile:
+.I sisu_configuration._sst
+
+.BR
+Filetype:
+.I SiSU text insert 0.58
+
+.BR
+Sourcefile Digest, MD5(sisu_configuration._sst)=
+.I 2a18ae8bbfec534c6e064d666ffbe20d
+
+.BR
+Skin_Digest:
+MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)=
+.I 20fc43cf3eb6590bc3399a1aef65c5a9
+
+.BR
+.B Generated
+
+.BR
+Document (metaverse) last generated:
+.I Sun Sep 23 01:14:02 +0100 2007
+
+.BR
+Generated by:
+.I SiSU
+.I 0.58.3
+of 2007w36/4 (2007\-09\-06)
+
+.BR
+Ruby version:
+.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux]
+
+
+.TP
+Other versions of this document:
+.TP
+manifest: <http://www.jus.uio.no/sisu/sisu_configuration/sisu_manifest.html>
+.TP
+html: <http://www.jus.uio.no/sisu/sisu_configuration/toc.html>
+.TP
+pdf: <http://www.jus.uio.no/sisu/sisu_configuration/portrait.pdf>
+.TP
+pdf: <http://www.jus.uio.no/sisu/sisu_configuration/landscape.pdf>
+." .TP
+." manpage: http://www.jus.uio.no/sisu/sisu_configuration/sisu_configuration.1
+.TP
+at: <http://www.jus.uio.no/sisu>
+.TP
+.TP
+* Generated by: SiSU 0.58.3 of 2007w36/4 (2007-09-06)
+.TP
+* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux]
+.TP
+* Last Generated on: Sun Sep 23 01:14:07 +0100 2007
+.TP
+* SiSU http://www.jus.uio.no/sisu