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/plain.txt | 476 +++++++++++++++++++++ 1 file changed, 476 insertions(+) create mode 100644 data/doc/manuals_generated/sisu_manual/sisu_quickstart/plain.txt (limited to 'data/doc/manuals_generated/sisu_manual/sisu_quickstart/plain.txt') diff --git a/data/doc/manuals_generated/sisu_manual/sisu_quickstart/plain.txt b/data/doc/manuals_generated/sisu_manual/sisu_quickstart/plain.txt new file mode 100644 index 00000000..d4f3b297 --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/sisu_quickstart/plain.txt @@ -0,0 +1,476 @@ +SISU - SISU INFORMATION STRUCTURING UNIVERSE / STRUCTURED INFORMATION, +SERIALIZED UNITS - QUICKSTART, INSTALLATION AND USE, +RALPH AMISSAH +****************************************************************************** + +QUICKSTART - SISU INSTALLATION AND USE +====================================== + +1. QUICKSTART - GETTING STARTED HOWTO +------------------------------------- + +1.1 INSTALLATION +................ + +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. + + +1.1.1 DEBIAN INSTALLATION +......................... + +*SiSU* is available directly from the *Debian* Sid and testing archives (and +possibly Ubuntu), assuming your /etc/apt/sources.list is set accordingly: + + + + aptitude update + aptitude install sisu-complete + +The following /etc/apt/sources.list setting permits the download of additional +markup samples: + + + + #/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 + +The aptitude commands become: + + + + aptitude update + aptitude install sisu-complete sisu-markup-samples + +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 + + + + #/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 + +repeat the aptitude commands + + + + aptitude update + aptitude install sisu-complete sisu-markup-samples + +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. + + +1.1.2 RPM INSTALLATION +...................... + +RPMs are provided though untested, they are prepared by running alien against +the source package, and against the debs. + + +They may be downloaded from: + + + + + +as root type: + + + rpm -i [rpm package name] + + +1.1.3 INSTALLATION FROM SOURCE +.............................. + +To install *SiSU* from source check information at: + + + + + +* download the source package + + +* Unpack the source + + +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: + + +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. + +*setup.rb* + + +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: + + + + ruby setup.rb config + ruby setup.rb setup + #[and as root:] + ruby setup.rb install + +further information on setup.rb is available from: + + + + + + + + +*"install"* + + +The "install" file provided is an installer prepared using "rant". In the root +directory of the unpacked *SiSU* as root type: + + + ruby install base + + +or for a more complete installation: + + + ruby install + + +or + + + ruby install base + + +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. + + +Further information on "rant" is available from: + + + + + + + + +For a list of alternative actions you may type: + + + ruby install help + + + ruby install -T + + +1.2 TESTING SISU, GENERATING OUTPUT +................................... + +To check which version of sisu is installed: + + +sisu -v + + +Depending on your mode of installation one or a number of markup sample files +may be found either in the directory: + + +... + + +or + + +... + + +change directory to the appropriate one: + + +cd /usr/share/doc/sisu/sisu_markup_samples/dfsg + + +1.2.1 BASIC TEXT, PLAINTEXT, HTML, XML, ODF +........................................... + +Having moved to the directory that contains the markup samples (see +instructions above if necessary), choose a file and run sisu against it + + +sisu -NhwoabxXyv free_as_in_freedom.rms_and_free_software.sam_williams.sst + + +this will generate html including a concordance file, opendocument text format, +plaintext, XHTML and various forms of XML, and OpenDocument text + + +1.2.2 LATEX / PDF +................. + +Assuming a LaTeX engine such as tetex or texlive is installed with the required +modules (done automatically on selection of sisu-pdf in *Debian*) + + +Having moved to the directory that contains the markup samples (see +instructions above if necessary), choose a file and run sisu against it + + +sisu -pv free_as_in_freedom.rms_and_free_software.sam_williams.sst + + +sisu -3 free_as_in_freedom.rms_and_free_software.sam_williams.sst + + +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 + + +1.2.3 RELATIONAL DATABASE - POSTGRESQL, SQLITE +.............................................. + +Relational databases need some setting up - you must have permission to create +the database and write to it when you run sisu. + + +Assuming you have the database installed and the requisite permissions + + +sisu --sqlite --recreate + + +sisu --sqlite -v --import +free_as_in_freedom.rms_and_free_software.sam_williams.sst + + +sisu --pgsql --recreate + + +sisu --pgsql -v --import +free_as_in_freedom.rms_and_free_software.sam_williams.sst + + +1.3 GETTING HELP +................ + +1.3.1 THE MAN PAGES +................... + +Type: + + + man sisu + + +The man pages are also available online, though not always kept as up to date +as within the package itself: + + +* sisu.1 [link:] [^2] + + +- [2]: + +* sisu.8 [link:] [^3] + + +- [3]: + +* man directory [link:] [^4] + + +- [4]: + +1.3.2 BUILT IN HELP +................... + +sisu --help + + +sisu --help --env + + +sisu --help --commands + + +sisu --help --markup + + +1.3.3 THE HOME PAGE +................... + + + + + + + +1.4 MARKUP SAMPLES +.................. + +A number of markup samples (along with output) are available off: + + + + + +Additional markup samples are packaged separately in the file: + + +*** + + +On *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. + + +- [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. + +DOCUMENT INFORMATION (METADATA) +******************************* + +METADATA +-------- + +Document Manifest @ + + + +*Dublin Core* (DC) + + +/DC tags included with this document are provided here./ + + +DC Title: _SiSU - SiSU information Structuring Universe / Structured +information, Serialized Units - Quickstart, installation and use_ + + +DC Creator: _Ralph Amissah_ + + +DC Rights: _Copyright (C) Ralph Amissah 2007, part of SiSU documentation, +License GPL 3_ + + +DC Type: _information_ + + +DC Date created: _2006-09-06_ + + +DC Date available: _2006-09-06_ + + +DC Date issued: _2006-09-06_ + + +DC Date modified: _2007-09-16_ + + +DC Date: _2007-09-16_ + + +*Version Information* + + +Sourcefile: _sisu_quickstart.sst_ + + +Filetype: _SiSU text 0.57_ + + +Sourcefile Digest, MD5(sisu_quickstart.sst)= _05a047fd659fbbeaa3cdb982b5911bcd_ + + +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 04:11:02 +0100 2007_ + + +Generated by: _SiSU_ _0.59.0_ of 2007w38/0 (2007-09-23) + + +Ruby version: _ ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux]_ + + + +============================================================================== + + 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 + + + + + +============================================================================== +nil + +Other versions of this document: +manifest: + http://www.jus.uio.no/sisu/sisu_quickstart/sisu_manifest.html +html: + http://www.jus.uio.no/sisu/sisu_quickstart/toc.html +pdf: + http://www.jus.uio.no/sisu/sisu_quickstart/portrait.pdf + http://www.jus.uio.no/sisu/sisu_quickstart/landscape.pdf +plaintext (plain text): + http://www.jus.uio.no/sisu/sisu_quickstart/plain.txt +at: + http://www.jus.uio.no/sisu +* Generated by: SiSU 0.59.0 of 2007w38/0 (2007-09-23) +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +* Last Generated on: Sun Sep 23 04:11:51 +0100 2007 +* SiSU http://www.jus.uio.no/sisu -- cgit v1.2.3