diff options
Diffstat (limited to 'man/man8/sisu_quickstart.8')
| -rw-r--r-- | man/man8/sisu_quickstart.8 | 517 |
1 files changed, 517 insertions, 0 deletions
diff --git a/man/man8/sisu_quickstart.8 b/man/man8/sisu_quickstart.8 new file mode 100644 index 00000000..e13f84e4 --- /dev/null +++ b/man/man8/sisu_quickstart.8 @@ -0,0 +1,517 @@ +.TH "sisu_quickstart" "1" "2007-09-16" "0.58.3" "SiSU - SiSU information Structuring Universe / Structured information, Serialized Units" +.SH +SISU \- SISU INFORMATION STRUCTURING UNIVERSE / STRUCTURED INFORMATION, +SERIALIZED UNITS \- QUICKSTART, INSTALLATION AND USE, +RALPH AMISSAH +.BR + +.SH +QUICKSTART \- SISU INSTALLATION AND USE +.BR + +.SH +1. QUICKSTART \- GETTING STARTED HOWTO +.BR + +.SH +1.1 INSTALLATION + +.BR +Installation is currently most straightforward and tested on the +.B Debian +platform, as there are packages for the installation of sisu and all +requirements for what it does. + +.SH +1.1.1 DEBIAN INSTALLATION + +.BR +.B SiSU +is available directly from the +.B Debian +Sid and testing archives (and possibly Ubuntu), assuming your +/etc/apt/sources.list is set accordingly: + + +.nf + aptitude update + aptitude install sisu\-complete +.fi + +.BR +The following /etc/apt/sources.list setting permits the download of additional +markup samples: + + +.nf + #/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 +.fi + +.BR +The aptitude commands become: + + +.nf + aptitude update + aptitude install sisu\-complete sisu\-markup\-samples +.fi + +.BR +If there are newer versions of +.B SiSU +upstream of the +.B Debian +archives, they will be available by adding the following to your +/etc/apt/sources.list + + +.nf + #/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 +.fi + +.BR +repeat the aptitude commands + + +.nf + aptitude update + aptitude install sisu\-complete sisu\-markup\-samples +.fi + +.BR +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. + +.SH +1.1.2 RPM INSTALLATION + +.BR +RPMs are provided though untested, they are prepared by running alien against +the source package, and against the debs. + +.BR +They may be downloaded from: + +.BR + <http://www.jus.uio.no/sisu/SiSU/download.html#rpm> + +.BR +as root type: + +.BR + rpm \-i \ [rpm \ package \ name] + +.SH +1.1.3 INSTALLATION FROM SOURCE + +.BR +To install +.B SiSU +from source check information at: + +.BR + <http://www.jus.uio.no/sisu/SiSU/download.html#current> + +.BR +* download the source package + +.BR +* Unpack the source + +.BR +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: + +.BR +For basic use +.B SiSU +is only dependent on the programming language in which it is written +.B Ruby +, and +.B 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. + +.BR +.B setup.rb + +.BR +This is a standard ruby installer, using setup.rb is a three step process. In +the root directory of the unpacked +.B SiSU +as root type: + + +.nf + ruby setup.rb config + ruby setup.rb setup + #[and \ as \ root:] + ruby setup.rb install +.fi + +.BR +further information on setup.rb is available from: + +.BR + <http://i.loveruby.net/en/projects/setup/> + +.BR + <http://i.loveruby.net/en/projects/setup/doc/usage.html> + +.BR +.B \"install\" + +.BR +The \"install\" file provided is an installer prepared using \"rant\". In the +root directory of the unpacked +.B SiSU +as root type: + +.BR + ruby install base + +.BR +or for a more complete installation: + +.BR + ruby install + +.BR +or + +.BR + ruby install base + +.BR +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. + +.BR +Further information on \"rant\" is available from: + +.BR + <http://make.rubyforge.org/> + +.BR + <http://rubyforge.org/frs/?group_id=615> + +.BR +For a list of alternative actions you may type: + +.BR + ruby install help + +.BR + ruby install \-T + +.SH +1.2 TESTING SISU, GENERATING OUTPUT + +.BR +To check which version of sisu is installed: + +.BR +sisu \-v + +.BR +Depending on your mode of installation one or a number of markup sample files +may be found either in the directory: + +.BR +... + +.BR +or + +.BR +... + +.BR +change directory to the appropriate one: + +.BR +cd /usr/share/doc/sisu/sisu_markup_samples/dfsg + +.SH +1.2.1 BASIC TEXT, PLAINTEXT, HTML, XML, ODF + +.BR +Having moved to the directory that contains the markup samples (see +instructions above if necessary), choose a file and run sisu against it + +.BR +sisu \-NhwoabxXyv free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +this will generate html including a concordance file, opendocument text format, +plaintext, XHTML and various forms of XML, and OpenDocument text + +.SH +1.2.2 LATEX / PDF + +.BR +Assuming a LaTeX engine such as tetex or texlive is installed with the required +modules (done automatically on selection of sisu\-pdf in +.B Debian +) + +.BR +Having moved to the directory that contains the markup samples (see +instructions above if necessary), choose a file and run sisu against it + +.BR +sisu \-pv free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +sisu \-3 free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +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 + +.SH +1.2.3 RELATIONAL DATABASE \- POSTGRESQL, SQLITE + +.BR +Relational databases need some setting up \- you must have permission to create +the database and write to it when you run sisu. + +.BR +Assuming you have the database installed and the requisite permissions + +.BR +sisu \-\-sqlite \-\-recreate + +.BR +sisu \-\-sqlite \-v \-\-import +free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +sisu \-\-pgsql \-\-recreate + +.BR +sisu \-\-pgsql \-v \-\-import +free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.SH +1.3 GETTING HELP + +.SH +1.3.1 THE MAN PAGES + +.BR +Type: + +.BR + man sisu + +.BR +The man pages are also available online, though not always kept as up to date +as within the package itself: + +.BR +* sisu.1 <http://www.jus.uio.no/sisu/man/sisu.1> \ [^2] + +.BR +* sisu.8 <http://www.jus.uio.no/sisu/man/sisu.8> \ [^3] + +.BR +* man directory <http://www.jus.uio.no/sisu/man> \ [^4] + +.SH +1.3.2 BUILT IN HELP + +.BR +sisu \-\-help + +.BR +sisu \-\-help \-\-env + +.BR +sisu \-\-help \-\-commands + +.BR +sisu \-\-help \-\-markup + +.SH +1.3.3 THE HOME PAGE + +.BR +<http://www.jus.uio.no/sisu> + +.BR +<http://www.jus.uio.no/sisu/SiSU> + +.SH +1.4 MARKUP SAMPLES + +.BR +A number of markup samples (along with output) are available off: + +.BR +<http://www.jus.uio.no/sisu/SiSU/2.html> + +.BR +Additional markup samples are packaged separately in the file: + +.BR +.B * + +.BR +On +.B Debian +they are available in non\-free[^5] to include them it is necessary to +include non\-free in your /etc/apt/source.list or obtain them from the sisu +home site. + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ +<http://www.jus.uio.no/sisu/sisu_manual/sisu_quickstart/sisu_manifest.html> + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- SiSU information Structuring Universe / Structured information, +Serialized Units \- Quickstart, installation and use + +.BR +DC Creator: +.I Ralph Amissah + +.BR +DC Rights: +.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL +3 + +.BR +DC Type: +.I information + +.BR +DC Date created: +.I 2006\-09\-06 + +.BR +DC Date available: +.I 2006\-09\-06 + +.BR +DC Date issued: +.I 2006\-09\-06 + +.BR +DC Date modified: +.I 2007\-09\-16 + +.BR +DC Date: +.I 2007\-09\-16 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_quickstart.sst + +.BR +Filetype: +.I SiSU text 0.57 + +.BR +Sourcefile Digest, MD5(sisu_quickstart.sst)= +.I 05a047fd659fbbeaa3cdb982b5911bcd + +.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:00 +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 +.BI 1. +There is nothing to stop MySQL support being added in future. +.TP +.BI 2. +<http://www.jus.uio.no/sisu/man/sisu.1> +.TP +.BI 3. +<http://www.jus.uio.no/sisu/man/sisu.8> +.TP +.BI 4. +<http://www.jus.uio.no/sisu/man> +.TP +.BI 5. +the +.B Debian +Free Software guidelines require that everything distributed within +.B Debian +can be changed - and the documents are authors\' works that while freely +distributable are not freely changeable. + +.TP +Other versions of this document: +.TP +manifest: <http://www.jus.uio.no/sisu/sisu_quickstart/sisu_manifest.html> +.TP +html: <http://www.jus.uio.no/sisu/sisu_quickstart/toc.html> +.TP +pdf: <http://www.jus.uio.no/sisu/sisu_quickstart/portrait.pdf> +.TP +pdf: <http://www.jus.uio.no/sisu/sisu_quickstart/landscape.pdf> +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_quickstart/sisu_quickstart.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:06 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu |