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