introducing version 2, major patch, (version 1 libraries retained)
[software/sisu] / README
1 %% SiSU versions 1 & 2, 2010
2 Homepage: <http://www.jus.uio.no/sisu>
3 * README CHANGELOG CHANGELOG_v1 CHANGELOG_v2
4
5 Herein (this package) reside SiSU versions 1 and 2.
6
7 %% Description
8 ---------------
9
10 SiSU is lightweight markup based document creation and publishing framework
11 that is controlled from the command line. Prepare documents for SiSU using
12 your text editor of choice, then use SiSU to generate various output document
13 formats.
14
15 With minimal preparation of a plain-text (UTF-8) file using its native
16 markup-syntax, SiSU produces: plain-text, HTML, XHTML, XML, EPUB (v2 only)
17 ODF:ODT (Opendocument), LaTeX, PDF, and populates an SQL database (PostgreSQL
18 or SQLite) with text objects, roughly, paragraph sized chunks so that
19 document searches are done at this level of granularity.
20
21 Outputs share a common citation numbering system, associated with text
22 objects and any semantic meta-data provided about the document.
23
24 SiSU also provides concordance files, document content certificates and
25 manifests of generated output. Book indexes may be made.
26
27 SiSU takes advantage of well established open standard ways of representing
28 text, and provides a bridge to take advantage of the strengths of each,
29 while retaining minimal markup requirement. SiSU implements a "useful
30 common feature set" across document formats [coming from a humanities, law,
31 and possibly social sciences perspective, rather than technical or
32 scientific writing] ... focus is primarily on content and data integrity
33 rather than appearance, (though outputs in the various formats are
34 respectable).
35
36 Syntax highlighting files for a number of editors are provided.
37 A vim syntax highlighting file and an ftplugin with folds for sisu markup is
38 provided. Vim 7 includes syntax highlighting for SiSU.
39
40 man pages, and interactive help are provided.
41
42 Dependencies for various features are taken care of in sisu related packages.
43 The package sisu-complete installs the whole of SiSU.
44
45 Additional document markup samples are provided in the package
46 sisu-markup-samples which is found in the non-free archive the licenses for
47 the substantive content of the marked up documents provided is that provided
48 by the author or original publisher.
49
50 Homepage: <http://www.jus.uio.no/sisu>
51
52 %% Take 2
53 ---------
54
55 The ideas behind SiSU evolved working with managing static, published documents
56 that needed to be citable, ideally searchable and preferably available in
57 multiple formats over a period of time with a rapidly changing World Wide Web.
58 Initial experience was in 1993, one issue being that the document content
59 remained the same, but presentation needed to be updated with changing formats,
60 html in particular has really changed since then.
61
62 So the idea was to provide a minimal markup requirement for documents that
63 remained the same, and a generator to convert that markup custom producing
64 various output types. This made it possible to:
65
66 * have a marked-up document set and continue improving the presentation, as the
67 generators code was updated, e.g. update HTML as it evolves, and improve upon
68 LaTeX driven pdf output
69
70 * have available new document formats/ output types as they came to be of
71 interest, e.g. version 2 includes EPUB
72
73 * produce a citation system that is available across different output types,
74 text based on objects (rather than page numbers), i.e. you can accurately and
75 reliably cite text within a document regardless of the document format version
76 that is being looked at
77
78 * take advantage of the strengths of disparate technologies representing text,
79 each output type being custom generated for that format, the object citation
80 system lends itself as a result is that there is little necessity that one
81 output type should be based on or related to another, just that the content is
82 preserved and presented in a way that is well suited to the output type in
83 question
84
85 * produce consistent quality presentation for material, suitable where
86 substance/content is more important than appearance, there is some sacrifice of
87 flexibility and no concept of wysiwyg, e.g. there is no attempt to make pdf
88 output identical to html, rather the system attempts to take advantage of
89 making the best presentation it can in each output format taking advantage of
90 the strengths of that format available to it given the minimal markup (sisu
91 document preparation); the citation system ensures you can pinpoint the same
92 text
93
94 SiSU works best:
95
96 * with published works (e.g. books, articles), static documents the content of
97 which is changed rarely, and ideally when they do in the form of a new edition.
98
99 * for literature and law related content
100
101 SiSU uses Unicode, utf-8 where it is available,
102 -----
103
104 SiSU - simple information structuring universe, is a publishing tool, document
105 generation and management, (and search enabling) tool primarily for literary,
106 academic and legal published works.
107
108 SiSU can be used for Internet, Intranet, local filesystem or cd publishing.
109
110 SiSU can be used directly off the filesystem, or from a database.
111
112 SiSU's scalability, is be dependent on your hardware, and filesystem and/or
113 database Postgresql.
114
115 Amongst it's characteristics are:
116
117 * simple mnemonoic markup style,
118
119 * the ability to produce multiple output formats, including html, XML, EPUB,
120 LaTeX, pdf (via LaTeX), stream to a relational database whilst retaining
121 document structure - Postgresql and Sqlite,
122
123 * that all share a common citation system (a simple idea from which much good),
124 possibly most exciting, the following: if fed into a relational database (as it
125 can be automatically), the document set is searchable, with results displayed
126 at a paragraph level, or the possibility of an indexed display of documents
127 identifying the paragraph in which the match is found (using the object
128 citation numbering system) together with a hyperlinked listing for each of each
129 paragraph in which the match is found. In any event citations using this system
130 (with or without the relational database) are relevant for all output formats.
131
132 * it is command line driven, and can be set up on a remote server
133
134 * Documents are marked up in SiSU syntax in your favourite editor. SiSU syntax
135 may be regarded as a type of smart ascii - which in its basic form is simpler
136 than the most elementary html. There is currently a syntax highlighter, and
137 folding for Vim. Syntax highlighters for other editors are welcome.
138
139 Input files should be UTF-8
140
141 Once set up it is simple to use.
142
143 %% Information, places to look
144 ---------------
145
146 Within the SiSU tarball:
147
148 ./data/doc/sisu/v2/sisu_markup_samples/sisu_manual
149
150 Once installed, directory equivalent to:
151
152 <file:///usr/share/doc/sisu/v2/sisu_markup_samples/sisu_manual/>
153
154 Available man pages are converted back to html using man2html:
155
156 <file:///usr/share/doc/sisu/v2/html/>
157
158 ./data/doc/sisu/v2/html/
159
160 %% Online Information, places to look
161 ---------------
162
163 <http://www.jus.uio.no/sisu>
164
165 Download Sources:
166 <http://www.jus.uio.no/sisu/SiSU/download.html#current>
167 <http://www.jus.uio.no/sisu/SiSU/download.html#debian>
168
169 %% Installation
170 ---------------
171 NB. Platform is Unix / Linux.
172
173 %% Debian
174 ---------------
175 If you use Debian use the Debian packages,
176 check the information at:
177 <http://www.jus.uio.no/sisu/SiSU/download.html#debian>
178
179 (A) SiSU is available directly off the Debian archives for Sid and testing. It
180 should necessary only to run as root:
181
182 aptitude update
183 aptitude install sisu-complete
184
185 (B) If there are newer versions of SiSU upstream of the Debian archives, they
186 will be available by adding the following to your /etc/apt/sources.list
187
188 deb http://www.jus.uio.no/sisu/archive unstable main non-free
189 deb-src http://www.jus.uio.no/sisu/archive unstable main non-free
190
191 [the non-free line is for document markup
192 samples, for which the substantive text is
193 provided under the author or original
194 publisher's license and which in most cases will
195 not be debian free software guideline compliant]
196
197 Then as root run:
198 aptitude update
199 aptitude install sisu-complete
200
201 %% RPM
202 ---------------
203 RPMs are provided though untested, they are prepared by running alien against the
204 source package, and against the debs.
205
206 They may be downloaded from:
207 <http://www.jus.uio.no/sisu/SiSU/download.html#rpm>
208
209 %% Source package .tgz
210 ---------------
211 Otherwise to install SiSU from source, check information at:
212 <http://www.jus.uio.no/sisu/SiSU/download.html#current>
213
214 alternative modes of installation from source are provided,
215 setup.rb (by Minero Aoki),
216 rake (by Jim Weirich) built install file,
217 rant (by Stefan Lang) built install file,
218
219 Ruby is the essential dependency for the basic operation of SiSU
220
221 1. Download the latest source (information available) from:
222 <http://www.jus.uio.no/sisu/SiSU/download.html#current>
223
224 2. Unpack the source
225
226 Note however, that additional external package dependencies,
227 such as texlive or postgresql should you desire to use it
228 are not taken care of for you.
229
230 %% to use setup.rb
231 ---------------
232 this is a three step process,
233 in the root directory of the unpacked SiSU as root type:
234
235 ruby setup.rb config
236 ruby setup.rb setup
237 #[as root:]
238 ruby setup.rb install
239
240 further information:
241 <http://i.loveruby.net/en/projects/setup/>
242 <http://i.loveruby.net/en/projects/setup/doc/usage.html>
243
244 %% to use install (prapared with "Rake")
245 ---------------
246 Rake must be installed on your system:
247 <http://rake.rubyforge.org/>
248 <http://rubyforge.org/frs/?group_id=50>
249
250 in the root directory of the unpacked SiSU as root type:
251 rake
252
253 or
254 rake base
255
256 This makes use of Rake (by Jim Weirich) and the provided Rakefile
257
258 For a list of alternative actions you may type:
259 rake help
260 rake -T
261
262 %% to use install (prapared with "Rant")
263 ---------------
264 (you may use the instructions above for rake substituting rant if rant is
265 installed on your system, or you may use an independent installer created using
266 rant as follows:)
267
268 in the root directory of the unpacked SiSU as root type:
269 ruby ./sisu-install
270
271 or
272 ruby ./sisu-install base
273
274 This makes use of Rant (by Stefan Lang) and the provided Rantfile. It has been
275 configured to do post installation setup setup configuration and generation of
276 first test file. Note however, that additional external package dependencies,
277 such as tetex-extra are not taken care of for you.
278
279 further information:
280 <http://make.rubyforge.org/>
281 <http://rubyforge.org/frs/?group_id=615>
282
283 For a list of alternative actions you may type:
284 ruby ./sisu-install help
285 ruby ./sisu-install -T
286
287 Dependencies
288 --------------
289 Once installed see 'man 8 sisu' for some information on additional programs
290 that sisu makes use of, and that you may need or wish to install. (this will
291 depend on such factors as whether you want to generate pdf, whether you will be
292 using SiSU with or without a database, ...) 'man sisu_markup-samples' may also be of
293 interest if the sisu-markup-samples package has also been installed.
294
295 The information in man 8 may not be most up to date, and it is possible that
296 more useful information can be gleaned from the following notes taken from the
297 Debian control file (end edited), gives an idea of additional packages that
298 SiSU can make use of if available, (the use/requirement of some of which are
299 interdependent for specific actions by SiSU):
300
301 Package: sisu
302 Architecture: all
303 Depends: ruby (>= 1.8.2), libwebrick-ruby, unzip, zip
304 Conflicts: vim-sisu, sisu-vim, sisu-remote
305 Replaces: vim-sisu, sisu-vim
306 Recommends: sisu-pdf, sisu-sqlite, sisu-postgresql, librmagick-ruby, trang,
307 tidy, librexml-ruby, openssl, rsync, openssh-client | lsh-client, keychain,
308 hyperestraier, kdissert, vim-addon-manager
309 Suggests: rcs | cvs, lv, texinfo, pinfo
310
311 Package: sisu-complete
312 Depends: ruby (>= 1.8.4), sisu, sisu-pdf, sisu-postgresql, sisu-sqlite
313 Recommends: hyperestraier
314
315 Package: sisu-pdf
316 Architecture: all
317 Depends: sisu, texlive-latex-base, texlive-fonts-recommended,
318 texlive-latex-recommended, texlive-latex-extra
319 Suggests: evince, xpdf
320
321 Package: sisu-postgresql
322 Depends: sisu, postgresql-8.1, libdbi-ruby, libdbm-ruby, libdbd-pg-ruby
323 Suggests: pgaccess, libdbd-pgsql, postgresql-contrib-8.1
324
325 Package: sisu-sqlite
326 Depends: sisu, sqlite, libdbi-ruby, libdbm-ruby, libdbd-sqlite-ruby
327 Suggests: libdbd-sqlite
328
329 Package: sisu-markup-samples
330 Depends: sisu
331
332 %% Quick start
333 ---------------
334 Most of the installation should be taken care of by the aptitude or rant
335 install. (The rant install if run in full will also test run the generation of
336 the first document).
337
338 After installation of sisu-complete, move to the document samples directory
339
340 cd /usr/share/doc/sisu/v2/sisu_markup_samples/dfsg
341
342 and run
343
344 sisu -3 free_as_in_freedom.rms_and_free_software.sam_williams.sst
345
346 [or the same:
347 sisu -NhwpoabxXyv free_as_in_freedom.rms_and_free_software.sam_williams.sst
348 ]
349
350 look at output results, see the "sisu_manifest" page created for the document
351
352 or to generate an online document move to a writable directory, as the file
353 will be downloaded there and e.g.
354
355 sisu -3 http://www.jus.uio.no/sisu/free_culture.lawrence_lessig/free_culture.lawrence_lessig.sst
356
357 the database stuff is extra perhaps, the latex stuff could be considered extra
358 perhaps but neither needs to be installed for most of sisu output to work
359
360 examine source document, vim has syntax support
361
362 gvim free_as_in_freedom.rms_and_free_software.sam_williams.sst
363
364 additional markup samples in
365 <http://www.jus.uio.no/sisu/SiSU/2.html>
366
367 For help
368 man sisu
369
370 or
371 sisu --help
372
373 e.g.
374 sisu --help env
375 for the way sisu "sees/maps" your system
376 sisu --help commands
377 for list of commands and so on
378
379 %% Configuration files
380 ---------------
381
382 The default configuration/setup is contained within the program and is altered
383 by configuration settings in /etc/[sisu version]/sisurc.yml
384 or in ~/.sisu/sisurc.yml
385
386 * configuration file - a yaml file
387 /etc/sisu/[sisu version]/sisurc.yml
388 ~/.sisu/sisurc.yml
389
390 * directory structure - setting up of output and working directory.
391
392 * skins - changing the appearance of a project, directory or individual
393 documents within ~/.sisu/skin
394 ~/.sisu/skin/doc contains individual skins, with symbolic links from
395 ~/.sisu/skin/dir if the contents of a directory are to take a particular
396 document skin.
397
398 * additional software - eg. Tex and LaTeX (tetex, tetex-base, tetex-extra on
399 Debian), Postgresql, [sqlite], trang, tidy, makeinfo, ... none of which are
400 required for basic html or XML processing.
401
402 * if you use Vim as editor there is a syntax highlighter and fold resource
403 config file for SiSU. I hope more syntax highlighters follow.
404
405 There are post installation steps (which are really part of the overall
406 installation)
407
408 sisu -C in your marked up document directory, should do some auto-configuring
409 provided you have the right permissions for the output directories. (and
410 provided the output directories have already been specified if you are not
411 using the defaults).
412
413 %% Use General Overview
414 ---------------
415 Documents are marked up in SiSU syntax and kept in an ordinary text editable
416 file, named with the suffix .sst, or .ssm
417
418 Marked up SiSU documents are usually kept in a sub-directory of your choosing
419
420 use the interactive help and man pages
421 sisu --help
422 man sisu
423
424 %% Help
425 ---------------
426
427 interactive help described below, or man page:
428
429 man sisu
430
431 man 8 sisu
432 'man sisu_markup-samples' [if the sisu-markup-samples package is also installed]
433
434 Once installed an interactive help is available typing 'sisu' (without) any
435 flags, and select an option:
436
437 sisu
438
439 alternatively, you could type e.g.
440 sisu --help commands
441 sisu --help env
442 sisu --help headers
443 sisu --help markup
444 sisu --help headings
445 etc.
446
447 for questions about mappings, output paths etc.
448 sisu --help env
449 sisu --help path
450 sisu --help directory
451
452 %% Directory Structure
453 ---------------
454 Once installed, type:
455 sisu --help env
456 or
457 sisu -V
458
459 %% Configuration File
460 ---------------
461
462 The defaults can be changed via SiSU's configure file sisurc.yml which the
463 program expects to find in ./_sisu ~/.sisu or /etc/sisu (searched in that
464 order, stopping on the first one found)
465
466 %% Markup
467 ---------------
468
469 See man pages.
470 man sisu
471
472 man 8 sisu
473
474 Once installed there is some information on SiSU Markup in its help:
475 sisu --help markup
476 and
477 sisu --help headers
478
479 Sample marked up document are provided with the download tarball in the
480 directory:
481 ./data/doc/sisu/v2/sisu_markup_samples/dfsg
482
483 These are installed on the system usually at:
484 /usr/share/doc/sisu/v2/sisu_markup_samples/dfsg
485
486 More markup samples are available in the package sisu-markup-samples
487 <http://www.jus.uio.no/sisu/SiSU/download.html#sisu-markup-samples>
488
489 Many more are available online off:
490 <http://www.jus.uio.no/sisu/SiSU/2.html>
491
492 %% Additional Things
493 ---------------
494
495 There is syntax support for some editors provided (together with a README file) in
496
497 ./data/sisu/v2/conf/editor-syntax-etc
498
499 usually installed to:
500
501 /usr/share/sisu/v2/conf/editor-syntax-etc
502
503 v1, v2 Changes
504 ---------------
505
506 See changelogs
507
508 From a developer's perspective the substantive change between the two versions
509 is to the middle layer, (the document abstraction, the intermediate document
510 representation used in processing). Version 1 uses strings and relies on
511 regular expressions to identify document objects, while Version 2 uses ruby
512 objects. The version 1 approach whilst programming language neutral offers less
513 control, and leads to complicated code; version 2 approach takes advantage of
514 features within the ruby language suited to what the application does.
515 Development is curently on version 2, version 1 is likely to remain for some
516 time as a reference implementation.
517
518 %% v1, v2 Compatibility Notes
519 ---------------
520
521 Versions 1 and 2 are not quite compatible, version 1 and version 2 will run
522 against each other's documents but document metadata, and processing
523 instructions may be lost.
524
525 On the input side, version 1 and 2 headers are different, version 2 headers
526 have been tidied, see document markup samples provided
527
528 On the output side, the sql databases produced if search is to be implemented
529 are not the same and a database must be generated for each version, most other
530 differences should be relatively cosmetic.
531
532 %% License
533 ---------------
534
535 License: GPL 3 or later see the copyright file in
536
537 ./data/doc/sisu
538
539 usually installed to:
540
541 /usr/share/doc/sisu
542
543 %% SiSU Standard
544 -----------------
545
546 SiSU uses:
547
548 * Standard SiSU markup syntax,
549 * Standard SiSU meta-markup syntax, and the
550 * Standard SiSU object citation numbering and system
551
552 © Ralph Amissah 1997, current 2006.
553 All Rights Reserved.
554
555 * however note the License section
556
557 CHANGELOG
558 ./CHANGELOG
559 and see
560 <http://www.jus.uio.no/sisu/SiSU/changelog.html>
561 <http://www.jus.uio.no/sisu/SiSU/changelog_markup_samples.html>