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 --- man/man1/sisu_configuration.1 | 368 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 368 insertions(+) create mode 100644 man/man1/sisu_configuration.1 (limited to 'man/man1/sisu_configuration.1') 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 + < + + +

this is my new homepage.

+ + + HOME + end + end +.fi + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ + + +.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: +.TP +html: +.TP +pdf: +.TP +pdf: +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_configuration/sisu_configuration.1 +.TP +at: +.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 -- cgit v1.2.3