mention of rake
[software/sisu] / README
1 SiSU 0.55 2007w27/6 2007-07-07
2 homepage: <http://www.jus.uio.no/sisu>
3
4 %% Description
5 ---------------
6
7 SiSU is lightweight markup based document creation and publishing framework
8 that is controlled from the command line. Prepare documents for SiSU using
9 your text editor of choice, then use SiSU to generate various output document
10 formats.
11
12 With minimal preparation of a plain-text (UTF-8) file using its native
13 markup-syntax, SiSU produces: plain-text, HTML, XHTML, XML, ODF:ODT
14 (Opendocument), LaTeX, PDF, and populates an SQL database (PostgreSQL or
15 SQLite) in paragraph sized chunks so that document searches are done at this
16 "atomic" level of granularity.
17
18 Outputs share a common citation numbering system, and any semantic meta-data
19 provided about the document.
20
21 SiSU also provides concordance files, document content certificates and
22 manifests of generated output.
23
24 SiSU takes advantage of well established open standard ways of representing
25 text, and provides a bridge to take advantage of the strengths of each,
26 while remaining simple. SiSU implements across document formats a "useful
27 common feature set" [coming from a humanities, law, and possibly social
28 sciences perspective, rather than technical or scientific writing] ...
29 focus is primarily on content and data integrity rather than appearance,
30 (though outputs in the various formats are respectable).
31
32 A vim syntax highlighting file and an ftplugin with folds for sisu markup is
33 provided. Vim 7 includes syntax highlighting for SiSU.
34
35 man pages, and interactive help are provided.
36
37 Dependencies for various features are taken care of in sisu related packages.
38 The package sisu-complete installs the whole of SiSU.
39
40 Additional document markup samples are provided in the package
41 sisu-markup-samples which is found in the non-free archive the licenses for
42 the substantive content of the marked up documents provided is that provided
43 by the author or original publisher.
44
45 Homepage: <http://www.jus.uio.no/sisu>
46
47 -----
48
49 SiSU - simple information structuring universe, is a publishing tool, document
50 generation and management, (and search enabling) tool primarily for literary,
51 academic and legal works.
52
53 SiSU can be used for Internet, Intranet, local filesystem or cd publishing.
54
55 SiSU can be used directly off the filesystem, or from a database.
56
57 SiSU's scalability, is be dependent on your hardware, and filesystem (in my
58 case Reiserfs), and/or database Postgresql.
59
60 Amongst it's characteristics are:
61
62 * simple mnemonoic markup style,
63
64 * the ability to produce multiple output formats, including
65 html, structured XML, LaTeX, pdf (via LaTeX), stream to a relational database
66 whilst retaining document structure - Postgresql and Sqlite,
67
68 * that all share a common citation system (a simple idea from which much good),
69 possibly most exciting, the following: if fed into a relational database (as it
70 can be automatically), the document set is searchable, with results displayed
71 at a paragraph level, or the possibility of an indexed display of documents in
72 which the match is found together with a hyperlinked listing for each of each
73 paragraph in which the match is found. In any event citations using this system
74 (with or without the relational database) are relevant for all output formats.
75
76 * it is command line driven, and can be set up on a remote server
77
78 * Documents are marked up in SiSU syntax in your favourite editor. SiSU syntax
79 may be regarded as a type of smart ascii - which in its basic form is simpler
80 than the most elementary html. There is currently a syntax highlighter, and
81 folding for Vim. Syntax highlighters for other editors are welcome.
82
83 Input files should be UTF-8
84
85 Once set up it is simple to use.
86
87 %% Online Information, places to look
88 ---------------
89
90 <http://www.jus.uio.no/sisu>
91
92 Download Sources:
93 <http://www.jus.uio.no/sisu/SiSU/download.html#current>
94 <http://www.jus.uio.no/sisu/SiSU/download.html#debian>
95
96 %% Installation
97 ---------------
98 NB. Platform is Unix / Linux.
99
100 %% Debian
101 ---------------
102 If you use Debian use the Debian packages,
103 check the information at:
104 <http://www.jus.uio.no/sisu/SiSU/download.html#debian>
105
106 (A) SiSU is available directly off the Debian archives for Sid and testing. It
107 should necessary only to run as root:
108
109 aptitude update
110 aptitude install sisu-complete
111
112 (B) If there are newer versions of SiSU upstream of the Debian archives, they
113 will be available by adding the following to your /etc/apt/sources.list
114
115 deb http://www.jus.uio.no/sisu/archive unstable main non-free
116 deb-src http://www.jus.uio.no/sisu/archive unstable main non-free
117
118 [the non-free line is for document markup
119 samples, for which the substantive text is
120 provided under the author or original
121 publisher's license and which in most cases will
122 not be debian free software guideline compliant]
123
124 Then as root run:
125 aptitude update
126 aptitude install sisu-complete
127
128 %% RPM
129 ---------------
130 RPMs are provided though untested, they are prepared by running alien against the
131 source package, and against the debs.
132
133 They may be downloaded from:
134 <http://www.jus.uio.no/sisu/SiSU/download.html#rpm>
135
136 %% Source package .tgz
137 ---------------
138 Otherwise to install SiSU from source, check information at:
139 <http://www.jus.uio.no/sisu/SiSU/download.html#current>
140
141 alternative modes of installation from source are provided,
142 setup.rb (by Minero Aoki),
143 rake (by Jim Weirich) built install file,
144 rant (by Stefan Lang) built install file,
145
146 Ruby is the essential dependency for the basic operation of SiSU
147
148 1. Download the latest source (information available) from:
149 <http://www.jus.uio.no/sisu/SiSU/download.html#current>
150
151 2. Unpack the source
152
153 Note however, that additional external package dependencies,
154 such as texlive or postgresql should you desire to use it
155 are not taken care of for you.
156
157 %% to use setup.rb
158 ---------------
159 this is a three step process,
160 in the root directory of the unpacked SiSU as root type:
161
162 ruby setup.rb config
163 ruby setup.rb setup
164 #[as root:]
165 ruby setup.rb install
166
167 further information:
168 <http://i.loveruby.net/en/projects/setup/>
169 <http://i.loveruby.net/en/projects/setup/doc/usage.html>
170
171 %% to use install (prapared with "Rake")
172 ---------------
173 Rake must be installed on your system:
174 <http://rake.rubyforge.org/>
175 <http://rubyforge.org/frs/?group_id=50>
176
177 in the root directory of the unpacked SiSU as root type:
178 rake
179
180 or
181 rake base
182
183 This makes use of Rake (by Jim Weirich) and the provided Rakefile
184
185 For a list of alternative actions you may type:
186 rake help
187 rake -T
188
189 %% to use install (prapared with "Rant")
190 ---------------
191 (you may use the instructions above for rake substituting rant if rant is
192 installed on your system, or you may use an independent installer created using
193 rant as follows:)
194
195 in the root directory of the unpacked SiSU as root type:
196 ruby ./sisu-install
197
198 or
199 ruby ./sisu-install base
200
201 This makes use of Rant (by Stefan Lang) and the provided Rantfile. It has been
202 configured to do post installation setup setup configuration and generation of
203 first test file. Note however, that additional external package dependencies,
204 such as tetex-extra are not taken care of for you.
205
206 further information:
207 <http://make.rubyforge.org/>
208 <http://rubyforge.org/frs/?group_id=615>
209
210 For a list of alternative actions you may type:
211 ruby ./sisu-install help
212 ruby ./sisu-install -T
213
214 Dependencies
215 --------------
216 Once installed see 'man 8 sisu' for some information on additional programs
217 that sisu makes use of, and that you may need or wish to install. (this will
218 depend on such factors as whether you want to generate pdf, whether you will be
219 using SiSU with or without a database, ...) 'man sisu_markup-samples' may also be of
220 interest if the sisu-markup-samples package has also been installed.
221
222 The information in man 8 may not be most up to date, and it is possible that
223 more useful information can be gleaned from the following notes taken from the
224 Debian control file (end edited), gives an idea of additional packages that
225 SiSU can make use of if available, (the use/requirement of some of which are
226 interdependent for specific actions by SiSU):
227
228 Package: sisu
229 Architecture: all
230 Depends: ruby (>= 1.8.2), libwebrick-ruby, unzip, zip
231 Conflicts: vim-sisu, sisu-vim, sisu-remote
232 Replaces: vim-sisu, sisu-vim
233 Recommends: sisu-pdf, sisu-sqlite, sisu-postgresql, librmagick-ruby, trang,
234 tidy, librexml-ruby, openssl, rsync, openssh-client | lsh-client, keychain,
235 hyperestraier, kdissert, vim-addon-manager
236 Suggests: rcs | cvs, lv, texinfo, pinfo
237
238 Package: sisu-complete
239 Depends: ruby (>= 1.8.4), sisu, sisu-pdf, sisu-postgresql, sisu-sqlite
240 Recommends: hyperestraier
241
242 Package: sisu-pdf
243 Architecture: all
244 Depends: sisu, texlive-latex-base, texlive-fonts-recommended,
245 texlive-latex-recommended, texlive-latex-extra
246 Suggests: evince, xpdf
247
248 Package: sisu-postgresql
249 Depends: sisu, postgresql-8.1, libdbi-ruby, libdbm-ruby, libdbd-pg-ruby
250 Suggests: pgaccess, libdbd-pgsql, postgresql-contrib-8.1
251
252 Package: sisu-sqlite
253 Depends: sisu, sqlite, libdbi-ruby, libdbm-ruby, libdbd-sqlite-ruby
254 Suggests: libdbd-sqlite
255
256 Package: sisu-markup-samples
257 Depends: sisu
258
259 %% Quick start
260 ---------------
261 Most of the installation should be taken care of by the aptitude or rant
262 install. (The rant install if run in full will also test run the generation of
263 the first document).
264
265 After installation of sisu-complete, move to the document samples directory
266
267 cd /usr/share/doc/sisu/sisu_markup_samples/dfsg
268
269 and run
270
271 sisu -3 free_as_in_freedom.rms_and_free_software.sam_williams.sst
272
273 [or the same:
274 sisu -NhwpoabxXyv free_as_in_freedom.rms_and_free_software.sam_williams.sst
275 ]
276
277 look at output results, see the "sisu_manifest" page created for the document
278
279 or to generate an online document move to a writable directory, as the file
280 will be downloaded there and e.g.
281
282 sisu -3 http://www.jus.uio.no/sisu/free_culture.lawrence_lessig/free_culture.lawrence_lessig.sst
283
284 the database stuff is extra perhaps, the latex stuff could be considered extra
285 perhaps but neither needs to be installed for most of sisu output to work
286
287 examine source document, vim has syntax support
288
289 gvim free_as_in_freedom.rms_and_free_software.sam_williams.sst
290
291 additional markup samples in
292 <http://www.jus.uio.no/sisu/SiSU/2.html>
293
294 For help
295 man sisu
296
297 or
298 sisu --help
299
300 e.g.
301 sisu --help env
302 for the way sisu "sees/maps" your system
303 sisu --help commands
304 for list of commands and so on
305
306 %% Configuration files
307 ---------------
308
309 The default configuration/setup is contained within the program and is altered
310 by configuration settings in /etc/[sisu version]/sisurc.yml
311 or in ~/.sisu/sisurc.yml
312
313 * configuration file - a yaml file
314 /etc/sisu/[sisu version]/sisurc.yml
315 ~/.sisu/sisurc.yml
316
317 * directory structure - setting up of output and working directory.
318
319 * skins - changing the appearance of a project, directory or individual
320 documents within ~/.sisu/skin
321 ~/.sisu/skin/doc contains individual skins, with symbolic links from
322 ~/.sisu/skin/dir if the contents of a directory are to take a particular
323 document skin.
324
325 * additional software - eg. Tex and LaTeX (tetex, tetex-base, tetex-extra on
326 Debian), Postgresql, [sqlite], trang, tidy, makeinfo, ... none of which are
327 required for basic html or XML processing.
328
329 * if you use Vim as editor there is a syntax highlighter and fold resource
330 config file for SiSU. I hope more syntax highlighters follow.
331
332 There are post installation steps (which are really part of the overall
333 installation)
334
335 sisu -C in your marked up document directory, should do some auto-configuring
336 provided you have the right permissions for the output directories. (and
337 provided the output directories have already been specified if you are not
338 using the defaults).
339
340 %% Use General Overview
341 ---------------
342 Documents are marked up in SiSU syntax and kept in an ordinary text editable
343 file, named with the suffix .sst, or .ssm
344
345 Marked up SiSU documents are usually kept in a sub-directory of your choosing
346
347 use the interactive help and man pages
348 sisu --help
349 man sisu
350
351 %% Help
352 ---------------
353
354 interactive help described below, or man page:
355
356 man sisu
357
358 man 8 sisu
359 'man sisu_markup-samples' [if the sisu-markup-samples package is also installed]
360
361 Once installed an interactive help is available typing 'sisu' (without) any
362 flags, and select an option:
363
364 sisu
365
366 alternatively, you could type e.g.
367 sisu --help commands
368 sisu --help env
369 sisu --help headers
370 sisu --help markup
371 sisu --help headings
372 etc.
373
374 for questions about mappings, output paths etc.
375 sisu --help env
376 sisu --help path
377 sisu --help directory
378
379 %% Directory Structure
380 ---------------
381 Once installed, type:
382 sisu --help env
383 or
384 sisu -V
385
386 %% Configuration File
387 ---------------
388
389 The defaults can be changed via SiSU's configure file sisurc.yml which the
390 program expects to find in ./_sisu ~/.sisu or /etc/sisu (searched in that
391 order, stopping on the first one found)
392
393 %% Markup
394 ---------------
395
396 See man pages.
397 man sisu
398
399 man 8 sisu
400
401 Once installed there is some information on SiSU Markup in its help:
402 sisu --help markup
403 and
404 sisu --help headers
405
406 Sample marked up document are provided with the download tarball in the
407 directory:
408 ./data/doc/sisu/sisu_markup_samples/dfsg
409
410 These are installed on the system usually at:
411 /usr/share/doc/sisu/sisu_markup_samples/dfsg
412
413 More markup samples are available in the package sisu-markup-samples
414 <http://www.jus.uio.no/sisu/SiSU/download.html#sisu-markup-samples>
415
416 Many more are available online off:
417 <http://www.jus.uio.no/sisu/SiSU/2.html>
418
419 %% Additional Things
420 ---------------
421
422 There is syntax support for some editors provided (together with a README file) in
423
424 ./data/sisu/conf/syntax
425
426 usually installed to:
427
428 /usr/share/sisu/conf/syntax
429
430 %% License
431 ---------------
432
433 License: GPL 3 or later see the copyright file in
434
435 ./data/doc/sisu
436
437 usually installed to:
438
439 /usr/share/doc/sisu
440
441 %% SiSU Standard
442 -----------------
443
444 SiSU uses:
445
446 * Standard SiSU markup syntax,
447 * Standard SiSU meta-markup syntax, and the
448 * Standard SiSU object citation numbering and system
449
450 © Ralph Amissah 1997, current 2006.
451 All Rights Reserved.
452
453 * however note the License section
454
455 CHANGELOG
456 ./CHANGELOG
457 and see
458 <http://www.jus.uio.no/sisu/SiSU/changelog.html>
459 <http://www.jus.uio.no/sisu/SiSU/changelog_markup_samples.html>