From 50d45c6deb0afd2e4222d2e33a45487a9d1fa676 Mon Sep 17 00:00:00 2001 From: Ralph Amissah Date: Sun, 23 Sep 2007 05:16:21 +0100 Subject: primarily todo with sisu documentation, changelog reproduced below: * start documenting sisu using sisu * sisu markup source files in data/doc/sisu/sisu_markup_samples/sisu_manual/ /usr/share/doc/sisu/sisu_markup_samples/sisu_manual/ * default output [sisu -3] in data/doc/manuals_generated/sisu_manual/ /usr/share/doc/manuals_generated/sisu_manual/ (adds substantially to the size of sisu package!) * help related edits * manpage, work on ability to generate manpages, improved * param, exclude footnote mark count when occurs within code block * plaintext changes made * shared_txt, line wrap visited * file:// link option introduced (in addition to existing https?:// and ftp://) a bit arbitrarily, diff here, [double check changes in sysenv and hub] * minor adjustments * html url match refinement * css added tiny_center * plaintext * endnotes fix * footnote adjustment to make more easily distinguishable from substantive text * flag -a only [flags -A -e -E dropped] controlled by modifiers --unix/msdos --footnote/endnote * defaults, homepage * renamed homepage (instead of index) implications for modifying skins, which need likewise to have any homepage entry renamed * added link to sisu_manual in homepage * css the css for the default homepage is renamed homepage.css (instead of index.css) [consider removing this and relying on html.css] * ruby version < ruby1.9 * place stop on installation and working with for now [ruby String.strip broken in ruby 1.9.0 (2007-09-10 patchlevel 0) [i486-linux], 2007-09-18:38/2] * debian/control restrict use to ruby > 1.8.4 and ruby < 1.9 * debian * debian/control restrict use to ruby > 1.8.4 and ruby < 1.9 * sisu-doc new sub-package for sisu documentation debian/control and sisu-doc.install --- data/doc/manuals_generated/sisu_manual/man/sisu.1 | 5042 +++++++++++++++++++++ 1 file changed, 5042 insertions(+) create mode 100644 data/doc/manuals_generated/sisu_manual/man/sisu.1 (limited to 'data/doc/manuals_generated/sisu_manual/man/sisu.1') diff --git a/data/doc/manuals_generated/sisu_manual/man/sisu.1 b/data/doc/manuals_generated/sisu_manual/man/sisu.1 new file mode 100644 index 00000000..8da9be45 --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/man/sisu.1 @@ -0,0 +1,5042 @@ +.TH "sisu" "1" "2007-08-30" "0.59.0" "SiSU - SiSU information Structuring Universe" +.SH +SISU \- SISU INFORMATION STRUCTURING UNIVERSE \- MANUAL \ [0.58], +RALPH AMISSAH +.BR + +.SH +WHAT IS SISU? +.BR + +.SH +1. INTRODUCTION \- WHAT IS SISU? +.BR + +.BR +.B SiSU +is a system for document markup, publishing (in multiple open standard +formats) and search + +.BR +.B SiSU +[^1] is a[^2] framework for document structuring, publishing and search, +comprising of (a) a lightweight document structure and presentation markup +syntax and (b) an accompanying engine for generating standard document format +outputs from documents prepared in sisu markup syntax, which is able to produce +multiple standard outputs that (can) share a common numbering system for the +citation of text within a document. + +.BR +.B SiSU +is developed under an open source, software libre license (GPL3). It has been +developed in the context of coping with large document sets with evolving +markup related technologies, for which you want multiple output formats, a +common mechanism for cross\-output\-format citation, and search. + +.BR +.B SiSU +both defines a markup syntax and provides an engine that produces open +standards format outputs from documents prepared with +.B SiSU +markup. From a single lightly prepared document sisu custom builds several +standard output formats which share a common (text object) numbering system for +citation of content within a document (that also has implications for search). +The sisu engine works with an abstraction of the document\'s structure and +content from which it is possible to generate different forms of representation +of the document. Significantly +.B SiSU +markup is more sparse than html and outputs which include html, LaTeX, +landscape and portrait pdfs, Open Document Format (ODF), all of which can be +added to and updated. +.B SiSU +is also able to populate SQL type databases at an object level, which means +that searches can be made with that degree of granularity. Results of objects +(primarily paragraphs and headings) can be viewed directly in the database, or +just the object numbers shown \- your search criteria is met in these documents +and at these locations within each document. + +.BR +Source document preparation and output generation is a two step process: (i) +document source is prepared, that is, marked up in sisu markup syntax and (ii) +the desired output subsequently generated by running the sisu engine against +document source. Output representations if updated (in the sisu engine) can be +generated by re\-running the engine against the prepared source. Using +.B SiSU +markup applied to a document, +.B SiSU +custom builds various standard open output formats including plain text, +HTML, XHTML, XML, OpenDocument, LaTeX or PDF files, and populate an SQL +database with objects[^3] (equating generally to paragraph\-sized chunks) so +searches may be performed and matches returned with that degree of granularity +( e.g. your search criteria is met by these documents and at these locations +within each document). Document output formats share a common object numbering +system for locating content. This is particularly suitable for \"published\" +works (finalized texts as opposed to works that are frequently changed or +updated) for which it provides a fixed means of reference of content. + +.BR +In preparing a +.B SiSU +document you optionally provide semantic information related to the document +in a document header, and in marking up the substantive text provide +information on the structure of the document, primarily indicating heading +levels and footnotes. You also provide information on basic text attributes +where used. The rest is automatic, sisu from this information custom builds[^4] +the different forms of output requested. + +.BR +.B SiSU +works with an abstraction of the document based on its structure which is +comprised of its frame[^5] and the objects[^6] it contains, which enables +.B SiSU +to represent the document in many different ways, and to take advantage of +the strengths of different ways of presenting documents. The objects are +numbered, and these numbers can be used to provide a common base for citing +material within a document across the different output format types. This is +significant as page numbers are not suited to the digital age, in web +publishing, changing a browser\'s default font or using a different browser +means that text appears on different pages; and in publishing in different +formats, html, landscape and portrait pdf etc. again page numbers are of no use +to cite text in a manner that is relevant against the different output types. +Dealing with documents at an object level together with object numbering also +has implications for search. + +.BR +One of the challenges of maintaining documents is to keep them in a format that +would allow users to use them without depending on a proprietary software +popular at the time. Consider the ease of dealing with legacy proprietary +formats today and what guarantee you have that old proprietary formats will +remain (or can be read without proprietary software/equipment) in 15 years +time, or the way the way in which html has evolved over its relatively short +span of existence. +.B SiSU +provides the flexibility of outputing documents in multiple non\-proprietary +open formats including html, pdf[^7] and the ISO standard ODF.[^8] Whilst +.B SiSU +relies on software, the markup is uncomplicated and minimalistic which +guarantees that future engines can be written to run against it. It is also +easily converted to other formats, which means documents prepared in +.B SiSU +can be migrated to other document formats. Further security is provided by +the fact that the software itself, +.B SiSU +is available under GPL3 a licence that guarantees that the source code will +always be open, and free as in libre which means that that code base can be +used updated and further developed as required under the terms of its license. +Another challenge is to keep up with a moving target. +.B SiSU +permits new forms of output to be added as they become important, (Open +Document Format text was added in 2006), and existing output to be updated +(html has evolved and the related module has been updated repeatedly over the +years, presumably when the World Wide Web Consortium (w3c) finalises html 5 +which is currently under development, the html module will again be updated +allowing all existing documents to be regenerated as html 5). + +.BR +The document formats are written to the file\-system and available for indexing +by independent indexing tools, whether off the web like Google and Yahoo or on +the site like Lucene and Hyperestraier. + +.BR +.B SiSU +also provides other features such as concordance files and document content +certificates, and the working against an abstraction of document structure has +further possibilities for the research and development of other document +representations, the availability of objects is useful for example for topic +maps and the commercial law thesaurus by Vikki Rogers and Al Krtizer, together +with the flexibility of +.B SiSU +offers great possibilities. + +.BR +.B SiSU +is primarily for published works, which can take advantage of the citation +system to reliably reference its documents. +.B SiSU +works well in a complementary manner with such collaborative technologies as +Wikis, which can take advantage of and be used to discuss the substance of +content prepared in +.B SiSU +. + +.BR + + +.SH +2. HOW DOES SISU WORK? +.BR + +.BR +.B SiSU +markup is fairly minimalistic, it consists of: a (largely optional) document +header, made up of information about the document (such as when it was +published, who authored it, and granting what rights) and any processing +instructions; and markup within the substantive text of the document, which is +related to document structure and typeface. +.B SiSU +must be able to discern the structure of a document, (text headings and their +levels in relation to each other), either from information provided in the +document header or from markup within the text (or from a combination of both). +Processing is done against an abstraction of the document comprising of +information on the document\'s structure and its objects,[2] which the program +serializes (providing the object numbers) and which are assigned hash sum +values based on their content. This abstraction of information about document +structure, objects, (and hash sums), provides considerable flexibility in +representing documents different ways and for different purposes (e.g. search, +document layout, publishing, content certification, concordance etc.), and +makes it possible to take advantage of some of the strengths of established +ways of representing documents, (or indeed to create new ones). + +.SH +3. SUMMARY OF FEATURES +.BR + +.BR +* sparse/minimal markup (clean utf\-8 source texts). Documents are prepared in +a single UTF\-8 file using a minimalistic mnemonic syntax. Typical literature, +documents like \"War and Peace\" require almost no markup, and most of the +headers are optional. + +.BR +* markup is easily readable/parsable by the human eye, (basic markup is simpler +and more sparse than the most basic HTML), \ [this \ may \ also \ be \ +converted \ to \ XML \ representations \ of \ the \ same \ input/source \ +document]. + +.BR +* markup defines document structure (this may be done once in a header +pattern\-match description, or for heading levels individually); basic text +attributes (bold, italics, underscore, strike\-through etc.) as required; and +semantic information related to the document (header information, extended +beyond the Dublin core and easily further extended as required); the headers +may also contain processing instructions. +.B SiSU +markup is primarily an abstraction of document structure and document +metadata to permit taking advantage of the basic strengths of existing +alternative practical standard ways of representing documents \ [be \ that \ +browser \ viewing, \ paper \ publication, \ sql \ search \ etc.] (html, xml, +odf, latex, pdf, sql) + +.BR +* for output produces reasonably elegant output of established industry and +institutionally accepted open standard formats.[3] takes advantage of the +different strengths of various standard formats for representing documents, +amongst the output formats currently supported are: + +.BR + * html \- both as a single scrollable text and a segmented document + +.BR + * xhtml + +.BR + * XML \- both in sax and dom style xml structures for further development as + required + +.BR + * ODF \- open document format, the iso standard for document storage + +.BR + * LaTeX \- used to generate pdf + +.BR + * pdf (via LaTeX) + +.BR + * sql \- population of an sql database, (at the same object level that is + used to cite text within a document) + +.BR +Also produces: concordance files; document content certificates (md5 or sha256 +digests of headings, paragraphs, images etc.) and html manifests (and sitemaps +of content). (b) takes advantage of the strengths implicit in these very +different output types, (e.g. PDFs produced using typesetting of LaTeX, +databases populated with documents at an individual object/paragraph level, +making possible granular search (and related possibilities)) + +.BR +* ensuring content can be cited in a meaningful way regardless of selected +output format. Online publishing (and publishing in multiple document formats) +lacks a useful way of citing text internally within documents (important to +academics generally and to lawyers) as page numbers are meaningless across +browsers and formats. sisu seeks to provide a common way of pinpoint the text +within a document, (which can be utilized for citation and by search engines). +The outputs share a common numbering system that is meaningful (to man and +machine) across all digital outputs whether paper, screen, or database +oriented, (pdf, HTML, xml, sqlite, postgresql), this numbering system can be +used to reference content. + +.BR +* Granular search within documents. SQL databases are populated at an object +level (roughly headings, paragraphs, verse, tables) and become searchable with +that degree of granularity, the output information provides the +object/paragraph numbers which are relevant across all generated outputs; it is +also possible to look at just the matching paragraphs of the documents in the +database; \ [output \ indexing \ also \ work \ well \ with \ search \ indexing +\ tools \ like \ hyperestraier]. + +.BR +* long term maintainability of document collections in a world of changing +formats, having a very sparsely marked\-up source document base. there is a +considerable degree of future\-proofing, output representations are +\"upgradeable\", and new document formats may be added. e.g. addition of odf +(open document text) module in 2006 and in future html5 output sometime in +future, without modification of existing prepared texts + +.BR +* SQL search aside, documents are generated as required and static once +generated. + +.BR +* documents produced are static files, and may be batch processed, this needs +to be done only once but may be repeated for various reasons as desired +(updated content, addition of new output formats, updated technology document +presentations/representations) + +.BR +* document source (plaintext utf\-8) if shared on the net may be used as input +and processed locally to produce the different document outputs + +.BR +* document source may be bundled together (automatically) with associated +documents (multiple language versions or master document with inclusions) and +images and sent as a zip file called a sisupod, if shared on the net these too +may be processed locally to produce the desired document outputs + +.BR +* generated document outputs may automatically be posted to remote sites. + +.BR +* for basic document generation, the only software dependency is +.B Ruby +, and a few standard Unix tools (this covers plaintext, HTML, XML, ODF, +LaTeX). To use a database you of course need that, and to convert the LaTeX +generated to pdf, a latex processor like tetex or texlive. + +.BR +* as a developers tool it is flexible and extensible + +.BR +Syntax highlighting for +.B SiSU +markup is available for a number of text editors. + +.BR +.B SiSU +is less about document layout than about finding a way with little markup to +be able to construct an abstract representation of a document that makes it +possible to produce multiple representations of it which may be rather +different from each other and used for different purposes, whether layout and +publishing, or search of content + +.BR +i.e. to be able to take advantage from this minimal preparation starting point +of some of the strengths of rather different established ways of representing +documents for different purposes, whether for search (relational database, or +indexed flat files generated for that purpose whether of complete documents, or +say of files made up of objects), online viewing (e.g. html, xml, pdf), or +paper publication (e.g. pdf)... + +.BR +the solution arrived at is by extracting structural information about the +document (about headings within the document) and by tracking objects (which +are serialized and also given hash values) in the manner described. It makes +possible representations that are quite different from those offered at +present. For example objects could be saved individually and identified by +their hashes, with an index of how the objects relate to each other to form a +document. + +.SH +4. HELP +.BR + +.SH +4.1 SISU MANUAL + +.BR +The most up to date information on sisu should be contained in the sisu_manual, +available at: + +.BR + + +.BR +and (from +.B SiSU +0.59 onwards) installed locally at: + +.BR + /usr/share/doc/sisu/sisu_manual/ + +.BR +or equivalent directory + +.BR +Within the +.B SiSU +tarball at: + +.BR + ./data/doc/sisu/sisu_manual/ + +.SH +4.2 SISU MAN PAGES + +.BR +If +.B SiSU +is installed on your system usual man commands should be available, try: + +.BR + man sisu + +.BR + man sisu_markup + +.BR + man sisu_commands + +.BR +Most +.B SiSU +man pages are generated directly from sisu documents that are used to prepare +the sisu manual, the sources files for which are located within the +.B SiSU +tarball at: + +.BR + ./data/doc/sisu/sisu_manual/ + +.BR +Once installed, directory equivalent to: + +.BR + /usr/share/doc/sisu/sisu_manual/ + +.BR +Available man pages are converted back to html using man2html: + +.BR + /usr/share/doc/sisu/html/ + +.BR + ./data/doc/sisu/html/ + +.BR +The +.B SiSU +man pages can be viewed online at:[^9] + +.BR +An online version of the sisu man page is available here: + +.BR +* various sisu man pages \ [^10] + +.BR +* sisu.1 \ [^11] + +.BR +* sisu.8 \ [^12] + +.BR +* sisu_examples.1 \ [^13] + +.BR +* sisu_webrick.1 \ [^14] + +.SH +4.3 SISU BUILT\-IN INTERACTIVE HELP + +.BR +This is particularly useful when current installation information is obtained +as the interactive help is able to provide information on your sisu +configuration and setup. + +.BR + sisu \-\-help + +.BR + sisu \-\-help \ [subject] + +.BR + sisu \-\-help env \ [for \ feedback \ on \ the \ way \ your \ system \ is \ + setup \ with \ regard \ to \ sisu] + +.BR + sisu \-V \ [same \ as \ above \ command] + +.BR + sisu \-\-help commands + +.BR + sisu \-\-help markup + +.BR +Apart from real\-time information on your current configuration the +.B SiSU +manual and man pages are likely to contain more up\-to\-date information than +the sisu interactive help (for example on commands and markup). + +.BR +NOTE: Running the command sisu (alone without any flags, filenames or +wildcards) brings up the interactive help, as does any sisu command that is not +recognised. Enter to escape. + +.SH +4.4 HELP SOURCES + +.BR +For lists of alternative help sources, see: + +.BR +.B man page + +.BR + man sisu_help_sources + +.BR +.B man2html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_help_sources/index.html + +.BR +.B sisu generated html + +.BR + /usr/share/doc/sisu/html/sisu_help_sources/index.html + +.BR + + +.BR + + +.SH +5. COMMANDS SUMMARY +.BR + +.SH +5.1 SYNOPSIS + +.BR +.B SiSU +\- Structured information, Serialized Units \- a document publishing system + +.BR +sisu \ [ \ \-abcDdFHhIiMmNnopqRrSsTtUuVvwXxYyZz0\-9 \ ] \ [ \ filename/ \ +wildcard \ ] + +.BR +sisu \ [ \ \-Ddcv \ ] \ [ \ instruction \ ] + +.BR +sisu \ [ \ \-CcFLSVvW \ ] + +.BR +Note: commands should be issued from within the directory that contains the +marked up files, cd to markup directory. + +.SH +5.2 DESCRIPTION + +.BR +.B SiSU +.B SiSU +is a document publishing system, that from a simple single marked\-up +document, produces multiple of output formats including: plaintext, html, +LaTeX, pdf, xhtml, XML, info, and SQL (PostgreSQL and SQLite), which share +numbered text objects (\"object citation numbering\") and the same document +structure information. For more see: + +.SH +5.3 DOCUMENT PROCESSING COMMAND FLAGS + +.TP +.B \ \-a \ \ [filename/wildcard] +produces plaintext with Unix linefeeds and without markup, (object numbers +are omitted), has footnotes at end of each paragraph that contains them \ [ \ +\-A \ for \ equivalent \ dos \ (linefeed) \ output \ file] \ [see \ \-e \ for \ +endnotes]. (Options include: \-\-endnotes for endnotes \-\-footnotes for +footnotes at the end of each paragraph \-\-unix for unix linefeed (default) +\-\-msdos for msdos linefeed) + +.TP +.B \ \-b \ \ [filename/wildcard] +produces xhtml/XML output for browser viewing (sax parsing). + +.TP +.B \ \-C \ \ [\-\-init\-site] +configure/initialise shared output directory files initialize shared output +directory (config files such as css and dtd files are not updated if they +already exist unless modifier is used). \-C \-\-init\-site configure/initialise +site more extensive than \-C on its own, shared output directory files/force +update, existing shared output config files such as css and dtd files are +updated if this modifier is used. + +.TP +.B \ \-CC +\ configure/initialise \ shared \ output \ directory \ files \ initialize \ +shared \ output \ directory \ (config \ files \ such \ as \ css \ and \ dtd \ +files \ are \ not \ updated \ if \ they \ already \ exist \ unless \ modifier \ +is \ used). \ The \ equivalent \ of: \ \-C \ \-\-init\-site \ +configure/initialise \ site, \ more \ extensive \ than \ \-C \ on \ its \ own, +\ shared \ output \ directory \ files/force \ update, \ existing \ shared \ +output \ config \ files \ such \ as \ css \ and \ dtd \ files \ are \ updated \ +if \ \-CC \ is \ used. \ + +.TP +.B \ \-c \ \ [filename/wildcard] +screen toggle ansi screen colour on or off depending on default set (unless +\-c flag is used: if sisurc colour default is set to \'true\', output to screen +will be with colour, if sisurc colour default is set to \'false\' or is +undefined screen output will be without colour). + +.TP +.B \ \-D \ \ [instruction] \ [filename] +database postgresql ( \-\-pgsql may be used instead) possible instructions, +include: \-\-createdb; \-\-create; \-\-dropall; \-\-import \ [filename]; +\-\-update \ [filename]; \-\-remove \ [filename]; see database section below. + +.TP +.B \ \-d \ \ [\-\-db\-[database \ type \ (sqlite|pg)]] \-\-[instruction] \ +[filename] +database type default set to sqlite, (for which \-\-sqlite may be used +instead) or to specify another database \-\-db\-[pgsql, \ sqlite] (however see +\-D) possible instructions include: \-\-createdb; \-\-create; \-\-dropall; +\-\-import \ [filename]; \-\-update \ [filename]; \-\-remove \ [filename]; see +database section below. + +.TP +.B \ \-F \ \ [\-\-webserv=webrick] +generate examples of (naive) cgi search form for sqlite and pgsql depends on +your already having used sisu to populate an sqlite and/or pgsql database, (the +sqlite version scans the output directories for existing sisu_sqlite databases, +so it is first necessary to create them, before generating the search form) see +\-d \-D and the database section below. If the optional parameter +\-\-webserv=webrick is passed, the cgi examples created will be set up to use +the default port set for use by the webrick server, (otherwise the port is left +blank and the system setting used, usually 80). The samples are dumped in the +present work directory which must be writable, (with screen instructions given +that they be copied to the cgi\-bin directory). \-Fv (in addition to the above) +provides some information on setting up hyperestraier for sisu + +.TP +.B \ \-H \ \ [filename/wildcard] +produces html without link suffixes (.html .pdf etc.) (\"Hide\"). Requires an +appropriately configured web server. \ [behaviour \ switched \ after \ 0.35 \ +see \ \-h]. + +.TP +.B \ \-h \ \ [filename/wildcard] +produces html (with hardlinks i.e. with name suffixes in links/local urls). +html, with internal document links that include the document suffix, i.e. +whether it is .html or .pdf (required for browsing directly off a file system, +and works with most web servers). \ [behaviour \ switched \ after \ 0.35 \ see +\ \-H]. + +.TP +.B \ \-I \ \ [filename/wildcard] +produces texinfo and info file, (view with pinfo). + +.TP +.B \ \-L +\ prints \ license \ information. \ + +.TP +.B \ \-M \ \ [filename/wildcard/url] +maintenance mode files created for processing preserved and their locations +indicated. (also see \-V) + +.TP +.B \ \-m \ \ [filename/wildcard/url] +assumed for most other flags, creates new meta\-markup file, (the metaverse ) +that is used in all subsequent processing of other output. This step is assumed +for most processing flags. To skip it see \-n + +.TP +.B \ \-N \ \ [filename/wildcard/url] +document digest or document content certificate ( DCC ) as md5 digest tree of +the document: the digest for the document, and digests for each object +contained within the document (together with information on software versions +that produced it) (digest.txt). \-NV for verbose digest output to screen. + +.TP +.B \ \-n \ \ [filename/wildcard/url] +skip meta\-markup (building of \"metaverse\"), this skips the equivalent of +\-m which is otherwise assumed by most processing flags. + +.TP +.B \ \-o \ \ [filename/wildcard/url] +output basic document in opendocument file format (opendocument.odt). + +.TP +.B \ \-p \ \ [filename/wildcard] +produces LaTeX pdf (portrait.pdf & landscape.pdf). Default paper size is set +in config file, or document header, or provided with additional command line +parameter, e.g. \-\-papersize\-a4 preset sizes include: \'A4\', U.S. \'letter\' +and \'legal\' and book sizes \'A5\' and \'B5\' (system defaults to A4). + +.TP +.B \ \-q \ \ [filename/wildcard] +quiet less output to screen. + +.TP +.B \ \-R \ \ [filename/wildcard] +copies sisu output files to remote host using rsync. This requires that +sisurc.yml has been provided with information on hostname and username, and +that you have your \"keys\" and ssh agent in place. Note the behavior of rsync +different if \-R is used with other flags from if used alone. Alone the rsync +\-\-delete parameter is sent, useful for cleaning the remote directory (when +\-R is used together with other flags, it is not). Also see \-r + +.TP +.B \ \-r \ \ [filename/wildcard] +copies sisu output files to remote host using scp. This requires that +sisurc.yml has been provided with information on hostname and username, and +that you have your \"keys\" and ssh agent in place. Also see \-R + +.TP +.B \ \-S +\ produces \ a \ sisupod \ a \ zipped \ sisu \ directory \ of \ markup \ +files \ including \ sisu \ markup \ source \ files \ and \ the \ directories \ +local \ configuration \ file, \ images \ and \ skins. \ Note: \ this \ only \ +includes \ the \ configuration \ files \ or \ skins \ contained \ in \ ./_sisu +\ not \ those \ in \ ~/.sisu \ \-S \ \ [filename/wildcard] option. Note: (this +option is tested only with zsh). + +.TP +.B \ \-S \ \ [filename/wildcard] +produces a zipped file of the prepared document specified along with +associated images, by default named sisupod.zip they may alternatively be named +with the filename extension .ssp This provides a quick way of gathering the +relevant parts of a sisu document which can then for example be emailed. A +sisupod includes sisu markup source file, (along with associated documents if a +master file, or available in multilingual versions), together with related +images and skin. +.B SiSU +commands can be run directly against a sisupod contained in a local +directory, or provided as a url on a remote site. As there is a security issue +with skins provided by other users, they are not applied unless the flag +\-\-trust or \-\-trusted is added to the command instruction, it is recommended +that file that are not your own are treated as untrusted. The directory +structure of the unzipped file is understood by sisu, and sisu commands can be +run within it. Note: if you wish to send multiple files, it quickly becomes +more space efficient to zip the sisu markup directory, rather than the +individual files for sending). See the \-S option without \ +[filename/wildcard]. + +.TP +.B \ \-s \ \ [filename/wildcard] +copies sisu markup file to output directory. + +.TP +.B \ \-t \ \ [filename/wildcard \ (*.termsheet.rb)] +standard form document builder, preprocessing feature + +.TP +.B \ \-U \ \ [filename/wildcard] +prints url output list/map for the available processing flags options and +resulting files that could be requested, (can be used to get a list of +processing options in relation to a file, together with information on the +output that would be produced), \-u provides url output mapping for those flags +requested for processing. The default assumes sisu_webrick is running and +provides webrick url mappings where appropriate, but these can be switched to +file system paths in sisurc.yml + +.TP +.B \ \-u \ \ [filename/wildcard] +provides url mapping of output files for the flags requested for processing, +also see \-U + +.TP +.B \ \-V +\ on \ its \ own, \ provides +.B \ SiSU +\ version \ and \ environment \ information \ (sisu \ \-\-help \ env) \ + +.TP +.B \ \-V \ \ [filename/wildcard] +even more verbose than the \-v flag. (also see \-M) + +.TP +.B \ \-v +\ on \ its \ own, \ provides +.B \ SiSU +\ version \ information \ + +.TP +.B \ \-v \ \ [filename/wildcard] +provides verbose output of what is being built, where it is being built (and +error messages if any), as with \-u flag provides a url mapping of files +created for each of the processing flag requests. See also \-V + +.TP +.B \ \-W +\ starts \ ruby\'s \ webrick \ webserver \ points \ at \ sisu \ output \ +directories, \ the \ default \ port \ is \ set \ to \ 8081 \ and \ can \ be \ +changed \ in \ the \ resource \ configuration \ files. \ \ [tip: \ the \ +webrick \ server \ requires \ link \ suffixes, \ so \ html \ output \ should \ +be \ created \ using \ the \ \-h \ option \ rather \ than \ \-H; \ also, \ note +\ \-F \ webrick \ ]. + +.TP +.B \ \-w \ \ [filename/wildcard] +produces concordance (wordmap) a rudimentary index of all the words in a +document. (Concordance files are not generated for documents of over 260,000 +words unless this limit is increased in the file sisurc.yml) + +.TP +.B \ \-X \ \ [filename/wildcard] +produces XML output with deep document structure, in the nature of dom. + +.TP +.B \ \-x \ \ [filename/wildcard] +produces XML output shallow structure (sax parsing). + +.TP +.B \ \-Y \ \ [filename/wildcard] +produces a short sitemap entry for the document, based on html output and the +sisu_manifest. \-\-sitemaps generates/updates the sitemap index of existing +sitemaps. (Experimental, \ [g,y,m \ announcement \ this \ week]) + +.TP +.B \ \-y \ \ [filename/wildcard] +produces an html summary of output generated (hyperlinked to content) and +document specific metadata (sisu_manifest.html). This step is assumed for most +processing flags. + +.TP +.B \ \-Z \ \ [filename/wildcard] +Zap, if used with other processing flags deletes output files of the type +about to be processed, prior to processing. If \-Z is used as the lone +processing related flag (or in conjunction with a combination of \-[mMvVq]), +will remove the related document output directory. + +.TP +.B \ \-z \ \ [filename/wildcard] +produces php (zend) \ [this \ feature \ is \ disabled \ for \ the \ time \ +being] + +.SH +6. COMMAND LINE MODIFIERS +.BR + +.TP +.B \ \-\-no\-ocn +\ \ [with \ \-h \ \-H \ or \ \-p] switches off object citation numbering. +Produce output without identifying numbers in margins of html or LaTeX/pdf +output. + +.TP +.B \ \-\-no\-annotate +\ strips \ output \ text \ of \ editor \ endnotes[^*1] denoted by asterisk or +dagger/plus sign + +.TP +.B \ \-\-no\-asterisk +\ strips \ output \ text \ of \ editor \ endnotes[^*2] denoted by asterisk +sign + +.TP +.B \ \-\-no\-dagger +\ strips \ output \ text \ of \ editor \ endnotes[^+1] denoted by dagger/plus +sign + +.SH +7. DATABASE COMMANDS +.BR + +.BR +dbi \- database interface + +.BR +\-D or \-\-pgsql set for postgresql \-d or \-\-sqlite default set for sqlite +\-d is modifiable with \-\-db=[database \ type \ (pgsql \ or \ sqlite)] + +.TP +.B \ \-Dv \ \-\-createall +\ initial \ step, \ creates \ required \ relations \ (tables, \ indexes) \ in +\ existing \ postgresql \ database \ (a \ database \ should \ be \ created \ +manually \ and \ given \ the \ same \ name \ as \ working \ directory, \ as \ +requested) \ (rb.dbi) \ \ [ \ \-dv \ \-\-createall \ sqlite \ equivalent] it +may be necessary to run sisu \-Dv \-\-createdb initially NOTE: at the present +time for postgresql it may be necessary to manually create the database. The +command would be \'createdb \ [database \ name]\' where database name would be +SiSU_[present \ working \ directory \ name \ (without \ path)]. Please use only +alphanumerics and underscores. + +.TP +.B \ \-Dv \ \-\-import +\ \ [filename/wildcard] imports data specified to postgresql db (rb.dbi) \ [ +\ \-dv \ \-\-import \ sqlite \ equivalent] + +.TP +.B \ \-Dv \ \-\-update +\ \ [filename/wildcard] updates/imports specified data to postgresql db +(rb.dbi) \ [ \ \-dv \ \-\-update \ sqlite \ equivalent] + +.TP +.B \ \-D \ \-\-remove +\ \ [filename/wildcard] removes specified data to postgresql db (rb.dbi) \ [ +\ \-d \ \-\-remove \ sqlite \ equivalent] + +.TP +.B \ \-D \ \-\-dropall +\ kills \ data\" \ and \ drops \ (postgresql \ or \ sqlite) \ db, \ tables \ +& \ indexes \ \ [ \ \-d \ \-\-dropall \ sqlite \ equivalent] + +.BR +The v in e.g. \-Dv is for verbose output. + +.SH +8. SHORTCUTS, SHORTHAND FOR MULTIPLE FLAGS +.BR + +.TP +.B \ \-\-update \ \ [filename/wildcard] +Checks existing file output and runs the flags required to update this +output. This means that if only html and pdf output was requested on previous +runs, only the \-hp files will be applied, and only these will be generated +this time, together with the summary. This can be very convenient, if you offer +different outputs of different files, and just want to do the same again. + +.TP +.B \ \-0 \ to \ \-5 \ \ [filename \ or \ wildcard] +Default shorthand mappings (note that the defaults can be changed/configured +in the sisurc.yml file): + +.TP +.B \ \-0 +\ \-mNhwpAobxXyYv \ \ [this \ is \ the \ default \ action \ run \ when \ no \ +options \ are \ give, \ i.e. \ on \ \'sisu \ \ [filename]\'] + +.TP +.B \ \-1 +\ \-mNHwpy \ + +.TP +.B \ \-2 +\ \-mNHwpaoy \ + +.TP +.B \ \-3 +\ \-mNhwpAobxXyY \ + +.TP +.B \ \-4 +\ \-mNhwpAobxXDyY \ \-\-import \ + +.TP +.B \ \-5 +\ \-mNhwpAobxXDyY \ \-\-update \ + +.BR +add \-v for verbose mode and \-c for color, e.g. sisu \-2vc \ [filename \ or \ +wildcard] + +.BR +consider \-u for appended url info or \-v for verbose output + +.SH +8.0.1 COMMAND LINE WITH FLAGS \- BATCH PROCESSING + +.BR +In the data directory run sisu \-mh filename or wildcard eg. \"sisu \-h +cisg.sst\" or \"sisu \-h *.{sst,ssm}\" to produce html version of all +documents. + +.BR +Running sisu (alone without any flags, filenames or wildcards) brings up the +interactive help, as does any sisu command that is not recognised. Enter to +escape. + +.SH +9. INTRODUCTION TO SISU MARKUP[^15] +.BR + +.SH +9.1 SUMMARY + +.BR +.B SiSU +source documents are plaintext (UTF\-8)[^16] files + +.BR +All paragraphs are separated by an empty line. + +.BR +Markup is comprised of: + +.BR +* at the top of a document, the document header made up of semantic meta\-data +about the document and if desired additional processing instructions (such an +instruction to automatically number headings from a particular level down) + +.BR +* followed by the prepared substantive text of which the most important single +characteristic is the markup of different heading levels, which define the +primary outline of the document structure. Markup of substantive text includes: + +.BR + * heading levels defines document structure + +.BR + * text basic attributes, italics, bold etc. + +.BR + * grouped text (objects), which are to be treated differently, such as code + blocks or poems. + +.BR + * footnotes/endnotes + +.BR + * linked text and images + +.BR + * paragraph actions, such as indent, bulleted, numbered\-lists, etc. + +.BR +Some interactive help on markup is available, by typing sisu and selecting +markup or sisu \-\-help markup + +.SH +9.2 MARKUP EXAMPLES + +.SH +9.2.1 ONLINE + +.BR +Online markup examples are available together with the respective outputs +produced from or from + + +.BR +There is of course this document, which provides a cursory overview of sisu +markup and the respective output produced: + + +.BR +Some example marked up files are available as html with syntax highlighting for +viewing: + +.BR +an alternative presentation of markup syntax: + + +.SH +9.2.2 INSTALLED + +.BR +With +.B SiSU +installed sample skins may be found in: +/usr/share/doc/sisu/sisu_markup_samples/dfsg (or equivalent directory) and if +sisu\-markup\-samples is installed also under: +/usr/share/doc/sisu/sisu_markup_samples/non\-free + +.SH +10. MARKUP OF HEADERS +.BR + +.BR +Headers consist of semantic meta\-data about a document, which can be used by +any output module of the program; and may in addition include extra processing +instructions. + +.BR +Note: the first line of a document may include information on the markup +version used in the form of a comment. Comments are a percentage mark at the +start of a paragraph (and as the first character in a line of text) followed by +a space and the comment: + + +.nf + % this would be a comment +.fi + +.SH +10.1 SAMPLE HEADER + +.BR +This current document has a header similar to this one (without the comments): + + +.nf + % SiSU 0.57 + @title: SiSU + @subtitle: Markup \ [0.58] + @creator: Ralph Amissah + @rights: Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL 3 + @type: information + @subject: ebook, epublishing, electronic book, electronic publishing, electronic document, electronic citation, data structure, citation systems, search + @date.created: 2002\-08\-28 + @date.issued: 2002\-08\-28 + @date.available: 2002\-08\-28 + @date.modified: 2007\-09\-16 + @date: 2007\-09\-16 + @level: new=C; break=1; num_top=1 + % comment: in this @level header num_top=1 starts automatic heading numbering at heading level 1 (numbering continues 3 levels down); the new and break instructions are used by the LaTeX/pdf and odf output to determine where to put page breaks (that are not used by html output or say sql database population). + @skin: skin_sisu_manual + % skins modify the appearance of a document and are placed in a sub\-directory under ./_sisu/skin ~/.sisu/skin or /etc/sisu/skin. A skin may affect single documents that request them, all documents in a directory, or be site\-wide. (A document is affected by a single skin) + @bold: /Gnu|Debian|Ruby|SiSU/ + @links: { SiSU Manual }http://www.jus.uio.no/sisu/sisu_manual/ + { Book Samples and Markup Examples }http://www.jus.uio.no/sisu/SiSU/2.html + { SiSU @ Wikipedia }http://en.wikipedia.org/wiki/SiSU + { SiSU @ Freshmeat }http://freshmeat.net/projects/sisu/ + { SiSU @ Ruby Application Archive }http://raa.ruby\-lang.org/project/sisu/ + { SiSU @ Debian }http://packages.qa.debian.org/s/sisu.html + { SiSU Download }http://www.jus.uio.no/sisu/SiSU/download.html + { SiSU Changelog }http://www.jus.uio.no/sisu/SiSU/changelog.html +.fi + +.SH +10.2 AVAILABLE HEADERS + +.BR +Header tags appear at the beginning of a document and provide meta information +on the document (such as the Dublin Core), or information as to how the +document as a whole is to be processed. All header instructions take either the +form @headername: or 0~headername. All Dublin Core meta tags are available + +.BR +.B @indentifier: +information or instructions + +.BR +where the \"identifier\" is a tag recognised by the program, and the +\"information\" or \"instructions\" belong to the tag/indentifier specified + +.BR +Note: a header where used should only be used once; all headers apart from +@title: are optional; the @structure: header is used to describe document +structure, and can be useful to know. + +.BR +This is a sample header + +.BR +.B % SiSU 0.38 +\ [declared \ file\-type \ identifier \ with \ markup \ version] + +.BR +.B @title: +\ [title \ text] This is the title of the document and used as such, this +header is the only one that is +.I mandatory + +.BR +.B @subtitle: +The Subtitle if any + +.BR +.B @creator: +\ [or \ @author:] Name of Author + +.BR +.B @subject: +(whatever your subject) + +.BR +.B @description: + +.BR +.B @publisher: + +.BR +.B @contributor: + +.BR +.B @translator: +\ [or \ @translated_by:] + +.BR +.B @illustrator: +\ [or \ @illustrated_by:] + +.BR +.B @prepared_by: +\ [or \ @digitized_by:] + +.BR +.B @date: 2000\-08\-27 +\ [ \ also \ @date.created: \ @date.issued: \ @date.available: \ @date.valid: +\ @date.modified: \ ] + +.BR +.B @type: article + +.BR +.B @format: + +.BR +.B @identifier: + +.BR +.B @source: + +.BR +.B @language: +\ [or \ @language.document:] \ [country \ code \ for \ language \ if \ +available, \ or \ language, \ English, \ en \ is \ the \ default \ setting] (en +\- English, fr \- French, de \- German, it \- Italian, es \- Spanish, pt \- +Portuguese, sv \- Swedish, da \- Danish, fi \- Finnish, no \- Norwegian, is \- +Icelandic, nl \- Dutch, et \- Estonian, hu \- Hungarian, pl \- Polish, ro \- +Romanian, ru \- Russian, el \- Greek, uk \- Ukranian, tr \- Turkish, sk \- +Slovak, sl \- Slovenian, hr \- Croatian, cs \- Czech, bg \- Bul garian ) \ +[however, \ encodings \ are \ not \ available \ for \ all \ of \ the \ +languages \ listed.] + +.BR +[@language.original: \ original \ language \ in \ which \ the \ work \ was \ +published] + +.BR +.B @papersize: +(A4|US_letter|book_B5|book_A5|US_legal) + +.BR +.B @relation: + +.BR +.B @coverage: + +.BR +.B @rights: +Copyright (c) Name of Right Holder, all rights reserved, or as granted: +public domain, copyleft, creative commons variant, etc. + +.BR +.B @owner: + +.BR +.B @keywords: +text document generation processing management latex pdf structured xml +citation \ [your \ keywords \ here, \ used \ for \ example \ by \ rss \ feeds, +\ and \ in \ sql \ searches] + +.BR +.B @abstract: +\ [paper \ abstract, \ placed \ after \ table \ of \ contents] + +.BR +.B @comment: +\ [...] + +.BR +.B @catalogue: +loc=[Library \ of \ Congress \ classification]; dewey=[Dewey \ +classification]; isbn=[ISBN]; pg=[Project \ Gutenberg \ text \ number] + +.BR +.B @classify_loc: +\ [Library \ of \ Congress \ classification] + +.BR +.B @classify_dewey: +\ [Dewey \ classification] + +.BR +.B @classify_isbn: +\ [ISBN] + +.BR +.B @classify_pg: +\ [Project \ Gutenberg \ text \ number] + +.BR +.B @prefix: +\ [prefix \ is \ placed \ just \ after \ table \ of \ contents] + +.BR +.B @prefix_a: +\ [prefix \ is \ placed \ just \ before \ table \ of \ contents \ \- \ not \ +implemented] + +.BR +.B @prefix_b: + +.BR +.B @rcs: +$Id: sisu_markup.sst,v 1.2 2007/09/08 17:12:47 ralph Exp $ \ [used \ by \ rcs +\ or \ cvs \ to \ embed \ version \ (revision \ control) \ information \ into \ +document, \ rcs \ or \ cvs \ can \ usefully \ provide \ a \ history \ of \ +updates \ to \ a \ document \ ] + +.BR +.B @structure: +PART; CHAPTER; SECTION; ARTICLE; none; none; +optional, document structure can be defined by words to match or regular +expression (the regular expression is assumed to start at the beginning of a +line of text i.e. ^) default markers :A~ to :C~ and 1~ to 6~ can be used within +text instead, without this header tag, and may be used to supplement the +instructions provided in this header tag if provided (@structure: is a synonym +for @toc:) + +.BR +.B @level: +newpage=3; breakpage=4 +\ [paragraph \ level, \ used \ by \ latex \ to \ breakpages, \ the \ page \ +is \ optional \ eg. \ in \ newpage] + +.BR +.B @markup: +information on the markup used, e.g. new=1,2,3; break=4; num_top=4 \ [or \ +newpage=1,2,3; \ breakpage=4; \ num_top=4] newpage and breakpage, heading +level, used by LaTeX to breakpages. breakpage: starts on a new page in single +column text and on a new column in double column text; newpage: starts on a new +page for both single and double column texts. +num_top=4 \ [auto\-number \ document, \ starting \ at \ level \ 4. \ the \ +default \ is \ to \ provide \ 3 \ levels, \ as \ in \ 1 \ level \ 4, \ 1.1 \ +level \ 5, \ 1.1.1 \ level \ 6, \ markup \ to \ be \ merged \ within \ level] +num_extract \ [take \ numbering \ of \ headings \ provided \ (manually \ in \ +marked \ up \ source \ document), \ and \ use \ for \ numbering \ of \ +segments. \ Available \ where \ a \ clear \ numbering \ structure \ is \ +provided \ within \ document, \ without \ the \ repetition \ of \ a \ number \ +in \ a \ header.] \ [In \ 0.38 \ notation, \ you \ would \ map \ to \ the \ +equivalent \ levels, \ the \ examples \ provided \ would \ map \ to \ the \ +following \ new=A,B,C; \ break=1; \ num_top=1 \ \ [or \ newpage=A,B,C; \ +breakpage=1; \ num_top=1] see headings] + +.BR +.B @bold: +\ [regular \ expression \ of \ words/phrases \ to \ be \ made \ bold] + +.BR +.B @italics: +\ [regular \ expression \ of \ words/phrases \ to \ italicise] + +.BR +.B @vocabulary: +name of taxonomy/vocabulary/wordlist to use against document + +.BR +.B @skin: +skin_doc_[name_of_desired_document_skin] +skins change default settings related to the appearance of documents +generated, such as the urls of the home site, and the icon/logo for the +document or site. + +.BR +.B @links: +{ +.B SiSU +}http://www.jus.uio.no/sisu/; +{ FSF }http://www.fsf.org + +.BR +.B @promo: +sisu, ruby, search_libre_docs, open_society +\ [places \ content \ in \ right \ pane \ in \ html, \ makes \ use \ of \ +list.yml \ and \ promo.yml, \ commented \ out \ sample \ in \ document \ +sample: \ +free_as_in_freedom.richard_stallman_crusade_for_free_software.sam_williams.sst] + +.SH +11. MARKUP OF SUBSTANTIVE TEXT +.BR + +.SH +11.1 HEADING LEVELS + +.BR +Heading levels are :A~ ,:B~ ,:C~ ,1~ ,2~ ,3~ ... :A \- :C being part / section +headings, followed by other heading levels, and 1 \-6 being headings followed +by substantive text or sub\-headings. :A~ usually the title :A~? conditional +level 1 heading (used where a stand\-alone document may be imported into +another) + +.BR +.B :A~ \ [heading \ text] +Top level heading \ [this \ usually \ has \ similar \ content \ to \ the \ +title \ @title: \ ] NOTE: the heading levels described here are in 0.38 +notation, see heading + +.BR +.B :B~ \ [heading \ text] +Second level heading \ [this \ is \ a \ heading \ level \ divider] + +.BR +.B :C~ \ [heading \ text] +Third level heading \ [this \ is \ a \ heading \ level \ divider] + +.BR +.B 1~ \ [heading \ text] +Top level heading preceding substantive text of document or sub\-heading 2, +the heading level that would normally be marked 1. or 2. or 3. etc. in a +document, and the level on which sisu by default would break html output into +named segments, names are provided automatically if none are given (a number), +otherwise takes the form 1~my_filename_for_this_segment + +.BR +.B 2~ \ [heading \ text] +Second level heading preceding substantive text of document or sub\-heading +3, the heading level that would normally be marked 1.1 or 1.2 or 1.3 or 2.1 +etc. in a document. + +.BR +.B 3~ \ [heading \ text] +Third level heading preceding substantive text of document, that would +normally be marked 1.1.1 or 1.1.2 or 1.2.1 or 2.1.1 etc. in a document + + +.nf + 1~filename level 1 heading, + % the primary division such as Chapter that is followed by substantive text, and may be further subdivided (this is the level on which by default html segments are made) +.fi + +.SH +11.2 FONT ATTRIBUTES + +.BR +.B markup example: + + +.nf + normal text !{emphasis}! *{bold text}* _{underscore}_ /{italics}/ \"{citation}\" ^{superscript}^ ,{subscript}, +{inserted text}+ + normal text + !{emphasis}! + *{bold text}* + _{underscore} + /{italics}/ + \"{citation}\" + ^{superscript}^ + ,{subscript}, + +{inserted text}+ + \-{strikethrough}\- +.fi + +.BR +.B resulting output: + +.BR +normal text emphasis +.B bold text +.I underscore +.I italics +citation ^superscript^ \ [subscript] inserted text +strikethrough + +.BR +normal text + +.BR +emphasis + +.BR +.B bold text + +.BR +.I underscore + +.BR +.I italics + +.BR +citation + +.BR +^superscript^ + +.BR +[subscript] + +.BR +inserted text + +.BR +strikethrough + +.SH +11.3 INDENTATION AND BULLETS + +.BR +.B markup example: + + +.nf + ordinary paragraph + _1 indent paragraph one step + _2 indent paragraph two steps + _9 indent paragraph nine steps +.fi + +.BR +.B resulting output: + +.BR +ordinary paragraph + +.BR + indent paragraph one step + +.BR + indent paragraph two steps + +.BR + indent paragraph nine steps + +.BR +.B markup example: + + +.nf + * bullet text + _1* bullet text, first indent + _2* bullet text, two step indent +.fi + +.BR +.B resulting output: + +.BR +* bullet text + +.BR + * bullet text, first indent + +.BR + * bullet text, two step indent + +.BR +Numbered List (not to be confused with headings/titles, (document structure)) + +.BR +.B markup example: + + +.nf + # numbered list numbered list 1., 2., 3, etc. + _# numbered list numbered list indented a., b., c., d., etc. +.fi + +.SH +11.4 FOOTNOTES / ENDNOTES + +.BR +Footnotes and endnotes not distinguished in markup. They are automatically +numbered. Depending on the output file format (html, odf, pdf etc.), the +document output selected will have either footnotes or endnotes. + +.BR +.B markup example: + + +.nf + ~{ a footnote or endnote }~ +.fi + +.BR +.B resulting output: + +.BR +[^17] + +.BR +.B markup example: + + +.nf + normal text~{ self contained endnote marker & endnote in one }~ continues +.fi + +.BR +.B resulting output: + +.BR +normal text[^18] continues + +.BR +.B markup example: + + +.nf + normal text ~{* unnumbered asterisk footnote/endnote, insert multiple asterisks if required }~ continues + normal text ~{** another unnumbered asterisk footnote/endnote }~ continues +.fi + +.BR +.B resulting output: + +.BR +normal text \ [^*] continues + +.BR +normal text \ [^**] continues + +.BR +.B markup example: + + +.nf + normal text ~[* \ editors \ notes, \ numbered \ asterisk \ footnote/endnote \ series \ ]~ continues + normal text ~[+ \ editors \ notes, \ numbered \ asterisk \ footnote/endnote \ series \ ]~ continues +.fi + +.BR +.B resulting output: + +.BR +normal text \ [^*3] continues + +.BR +normal text \ [^+2] continues + +.BR +.B Alternative endnote pair notation for footnotes/endnotes: + + +.nf +.nf + % note the endnote marker \"~^\" + normal text~^ continues + ^~ endnote text following the paragraph in which the marker occurs +.fi + +.BR +the standard and pair notation cannot be mixed in the same document + +.SH +11.5 LINKS + +.SH +11.5.1 NAKED URLS WITHIN TEXT, DEALING WITH URLS + +.BR +urls are found within text and marked up automatically. A url within text is +automatically hyperlinked to itself and by default decorated with angled +braces, unless they are contained within a code block (in which case they are +passed as normal text), or escaped by a preceding underscore (in which case the +decoration is omitted). + +.BR +.B markup example: + + +.nf + normal text http://www.jus.uio.no/sisu continues +.fi + +.BR +.B resulting output: + +.BR +normal text continues + +.BR +An escaped url without decoration + +.BR +.B markup example: + + +.nf + normal text http://www.jus.uio.no/sisu continues + deb http://www.jus.uio.no/sisu/archive unstable main non\-free +.fi + +.BR +.B resulting output: + +.BR +normal text http://www.jus.uio.no/sisu continues + +.BR +deb http://www.jus.uio.no/sisu/archive unstable main non\-free + +.BR +where a code block is used there is neither decoration nor hyperlinking, code +blocks are discussed later in this document + +.BR +.B resulting output: + + +.nf + deb http://www.jus.uio.no/sisu/archive unstable main non\-free + deb\-src http://www.jus.uio.no/sisu/archive unstable main non\-free +.fi + +.BR +To link text or an image to a url the markup is as follows + +.BR +.B markup example: + + +.nf + about { SiSU }http://url.org markup +.fi + +.SH +11.5.2 LINKING TEXT + +.BR +.B resulting output: + +.BR +about SiSU markup + +.BR +A shortcut notation is available so the url link may also be provided +automatically as a footnote + +.BR +.B markup example: + + +.nf + about {~^ SiSU }http://url.org markup +.fi + +.BR +.B resulting output: + +.BR +about SiSU \ [^19] markup + +.SH +11.5.3 LINKING IMAGES + +.BR +.B markup example: + + +.nf + [ tux.png ] + % various url linked images + [ tux.png ] + [ GnuDebianLinuxRubyBetterWay.png ] + {~^ ruby_logo.png \"Ruby\" }http://www.ruby\-lang.org/en/ +.fi + +.BR +.B resulting output: + +.BR +[ tux.png ] + +.BR +tux.png 64x80 \"Gnu/Linux \- a better way\" + +.BR +[ \ ruby_logo \ (png \ missing) \ ] \ [^20] + +.BR +GnuDebianLinuxRubyBetterWay.png 100x101 \"Way Better \- with Gnu/Linux, Debian +and Ruby\" + +.BR +.B linked url footnote shortcut + + +.nf + {~^ \ [text \ to \ link] }http://url.org + % maps to: { \ [text \ to \ link] }http://url.org ~{ http://url.org }~ + % which produces hyper\-linked text within a document/paragraph, with an endnote providing the url for the text location used in the hyperlink +.fi + + +.nf + text marker *~name +.fi + +.BR +note at a heading level the same is automatically achieved by providing names +to headings 1, 2 and 3 i.e. 2~[name] and 3~[name] or in the case of +auto\-heading numbering, without further intervention. + +.SH +11.6 GROUPED TEXT + +.SH +11.6.1 TABLES + +.BR +Tables may be prepared in two either of two forms + +.BR +.B markup example: + + +.nf + table{ c3; 40; 30; 30; + This is a table + this would become column two of row one + column three of row one is here + And here begins another row + column two of row two + column three of row two, and so on + }table +.fi + +.BR +.B resulting output: + + \ [table \ omitted, \ see \ other \ document \ formats] + +.BR +a second form may be easier to work with in cases where there is not much +information in each column + +.BR +.B markup example: +[^21] + + +.nf + !_ Table 3.1: Contributors to Wikipedia, January 2001 \- June 2005 + {table~h 24; 12; 12; 12; 12; 12; 12;} + |Jan. 2001|Jan. 2002|Jan. 2003|Jan. 2004|July 2004|June 2006 + Contributors* | 10| 472| 2,188| 9,653| 25,011| 48,721 + Active contributors** | 9| 212| 846| 3,228| 8,442| 16,945 + Very active contributors*** | 0| 31| 190| 692| 1,639| 3,016 + No. of English language articles| 25| 16,000| 101,000| 190,000| 320,000| 630,000 + No. of articles, all languages | 25| 19,000| 138,000| 490,000| 862,000|1,600,000 + \* Contributed at least ten times; \** at least 5 times in last month; \*\** more than 100 times in last month. +.fi + +.BR +.B resulting output: + +.BR +.B Table 3.1: Contributors to Wikipedia, January 2001 \- June 2005 + + \ [table \ omitted, \ see \ other \ document \ formats] + +.BR +* Contributed at least ten times; ** at least 5 times in last month; *** more +than 100 times in last month. + +.SH +11.6.2 POEM + +.BR +.B basic markup: + + +.nf + poem{ + Your poem here + }poem + Each verse in a poem is given a separate object number. +.fi + +.BR +.B markup example: + + +.nf + poem{ + \'Fury said to a + mouse, That he + met in the + house, + \"Let us + both go to + law: I will + prosecute + YOU. \-\-Come, + I\'ll take no + denial; We + must have a + trial: For + really this + morning I\'ve + nothing + to do.\" + Said the + mouse to the + cur, \"Such + a trial, + dear Sir, + With + no jury + or judge, + would be + wasting + our + breath.\" + \"I\'ll be + judge, I\'ll + be jury,\" + Said + cunning + old Fury: + \"I\'ll + try the + whole + cause, + and + condemn + you + to + death.\"\' + }poem +.fi + +.BR +.B resulting output: + + + \'Fury said to a +.P + mouse, That he +.P + met in the +.P + house, +.P + \"Let us +.P + both go to +.P + law: I will +.P + prosecute +.P + YOU. \-\-Come, +.P + I\'ll take no +.P + denial; We +.P + must have a +.P + trial: For +.P + really this +.P + morning I\'ve +.P + nothing +.P + to do.\" +.P + Said the +.P + mouse to the +.P + cur, \"Such +.P + a trial, +.P + dear Sir, +.P + With +.P + no jury +.P + or judge, +.P + would be +.P + wasting +.P + our +.P + breath.\" +.P + \"I\'ll be +.P + judge, I\'ll +.P + be jury,\" +.P + Said +.P + cunning +.P + old Fury: +.P + \"I\'ll +.P + try the +.P + whole +.P + cause, +.P + and +.P + condemn +.P + you +.P + to +.P + death.\"\' +.P + +.SH +11.6.3 GROUP + +.BR +.B basic markup: + + +.nf + group{ + Your grouped text here + }group + A group is treated as an object and given a single object number. +.fi + +.BR +.B markup example: + + +.nf + group{ + \'Fury said to a + mouse, That he + met in the + house, + \"Let us + both go to + law: I will + prosecute + YOU. \-\-Come, + I\'ll take no + denial; We + must have a + trial: For + really this + morning I\'ve + nothing + to do.\" + Said the + mouse to the + cur, \"Such + a trial, + dear Sir, + With + no jury + or judge, + would be + wasting + our + breath.\" + \"I\'ll be + judge, I\'ll + be jury,\" + Said + cunning + old Fury: + \"I\'ll + try the + whole + cause, + and + condemn + you + to + death.\"\' + }group +.fi + +.BR +.B resulting output: + + + \'Fury said to a +.P + mouse, That he +.P + met in the +.P + house, +.P + \"Let us +.P + both go to +.P + law: I will +.P + prosecute +.P + YOU. \-\-Come, +.P + I\'ll take no +.P + denial; We +.P + must have a +.P + trial: For +.P + really this +.P + morning I\'ve +.P + nothing +.P + to do.\" +.P + Said the +.P + mouse to the +.P + cur, \"Such +.P + a trial, +.P + dear Sir, +.P + With +.P + no jury +.P + or judge, +.P + would be +.P + wasting +.P + our +.P + breath.\" +.P + \"I\'ll be +.P + judge, I\'ll +.P + be jury,\" +.P + Said +.P + cunning +.P + old Fury: +.P + \"I\'ll +.P + try the +.P + whole +.P + cause, +.P + and +.P + condemn +.P + you +.P + to +.P + death.\"\' +.P + +.SH +11.6.4 CODE + +.BR +Code tags are used to escape regular sisu markup, and have been used +extensively within this document to provide examples of +.B SiSU +markup. You cannot however use code tags to escape code tags. They are +however used in the same way as group or poem tags. + +.BR +A code\-block is treated as an object and given a single object number. \ [an \ +option \ to \ number \ each \ line \ of \ code \ may \ be \ considered \ at \ +some \ later \ time] + +.BR +.B use of code tags instead of poem compared, resulting output: + + +.nf + \'Fury said to a + mouse, That he + met in the + house, + \"Let us + both go to + law: I will + prosecute + YOU. \-\-Come, + I\'ll take no + denial; We + must have a + trial: For + really this + morning I\'ve + nothing + to do.\" + Said the + mouse to the + cur, \"Such + a trial, + dear Sir, + With + no jury + or judge, + would be + wasting + our + breath.\" + \"I\'ll be + judge, I\'ll + be jury,\" + Said + cunning + old Fury: + \"I\'ll + try the + whole + cause, + and + condemn + you + to + death.\"\' +.fi + +.SH +12. COMPOSITE DOCUMENTS MARKUP +.BR + +.BR +It is possible to build a document by creating a master document that requires +other documents. The documents required may be complete documents that could be +generated independently, or they could be markup snippets, prepared so as to be +easily available to be placed within another text. If the calling document is a +master document (built from other documents), it should be named with the +suffix +.B .ssm +Within this document you would provide information on the other documents +that should be included within the text. These may be other documents that +would be processed in a regular way, or markup bits prepared only for inclusion +within a master document +.B .sst +regular markup file, or +.B .ssi +(insert/information) A secondary file of the composite document is built +prior to processing with the same prefix and the suffix +.B ._sst + +.BR +basic markup for importing a document into a master document + + +.nf + << |filename1.sst|@|^| + << |filename2.ssi|@|^| +.fi + +.BR +The form described above should be relied on. Within the Vim editor it results +in the text thus linked becoming hyperlinked to the document it is calling in +which is convenient for editing. Alternative markup for importation of +documents under consideration, and occasionally supported have been. + + +.nf + r{filename} + {filename.ssi}require + << {filename.ssi} + % using textlink alternatives + |filename.ssi|@|^|require + << |filename.ssi|@|^| + % using thlnk alternatives + require + << +.fi + +.SH +MARKUP SYNTAX HISTORY +.BR + +.SH +13. NOTES RELATED TO FILES\-TYPES AND MARKUP SYNTAX +.BR + +.BR +0.38 is substantially current, depreciated 0.16 supported, though file names +were changed at 0.37 + +.BR +.B 0.52 +(2007w14/6) declared document type identifier at start of text/document: + +.BR + .B SiSU +0.52 + +.BR +or, backward compatible using the comment marker: + +.BR + % +.B SiSU +0.38 + +.BR +variations include \' +.B SiSU +(text|master|insert) \ [version]\' and \'sisu\-[version]\' + +.BR +.B 0.51 +(2007w13/6) skins changed (simplified), markup unchanged + +.BR +.B 0.42 +(2006w27/4) * (asterisk) type endnotes, used e.g. in relation to author + +.BR +.B 0.38 +(2006w15/7) introduced new/alternative notation for headers, e.g. @title: +(instead of 0~title), and accompanying document structure markup, +:A,:B,:C,1,2,3 (maps to previous 1,2,3,4,5,6) + +.BR +.B 0.37 +(2006w09/7) introduced new file naming convention, .sst (text), .ssm +(master), .ssi (insert), markup syntax unchanged + +.BR +.B 0.35 +(2005w52/3) sisupod, zipped content file introduced + +.BR +.B 0.23 +(2005w36/2) utf\-8 for markup file + +.BR +.B 0.22 +(2005w35/3) image dimensions may be omitted if rmagick is available to be +relied upon + +.BR +.B 0.20.4 +(2005w33/4) header 0~links + +.BR +.B 0.16 +(2005w25/2) substantial changes introduced to make markup cleaner, header +0~title type, and headings \ [1\-6]~ introduced, also percentage sign (%) at +start of a text line as comment marker + +.SH +14. SISU FILETYPES +.BR + +.BR +.B SiSU +has plaintext and binary filetypes, and can process either type of document. + +.SH +14.1 .SST .SSM .SSI MARKED UP PLAIN TEXT + +.BR +.B SiSU +documents are prepared as plain\-text (utf\-8) files with +.B SiSU +markup. They may make reference to and contain images (for example), which +are stored in the directory beneath them _sisu/image. +.B SiSU +plaintext markup files are of three types that may be distinguished by the +file extension used: regular text .sst; master documents, composite documents +that incorporate other text, which can be any regular text or text insert; and +inserts the contents of which are like regular text except these are marked +.ssi and are not processed. + +.BR +.B SiSU +processing can be done directly against a sisu documents; which may be +located locally or on a remote server for which a url is provided. + +.BR +.B SiSU +source markup can be shared with the command: + +.BR + sisu \-s \ [filename] + +.SH +14.1.1 SISU TEXT \- REGULAR FILES (.SST) + +.BR +The most common form of document in +.B SiSU +, see the section on +.B SiSU +markup. + +.BR + + +.BR + + +.SH +14.1.2 SISU MASTER FILES (.SSM) + +.BR +Composite documents which incorporate other +.B SiSU +documents which may be either regular +.B SiSU +text .sst which may be generated independently, or inserts prepared solely +for the purpose of being incorporated into one or more master documents. + +.BR +The mechanism by which master files incorporate other documents is described as +one of the headings under under +.B SiSU +markup in the +.B SiSU +manual. + +.BR +Note: Master documents may be prepared in a similar way to regular documents, +and processing will occur normally if a .sst file is renamed .ssm without +requiring any other documents; the .ssm marker flags that the document may +contain other documents. + +.BR +Note: a secondary file of the composite document is built prior to processing +with the same prefix and the suffix ._sst \ [^22] + +.BR + + +.BR + + +.SH +14.1.3 SISU INSERT FILES (.SSI) + +.BR +Inserts are documents prepared solely for the purpose of being incorporated +into one or more master documents. They resemble regular +.B SiSU +text files except they are ignored by the +.B SiSU +processor. Making a file a .ssi file is a quick and convenient way of +flagging that it is not intended that the file should be processed on its own. + +.SH +14.2 SISUPOD, ZIPPED BINARY CONTAINER (SISUPOD.ZIP, .SSP) + +.BR +A sisupod is a zipped +.B SiSU +text file or set of +.B SiSU +text files and any associated images that they contain (this will be extended +to include sound and multimedia\-files) + +.BR +.B SiSU +plaintext files rely on a recognised directory structure to find contents +such as images associated with documents, but all images for example for all +documents contained in a directory are located in the sub\-directory +_sisu/image. Without the ability to create a sisupod it can be inconvenient to +manually identify all other files associated with a document. A sisupod +automatically bundles all associated files with the document that is turned +into a pod. + +.BR +The structure of the sisupod is such that it may for example contain a single +document and its associated images; a master document and its associated +documents and anything else; or the zipped contents of a whole directory of +prepared +.B SiSU +documents. + +.BR +The command to create a sisupod is: + +.BR + sisu \-S \ [filename] + +.BR +Alternatively, make a pod of the contents of a whole directory: + +.BR + sisu \-S + +.BR +.B SiSU +processing can be done directly against a sisupod; which may be located +locally or on a remote server for which a url is provided. + +.BR + + +.BR + + +.SH +15. EXPERIMENTAL ALTERNATIVE INPUT REPRESENTATIONS +.BR + +.SH +15.1 ALTERNATIVE XML + +.BR +.B SiSU +offers alternative XML input representations of documents as a proof of +concept, experimental feature. They are however not strictly maintained, and +incomplete and should be handled with care. + +.BR +.B convert from sst to simple xml representations (sax, dom and node): + +.BR + sisu \-\-to\-sax \ [filename/wildcard] or sisu \-\-to\-sxs \ + [filename/wildcard] + +.BR + sisu \-\-to\-dom \ [filename/wildcard] or sisu \-\-to\-sxd \ + [filename/wildcard] + +.BR + sisu \-\-to\-node \ [filename/wildcard] or sisu \-\-to\-sxn \ + [filename/wildcard] + +.BR +.B convert to sst from any sisu xml representation (sax, dom and node): + +.BR + sisu \-\-from\-xml2sst \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]] + +.BR +or the same: + +.BR + sisu \-\-from\-sxml \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]] + +.SH +15.1.1 XML SAX REPRESENTATION + +.BR +To convert from sst to simple xml (sax) representation: + +.BR + sisu \-\-to\-sax \ [filename/wildcard] or sisu \-\-to\-sxs \ + [filename/wildcard] + +.BR +To convert from any sisu xml representation back to sst + +.BR + sisu \-\-from\-xml2sst \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]] + +.BR +or the same: + +.BR + sisu \-\-from\-sxml \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]] + +.SH +15.1.2 XML DOM REPRESENTATION + +.BR +To convert from sst to simple xml (dom) representation: + +.BR + sisu \-\-to\-dom \ [filename/wildcard] or sisu \-\-to\-sxd \ + [filename/wildcard] + +.BR +To convert from any sisu xml representation back to sst + +.BR + sisu \-\-from\-xml2sst \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]] + +.BR +or the same: + +.BR + sisu \-\-from\-sxml \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]] + +.SH +15.1.3 XML NODE REPRESENTATION + +.BR +To convert from sst to simple xml (node) representation: + +.BR + sisu \-\-to\-node \ [filename/wildcard] or sisu \-\-to\-sxn \ + [filename/wildcard] + +.BR +To convert from any sisu xml representation back to sst + +.BR + sisu \-\-from\-xml2sst \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]] + +.BR +or the same: + +.BR + sisu \-\-from\-sxml \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]] + +.SH +16. CONFIGURATION +.BR + +.SH +16.1 DETERMINING THE CURRENT CONFIGURATION + +.BR +Information on the current configuration of +.B SiSU +should be available with the help command: + +.BR + sisu \-v + +.BR +which is an alias for: + +.BR + sisu \-\-help env + +.BR +Either of these should be executed from within a directory that contains sisu +markup source documents. + +.SH +16.2 CONFIGURATION FILES (CONFIG.YML) + +.BR +.B SiSU +configration parameters are adjusted in the configuration file, which can be +used to override the defaults set. This includes such things as which directory +interim processing should be done in and where the generated output should be +placed. + +.BR +The +.B SiSU +configuration file is a yaml file, which means indentation is significant. + +.BR +.B SiSU +resource configuration is determined by looking at the following files if +they exist: + +.BR + ./_sisu/sisurc.yml + +.BR + ~/.sisu/sisurc.yml + +.BR + /etc/sisu/sisurc.yml + +.BR +The search is in the order listed, and the first one found is used. + +.BR +In the absence of instructions in any of these it falls back to the internal +program defaults. + +.BR +Configuration determines the output and processing directories and the database +access details. + +.BR +If +.B SiSU +is installed a sample sisurc.yml may be found in /etc/sisu/sisurc.yml + +.SH +17. SKINS +.BR + +.BR +Skins modify the default appearance of document output on a document, +directory, or site wide basis. Skins are looked for in the following locations: + +.BR + ./_sisu/skin + +.BR + ~/.sisu/skin + +.BR + /etc/sisu/skin + +.BR +.B Within the skin directory +are the following the default sub\-directories for document skins: + +.BR + ./skin/doc + +.BR + ./skin/dir + +.BR + ./skin/site + +.BR +A skin is placed in the appropriate directory and the file named skin_[name].rb + +.BR +The skin itself is a ruby file which modifies the default appearances set in +the program. + +.SH +17.1 DOCUMENT SKIN + +.BR +Documents take on a document skin, if the header of the document specifies a +skin to be used. + + +.nf + @skin: skin_united_nations +.fi + +.SH +17.2 DIRECTORY SKIN + +.BR +A directory may be mapped on to a particular skin, so all documents within that +directory take on a particular appearance. If a skin exists in the skin/dir +with the same name as the document directory, it will automatically be used for +each of the documents in that directory, (except where a document specifies the +use of another skin, in the skin/doc directory). + +.BR +A personal habit is to place all skins within the doc directory, and symbolic +links as needed from the site, or dir directories as required. + +.SH +17.3 SITE SKIN + +.BR +A site skin, modifies the program default skin. + +.SH +17.4 SAMPLE SKINS + +.BR +With +.B SiSU +installed sample skins may be found in: + +.BR + /etc/sisu/skin/doc and + /usr/share/doc/sisu/sisu_markup_samples/dfsg/_sisu/skin/doc + +.BR +(or equivalent directory) and if sisu\-markup\-samples is installed also under: + +.BR + /usr/share/doc/sisu/sisu_markup_samples/non\-free/_sisu/skin/doc + +.BR +Samples of list.yml and promo.yml (which are used to create the right column +list) may be found in: + +.BR + /usr/share/doc/sisu/sisu_markup_samples/dfsg/_sisu/skin/yml (or equivalent + directory) + +.SH +18. CSS \- CASCADING STYLE SHEETS (FOR HTML, XHTML AND XML) +.BR + +.BR +CSS files to modify the appearance of +.B SiSU +html, XHTML or XML may be placed in the configuration directory: ./_sisu/css; +~/.sisu/css or; /etc/sisu/css and these will be copied to the output +directories with the command sisu \-CC. + +.BR +The basic CSS file for html output is html.css, placing a file of that name in +directory _sisu/css or equivalent will result in the default file of that name +being overwritten. + +.BR +HTML: html.css + +.BR +XML DOM: dom.css + +.BR +XML SAX: sax.css + +.BR +XHTML: xhtml.css + +.BR +The default homepage may use homepage.css or html.css + +.BR +Under consideration is to permit the placement of a CSS file with a different +name in directory _sisu/css directory or equivalent, and change the default CSS +file that is looked for in a skin.[^23] + +.SH +19. ORGANISING CONTENT +.BR + +.SH +19.1 DIRECTORY STRUCTURE AND MAPPING + +.BR +The output directory root can be set in the sisurc.yml file. Under the root, +subdirectories are made for each directory in which a document set resides. If +you have a directory named poems or conventions, that directory will be created +under the output directory root and the output for all documents contained in +the directory of a particular name will be generated to subdirectories beneath +that directory (poem or conventions). A document will be placed in a +subdirectory of the same name as the document with the filetype identifier +stripped (.sst .ssm) + +.BR +The last part of a directory path, representing the sub\-directory in which a +document set resides, is the directory name that will be used for the output +directory. This has implications for the organisation of document collections +as it could make sense to place documents of a particular subject, or type +within a directory identifying them. This grouping as suggested could be by +subject (sales_law, english_literature); or just as conveniently by some other +classification (X University). The mapping means it is also possible to place +in the same output directory documents that are for organisational purposes +kept separately, for example documents on a given subject of two different +institutions may be kept in two different directories of the same name, under a +directory named after each institution, and these would be output to the same +output directory. Skins could be associated with each institution on a +directory basis and resulting documents will take on the appropriate different +appearance. + +.SH +19.2 ORGANISING CONTENT + +.SH +20. HOMEPAGES +.BR + +.BR +.B SiSU +is about the ability to auto\-generate documents. Home pages are regarded as +custom built items, and are not created by +.B SiSU +. More accurately, +.B SiSU +has a default home page, which will not be appropriate for use with other +sites, and the means to provide your own home page instead in one of two ways +as part of a site\'s configuration, these being: + +.BR +1. through placing your home page and other custom built documents in the +subdirectory _sisu/home/ (this probably being the easier and more convenient +option) + +.BR +2. through providing what you want as the home page in a skin, + +.BR +Document sets are contained in directories, usually organised by site or +subject. Each directory can/should have its own homepage. See the section on +directory structure and organisation of content. + +.SH +20.1 HOME PAGE AND OTHER CUSTOM BUILT PAGES IN A SUB\-DIRECTORY + +.BR +Custom built pages, including the home page index.html may be placed within the +configuration directory _sisu/home/ in any of the locations that is searched +for the configuration directory, namely ./_sisu; ~/_sisu; /etc/sisu From there +they are copied to the root of the output directory with the command: + +.BR + sisu \-CC + +.SH +20.2 HOME PAGE WITHIN A SKIN + +.BR +Skins are described in a separate section, but basically are a file written in +the programming language +.B Ruby +that may be provided to change the defaults that are provided with sisu with +respect to individual documents, a directories contents or for a site. + +.BR +If you wish to provide a homepage within a skin the skin should be in the +directory _sisu/skin/dir and have the name of the directory for which it is to +become the home page. Documents in the directory commercial_law would have the +homepage modified in skin_commercial law.rb; or the directory poems in +skin_poems.rb + + +.nf + class Home + def homepage + # place the html content of your homepage here, this will become index.html + < + + +

