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