56a3fe62cbbb7b18a83a34165f54f67b2f317b9c
[software/sisu] / data / doc / sisu / org / sisu.org
1 #+PRIORITIES: A F E
2 (emacs:evil mode gifts a "vim" of enticing "alternative" powers! ;)
3
4 * General
5
6 ** what is sisu?
7
8 Multiple output formats with a nod to the strengths of each output format and
9 the ability to cite text easily across output formats.
10
11 *** debian/control desc
12
13 documents - structuring, publishing in multiple formats and search
14 SiSU is a lightweight markup based, command line oriented, document
15 structuring, publishing and search framework for document collections.
16 .
17 With minimal preparation of a plain-text (UTF-8) file, using sisu markup syntax
18 in your text editor of choice, SiSU can generate various document formats, most
19 of which share a common object numbering system for locating content, including
20 plain text, HTML, XHTML, XML, EPUB, OpenDocument text (ODF:ODT), LaTeX, PDF
21 files, and populate an SQL database with objects (roughly paragraph-sized
22 chunks) so searches may be performed and matches returned with that degree of
23 granularity. Think of being able to finely match text in documents, using
24 common object numbers, across different output formats and across languages if
25 you have translations of the same document. For search, your criteria is met
26 by these documents at these locations within each document (equally relevant
27 across different output formats and languages). To be clear (if obvious) page
28 numbers provide none of this functionality. Object numbering is particularly
29 suitable for "published" works (finalized texts as opposed to works that are
30 frequently changed or updated) for which it provides a fixed means of reference
31 of content. Document outputs can also share provided semantic meta-data.
32 .
33 SiSU also provides concordance files, document content certificates and
34 manifests of generated output and the means to make book indexes that make use
35 of its object numbering.
36 .
37 Syntax highlighting and folding (outlining) files are provided for the Vim and
38 Emacs editors.
39 .
40 Dependencies for various features are taken care of in sisu related packages.
41 The package sisu-complete installs the whole of SiSU.
42 .
43 Additional document markup samples are provided in the package
44 sisu-markup-samples which is found in the non-free archive. The licenses for
45 the substantive content of the marked up documents provided is that provided
46 by the author or original publisher.
47 .
48 SiSU uses utf-8 & parses left to right. Currently supported languages:
49 am bg bn br ca cs cy da de el en eo es et eu fi fr ga gl he hi hr hy ia is it
50 ja ko la lo lt lv ml mr nl nn no oc pl pt pt_BR ro ru sa se sk sl sq sr sv ta
51 te th tk tr uk ur us vi zh (see XeTeX polyglossia & cjk)
52 .
53 SiSU works well under po4a translation management, for which an administrative
54 sample Rakefile is provided with sisu_manual under markup-samples. j
55
56 *** multiple document formats
57
58 Text can be represented in multiple output formats with different
59 characteristics that are (or may be) regarded as strengths/advantages and
60 therefore preferred in different contexts.
61
62 Given the different strengths and characteristics of various output formats, it
63 makes little sense to try too hard to make different representations of a
64 document look the same. More interesting is have document representations that
65 take advantage of each given outputs strengths. As valuable if not more so is
66 the ability to cite, find, discuss text with ease, across the different output
67 formats.
68
69 For citation across output formats, SiSU uses object citation numbers.
70
71 *** document structure and document objects
72
73 SiSU breaks marked up text into document structure and objects
74
75 Document structure being the document heading hierarchy (having separated out
76 the document header).
77
78 **** What are document objects?
79 An object is an identified meaningful unit of a document, most commonly a
80 paragraph of text, but also for example a table, code block, verse or image.
81
82 SiSU tracks these substantive document units as document objects (and their
83 relationship to the document structure).
84
85 *** object citation numbers
86
87 **** What are object citation numbers?
88
89 An object citation number is a sequential number assigned to a document object.
90
91 In sisu output documents share this common object numbering system (dubbed
92 "object citation numbering" (ocn)) that is meaningful (machine & human readable)
93 across various digital outputs whether paper, screen, or database oriented,
94 (PDF, html, XML, EPUB, sqlite, postgresql), and across multilingual content if
95 prepared appropriately. This numbering system can be used to reference content
96 across output types.
97
98 **** Why might I want object citation numbering?
99
100 The ability to cite and quickly locate text can be invaluable if not essential.
101 (whether for instruction or discussion).
102
103 In this digital & Internet age we have multiple ways to represent documents and
104 multiple document output formats as options with different characteristics,
105 strengths/advantages etc. We need a way to cite text that works and is relevant
106 independent of the document format used.
107
108 I want to discuss (cite) html text how do I do this?
109 how do I refer to / cite / discuss text in html?
110 Issue: html may be viewed online or printed, it is not tied to paper (as
111 e.g. pdf) and prints differently depending on selected font face and font size.
112
113 I want to discuss (cite) text that is available in multiple formats (e.g. pdf,
114 epub, html) without having to worry about the output format that is referred
115 to.
116 How do I refer to / discuss text that is available in more than one format,
117 uncertain of what format is preferred, used or available to my colleagues?
118 e.g. html and epub or pdf have rather different text representations, how do I
119 discuss ...
120
121 I would like to have a book index that is relevant (can be used) across multiple
122 output formats (e.g. pdf, epub, html)
123
124 How do I make a book index (or a concordance file) that works across multiple
125 output formats?
126
127 I would like to have search results indicating where in a document matches are
128 found and I would like it to be relevant across available output formats (e.g.
129 pdf, epub, html)
130 How do I get search results for locations of text within each relevant document
131
132 I would like to be able to discuss a text that has been translated ...
133 how do I find text across languages?
134 Where I have a nicely translated document, how do I point to or discuss with my
135 foreign language counterpart some detail of the text, or, how do I point my
136 foreign language counterpart to the text I would like to bring to his
137 attention.
138
139 *** "Granular" Search
140
141 Of interest is the ease of streaming documents to a relational database, at an
142 object (roughly paragraph) level and the potential for increased precision in
143 the presentation of matches that results thereby. The ability to serialize
144 html, LaTeX, XML, SQL, (whatever) is also inherent in / incidental to the
145 design.
146
147 *** Summary
148 SiSU information Structuring Universe
149 Structured information, Serialized Units <www.sisudoc.org> or
150 <www.jus.uio.no/sisu/> software for electronic texts, document collections,
151 books, digital libraries, and search, with "atomic search" and text positioning
152 system (shared text citation numbering: "ocn")
153 outputs include: plaintext, html, XHTML, XML, ODF (OpenDocument), EPUB, LaTeX,
154 PDF, SQL (PostgreSQL and SQLite)
155
156 *** SiSU Short Description
157
158 SiSU is a comprehensive future-proofing electronic document management system.
159 Built-in search capabilities allow you to search across multiple documents and
160 highlight matches in an easy-to-follow format. Paragraph numbering system
161 allows you to cite your electronic documents in a consistent manner across
162 multiple file formats. Multiple format outputs allow you to display your
163 documents in plain text, PDF (portrait and horizontal), OpenDocument format,
164 HTML, or e-book reading format (EPUB). Word mapping allows you to easily create
165 word indexes for your documents. Future-proofing flexibility allows you to
166 quickly adapt your documents to newer output formats as needed. All these and
167 many other features are achieved with little or no additional work on your
168 documents - by marking up the documents with a super simplistic markup
169 language, leaving the SiSU engine to handle the heavy-lifting processing.
170
171 Potential users of SiSU include individual authors who want to publish their
172 books or articles electronically to reach a broad audience, web publishers who
173 want to provide multiple channels of access to their electronic documents, or
174 any organizations which centrally manage a medium or large set of electronic
175 documents, especially governmental organizations which may prefer to keep their
176 documents in easily accessible yet non-proprietary formats.
177
178 SiSU is an Open Source project initiated and led by Ralph Amissah
179 <ralph.amissah@gmail.com> and can be contacted via mailing list
180 <http://lists.sisudoc.org/listinfo/sisu> at <sisu@lists.sisudoc.org>. SiSU is
181 licensed under the GNU General Public License.
182
183 **** notes
184
185 For less markup than the most elementary HTML you can have more. SiSU -
186 Structured information, Serialized Units for electronic documents, is an
187 information structuring, transforming, publishing and search framework with the
188 following features:
189
190 (i) markup syntax: (a) simpler than html, (b) mnemonic, influenced by
191 mail/messaging/wiki markup practices, (c) human readable, and easily writable,
192
193 (ii) (a) minimal markup requirement, (b) single file marked up for multiple outputs,
194
195 * documents are prepared in a single UTF-8 file using a minimalistic mnemonic
196 syntax. Typical literature, documents like "War and Peace" require almost no
197 markup, and most of the headers are optional.
198
199 * markup is easily readable/parsed by the human eye, (basic markup is simpler
200 and more sparse than the most basic html), [this may also be converted to XML
201 representations of the same input/source document].
202
203 * markup defines document structure (this may be done once in a header
204 pattern-match description, or for heading levels individually); basic text
205 attributes (bold, italics, underscore, strike-through etc.) as required; and
206 semantic information related to the document (header information, extended
207 beyond the Dublin core and easily further extended as required); the headers
208 may also contain processing instructions.
209
210 (iii) (a) multiple output formats, including amongst others: plaintext (UTF-8);
211 html; (structured) XML; ODF (Open Document text); EPUB; LaTeX; PDF (via LaTeX);
212 SQL type databases (currently PostgreSQL and SQLite). SiSU produces:
213 concordance files; document content certificates (md5 or sha256 digests of
214 headings, paragraphs, images etc.) and html manifests (and sitemaps of
215 content). (b) takes advantage of the strengths implicit in these very different
216 output types, (e.g. PDFs produced using typesetting of LaTeX, databases
217 populated with documents at an individual object/paragraph level, making
218 possible granular search (and related possibilities))
219
220 (iv) outputs share a common numbering system (dubbed "object citation
221 numbering" (ocn)) that is meaningful (to man and machine) across various
222 digital outputs whether paper, screen, or database oriented, (PDF, html, XML,
223 EPUB, sqlite, postgresql), this numbering system can be used to reference
224 content.
225
226 (v) SQL databases are populated at an object level (roughly headings,
227 paragraphs, verse, tables) and become searchable with that degree of
228 granularity, the output information provides the object/paragraph numbers which
229 are relevant across all generated outputs; it is also possible to look at just
230 the matching paragraphs of the documents in the database; [output indexing also
231 work well with search indexing tools like hyperesteier].
232
233 (vi) use of semantic meta-tags in headers permit the addition of semantic
234 information on documents, (the available fields are easily extended)
235
236 (vii) creates organised directory/file structure for (file-system) output,
237 easily mapped with its clearly defined structure, with all text objects
238 numbered, you know in advance where in each document output type, a bit of text
239 will be found (e.g. from an SQL search, you know where to go to find the
240 prepared html output or PDF etc.)... there is more; easy directory management
241 and document associations, the document preparation (sub-)directory may be used
242 to determine output (sub-)directory, the skin used, and the SQL database used,
243
244 (viii) "Concordance file" wordmap, consisting of all the words in a document
245 and their (text/ object) locations within the text, (and the possibility of
246 adding vocabularies),
247
248 (ix) document content certification and comparison considerations: (a) the
249 document and each object within it stamped with an sha256 hash making it
250 possible to easily check or guarantee that the substantive content of a document
251 is unchanged, (b) version control, documents integrated with time based source
252 control system, default RCS or CVS with use of $Id$ tag, which SiSU checks
253
254 (x) SiSU's minimalist markup makes for meaningful "diffing" of the substantive
255 content of markup-files,
256
257 (xi) easily skinnable, document appearance on a project/site wide, directory
258 wide, or document instance level easily controlled/changed,
259
260 (xii) in many cases a regular expression may be used (once in the document
261 header) to define all or part of a documents structure obviating or reducing
262 the need to provide structural markup within the document,
263
264 (xiii) prepared files may be batch process, documents produced are static files
265 so this needs to be done only once but may be repeated for various reasons as
266 desired (updated content, addition of new output formats, updated technology
267 document presentations/representations)
268
269 (xiv) possible to pre-process, which permits: the easy creation of standard
270 form documents, and templates/term-sheets, or; building of composite documents
271 (master documents) from other sisu marked up documents, or marked up parts,
272 i.e. import documents or parts of text into a main document should this be
273 desired
274
275 there is a considerable degree of future-proofing, output representations are
276 "upgradeable", and new document formats may be added.
277
278 (xv) there is a considerable degree of future-proofing, output representations
279 are "upgradeable", and new document formats may be added: (a) modular, (thanks
280 in no small part to Ruby) another output format required, write another
281 module.... (b) easy to update output formats (eg html, XHTML, LaTeX/PDF
282 produced can be updated in program and run against whole document set), (c)
283 easy to add, modify, or have alternative syntax rules for input, should you
284 need to,
285
286 (xvi) scalability, dependent on your file-system (ext3, Reiserfs, XFS,
287 whatever) and on the relational database used (currently Postgresql and
288 SQLite), and your hardware,
289
290 (xvii) only marked up files need be backed up, to secure the larger document
291 set produced,
292
293 (xviii) document management,
294
295 (xix) Syntax highlighting for SiSU markup is available for a number of text
296 editors.
297
298 (xx) remote operations: (a) run SiSU on a remote server, (having prepared sisu
299 markup documents locally or on that server, i.e. this solution where sisu is
300 installed on the remote server, would work whatever type of machine you chose
301 to prepare your markup documents on), (b) generated document outputs may be
302 posted by sisu to remote sites (using rsync/scp) (c) document source (plaintext
303 utf-8) if shared on the net may be identified by its url and processed locally
304 to produce the different document outputs.
305
306 (xxi) document source may be bundled together (automatically) with associated
307 documents (multiple language versions or master document with inclusions) and
308 images and sent as a zip file called a sisupod, if shared on the net these too
309 may be processed locally to produce the desired document outputs, these may be
310 downloaded, shared as email attachments, or processed by running sisu against
311 them, either using a url or the filename.
312
313 (xxii) for basic document generation, the only software dependency is Ruby, and
314 a few standard Unix tools (this covers plaintext, html, XML, ODF, EPUB, LaTeX).
315 To use a database you of course need that, and to convert the LaTeX generated
316 to PDF, a LaTeX processor like tetex or texlive.
317
318 as a developers tool it is flexible and extensible
319
320 *** description
321
322 SiSU ("SiSU information Structuring Universe" or "Structured information,
323 Serialized Units"),1 is a Unix command line oriented framework for document
324 structuring, publishing and search. Featuring minimalistic markup, multiple
325 standard outputs, a common citation system, and granular search. Using markup
326 applied to a document, SiSU can produce plain text, HTML, XHTML, XML,
327 OpenDocument, LaTeX or PDF files, and populate an SQL database with objects2
328 (equating generally to paragraph-sized chunks) so searches may be performed and
329 matches returned with that degree of granularity (e.g. your search criteria is
330 met by these documents and at these locations within each document). Document
331 output formats share a common object numbering system for locating content.
332 This is particularly suitable for "published" works (finalized texts as opposed
333 to works that are frequently changed or updated) for which it provides a fixed
334 means of reference of content. How it works
335
336 SiSU markup is fairly minimalistic, it consists of: a (largely optional)
337 document header, made up of information about the document (such as when it was
338 published, who authored it, and granting what rights) and any processing
339 instructions; and markup within text which is related to document structure and
340 typeface. SiSU must be able to discern the structure of a document, (text
341 headings and their levels in relation to each other), either from information
342 provided in the instruction header or from markup within the text (or from a
343 combination of both). Processing is done against an abstraction of the document
344 comprising of information on the document's structure and its objects,2 which
345 the program serializes (providing the object numbers) and which are assigned
346 hash sum values based on their content. This abstraction of information about
347 document structure, objects, (and hash sums), provides considerable flexibility
348 in representing documents different ways and for different purposes (e.g.
349 search, document layout, publishing, content certification, concordance etc.),
350 and makes it possible to take advantage of some of the strengths of established
351 ways of representing documents, (or indeed to create new ones).
352
353 1. also chosen for the meaning of the Finnish term "sisu".
354
355 2 objects include: headings, paragraphs, verse, tables, images, but not
356 footnotes/endnotes which are numbered separately and tied to the object from
357 which they are referenced.
358
359 More information on SiSU provided at: <www.sisudoc.org/sisu/SiSU>
360
361 SiSU was developed in relation to legal documents, and is strong across a wide
362 variety of texts (law, literature...(humanities, law and part of the social
363 sciences)). SiSU handles images but is not suitable for formulae/ statistics,
364 or for technical writing at this time.
365
366 SiSU has been developed and has been in use for several years. Requirements to
367 cover a wide range of documents within its use domain have been explored.
368
369 <ralph@amissah.com>
370 <ralph.amissah@gmail.com>
371 <sisu@lists.sisudoc.org>
372 <http://lists.sisudoc.org/listinfo/sisu>
373 2010
374 w3 since October 3 1993
375 ** Finding
376 *** source
377 http://git.sisudoc.org/gitweb/
378
379 sisu git repo:
380 http://git.sisudoc.org/gitweb/?p=code/sisu.git;a=summary
381
382 sisu-markup-samples git repo:
383 http://git.sisudoc.org/gitweb/?p=doc/sisu-markup-samples.git;a=summary
384
385 *** mailing list
386 sisu at lists.sisudoc.org
387 http://lists.sisudoc.org/listinfo/sisu
388
389 ** irc oftc #sisu
390
391 ** home pages
392 <http://www.sisudoc.org/>
393 <http://search.sisudoc.org/>
394 <http://www.jus.uio.no/sisu>
395
396 ** Installing sisu
397
398 *** where you take responsibility for having the correct dependencies
399
400 Provided you have *Ruby*, *SiSU* can be run.
401
402 SiSU should be run from the directory containing your sisu marked up document
403 set.
404
405 This works fine so long as you already have sisu external dependencies in
406 place. For many operations such as html, epub, odt this is likely to be fine.
407 Note however, that additional external package dependencies, such as texlive
408 (for pdfs), sqlite3 or postgresql (for search) should you desire to use them
409 are not taken care of for you.
410
411 **** run off the source tarball without installation
412
413 RUN OFF SOURCE PACKAGE DIRECTORY TREE (WITHOUT INSTALLING)
414 ..........................................................
415
416 ***** 1. Obtain the latest sisu source
417
418 using git:
419
420 http://git.sisudoc.org/gitweb/?p=code/sisu.git;a=summary
421 http://git.sisudoc.org/gitweb/?p=code/sisu.git;a=log
422
423 git clone git://git.sisudoc.org/git/code/sisu.git
424
425 or, identify latest available source:
426
427 https://packages.debian.org/sid/sisu
428 http://packages.qa.debian.org/s/sisu.html
429 http://qa.debian.org/developer.php?login=sisu@lists.sisudoc.org
430
431 http://sisudoc.org/sisu/archive/pool/main/s/sisu/
432
433 and download the:
434
435 sisu_5.4.5.orig.tar.xz
436
437 using debian tool dget:
438
439 The dget tool is included within the devscripts package
440 https://packages.debian.org/search?keywords=devscripts
441 to install dget install devscripts:
442
443 apt-get install devscripts
444
445 and then you can get it from Debian:
446 dget -xu http://ftp.fi.debian.org/debian/pool/main/s/sisu/sisu_5.4.5-1.dsc
447
448 or off sisu repos
449 dget -x http://www.jus.uio.no/sisu/archive/pool/main/s/sisu/sisu_5.4.5-1.dsc
450 or
451 dget -x http://sisudoc.org/sisu/archive/pool/main/s/sisu/sisu_5.4.5-1.dsc
452
453 ***** 2. Unpack the source
454
455 Provided you have *Ruby*, *SiSU* can be run without installation straight from
456 the source package directory tree.
457
458 Run ruby against the full path to bin/sisu (in the unzipped source package
459 directory tree). SiSU should be run from the directory containing your sisu
460 marked up document set.
461
462 ruby ~/sisu-5.4.5/bin/sisu --html -v document_name.sst
463
464 This works fine so long as you already have sisu external dependencies in
465 place. For many operations such as html, epub, odt this is likely to be fine.
466 Note however, that additional external package dependencies, such as texlive
467 (for pdfs), sqlite3 or postgresql (for search) should you desire to use them
468 are not taken care of for you.
469
470 **** gem install (with rake)
471
472 (i) create the gemspec; (ii) build the gem (from the gemspec); (iii) install
473 the gem
474
475 Provided you have ruby & rake, this can be done with the single command:
476
477 rake gem_create_build_install
478
479 to build and install sisu v5 & sisu v6, alias gemcbi
480
481 separate gems are made/installed for sisu v5 & sisu v6 contained in source.
482
483 to build and install sisu v5, alias gem5cbi:
484
485 rake gem_create_build_install_stable
486
487 to build and install sisu v6, alias gem6cbi:
488
489 rake gem_create_build_install_unstable
490
491 for individual steps (create, build, install) see rake options, rake -T to
492 specify sisu version for sisu installed via gem
493
494 gem search sisu
495
496 sisu _5.4.5_ --version
497
498 sisu _6.0.11_ --version
499
500 to uninstall sisu installed via gem
501
502 sudo gem uninstall --verbose sisu
503
504 For a list of alternative actions you may type:
505
506 rake help
507
508 rake -T
509
510 Rake: <http://rake.rubyforge.org/> <http://rubyforge.org/frs/?group_id=50>
511
512 **** installation with setup.rb
513
514 this is a three step process, in the root directory of the unpacked *SiSU* as
515 root type:
516
517 ruby setup.rb config
518 ruby setup.rb setup
519 #[as root:]
520 ruby setup.rb install
521
522 further information:
523 <http://i.loveruby.net/en/projects/setup/>
524 <http://i.loveruby.net/en/projects/setup/doc/usage.html>
525
526 ruby setup.rb config && ruby setup.rb setup && sudo ruby setup.rb install
527
528 *** Debian install
529
530 *SiSU* is available off the *Debian* archives. It should necessary only to run
531 as root, Using apt-get:
532
533 apt-get update
534
535 apt get install sisu-complete
536
537 (all sisu dependencies should be taken care of)
538
539 If there are newer versions of *SiSU* upstream, they will be available by
540 adding the following to your sources list /etc/apt/sources.list
541
542 #/etc/apt/sources.list
543
544 deb http://www.jus.uio.no/sisu/archive unstable main non-free
545 deb-src http://www.jus.uio.no/sisu/archive unstable main non-free
546
547 The non-free section is for sisu markup samples provided, which contain
548 authored works the substantive text of which cannot be changed, and which as a
549 result do not meet the debian free software guidelines.
550
551 *SiSU* is developed on *Debian*, and packages are available for *Debian* that
552 take care of the dependencies encountered on installation.
553
554 The package is divided into the following components:
555
556 *sisu*, the base code, (the main package on which the others depend), without
557 any dependencies other than ruby (and for convenience the ruby webrick web
558 server), this generates a number of types of output on its own, other
559 packages provide additional functionality, and have their dependencies
560
561 *sisu-complete*, a dummy package that installs the whole of greater sisu as
562 described below, apart from sisu -examples
563
564 *sisu-pdf*, dependencies used by sisu to produce pdf from /LaTeX/ generated
565
566 *sisu-postgresql*, dependencies used by sisu to populate postgresql database
567 (further configuration is necessary)
568
569 *sisu-sqlite*, dependencies used by sisu to populate sqlite database
570
571 *sisu-markup-samples*, sisu markup samples and other miscellany (under
572 *Debian* Free Software Guidelines non-free)
573
574 *SiSU* is available off Debian Unstable and Testing [link:
575 <http://packages.debian.org/cgi-bin/search_packages.pl?searchon=names&subword=1&version=all&release=all&keywords=sisu>]
576 [^1] install it using apt-get, aptitude or alternative *Debian* install tools.
577
578 ** sisu markup :sisu:markup:
579
580 *** sisu markup
581
582 #% structure - headings, levels
583 * headings (A-D, 1-3)
584 * inline
585 'A~ ' NOTE title level
586 'B~ ' NOTE optional
587 'C~ ' NOTE optional
588 'D~ ' NOTE optional
589 '1~ ' NOTE chapter level
590 '2~ ' NOTE optional
591 '3~ ' NOTE optional
592 '4~ ' NOTE optional :consider:
593 * node
594 * parent
595 * children
596
597 #% font face NOTE open & close marks, inline within paragraph
598 * emphasize '*{ ... }*' NOTE configure whether bold italics or underscore, default bold
599 * bold '!{ ... }!'
600 * italics '/{ ... }/'
601 * underscore '_{ ... }_'
602 * superscript '^{ ... }^'
603 * subscript ',{ ... },'
604 * strike '-{ ... }-'
605 * add '+{ ... }+'
606 * monospace '#{ ... }#'
607 #% para NOTE paragraph controls are at the start of a paragraph
608 * a para is a block of text separated from others by an empty line
609 * indent
610 * default, all '_1 ' up to '_9 '
611 * first line hang '_1_0 '
612 * first line indent further '_0_1 '
613 * bullet
614 [levels 1-6]
615 '_* '
616 '_1* '
617 '_2* '
618 * numbered list
619 [levels 1-3]
620 '# '
621
622 #% blocks NOTE text blocks that are not to be treated in the way that ordinary paragraphs would be
623 * code
624 * [type of markup if any]
625 * poem
626 * group
627 * alt
628 * tables
629 #% boxes
630 NOTE grouped text with code block type color & possibly default image, warning, tip, red, blue etc. decide [NB N/A not implemented]
631
632 #% notes NOTE inline within paragraph at the location where the note reference is to occur
633 * footnotes '~{ ... }~'
634 * [bibliography] [NB N/A not implemented]
635
636 #% links, linking
637 * links - external, web, url
638 * links - internal
639
640 #% images [multimedia?]
641 * images
642 * [base64 inline] [N/A not implemented]
643
644 #% object numbers
645 * ocn (object numbers)
646 automatically attributed to substantive objects, paragraphs, tables, blocks, verse (unless exclude marker provided)
647
648 #% contents
649 * toc (table of contents)
650 autogenerated from structure/headings information
651 * index (book index)
652 built from hints in newline text following a paragraph and starting with ={} has identifying rules for main and subsidiary text
653
654 #% breaks
655 * line break ' \\ ' inline
656 * page break, column break ' -\\- ' start of line, breaks a column, starts a new column, if using columns, else breaks the page, starts a new page.
657 * page break, page new ' =\\= ' start of line, breaks the page, starts a new page.
658 * horizontal '-..-' start of line, rule page (break) line across page (dividing paragraphs)
659
660 #% book type index
661
662 #% comment
663 * comment
664
665 #% misc
666 * term & definition
667
668 *** syntax hilighting
669
670 **** vim
671 data/sisu/conf/editor-syntax-etc/vim/
672 data/sisu/conf/editor-syntax-etc/vim/syntax/sisu.vim
673
674 **** emacs
675 data/sisu/conf/editor-syntax-etc/emacs/
676 data/sisu/conf/editor-syntax-etc/emacs/sisu-mode.el
677 ** todo
678 sisu_todo.org