this is my new homepage.

+ + + HOME + end + end +.fi + +.SH +21. MARKUP AND OUTPUT EXAMPLES +.BR + +.SH +21.1 MARKUP EXAMPLES + +.BR +Current markup examples and document output samples are provided at + + +.BR +Some markup with syntax highlighting may be found under + but is not as up to date. + +.BR +For some documents hardly any markup at all is required at all, other than a +header, and an indication that the levels to be taken into account by the +program in generating its output are. + +.SH +22. SISU SEARCH \- INTRODUCTION +.BR + +.BR +.B SiSU +output can easily and conveniently be indexed by a number of standalone +indexing tools, such as Lucene, Hyperestraier. + +.BR +Because the document structure of sites created is clearly defined, and the +text object citation system is available hypothetically at least, for all forms +of output, it is possible to search the sql database, and either read results +from that database, or just as simply map the results to the html output, which +has richer text markup. + +.BR +In addition to this +.B SiSU +has the ability to populate a relational sql type database with documents at +an object level, with objects numbers that are shared across different output +types, which make them searchable with that degree of granularity. Basically, +your match criteria is met by these documents and at these locations within +each document, which can be viewed within the database directly or in various +output formats. + +.SH +23. SQL +.BR + +.SH +23.1 POPULATING SQL TYPE DATABASES + +.BR +.B SiSU +feeds sisu markupd documents into sql type databases PostgreSQL[^24] and/or +SQLite[^25] database together with information related to document structure. + +.BR +This is one of the more interesting output forms, as all the structural data of +the documents are retained (though can be ignored by the user of the database +should they so choose). All site texts/documents are (currently) streamed to +four tables: + +.BR + * one containing semantic (and other) headers, including, title, author, + subject, (the Dublin Core...); + +.BR + * another the substantive texts by individual \"paragraph\" (or object) \- + along with structural information, each paragraph being identifiable by its + paragraph number (if it has one which almost all of them do), and the + substantive text of each paragraph quite naturally being searchable (both in + formatted and clean text versions for searching); and + +.BR + * a third containing endnotes cross\-referenced back to the paragraph from + which they are referenced (both in formatted and clean text versions for + searching). + +.BR + * a fourth table with a one to one relation with the headers table contains + full text versions of output, eg. pdf, html, xml, and ascii. + +.BR +There is of course the possibility to add further structures. + +.BR +At this level +.B SiSU +loads a relational database with documents chunked into objects, their +smallest logical structurally constituent parts, as text objects, with their +object citation number and all other structural information needed to construct +the document. Text is stored (at this text object level) with and without +elementary markup tagging, the stripped version being so as to facilitate ease +of searching. + +.BR +Being able to search a relational database at an object level with the +.B SiSU +citation system is an effective way of locating content generated by +.B SiSU +. As individual text objects of a document stored (and indexed) together with +object numbers, and all versions of the document have the same numbering, +complex searches can be tailored to return just the locations of the search +results relevant for all available output formats, with live links to the +precise locations in the database or in html/xml documents; or, the structural +information provided makes it possible to search the full contents of the +database and have headings in which search content appears, or to search only +headings etc. (as the Dublin Core is incorporated it is easy to make use of +that as well). + +.SH +24. POSTGRESQL +.BR + +.SH +24.1 NAME + +.BR +.B SiSU +\- Structured information, Serialized Units \- a document publishing system, +postgresql dependency package + +.SH +24.2 DESCRIPTION + +.BR +Information related to using postgresql with sisu (and related to the +sisu_postgresql dependency package, which is a dummy package to install +dependencies needed for +.B SiSU +to populate a postgresql database, this being part of +.B SiSU +\- man sisu). + +.SH +24.3 SYNOPSIS + +.BR + sisu \-D \ [instruction] \ [filename/wildcard \ if \ required] + +.BR + sisu \-D \-\-pg \-\-[instruction] \ [filename/wildcard \ if \ required] + +.SH +24.4 COMMANDS + +.BR +Mappings to two databases are provided by default, postgresql and sqlite, the +same commands are used within sisu to construct and populate databases however +\-d (lowercase) denotes sqlite and \-D (uppercase) denotes postgresql, +alternatively \-\-sqlite or \-\-pgsql may be used + +.BR +.B \-D or \-\-pgsql +may be used interchangeably. + +.SH +24.4.1 CREATE AND DESTROY DATABASE + +.TP +.B \ \-\-pgsql \ \-\-createall +\ initial \ step, \ creates \ required \ relations \ (tables, \ indexes) \ in +\ existing \ (postgresql) \ database \ (a \ database \ should \ be \ created \ +manually \ and \ given \ the \ same \ name \ as \ working \ directory, \ as \ +requested) \ (rb.dbi) \ + +.TP +.B \ sisu \ \-D \ \-\-createdb +\ creates \ database \ where \ no \ database \ existed \ before \ + +.TP +.B \ sisu \ \-D \ \-\-create +\ creates \ database \ tables \ where \ no \ database \ tables \ existed \ +before \ + +.TP +.B \ sisu \ \-D \ \-\-Dropall +\ destroys \ database \ (including \ all \ its \ content)! \ kills \ data \ +and \ drops \ tables, \ indexes \ and \ database \ associated \ with \ a \ +given \ directory \ (and \ directories \ of \ the \ same \ name). \ + +.TP +.B \ sisu \ \-D \ \-\-recreate +\ destroys \ existing \ database \ and \ builds \ a \ new \ empty \ database +\ structure \ + +.SH +24.4.2 IMPORT AND REMOVE DOCUMENTS + +.TP +.B \ sisu \ \-D \ \-\-import \ \-v \ \ [filename/wildcard] +populates database with the contents of the file. Imports documents(s) +specified to a postgresql database (at an object level). + +.TP +.B \ sisu \ \-D \ \-\-update \ \-v \ \ [filename/wildcard] +updates file contents in database + +.TP +.B \ sisu \ \-D \ \-\-remove \ \-v \ \ [filename/wildcard] +removes specified document from postgresql database. + +.SH +25. SQLITE +.BR + +.SH +25.1 NAME + +.BR +.B SiSU +\- Structured information, Serialized Units \- a document publishing system. + +.SH +25.2 DESCRIPTION + +.BR +Information related to using sqlite with sisu (and related to the sisu_sqlite +dependency package, which is a dummy package to install dependencies needed for +.B SiSU +to populate an sqlite database, this being part of +.B SiSU +\- man sisu). + +.SH +25.3 SYNOPSIS + +.BR + sisu \-d \ [instruction] \ [filename/wildcard \ if \ required] + +.BR + sisu \-d \-\-(sqlite|pg) \-\-[instruction] \ [filename/wildcard \ if \ + required] + +.SH +25.4 COMMANDS + +.BR +Mappings to two databases are provided by default, postgresql and sqlite, the +same commands are used within sisu to construct and populate databases however +\-d (lowercase) denotes sqlite and \-D (uppercase) denotes postgresql, +alternatively \-\-sqlite or \-\-pgsql may be used + +.BR +.B \-d or \-\-sqlite +may be used interchangeably. + +.SH +25.4.1 CREATE AND DESTROY DATABASE + +.TP +.B \ \-\-sqlite \ \-\-createall +\ initial \ step, \ creates \ required \ relations \ (tables, \ indexes) \ in +\ existing \ (sqlite) \ database \ (a \ database \ should \ be \ created \ +manually \ and \ given \ the \ same \ name \ as \ working \ directory, \ as \ +requested) \ (rb.dbi) \ + +.TP +.B \ sisu \ \-d \ \-\-createdb +\ creates \ database \ where \ no \ database \ existed \ before \ + +.TP +.B \ sisu \ \-d \ \-\-create +\ creates \ database \ tables \ where \ no \ database \ tables \ existed \ +before \ + +.TP +.B \ sisu \ \-d \ \-\-dropall +\ destroys \ database \ (including \ all \ its \ content)! \ kills \ data \ +and \ drops \ tables, \ indexes \ and \ database \ associated \ with \ a \ +given \ directory \ (and \ directories \ of \ the \ same \ name). \ + +.TP +.B \ sisu \ \-d \ \-\-recreate +\ destroys \ existing \ database \ and \ builds \ a \ new \ empty \ database +\ structure \ + +.SH +25.4.2 IMPORT AND REMOVE DOCUMENTS + +.TP +.B \ sisu \ \-d \ \-\-import \ \-v \ \ [filename/wildcard] +populates database with the contents of the file. Imports documents(s) +specified to an sqlite database (at an object level). + +.TP +.B \ sisu \ \-d \ \-\-update \ \-v \ \ [filename/wildcard] +updates file contents in database + +.TP +.B \ sisu \ \-d \ \-\-remove \ \-v \ \ [filename/wildcard] +removes specified document from sqlite database. + +.SH +26. INTRODUCTION +.BR + +.SH +26.1 SEARCH \- DATABASE FRONTEND SAMPLE, UTILISING DATABASE AND SISU FEATURES, +INCLUDING OBJECT CITATION NUMBERING (BACKEND CURRENTLY POSTGRESQL) + +.BR +Sample search frontend \ [^26] A small database and +sample query front\-end (search from) that makes use of the citation system, +.I object citation numbering +to demonstrates functionality.[^27] + +.BR +.B SiSU +can provide information on which documents are matched and at what locations +within each document the matches are found. These results are relevant across +all outputs using object citation numbering, which includes html, XML, LaTeX, +PDF and indeed the SQL database. You can then refer to one of the other outputs +or in the SQL database expand the text within the matched objects (paragraphs) +in the documents matched. + +.BR +Note you may set results either for documents matched and object number +locations within each matched document meeting the search criteria; or display +the names of the documents matched along with the objects (paragraphs) that +meet the search criteria.[^28] + +.TP +.B \ sisu \ \-F \ \-\-webserv\-webrick +\ builds \ a \ cgi \ web \ search \ frontend \ for \ the \ database \ created +\ + +.BR +The following is feedback on the setup on a machine provided by the help +command: + +.BR + sisu \-\-help sql + + +.nf + Postgresql + user: ralph + current db set: SiSU_sisu + port: 5432 + dbi connect: DBI:Pg:database=SiSU_sisu;port=5432 + sqlite + current db set: /home/ralph/sisu_www/sisu/sisu_sqlite.db + dbi connect DBI:SQLite:/home/ralph/sisu_www/sisu/sisu_sqlite.db +.fi + +.BR +Note on databases built + +.BR +By default, \ [unless \ otherwise \ specified] databases are built on a +directory basis, from collections of documents within that directory. The name +of the directory you choose to work from is used as the database name, i.e. if +you are working in a directory called /home/ralph/ebook the database SiSU_ebook +is used. \ [otherwise \ a \ manual \ mapping \ for \ the \ collection \ is \ +necessary] + +.SH +26.2 SEARCH FORM + +.TP +.B \ sisu \ \-F +\ generates \ a \ sample \ search \ form, \ which \ must \ be \ copied \ to \ +the \ web\-server \ cgi \ directory \ + +.TP +.B \ sisu \ \-F \ \-\-webserv\-webrick +\ generates \ a \ sample \ search \ form \ for \ use \ with \ the \ webrick \ +server, \ which \ must \ be \ copied \ to \ the \ web\-server \ cgi \ directory +\ + +.TP +.B \ sisu \ \-Fv +\ as \ above, \ and \ provides \ some \ information \ on \ setting \ up \ +hyperestraier \ + +.TP +.B \ sisu \ \-W +\ starts \ the \ webrick \ server \ which \ should \ be \ available \ +wherever \ sisu \ is \ properly \ installed \ + +.BR +The generated search form must be copied manually to the webserver directory as +instructed + +.SH +27. HYPERESTRAIER +.BR + +.BR +See the documentation for hyperestraier: + +.BR + + +.BR + /usr/share/doc/hyperestraier/index.html + +.BR + man estcmd + +.BR +on sisu_hyperestraier: + +.BR + man sisu_hyperestraier + +.BR + /usr/share/doc/sisu/sisu_markup/sisu_hyperestraier/index.html + +.BR +NOTE: the examples that follow assume that sisu output is placed in the +directory /home/ralph/sisu_www + +.BR +(A) to generate the index within the webserver directory to be indexed: + +.BR + estcmd gather \-sd \ [index \ name] \ [directory \ path \ to \ index] + +.BR +the following are examples that will need to be tailored according to your +needs: + +.BR + cd /home/ralph/sisu_www + +.BR + estcmd gather \-sd casket /home/ralph/sisu_www + +.BR +you may use the \'find\' command together with \'egrep\' to limit indexing to +particular document collection directories within the web server directory: + +.BR + find /home/ralph/sisu_www \-type f | egrep + \'/home/ralph/sisu_www/sisu/.+?.html$\' |estcmd gather \-sd casket \- + +.BR +Check which directories in the webserver/output directory (~/sisu_www or +elsewhere depending on configuration) you wish to include in the search index. + +.BR +As sisu duplicates output in multiple file formats, it it is probably +preferable to limit the estraier index to html output, and as it may also be +desirable to exclude files \'plain.txt\', \'toc.html\' and +\'concordance.html\', as these duplicate information held in other html output +e.g. + +.BR + find /home/ralph/sisu_www \-type f | egrep + \'/sisu_www/(sisu|bookmarks)/.+?.html$\' | egrep \-v + \'(doc|concordance).html$\' |estcmd gather \-sd casket \- + +.BR +from your current document preparation/markup directory, you would construct a +rune along the following lines: + +.BR + find /home/ralph/sisu_www \-type f | egrep \'/home/ralph/sisu_www/([specify \ + first \ directory \ for \ inclusion]|[specify \ second \ directory \ for \ + inclusion]|[another \ directory \ for \ inclusion? \ ...])/.+?.html$\' | + egrep \-v \'(doc|concordance).html$\' |estcmd gather \-sd + /home/ralph/sisu_www/casket \- + +.BR +(B) to set up the search form + +.BR +(i) copy estseek.cgi to your cgi directory and set file permissions to 755: + +.BR + sudo cp \-vi /usr/lib/estraier/estseek.cgi /usr/lib/cgi\-bin + +.BR + sudo chmod \-v 755 /usr/lib/cgi\-bin/estseek.cgi + +.BR + sudo cp \-v /usr/share/hyperestraier/estseek.* /usr/lib/cgi\-bin + +.BR + \ [see \ estraier \ documentation \ for \ paths] + +.BR +(ii) edit estseek.conf, with attention to the lines starting \'indexname:\' and +\'replace:\': + +.BR + indexname: /home/ralph/sisu_www/casket + +.BR + replace: ^file:///home/ralph/sisu_www{{!}}http://localhost + +.BR + replace: /index.html?${{!}}/ + +.BR +(C) to test using webrick, start webrick: + +.BR + sisu \-W + +.BR +and try open the url: + +.SH +28. SISU_WEBRICK +.BR + +.SH +28.1 NAME + +.BR +.B SiSU +\- Structured information, Serialized Units \- a document publishing system + +.SH +28.2 SYNOPSIS + +.BR +sisu_webrick \ [port] + +.BR +or + +.BR +sisu \-W \ [port] + +.SH +28.3 DESCRIPTION + +.BR +sisu_webrick is part of +.B SiSU +(man sisu) sisu_webrick starts +.B Ruby +\'s Webrick web\-server and points it to the directories to which +.B SiSU +output is written, providing a list of these directories (assuming +.B SiSU +is in use and they exist). + +.BR +The default port for sisu_webrick is set to 8081, this may be modified in the +yaml file: ~/.sisu/sisurc.yml a sample of which is provided as +/etc/sisu/sisurc.yml (or in the equivalent directory on your system). + +.SH +28.4 SUMMARY OF MAN PAGE + +.BR +sisu_webrick, may be started on it\'s own with the command: sisu_webrick \ +[port] or using the sisu command with the \-W flag: sisu \-W \ [port] + +.BR +where no port is given and settings are unchanged the default port is 8081 + +.SH +28.5 DOCUMENT PROCESSING COMMAND FLAGS + +.BR +sisu \-W \ [port] starts +.B Ruby +Webrick web\-server, serving +.B SiSU +output directories, on the port provided, or if no port is provided and the +defaults have not been changed in ~/.sisu/sisurc.yaml then on port 8081 + +.SH +28.6 FURTHER INFORMATION + +.BR +For more information on +.B SiSU +see: + +.BR +or man sisu + +.SH +28.7 AUTHOR + +.BR +Ralph Amissah or + +.SH +28.8 SEE ALSO + +.BR + sisu(1) + +.BR + sisu_vim(7) + +.BR + sisu(8) + +.SH +29. REMOTE SOURCE DOCUMENTS +.BR + +.BR +.B SiSU +processing instructions can be run against remote source documents by +providing the url of the documents against which the processing instructions +are to be carried out. The remote +.B SiSU +documents can either be sisu marked up files in plaintext .sst or .ssm or; +zipped sisu files, sisupod.zip or filename.ssp + +.BR +.B .sst / .ssm \- sisu text files + +.BR +.B SiSU +can be run against source text files on a remote machine, provide the +processing instruction and the url. The source file and any associated parts +(such as images) will be downloaded and generated locally. + + +.nf + sisu \-3 http://[provide \ url \ to \ valid \ .sst \ or \ .ssm \ file] +.fi + +.BR +Any of the source documents in the sisu examples page can be used in this way, +see and use the url for the desired +document. + +.BR +NOTE: to set up a remote machine to serve +.B SiSU +documents in this way, images should be in the directory relative to the +document source ../_sisu/image + +.BR +.B sisupod \- zipped sisu files + +.BR +A sisupod is the zipped content of a sisu marked up text or texts and any other +associated parts to the document such as images. + +.BR +.B SiSU +can be run against a sisupod on a (local or) remote machine, provide the +processing instruction and the url, the sisupod will be downloaded and the +documents it contains generated locally. + + +.nf + sisu \-3 http://[provide \ url \ to \ valid \ sisupod.zip \ or \ .ssp \ file] +.fi + +.BR +Any of the source documents in the sisu examples page can be used in this way, +see and use the url for the desired +document. + +.SH +REMOTE DOCUMENT OUTPUT +.BR + +.SH +30. REMOTE OUTPUT +.BR + +.BR +Once properly configured +.B SiSU +output can be automatically posted once generated to a designated remote +machine using either rsync, or scp. + +.BR +In order to do this some ssh authentication agent and keychain or similar tool +will need to be configured. Once that is done the placement on a remote host +can be done seamlessly with the \-r (for scp) or \-R (for rsync) flag, which +may be used in conjunction with other processing flags, e.g. + + +.nf + sisu \-3R sisu_remote.sst +.fi + +.SH +30.1 COMMANDS + +.TP +.B \ \-R \ \ [filename/wildcard] +copies sisu output files to remote host using rsync. This requires that +sisurc.yml has been provided with information on hostname and username, and +that you have your \"keys\" and ssh agent in place. Note the behavior of rsync +different if \-R is used with other flags from if used alone. Alone the rsync +\-\-delete parameter is sent, useful for cleaning the remote directory (when +\-R is used together with other flags, it is not). Also see \-r + +.TP +.B \ \-r \ \ [filename/wildcard] +copies sisu output files to remote host using scp. This requires that +sisurc.yml has been provided with information on hostname and username, and +that you have your \"keys\" and ssh agent in place. Also see \-R + +.SH +30.2 CONFIGURATION + +.BR +[expand \ on \ the \ setting \ up \ of \ an \ ssh\-agent \ / \ keychain] + +.SH +31. REMOTE SERVERS +.BR + +.BR +As +.B SiSU +is generally operated using the command line, and works within a Unix type +environment, +.B SiSU +the program and all documents can just as easily be on a remote server, to +which you are logged on using a terminal, and commands and operations would be +pretty much the same as they would be on your local machine. + +.SH +32. QUICKSTART \- GETTING STARTED HOWTO +.BR + +.SH +32.1 INSTALLATION + +.BR +Installation is currently most straightforward and tested on the +.B Debian +platform, as there are packages for the installation of sisu and all +requirements for what it does. + +.SH +32.1.1 DEBIAN INSTALLATION + +.BR +.B SiSU +is available directly from the +.B Debian +Sid and testing archives (and possibly Ubuntu), assuming your +/etc/apt/sources.list is set accordingly: + + +.nf + aptitude update + aptitude install sisu\-complete +.fi + +.BR +The following /etc/apt/sources.list setting permits the download of additional +markup samples: + + +.nf + #/etc/apt/sources.list + deb http://ftp.fi.debian.org/debian/ unstable main non\-free contrib + deb\-src http://ftp.fi.debian.org/debian/ unstable main non\-free contrib + d +.fi + +.BR +The aptitude commands become: + + +.nf + aptitude update + aptitude install sisu\-complete sisu\-markup\-samples +.fi + +.BR +If there are newer versions of +.B SiSU +upstream of the +.B Debian +archives, they will be available by adding the following to your +/etc/apt/sources.list + + +.nf + #/etc/apt/sources.list + deb http://www.jus.uio.no/sisu/archive unstable main non\-free + deb\-src http://www.jus.uio.no/sisu/archive unstable main non\-free +.fi + +.BR +repeat the aptitude commands + + +.nf + aptitude update + aptitude install sisu\-complete sisu\-markup\-samples +.fi + +.BR +Note however that it is not necessary to install sisu\-complete if not all +components of sisu are to be used. Installing just the package sisu will +provide basic functionality. + +.SH +32.1.2 RPM INSTALLATION + +.BR +RPMs are provided though untested, they are prepared by running alien against +the source package, and against the debs. + +.BR +They may be downloaded from: + +.BR + + +.BR +as root type: + +.BR + rpm \-i \ [rpm \ package \ name] + +.SH +32.1.3 INSTALLATION FROM SOURCE + +.BR +To install +.B SiSU +from source check information at: + +.BR + + +.BR +* download the source package + +.BR +* Unpack the source + +.BR +Two alternative modes of installation from source are provided, setup.rb (by +Minero Aoki) and a rant(by Stefan Lang) built install file, in either case: the +first steps are the same, download and unpack the source file: + +.BR +For basic use +.B SiSU +is only dependent on the programming language in which it is written +.B Ruby +, and +.B SiSU +will be able to generate html, various XMLs, including ODF (and will also +produce LaTeX). Dependencies required for further actions, though it relies on +the installation of additional dependencies which the source tarball does not +take care of, for things like using a database (postgresql or sqlite)[^29] or +converting LaTeX to pdf. + +.BR +.B setup.rb + +.BR +This is a standard ruby installer, using setup.rb is a three step process. In +the root directory of the unpacked +.B SiSU +as root type: + + +.nf + ruby setup.rb config + ruby setup.rb setup + #[and \ as \ root:] + ruby setup.rb install +.fi + +.BR +further information on setup.rb is available from: + +.BR + + +.BR + + +.BR +.B \"install\" + +.BR +The \"install\" file provided is an installer prepared using \"rant\". In the +root directory of the unpacked +.B SiSU +as root type: + +.BR + ruby install base + +.BR +or for a more complete installation: + +.BR + ruby install + +.BR +or + +.BR + ruby install base + +.BR +This makes use of Rant (by Stefan Lang) and the provided Rantfile. It has been +configured to do post installation setup setup configuration and generation of +first test file. Note however, that additional external package dependencies, +such as tetex\-extra are not taken care of for you. + +.BR +Further information on \"rant\" is available from: + +.BR + + +.BR + + +.BR +For a list of alternative actions you may type: + +.BR + ruby install help + +.BR + ruby install \-T + +.SH +32.2 TESTING SISU, GENERATING OUTPUT + +.BR +To check which version of sisu is installed: + +.BR +sisu \-v + +.BR +Depending on your mode of installation one or a number of markup sample files +may be found either in the directory: + +.BR +... + +.BR +or + +.BR +... + +.BR +change directory to the appropriate one: + +.BR +cd /usr/share/doc/sisu/sisu_markup_samples/dfsg + +.SH +32.2.1 BASIC TEXT, PLAINTEXT, HTML, XML, ODF + +.BR +Having moved to the directory that contains the markup samples (see +instructions above if necessary), choose a file and run sisu against it + +.BR +sisu \-NhwoabxXyv free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +this will generate html including a concordance file, opendocument text format, +plaintext, XHTML and various forms of XML, and OpenDocument text + +.SH +32.2.2 LATEX / PDF + +.BR +Assuming a LaTeX engine such as tetex or texlive is installed with the required +modules (done automatically on selection of sisu\-pdf in +.B Debian +) + +.BR +Having moved to the directory that contains the markup samples (see +instructions above if necessary), choose a file and run sisu against it + +.BR +sisu \-pv free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +sisu \-3 free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +should generate most available output formats: html including a concordance +file, opendocument text format, plaintext, XHTML and various forms of XML, and +OpenDocument text and pdf + +.SH +32.2.3 RELATIONAL DATABASE \- POSTGRESQL, SQLITE + +.BR +Relational databases need some setting up \- you must have permission to create +the database and write to it when you run sisu. + +.BR +Assuming you have the database installed and the requisite permissions + +.BR +sisu \-\-sqlite \-\-recreate + +.BR +sisu \-\-sqlite \-v \-\-import +free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +sisu \-\-pgsql \-\-recreate + +.BR +sisu \-\-pgsql \-v \-\-import +free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.SH +32.3 GETTING HELP + +.SH +32.3.1 THE MAN PAGES + +.BR +Type: + +.BR + man sisu + +.BR +The man pages are also available online, though not always kept as up to date +as within the package itself: + +.BR +* sisu.1 \ [^30] + +.BR +* sisu.8 \ [^31] + +.BR +* man directory \ [^32] + +.SH +32.3.2 BUILT IN HELP + +.BR +sisu \-\-help + +.BR +sisu \-\-help \-\-env + +.BR +sisu \-\-help \-\-commands + +.BR +sisu \-\-help \-\-markup + +.SH +32.3.3 THE HOME PAGE + +.BR + + +.BR + + +.SH +32.4 MARKUP SAMPLES + +.BR +A number of markup samples (along with output) are available off: + +.BR + + +.BR +Additional markup samples are packaged separately in the file: + +.BR +.B * + +.BR +On +.B Debian +they are available in non\-free[^33] to include them it is necessary to +include non\-free in your /etc/apt/source.list or obtain them from the sisu +home site. + +.SH +33. EDITOR FILES, SYNTAX HIGHLIGHTING +.BR + +.BR +The directory: + +.BR + ./data/sisu/conf/editor\-syntax\-etc/ + +.BR + /usr/share/sisu/conf/editor\-syntax\-etc + +.BR +contains rudimentary sisu syntax highlighting files for: + +.BR +* (g)vim + +.BR + package: sisu\-vim + +.BR +status: largely done + +.BR + there is a vim syntax highlighting and folds component + +.BR +* gedit + +.BR +* gobby + +.BR + file: sisu.lang + +.BR +place in: + +.BR + /usr/share/gtksourceview\-1.0/language\-specs + +.BR +or + +.BR + ~/.gnome2/gtksourceview\-1.0/language\-specs + +.BR + status: very basic syntax highlighting + +.BR + comments: this editor features display line wrap and is used by Goby! + +.BR +* nano + +.BR + file: nanorc + +.BR +save as: + +.BR + ~/.nanorc + +.BR + status: basic syntax highlighting + +.BR + comments: assumes dark background; no display line\-wrap; does line breaks + +.BR +* diakonos (an editor written in ruby) + +.BR +file: diakonos.conf + +.BR +save as: + +.BR + ~/.diakonos/diakonos.conf + +.BR +includes: + +.BR + status: basic syntax highlighting + +.BR +comments: assumes dark background; no display line\-wrap + +.BR +* kate & kwrite + +.BR + file: sisu.xml + +.BR + place in: + +.BR + /usr/share/apps/katepart/syntax + +.BR + or + +.BR + ~/.kde/share/apps/katepart/syntax + +.BR + \ [settings::configure \ kate::{highlighting,filetypes}] + +.BR + \ [tools::highlighting::{markup,scripts}:: +.B \ SiSU +] + +.BR +* nedit + +.BR + file: sisu_nedit.pats + +.BR + nedit \-import sisu_nedit.pats + +.BR + status: a very clumsy first attempt \ [not \ really \ done] + +.BR + comments: this editor features display line wrap + +.BR +* emacs + +.BR + files: sisu\-mode.el + +.BR + to file ~/.emacs add the following 2 lines: + +.BR + (add\-to\-list \'load\-path \"/usr/share/sisu\-examples/config/syntax_hi\") + +.BR + (require \'sisu\-mode.el) + +.BR + \ [not \ done \ / \ not \ yet \ included] + +.BR +* vim & gvim + +.BR + files: + +.BR + package is the most comprehensive sisu syntax highlighting and editor + environment provided to date (is for vim/ gvim, and is separate from the + contents of this directory) + +.BR + status: this includes: syntax highlighting; vim folds; some error checking + +.BR + comments: this editor features display line wrap + +.BR +NOTE: + +.BR +[ +.B \ SiSU +\ parses \ files \ with \ long \ lines \ or \ line \ breaks, \ but, \ display +\ linewrap \ (without \ line\-breaks) \ is \ a \ convenient \ editor \ feature +\ to \ have \ for \ sisu \ markup] + +.SH +34. HELP SOURCES +.BR + +.BR +For a summary of alternative ways to get help on +.B SiSU +try one of the following: + +.BR +.B man page + +.BR + man sisu_help + +.BR +.B man2html + +.BR + + +.BR + + +.BR +.B sisu generated output \- links to html + +.BR + + +.BR + + +.BR + + +.BR +.B help sources lists + +.BR +Alternative sources for this help sources page listed here: + +.BR + man sisu_help_sources + +.BR + + +.BR + + +.BR + + +.BR + + +.SH +34.1 MAN PAGES + +.SH +34.1.1 MAN + +.BR + man sisu + +.BR + man sisu_commands + +.BR + man 7 sisu_complete + +.BR + man sisu_configuration + +.BR + man 8 sisu_faq + +.BR + man sisu_filetypes + +.BR + man sisu_help + +.BR + man sisu_help_sources + +.BR + man 8 sisu_howto + +.BR + man sisu_introduction + +.BR + man sisu_markup + +.BR + man sisu_output_overview + +.BR + man 7 sisu_pdf + +.BR + man 7 sisu_postgresql + +.BR + man 8 sisu_quickstart + +.BR + man 8 sisu_remote + +.BR + man 8 sisu_search + +.BR + man sisu_skin + +.BR + man 7 sisu_sqlite + +.BR + man 8 sisu_syntax_highlighting + +.BR + man 7 sisu_vim + +.BR + man sisu_webrick + +.SH +34.2 SISU GENERATED OUTPUT \- LINKS TO HTML + +.BR +Note +.B SiSU +documentation is prepared in +.B SiSU +and output is available in multiple formats including amongst others html, +pdf, and odf which may be also be accessed via the html pages[^34] + +.SH +34.2.1 LOCALLY INSTALLED + +.BR + + +.BR + + +.BR + + +.BR + /usr/share/doc/sisu/sisu_manual/sisu/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_commands/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_complete/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_configuration/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_description/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_examples/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_faq/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_filetypes/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_help/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_help_sources/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_howto/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_introduction/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_manual/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_markup/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_output_overview/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_pdf/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_postgresql/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_quickstart/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_remote/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_search/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_skin/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_sqlite/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_syntax_highlighting/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_vim/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_webrick/index.html + +.SH +34.2.2 WWW.SISUDOC.ORG + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.SH +34.2.3 WWW.JUS.UIO.NO/SISU + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.SH +34.2.4 MAN2HTML + +.SH +34.2.5 LOCALLY INSTALLED + +.BR + + +.BR + + +.BR + + +.BR + /usr/share/doc/sisu/html/sisu.1.html + +.BR + /usr/share/doc/sisu/html/sisu_commands.1.html + +.BR + /usr/share/doc/sisu/html/sisu_complete.7.html + +.BR + /usr/share/doc/sisu/html/sisu_configuration.1.html + +.BR + /usr/share/doc/sisu/html/sisu_faq.8.html + +.BR + /usr/share/doc/sisu/html/sisu_help.1.html + +.BR + /usr/share/doc/sisu/html/sisu_help_sources.1.html + +.BR + /usr/share/doc/sisu/html/sisu_howto.8.html + +.BR + /usr/share/doc/sisu/html/sisu_markup.1.html + +.BR + /usr/share/doc/sisu/html/sisu_pdf.7.html + +.BR + /usr/share/doc/sisu/html/sisu_postgresql.7.html + +.BR + /usr/share/doc/sisu/html/sisu_quickstart.8.html + +.BR + /usr/share/doc/sisu/html/sisu_remote.8.html + +.BR + /usr/share/doc/sisu/html/sisu_search.8.html + +.BR + /usr/share/doc/sisu/html/sisu_skin.1.html + +.BR + /usr/share/doc/sisu/html/sisu_sqlite.7.html + +.BR + /usr/share/doc/sisu/html/sisu_syntax_highlighting.8.html + +.BR + /usr/share/doc/sisu/html/sisu_vim.7.html + +.BR + /usr/share/doc/sisu/html/sisu_webrick.1.html + +.SH +34.2.6 WWW.SISUDOC.ORG + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.SH +34.2.7 WWW.JUS.UIO.NO/SISU + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ + + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- SiSU information Structuring Universe \- Manual \ [0.58] + +.BR +DC Creator: +.I Ralph Amissah + +.BR +DC Rights: +.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL +3 + +.BR +DC Type: +.I information + +.BR +DC Date created: +.I 2002\-08\-28 + +.BR +DC Date issued: +.I 2002\-08\-28 + +.BR +DC Date available: +.I 2002\-08\-28 + +.BR +DC Date modified: +.I 2007\-08\-30 + +.BR +DC Date: +.I 2007\-08\-30 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu._sst + +.BR +Filetype: +.I SiSU text insert 0.58 + +.BR +Sourcefile Digest, MD5(sisu._sst)= +.I 850b4b4b2da877667488ddfa325b6581 + +.BR +Skin_Digest: +MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +.I 20fc43cf3eb6590bc3399a1aef65c5a9 + +.BR +.B Generated + +.BR +Document (metaverse) last generated: +.I Sun Sep 23 04:13:41 +0100 2007 + +.BR +Generated by: +.I SiSU +.I 0.59.0 +of 2007w38/0 (2007\-09\-23) + +.BR +Ruby version: +.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux] + +.TP +.BI 1. +\" +.B SiSU +information Structuring Universe\" or \"Structured information, Serialized +Units\". + also chosen for the meaning of the Finnish term "sisu". +.TP +.BI 2. +Unix command line oriented +.TP +.BI 3. +objects include: headings, paragraphs, verse, tables, images, but not +footnotes/endnotes which are numbered separately and tied to the object from +which they are referenced. +.TP +.BI 4. +i.e. the html, pdf, odf outputs are each built individually and optimised for +that form of presentation, rather than for example the html being a saved +version of the odf, or the pdf being a saved version of the html. +.TP +.BI 5. +the different heading levels +.TP +.BI 6. +units of text, primarily paragraphs and headings, also any tables, poems, +code-blocks +.TP +.BI 7. +Specification submitted by Adobe to ISO to become a full open ISO +specification + +.TP +.BI 8. +ISO/IEC 26300:2006 +.TP +.BI 9. +generated from source using rman + + With regard to +.B SiSU +man pages the formatting generated for markup syntax is not quite right, for +that you might prefer the links under: + +.TP +.BI 10. + +.TP +.BI 11. + +.TP +.BI 12. + +.TP +.BI 13. + +.TP +.BI 14. + +.TP +.BI *1. +square brackets +.TP +.BI *2. +square brackets +.TP +.BI +1. +square brackets +.TP +.BI 15. +From sometime after SiSU 0.58 it should be possible to describe SiSU markup +using SiSU, which though not an original design goal is useful. +.TP +.BI 16. +files should be prepared using UTF-8 character encoding +.TP +.BI 17. +a footnote or endnote +.TP +.BI 18. +self contained endnote marker & endnote in one +.TP +.BI *. +unnumbered asterisk footnote/endnote, insert multiple asterisks if required +.TP +.BI **. +another unnumbered asterisk footnote/endnote +.TP +.BI *3. +editors notes, numbered asterisk footnote/endnote series +.TP +.BI +2. +editors notes, numbered asterisk footnote/endnote series +.TP +.BI 19. + +.TP +.BI 20. + +.TP +.BI 21. +Table from the Wealth of Networks by Yochai Benkler + +.TP +.BI 22. +.ssc (for composite) is under consideration but ._sst makes clear that this +is not a regular file to be worked on, and thus less likely that people will +have \"accidents\", working on a .ssc file that is overwritten by subsequent +processing. It may be however that when the resulting file is shared .ssc is an +appropriate suffix to use. +.TP +.BI 23. +.B SiSU +has worked this way in the past, though this was dropped as it was thought +the complexity outweighed the flexibility, however, the balance was rather fine +and this behaviour could be reinstated. +.TP +.BI 24. + + + +.TP +.BI 25. + + +.TP +.BI 26. + +.TP +.BI 27. +(which could be extended further with current back-end). As regards scaling +of the database, it is as scalable as the database (here Postgresql) and +hardware allow. +.TP +.BI 28. +of this feature when demonstrated to an IBM software innovations evaluator +in 2004 he said to paraphrase: this could be of interest to us. We have large +document management systems, you can search hundreds of thousands of documents +and we can tell you which documents meet your search criteria, but there is no +way we can tell you without opening each document where within each your +matches are found. +.TP +.BI 29. +There is nothing to stop MySQL support being added in future. +.TP +.BI 30. + +.TP +.BI 31. + +.TP +.BI 32. + +.TP +.BI 33. +the +.B Debian +Free Software guidelines require that everything distributed within +.B Debian +can be changed - and the documents are authors\' works that while freely +distributable are not freely changeable. +.TP +.BI 34. +named index.html or more extensively through sisu_manifest.html + +.TP +Other versions of this document: +.TP +manifest: +.TP +html: +.TP +pdf: +.TP +pdf: +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu/sisu.1 +.TP +at: +.TP +.TP +* Generated by: SiSU 0.59.0 of 2007w38/0 (2007-09-23) +.TP +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +.TP +* Last Generated on: Sun Sep 23 04:13:48 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu -- cgit v1.2.3