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 --- .../sisu_manual/sisu_configuration/sax.xml | 466 +++++++++++++++++++++ 1 file changed, 466 insertions(+) create mode 100644 data/doc/manuals_generated/sisu_manual/sisu_configuration/sax.xml (limited to 'data/doc/manuals_generated/sisu_manual/sisu_configuration/sax.xml') diff --git a/data/doc/manuals_generated/sisu_manual/sisu_configuration/sax.xml b/data/doc/manuals_generated/sisu_manual/sisu_configuration/sax.xml new file mode 100644 index 00000000..3da1a79b --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/sisu_configuration/sax.xml @@ -0,0 +1,466 @@ + + + + + + + Title: + + SiSU - Configuration [0.58] + +
+ Creator: + + Ralph Amissah + +
+ Rights: + + Ralph Amissah + +
+ Type: + + information + +
+ Subject: + + ebook, epublishing, electronic book, electronic publishing, electronic document, electronic citation, data structure, citation systems, search + +
+ Date created: + + 2002-08-28 + +
+ Date issued: + + 2002-08-28 + +
+ Date available: + + 2007-08-28 + +
+ Date modified: + + 2007-08-30 + +
+ Date: + + 2007-08-30 + +
+ + + + 1 + + SiSU - Configuration [0.58],
Ralph Amissah + + + + 2 + + Configuration of Environment + + + + 3 + + 1. Configuration + + + + 4 + + 1.1 Determining the Current Configuration + + + + 5 + + Information on the current configuration of SiSU should be +available with the help command: + + + + 6 + + sisu -v + + + + 7 + + which is an alias for: + + + + 8 + + sisu --help env + + + + 9 + + Either of these should be executed from within a directory that +contains sisu markup source documents. + + + + 10 + + 1.2 Configuration files (config.yml) + + + + 11 + + 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. + + + + 12 + + The SiSU configuration file is a yaml file, which means +indentation is significant. + + + + 13 + + SiSU resource configuration is determined by looking at the +following files if they exist: + + + + 14 + + ./_sisu/sisurc.yml + + + + 15 + + ~/.sisu/sisurc.yml + + + + 16 + + /etc/sisu/sisurc.yml + + + + 17 + + The search is in the order listed, and the first one found is used. + + + + 18 + + In the absence of instructions in any of these it falls back to the +internal program defaults. + + + + 19 + + Configuration determines the output and processing directories and the +database access details. + + + + 20 + + If SiSU is installed a sample sisurc.yml may be found in +/etc/sisu/sisurc.yml + + + + 21 + + Configuration of Documents + + + + 22 + + 2. Skins + + + + 23 + + Skins modify the default appearance of document output on a document, +directory, or site wide basis. Skins are looked for in the following +locations: + + + + 24 + + ./_sisu/skin + + + + 25 + + ~/.sisu/skin + + + + 26 + + /etc/sisu/skin + + + + 27 + + Within the skin directory are the following the default +sub-directories for document skins: + + + + 28 + + ./skin/doc + + + + 29 + + ./skin/dir + + + + 30 + + ./skin/site + + + + 31 + + A skin is placed in the appropriate directory and the file named +skin_[name].rb + + + + 32 + + The skin itself is a ruby file which modifies the default appearances +set in the program. + + + + 33 + + 2.1 Document Skin + + + + 34 + + Documents take on a document skin, if the header of the document +specifies a skin to be used. + + + + 35 + +      @skin: skin_united_nations     + + + + 36 + + 2.2 Directory Skin + + + + 37 + + 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). + + + + 38 + + 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. + + + + 39 + + 2.3 Site Skin + + + + 40 + + A site skin, modifies the program default skin. + + + + 41 + + 2.4 Sample Skins + + + + 42 + + With SiSU installed sample skins may be found in: + + + + 43 + + /etc/sisu/skin/doc and +/usr/share/doc/sisu/sisu_markup_samples/dfsg/_sisu/skin/doc + + + + 44 + + (or equivalent directory) and if sisu-markup-samples is installed also +under: + + + + 45 + + /usr/share/doc/sisu/sisu_markup_samples/non-free/_sisu/skin/doc + + + + 46 + + Samples of list.yml and promo.yml (which are used to create the right +column list) may be found in: + + + + 47 + + /usr/share/doc/sisu/sisu_markup_samples/dfsg/_sisu/skin/yml (or +equivalent directory) + + + + 48 + + 3. Homepages + + + + 49 + + SiSU is about the ability to auto-generate documents. Home pages +are regarded as custom built items, and are not created by SiSU. +More accurately, 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: + + + + 50 + + 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) + + + + 51 + + 2. through providing what you want as the home page in a skin, + + + + 52 + + 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. + + + + 53 + + 3.1 Home page and other custom built pages in a sub-directory + + + + 54 + + 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: + + + + 55 + + sisu -CC + + + + 56 + + 3.2 Home page within a skin + + + + 57 + + 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. + + + + 58 + + 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 + + + + 59 + +        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     + + + + -- cgit v1.2.3