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_quickstart/sax.xml | 767 +++++++++++++++++++++ 1 file changed, 767 insertions(+) create mode 100644 data/doc/manuals_generated/sisu_manual/sisu_quickstart/sax.xml (limited to 'data/doc/manuals_generated/sisu_manual/sisu_quickstart/sax.xml') diff --git a/data/doc/manuals_generated/sisu_manual/sisu_quickstart/sax.xml b/data/doc/manuals_generated/sisu_manual/sisu_quickstart/sax.xml new file mode 100644 index 00000000..732593a6 --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/sisu_quickstart/sax.xml @@ -0,0 +1,767 @@ + + + + + + + Title: + + SiSU - SiSU information Structuring Universe / Structured information, Serialized Units - Quickstart, installation and use + +
+ Creator: + + Ralph Amissah + +
+ Rights: + + Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL 3 + +
+ Type: + + information + +
+ Subject: + + ebook, epublishing, electronic book, electronic publishing, electronic document, electronic citation, data structure, citation systems, search + +
+ Date created: + + 2006-09-06 + +
+ Date available: + + 2006-09-06 + +
+ Date issued: + + 2006-09-06 + +
+ Date modified: + + 2007-09-16 + +
+ Date: + + 2007-09-16 + +
+ + + + 1 + + SiSU - SiSU information Structuring Universe / Structured information, +Serialized Units - Quickstart, installation and use,
Ralph +Amissah + + + + 2 + + Quickstart - SiSU installation and use + + + + 3 + + 1. Quickstart - Getting Started Howto + + + + 4 + + 1.1 Installation + + + + 5 + + Installation is currently most straightforward and tested on the +Debian platform, as there are packages for the installation of +sisu and all requirements for what it does. + + + + 6 + + 1.1.1 Debian Installation + + + + 7 + + SiSU is available directly from the Debian Sid and +testing archives (and possibly Ubuntu), assuming your +/etc/apt/sources.list is set accordingly: + + + + 8 + +        aptitude update
       aptitude install sisu-complete     + + + + 9 + + The following /etc/apt/sources.list setting permits the download of +additional markup samples: + + + + 10 + +      #/etc/apt/sources.list

       deb http://ftp.fi.debian.org/debian/ unstable main non-free contrib
       deb-src http://ftp.fi.debian.org/debian/ unstable main non-free contrib
     d     + + + + 11 + + The aptitude commands become: + + + + 12 + +        aptitude update
       aptitude install sisu-complete sisu-markup-samples     + + + + 13 + + If there are newer versions of SiSU upstream of the +Debian archives, they will be available by adding the following +to your /etc/apt/sources.list + + + + 14 + +      #/etc/apt/sources.list

       deb http://www.jus.uio.no/sisu/archive unstable main non-free
       deb-src http://www.jus.uio.no/sisu/archive unstable main non-free     + + + + 15 + + repeat the aptitude commands + + + + 16 + +        aptitude update
       aptitude install sisu-complete sisu-markup-samples     + + + + 17 + + Note however that it is not necessary to install sisu-complete if not +all components of sisu are to be used. Installing just the package sisu +will provide basic functionality. + + + + 18 + + 1.1.2 RPM Installation + + + + 19 + + RPMs are provided though untested, they are prepared by running alien +against the source package, and against the debs. + + + + 20 + + They may be downloaded from: + + + + 21 + + <http://www.jus.uio.no/sisu/SiSU/download.html#rpm> + + + + 22 + + as root type: + + + + 23 + + rpm -i [rpm package name] + + + + 24 + + 1.1.3 Installation from source + + + + 25 + + To install SiSU from source check information at: + + + + 26 + + <http://www.jus.uio.no/sisu/SiSU/download.html#current> + + + + 27 + + download the source package + + + + 28 + + Unpack the source + + + + 29 + + Two alternative modes of installation from source are provided, +setup.rb (by Minero Aoki) and a rant(by Stefan Lang) built install +file, in either case: the first steps are the same, download and unpack +the source file: + + + + 30 + + For basic use SiSU is only dependent on the programming language +in which it is written Ruby, and SiSU will be able to +generate html, various XMLs, including ODF (and will also produce +LaTeX). Dependencies required for further actions, though it relies on +the installation of additional dependencies which the source tarball +does not take care of, for things like using a database (postgresql or +sqlite)1 or converting LaTeX to pdf. + + + 1 + + There is nothing to stop MySQL support being added in future. + + + + + 31 + + setup.rb + + + + 32 + + This is a standard ruby installer, using setup.rb is a three step +process. In the root directory of the unpacked SiSU as root +type: + + + + 33 + +          ruby setup.rb config
         ruby setup.rb setup
         #[and as root:]
         ruby setup.rb install     + + + + 34 + + further information on setup.rb is available from: + + + + 35 + + <http://i.loveruby.net/en/projects/setup/> + + + + 36 + + <http://i.loveruby.net/en/projects/setup/doc/usage.html> + + + + 37 + + "install" + + + + 38 + + The "install" file provided is an installer prepared using "rant". In +the root directory of the unpacked SiSU as root type: + + + + 39 + + ruby install base + + + + 40 + + or for a more complete installation: + + + + 41 + + ruby install + + + + 42 + + or + + + + 43 + + ruby install base + + + + 44 + + This makes use of Rant (by Stefan Lang) and the provided Rantfile. It +has been configured to do post installation setup setup configuration +and generation of first test file. Note however, that additional +external package dependencies, such as tetex-extra are not taken care +of for you. + + + + 45 + + Further information on "rant" is available from: + + + + 46 + + <http://make.rubyforge.org/> + + + + 47 + + <http://rubyforge.org/frs/?group_id=615> + + + + 48 + + For a list of alternative actions you may type: + + + + 49 + + ruby install help + + + + 50 + + ruby install -T + + + + 51 + + 1.2 Testing SiSU, generating output + + + + 52 + + To check which version of sisu is installed: + + + + 53 + + sisu -v + + + + 54 + + Depending on your mode of installation one or a number of markup sample +files may be found either in the directory: + + + + 55 + + ... + + + + 56 + + or + + + + 57 + + ... + + + + 58 + + change directory to the appropriate one: + + + + 59 + + cd /usr/share/doc/sisu/sisu_markup_samples/dfsg + + + + 60 + + 1.2.1 basic text, plaintext, html, XML, ODF + + + + 61 + + Having moved to the directory that contains the markup samples (see +instructions above if necessary), choose a file and run sisu against it + + + + 62 + + sisu -NhwoabxXyv +free_as_in_freedom.rms_and_free_software.sam_williams.sst + + + + 63 + + this will generate html including a concordance file, opendocument text +format, plaintext, XHTML and various forms of XML, and OpenDocument +text + + + + 64 + + 1.2.2 LaTeX / pdf + + + + 65 + + Assuming a LaTeX engine such as tetex or texlive is installed with the +required modules (done automatically on selection of sisu-pdf in +Debian) + + + + 66 + + Having moved to the directory that contains the markup samples (see +instructions above if necessary), choose a file and run sisu against it + + + + 67 + + sisu -pv free_as_in_freedom.rms_and_free_software.sam_williams.sst + + + + 68 + + sisu -3 free_as_in_freedom.rms_and_free_software.sam_williams.sst + + + + 69 + + should generate most available output formats: html including a +concordance file, opendocument text format, plaintext, XHTML and +various forms of XML, and OpenDocument text and pdf + + + + 70 + + 1.2.3 relational database - postgresql, sqlite + + + + 71 + + Relational databases need some setting up - you must have permission to +create the database and write to it when you run sisu. + + + + 72 + + Assuming you have the database installed and the requisite permissions + + + + 73 + + sisu --sqlite --recreate + + + + 74 + + sisu --sqlite -v --import +free_as_in_freedom.rms_and_free_software.sam_williams.sst + + + + 75 + + sisu --pgsql --recreate + + + + 76 + + sisu --pgsql -v --import +free_as_in_freedom.rms_and_free_software.sam_williams.sst + + + + 77 + + 1.3 Getting Help + + + + 78 + + 1.3.1 The man pages + + + + 79 + + Type: + + + + 80 + + man sisu + + + + 81 + + The man pages are also available online, though not always kept as up +to date as within the package itself: + + + + 82 + + sisu.1 +2 + + + 2 + + <http://www.jus.uio.no/sisu/man/sisu.1> + + + + + 83 + + sisu.8 +3 + + + 3 + + <http://www.jus.uio.no/sisu/man/sisu.8> + + + + + 84 + + man directory +4 + + + 4 + + <http://www.jus.uio.no/sisu/man> + + + + + 85 + + 1.3.2 Built in help + + + + 86 + + sisu --help + + + + 87 + + sisu --help --env + + + + 88 + + sisu --help --commands + + + + 89 + + sisu --help --markup + + + + 90 + + 1.3.3 The home page + + + + 91 + + <http://www.jus.uio.no/sisu> + + + + 92 + + <http://www.jus.uio.no/sisu/SiSU> + + + + 93 + + 1.4 Markup Samples + + + + 94 + + A number of markup samples (along with output) are available off: + + + + 95 + + <http://www.jus.uio.no/sisu/SiSU/2.html> + + + + 96 + + Additional markup samples are packaged separately in the file: + + + + 97 + + * + + + + 98 + + On Debian they are available in non-free5 to include +them it is necessary to include non-free in your /etc/apt/source.list +or obtain them from the sisu home site. + + + 5 + + the Debian Free Software guidelines require that everything +distributed within Debian can be changed - and the documents are +authors' works that while freely distributable are not freely +changeable. + + + + + 0 + + Endnotes + + + + -- cgit v1.2.3