From 50d45c6deb0afd2e4222d2e33a45487a9d1fa676 Mon Sep 17 00:00:00 2001 From: Ralph Amissah Date: Sun, 23 Sep 2007 05:16:21 +0100 Subject: primarily todo with sisu documentation, changelog reproduced below: * start documenting sisu using sisu * sisu markup source files in data/doc/sisu/sisu_markup_samples/sisu_manual/ /usr/share/doc/sisu/sisu_markup_samples/sisu_manual/ * default output [sisu -3] in data/doc/manuals_generated/sisu_manual/ /usr/share/doc/manuals_generated/sisu_manual/ (adds substantially to the size of sisu package!) * help related edits * manpage, work on ability to generate manpages, improved * param, exclude footnote mark count when occurs within code block * plaintext changes made * shared_txt, line wrap visited * file:// link option introduced (in addition to existing https?:// and ftp://) a bit arbitrarily, diff here, [double check changes in sysenv and hub] * minor adjustments * html url match refinement * css added tiny_center * plaintext * endnotes fix * footnote adjustment to make more easily distinguishable from substantive text * flag -a only [flags -A -e -E dropped] controlled by modifiers --unix/msdos --footnote/endnote * defaults, homepage * renamed homepage (instead of index) implications for modifying skins, which need likewise to have any homepage entry renamed * added link to sisu_manual in homepage * css the css for the default homepage is renamed homepage.css (instead of index.css) [consider removing this and relying on html.css] * ruby version < ruby1.9 * place stop on installation and working with for now [ruby String.strip broken in ruby 1.9.0 (2007-09-10 patchlevel 0) [i486-linux], 2007-09-18:38/2] * debian/control restrict use to ruby > 1.8.4 and ruby < 1.9 * debian * debian/control restrict use to ruby > 1.8.4 and ruby < 1.9 * sisu-doc new sub-package for sisu documentation debian/control and sisu-doc.install --- data/doc/sisu/html/sisu_configuration.1.html | 254 +++++++++++++++++++++++++++ 1 file changed, 254 insertions(+) create mode 100644 data/doc/sisu/html/sisu_configuration.1.html (limited to 'data/doc/sisu/html/sisu_configuration.1.html') diff --git a/data/doc/sisu/html/sisu_configuration.1.html b/data/doc/sisu/html/sisu_configuration.1.html new file mode 100644 index 00000000..ad8f13fc --- /dev/null +++ b/data/doc/sisu/html/sisu_configuration.1.html @@ -0,0 +1,254 @@ + + + + + +"sisu_configuration"("1") manual page + + +Table of Contents

+SISU - CONFIGURATION  [0.58], RALPH AMISSAH +

CONFIGURATION OF ENVIRONMENT + +

1. CONFIGURATION +

1.1 DETERMINING THE CURRENT CONFIGURATION +

Information +on the current configuration of SiSU should be available with the help +command: +

sisu -v
+ +

which is an alias for: +

sisu --help env
+ +

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

1.2 CONFIGURATION FILES (CONFIG.YML) +

SiSU +configration parameters are adjusted in the configuration file, which can +be used to override the defaults set. This includes such things as which +directory interim processing should be done in and where the generated +output should be placed. +

The SiSU configuration file is a yaml file, which +means indentation is significant. +

SiSU resource configuration is determined +by looking at the following files if they exist: +

./_sisu/sisurc.yml
+ +

~/.sisu/sisurc.yml
+ +

/etc/sisu/sisurc.yml
+ +

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

+ In the absence of instructions in any of these it falls back to the internal +program defaults. +

Configuration determines the output and processing directories +and the database access details. +

If SiSU is installed a sample sisurc.yml + +

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

CONFIGURATION OF DOCUMENTS +

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

./_sisu/skin
+ +

~/.sisu/skin
+ +

/etc/sisu/skin
+ +

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

./skin/doc
+ +

./skin/dir
+ +

./skin/site
+ +

A skin is placed in the appropriate directory and the file named skin_[name].rb + +

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

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

2.2 DIRECTORY SKIN +

A directory may be mapped on to a particular skin, +so all documents within that directory take on a particular appearance. +If a skin exists in the skin/dir with the same name as the document directory, +it will automatically be used for each of the documents in that directory, +(except where a document specifies the use of another skin, in the skin/doc +directory). +

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

2.3 SITE SKIN +

A site skin, modifies the program default skin. +

2.4 SAMPLE + +

SKINS +

With SiSU installed sample skins may be found in: +

/etc/sisu/skin/doc +and
+ /usr/share/doc/sisu/sisu_markup_samples/dfsg/_sisu/skin/doc
+ +

(or equivalent directory) and if sisu-markup-samples is installed also +under: +

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

Samples of list.yml and promo.yml (which are used to create the right +column list) may be found in: +

/usr/share/doc/sisu/sisu_markup_samples/dfsg/_sisu/skin/yml +(or equivalent
+ directory)
+ +

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

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

3.2 HOME PAGE WITHIN A SKIN +

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

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

+


+

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

DOCUMENT INFORMATION (METADATA) +

METADATA +

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

Dublin Core (DC) +

DC tags included with this document are provided here. + +

DC Title: SiSU - Configuration  [0.58] +

DC Creator: Ralph Amissah +

DC +Rights: Ralph Amissah +

DC Type: information +

DC Date created: 2002-08-28 + +

DC Date issued: 2002-08-28 +

DC Date available: 2007-08-28 +

DC Date modified: + +

2007-08-30 +

DC Date: 2007-08-30 +

Version Information +

Sourcefile: sisu_configuration._sst + +

Filetype: SiSU text insert 0.58 +

Sourcefile Digest, MD5(sisu_configuration._sst)= + +

2a18ae8bbfec534c6e064d666ffbe20d +

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: Sun Sep 23 01:14:02 +0100 2007 +

Generated by: SiSU 0.58.3 of +2007w36/4 (2007-09-06) +

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

+

+

+ +
Other versions of this document:
+
+ +
manifest: <http://www.jus.uio.no/sisu/sisu_configuration/sisu_manifest.html + +> +
+
+ +
html: <http://www.jus.uio.no/sisu/sisu_configuration/toc.html + +>
+
+ +
pdf: <http://www.jus.uio.no/sisu/sisu_configuration/portrait.pdf + +> +
+
+ +
pdf: <http://www.jus.uio.no/sisu/sisu_configuration/landscape.pdf + +>
+
+ +
at: <http://www.jus.uio.no/sisu + +> +
+
+ +
* Generated by: SiSU 0.58.3 of 2007w36/4 (2007-09-06)
+
+ +
* Ruby version: ruby +1.8.6 (2007-06-07 patchlevel 36) [i486-linux]
+
+ +
* Last Generated on: Sun Sep 23 +01:14:07 +0100 2007
+
+ +
* SiSU http://www.jus.uio.no/sisu +
+
+
+

+ + -- cgit v1.2.3