From 1ffd1da38f779145d6d3685b705fc51e4f90a17b Mon Sep 17 00:00:00 2001 From: Ralph Amissah Date: Sat, 5 Mar 2011 21:29:24 -0500 Subject: documentation, remove some files --- man/man1/sisu3.1 | 4806 ------------------------------------------------------ 1 file changed, 4806 deletions(-) delete mode 100644 man/man1/sisu3.1 (limited to 'man') diff --git a/man/man1/sisu3.1 b/man/man1/sisu3.1 deleted file mode 100644 index 96b69e36..00000000 --- a/man/man1/sisu3.1 +++ /dev/null @@ -1,4806 +0,0 @@ -.TH "sisu" "1" "2011-02-07" "3.0.0" "SiSU" -.SH NAME -sisu \- documents: markup, structuring, publishing in multiple standard formats, and search -.SH SYNOPSIS -sisu [\-abcDdFehIiMmNnopqRrSsTtUuVvwXxYyZz0\-9] [filename/wildcard] - -.BR -sisu [\-P] [language_directory/filename language_directory] - -.BR -sisu [\-Ddcv] [instruction] [filename/wildcard] - -.BR -sisu [\-CcFLSVvW] - -.BR -sisu \-\-v2 [operations] - -.BR -sisu \-\-v1 [operations] -.SH -SISU \- MANUAL, -RALPH AMISSAH -.BR - -.SH -WHAT IS SISU? -.BR - -.SH -1. INTRODUCTION \- WHAT IS SISU? -.BR - -.BR -.B SiSU -is a framework for document structuring, publishing (in multiple open -standard formats) 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 (including -the population of sql databases) 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). Its use -case for development is work with medium to large document sets and cope with -evolving document formats/ representation technologies. Documents are prepared -once, and generated as need be to update the technical presentation or add -additional output formats. Various output formats (including search related -output) share a common mechanism for cross\-output\-format citation. - -.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, EPUB, 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. - -.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 (to take advantage of the strengths of different ways of -representing documents) various standard open output formats including plain -text, HTML, XHTML, XML, EPUB, OpenDocument, LaTeX or PDF files, and populate an -SQL database with objects[^1] (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[^2] -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 headings[^3] and objects[^4], 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 basis for citing -material within a document across the different output format types. This is -significant as page numbers are not well suited to the digital age, in web -publishing, changing a browser's default font or using a different browser can -mean that text will appear on a different page; and publishing in different -formats, html, landscape and portrait pdf etc. again page numbers are not -useful to cite text. Dealing with documents at an object level together with -object numbering also has implications for search that -.B SiSU -is able to take advantage of. - -.BR -One of the challenges of maintaining documents is to keep them in a format that -allows use of them independently of proprietary platforms. Consider issues -related to 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 producing documents in multiple non\-proprietary -open formats including html, pdf[^5] ODF,[^6] and EPUB.[^7] 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 when it became an ISO standard for -office applications and the archival of documents), EPUB was introduced in -2009; and allows the technical representations 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 thesauri, 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. COMMANDS SUMMARY -.BR - -.SH -2.1 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, -xhtml, XML, epub, odt (odf text), LaTeX, pdf, info, and SQL (PostgreSQL and -SQLite), which share numbered text objects ("object citation numbering") and -the same document structure information. For more see: - - -.SH -2.2 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] -see \-\-xhtml - -.TP -.B \-\-color\-toggle [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). Alias \-c - -.TP -.B \-\-concordance [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). Alias \-w - -.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] -see \-\-color\-toggle - -.TP -.B \-\-dal [filename/wildcard/url] -assumed for most other flags, creates new intermediate files for processing -(document abstraction) that is used in all subsequent processing of other -output. This step is assumed for most processing flags. To skip it see \-n. -Alias \-m - -.TP -.B \-\-delete [filename/wildcard] -see \-\-zap - -.TP -.B \-D [instruction] [filename] -see \-\-pg - -.TP -.B \-d [\-\-db\-[database \ type \ (sqlite|pg)]] \-\-[instruction] [filename] -see \-\-sqlite - -.TP -.B \-\-epub [filename/wildcard] -produces an epub document, [sisu \ version \ 2 \ only] (filename.epub). Alias -\-e - -.TP -.B \-e [filename/wildcard] -see \-\-epub - -.TP -.B \-F [\-\-webserv=webrick] -see \-\-sample\-search\-form - -.TP -.B \-\-git [filename/wildcard] -produces or updates markup source file structure in a git repo (experimental -and subject to change). Alias \-g - -.TP -.B \-g [filename/wildcard] -see \-\-git - -.TP -.B \-\-harvest *.ss[tm] -makes two lists of sisu output based on the sisu markup documents in a -directory: list of author and authors works (year and titles), and; list by -topic with titles and author. Makes use of header metadata fields (author, -title, date, topic_register). Can be used with maintenance (\-M) and remote -placement (\-R) flags. - -.TP -.B \-\-help [topic] -provides help on the selected topic, where topics (keywords) include: list, -(com)mands, short(cuts), (mod)ifiers, (env)ironment, markup, syntax, headers, -headings, endnotes, tables, example, customise, skin, (dir)ectories, path, -(lang)uage, db, install, setup, (conf)igure, convert, termsheet, search, sql, -features, license - -.TP -.B \-\-html [filename/wildcard] -produces html output, segmented text with table of contents (toc.html and -index.html) and the document in a single file (scroll.html). Alias \-h - -.TP -.B \-h [filename/wildcard] -see \-\-html - -.TP -.B \-I [filename/wildcard] -see \-\-texinfo - -.TP -.B \-i [filename/wildcard] -see \-\-manpage - -.TP -.B \-L -prints license information. - -.TP -.B \-\-machine [filename/wildcard/url] -see \-\-dal (document abstraction level/layer) - -.TP -.B \-\-maintenance [filename/wildcard/url] -maintenance mode files created for processing preserved and their locations -indicated. (also see \-V). Alias \-M - -.TP -.B \-\-manpage [filename/wildcard] -produces man page of file, not suitable for all outputs. Alias \-i - -.TP -.B \-M [filename/wildcard/url] -see \-\-maintenance - -.TP -.B \-m [filename/wildcard/url] -see \-\-dal (document abstraction level/layer) - -.TP -.B \-\-no\-ocn -[with \ \-\-html \ \-\-pdf \ or \ \-\-epub] switches off object citation -numbering. Produce output without identifying numbers in margins of html or -LaTeX/pdf output. - -.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 the creation of intermediate processing files (document abstraction) if -they already exist, this skips the equivalent of \-m which is otherwise assumed -by most processing flags. - -.TP -.B \-\-odf [filename/wildcard/url] -see \-\-odt - -.TP -.B \-\-odt [filename/wildcard/url] -output basic document in opendocument file format (opendocument.odt). Alias -\-o - -.TP -.B \-o [filename/wildcard/url] -see \-\-odt - -.TP -.B \-\-pdf [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). Alias \-p - -.TP -.B \-\-pg [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. Alias -\-D - -.TP -.B \-\-po [language_directory/filename language_directory] -see \-\-po4a - -.TP -.B \-\-po4a [language_directory/filename language_directory] -produces .pot and po files for the file in the languages specified by the -language directory. SiSU markup is placed in subdirectories named with the -language code, e.g. en/ fr/ es/. The sisu config file must set the output -directory structure to multilingual. v3, experimental - -.TP -.B \-P [language_directory/filename language_directory] -see \-\-po4a - -.TP -.B \-p [filename/wildcard] -see \-\-pdf - -.TP -.B \-\-quiet [filename/wildcard] -quiet less output to screen. - -.TP -.B \-q [filename/wildcard] -see \-\-quiet - -.TP -.B \-\-rsync [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 \-\-scp. Alias \-R - -.TP -.B \-R [filename/wildcard] -see \-\-rsync - -.TP -.B \-r [filename/wildcard] -see \-\-scp - -.TP -.B \-\-sample\-search\-form [\-\-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. Alias \-F - -.TP -.B \-\-scp [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 \-\-rsync. Alias \-r - -.TP -.B \-\-sqlite \-\-[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. Alias \-d - -.TP -.B \-\-sisupod -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). Alias \-S - -.TP -.B \-\-sisupod [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]. -Alias \-S - -.TP -.B \-\-source [filename/wildcard] -copies sisu markup file to output directory. Alias \-s - -.TP -.B \-S -see \-\-sisupod - -.TP -.B \-S [filename/wildcard] -see \-\-sisupod - -.TP -.B \-s [filename/wildcard] -see \-\-source - -.TP -.B \-\-texinfo [filename/wildcard] -produces texinfo and info file, (view with pinfo). Alias \-I - -.TP -.B \-\-txt [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). Alias \-t - -.TP -.B \-T [filename/wildcard \ (*.termsheet.rb)] -standard form document builder, preprocessing feature - -.TP -.B \-t [filename/wildcard] -see \-\-txt - -.TP -.B \-\-urls [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. Alias \-U - -.TP -.B \-U [filename/wildcard] -see \-\-urls - -.TP -.B \-u [filename/wildcard] -provides url mapping of output files for the flags requested for processing, -also see \-U - -.TP -.B \-\-v1 [filename/wildcard] -invokes the sisu v1 document parser/generator. For use with sisu v1 markup -documents. (Markup conversion to v2 involves the modification of document -headers) - -.TP -.B \-\-v2 [filename/wildcard] -invokes the sisu v2 document parser/generator. This is the default and is -normally omitted. - -.TP -.B \-\-verbose [filename/wildcard] -provides verbose output of what is being generated, where output is placed -(and error messages if any), as with \-u flag provides a url mapping of files -created for each of the processing flag requests. Alias \-v - -.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. - -.TP -.B \-v -on its own, provides -.B SiSU -version information - -.TP -.B \-v [filename/wildcard] -see \-\-verbose - -.TP -.B \-\-webrick -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 \ ]. Alias \-W - -.TP -.B \-W -see \-\-webrick - -.TP -.B \-\-wordmap [filename/wildcard] -see \-\-concordance - -.TP -.B \-w [filename/wildcard] -see \-\-concordance - -.TP -.B \-\-xhtml [filename/wildcard] -produces xhtml/XML output for browser viewing (sax parsing). Alias \-b - -.TP -.B \-\-xml\-dom [filename/wildcard] -produces XML output with deep document structure, in the nature of dom. Alias -\-X - -.TP -.B \-\-xml\-sax [filename/wildcard] -produces XML output shallow structure (sax parsing). Alias \-x - -.TP -.B \-X [filename/wildcard] -see \-\-xml\-dom - -.TP -.B \-x [filename/wildcard] -see \-\-xml\-sax - -.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 \-\-zap [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. Alias \-Z - -.TP -.B \-Z [filename/wildcard] -see \-\-zap - -.SH -3. COMMAND LINE MODIFIERS -.BR - -.TP -.B \-\-no\-ocn -[with \ \-\-html \ \-\-pdf \ or \ \-\-epub] 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 -4. 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 \-\-pg \-v \-\-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 \-\-pg \-v \-\-import -[filename/wildcard] imports data specified to postgresql db (rb.dbi) [ \ \-dv -\ \-\-import \ sqlite \ equivalent] - -.TP -.B \-\-pg \-v \-\-update -[filename/wildcard] updates/imports specified data to postgresql db (rb.dbi) -[ \ \-dv \ \-\-update \ sqlite \ equivalent] - -.TP -.B \-\-pg \-\-remove -[filename/wildcard] removes specified data to postgresql db (rb.dbi) [ \ \-d -\ \-\-remove \ sqlite \ equivalent] - -.TP -.B \-\-pg \-\-dropall -kills data" and drops (postgresql or sqlite) db, tables & indexes [ \ \-d \ -\-\-dropall \ sqlite \ equivalent] - -.BR -The \-v is for verbose output. - -.SH -5. 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 -\-mhewpy - -.TP -.B \-2 -\-mhewpaoy - -.TP -.B \-3 -\-mhewpAobxXyY - -.TP -.B \-4 -\-mhewpAobxXDyY \-\-import - -.TP -.B \-5 -\-mhewpAobxXDyY \-\-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 -5.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 -6. HELP -.BR - -.SH -6.1 SISU MANUAL - -.BR -The most up to date information on sisu should be contained in the sisu_manual, -available at: - -.BR - - -.BR -The manual can be generated from source, found respectively, either within the -.B SiSU -tarball or installed locally at: - -.BR - ./data/doc/sisu/v2/sisu_markup_samples/sisu_manual/ - -.BR - /usr/share/doc/sisu/v2/sisu_markup_samples/sisu_manual/ - -.BR -move to the respective directory and type e.g.: - -.BR - sisu sisu_manual.ssm - -.SH -6.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/v2/sisu_markup_samples/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/v2/html/ - -.BR - ./data/doc/sisu/v2/html/ - -.BR -An online version of the sisu man page is available here: - -.BR -* various sisu man pages [^8] - -.BR -* sisu.1 [^9] - -.SH -6.3 SISU BUILT\-IN INTERACTIVE HELP - -.BR -This is particularly useful for getting the current sisu setup/environment -information: - -.BR - sisu \-\-help - -.BR - sisu \-\-help [subject] - -.BR - sisu \-\-help commands - -.BR - sisu \-\-help markup - -.BR - sisu \-\-help env [for \ feedback \ on \ the \ way \ your \ system \ is \ - setup \ with \ regard \ to \ sisu] - -.BR - sisu \-V [environment \ information, \ same \ as \ above \ command] - -.BR - sisu (on its own provides version and some help information) - -.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 -6.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/v2/html/sisu.1.html - -.BR - - -.SH -7. INTRODUCTION TO SISU MARKUP[^10] -.BR - -.SH -7.1 SUMMARY - -.BR -.B SiSU -source documents are plaintext (UTF\-8)[^11] 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 - -.BR -To check the markup in a file: - -.BR - sisu \-\-identify [filename].sst - -.BR -For brief descriptive summary of markup history - -.BR - sisu \-\-query\-history - -.BR -or if for a particular version: - -.BR - sisu \-\-query\-0.38 - -.SH -7.2 MARKUP EXAMPLES - -.SH -7.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 -7.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 -8. MARKUP OF HEADERS -.BR - -.BR -Headers contain either: semantic meta\-data about a document, which can be used -by any output module of the program, or; 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 -8.1 SAMPLE HEADER - -.BR -This current document is loaded by a master document that has a header similar -to this one: - - -.nf - % SiSU master 2.0 - @title: SiSU - :subtitle: Manual - @creator: :author: Amissah, Ralph - @rights: Copyright (C) Ralph Amissah 2007, License GPL 3 - @classify: - :type: information - :topic_register: SiSU:manual;electronic documents:SiSU:manual - :subject: ebook, epublishing, electronic book, electronic publishing, - electronic document, electronic citation, data structure, - citation systems, search - % used_by: manual - @date: :published: 2008\-05\-22 - :created: 2002\-08\-28 - :issued: 2002\-08\-28 - :available: 2002\-08\-28 - :modified: 2010\-03\-03 - @make: :num_top: 1 - :breaks: new=C; break=1 - :skin: skin_sisu_manual - :bold: /Gnu|Debian|Ruby|SiSU/ - :manpage: name=sisu \- documents: markup, structuring, publishing - in multiple standard formats, and search; - synopsis=sisu \ [\-abcDdeFhIiMmNnopqRrSsTtUuVvwXxYyZz0\-9] \ [filename/wildcard \ ] - . sisu \ [\-Ddcv] \ [instruction] - . sisu \ [\-CcFLSVvW] - . sisu \-\-v2 \ [operations] - . sisu \-\-v1 \ [operations] - @links: { SiSU Manual }http://www.jus.uio.no/sisu/sisu_manual/ - { Book Samples and Markup Examples }http://www.jus.uio.no/sisu/SiSU/examples.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 - { SiSU help }http://www.jus.uio.no/sisu/sisu_manual/sisu_help/ - { SiSU help sources }http://www.jus.uio.no/sisu/sisu_manual/sisu_help_sources/ -.fi - -.SH -8.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 - - -.nf - % SiSU 2.0 \ [declared \ file\-type \ identifier \ with \ markup \ version] -.fi - -.nf - @title: \ [title \ text] \ [this \ header \ is \ the \ only \ one \ that \ is \ mandatory] - :subtitle: \ [subtitle \ if \ any] - :language: English -.fi - -.nf - @creator: :author: \ [Lastname, \ First \ names] - :illustrator: \ [Lastname, \ First \ names] - :translator: \ [Lastname, \ First \ names] - :prepared_by: \ [Lastname, \ First \ names] -.fi - -.nf - @date: :published: \ [year \ or \ yyyy\-mm\-dd] - :created: \ [year \ or \ yyyy\-mm\-dd] - :issued: \ [year \ or \ yyyy\-mm\-dd] - :available: \ [year \ or \ yyyy\-mm\-dd] - :modified: \ [year \ or \ yyyy\-mm\-dd] - :valid: \ [year \ or \ yyyy\-mm\-dd] - :added_to_site: \ [year \ or \ yyyy\-mm\-dd] - :translated: \ [year \ or \ yyyy\-mm\-dd] -.fi - -.nf - @rights: :copyright: Copyright (C) \ [Year \ and \ Holder] - :license: \ [Use \ License \ granted] - :text: \ [Year \ and \ Holder] - :translation: \ [Name, \ Year] - :illustrations: \ [Name, \ Year] -.fi - -.nf - @classify: - :topic_register: SiSU:markup sample:book;book:novel:fantasy - :type: - :subject: - :description: - :keywords: - :abstract: - :isbn: \ [ISBN] - :loc: \ [Library \ of \ Congress \ classification] - :dewey: \ [Dewey \ classification - :pg: \ [Project \ Gutenberg \ text \ number] -.fi - -.nf - @links: { SiSU }http://www.jus.uio.no/sisu/ - { FSF }http://www.fsf.org -.fi - -.nf - @make: - :skin: skin_name - [skins change default settings related to the appearance of documents generated] - :num_top: 1 - :headings: \ [text \ to \ match \ for \ each \ level - (e.g. PART; Chapter; Section; Article; - or another: none; BOOK|FIRST|SECOND; none; CHAPTER;) - :breaks: new=:C; break=1 - :promo: sisu, ruby, sisu_search_libre, open_society - :bold: [regular expression of words/phrases to be made bold] - :italics: \ [regular \ expression \ of \ words/phrases \ to \ italicise] -.fi - -.nf - @original: :language: \ [language] -.fi - -.nf - @notes: :comment: - :prefix: \ [prefix \ is \ placed \ just \ after \ table \ of \ contents] -.fi - -.SH -9. MARKUP OF SUBSTANTIVE TEXT -.BR - -.SH -9.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 -9.2 FONT ATTRIBUTES - -.BR -.B markup example: - - -.nf - normal text, *{emphasis}*, !{bold text}!, /{italics}/, _{underscore}_, "{citation}", - ^{superscript}^, ,{subscript},, +{inserted text}+, \-{strikethrough}\- #{monospace}# -.BR - normal text -.BR - !{emphasis}! -.BR - *{bold text}* -.BR - _{underscore}_ -.BR - /{italics}/ -.BR - "{citation}" -.BR - ^{superscript}^ -.BR - ,{subscript}, -.BR - +{inserted text}+ -.BR - \-{strikethrough}\- -.BR - #{monospace}# -.fi - -.BR -.B resulting output: - -.BR -normal text -.B emphasis -.B bold text -.I underscore -.I italics -"citation" ^superscript^ [subscript] ++inserted text++ \-\-strikethrough\-\- monospace - -.BR -normal text - -.BR -.B emphasis -[note: \ can \ be \ configured \ to \ be \ represented \ by \ bold, \ italics -\ or \ underscore] - -.BR -.B bold text - -.BR -.I italics - -.BR -.I underscore - -.BR -"citation" - -.BR -^superscript^ - -.BR -[subscript] - -.BR -++inserted text++ - -.BR -\-\-strikethrough\-\- - -.BR -monospace - -.SH -9.3 INDENTATION AND BULLETS - -.BR -.B markup example: - - -.nf - ordinary paragraph -.BR - _1 indent paragraph one step -.BR - _2 indent paragraph two steps -.BR - _9 indent paragraph nine steps -.fi - - -.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 -.BR - _1* bullet text, first indent -.BR - _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. -.BR - _# numbered list numbered list indented a., b., c., d., etc. -.fi - -.SH -9.4 FOOTNOTES / ENDNOTES - -.BR -Footnotes and endnotes not distinguished in markup. They are automatically -numbered. Depending on the output file format (html, EPUB, 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 -[^12] - -.BR -.B markup example: - - -.nf - normal text~{ self contained endnote marker & endnote in one }~ continues -.fi - -.BR -.B resulting output: - -.BR -normal text[^13] continues - -.BR -.B markup example: - - -.nf - normal text ~{* unnumbered asterisk footnote/endnote, insert multiple asterisks if required }~ continues -.BR - 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 -.BR - 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 - % note the endnote marker \"~^\" -.BR - normal text~^ continues -.BR - ^~ 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 -9.5 LINKS - -.SH -9.5.1 NAKED URLS WITHIN TEXT, DEALING WITH URLS - -.BR -urls found within text are 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 -.BR - 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 -9.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 -abou tSiSU [^14] markup - -.SH -9.5.3 LINKING IMAGES - -.BR -.B markup example: - - -.nf - { tux.png 64x80 }image -.BR - % various url linked images -.BR - {tux.png 64x80 \"a better way\" }http://www.jus.uio.no/sisu/ -.BR -.BR - {GnuDebianLinuxRubyBetterWay.png 100x101 \"Way Better \- with Gnu/Linux, Debian and Ruby\" }http://www.jus.uio.no/sisu/ -.BR -.BR - {~^ ruby_logo.png \"Ruby\" }http://www.ruby\-lang.org/en/ -.BR -.BR -.fi - -.BR -.B resulting output: - -.BR -[ tux.png ] - -.BR -tux.png 64x80 \"Gnu/Linux \- a better way\" - -.BR -[ \ ruby_logo \ (png \ missing) \ ] [^15] - -.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 -9.6 GROUPED TEXT - -.SH -9.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: -[^16] - - -.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 -9.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 -.BR - mouse, That he -.BR - met in the -.BR - house, -.BR - \"Let us -.BR - both go to -.BR - law: I will -.BR - prosecute -.BR - YOU. \-\-Come, -.BR - I\'ll take no -.BR - denial; We -.BR - must have a -.BR - trial: For -.BR - really this -.BR - morning I\'ve -.BR - nothing -.BR - to do.\" -.BR - Said the -.BR - mouse to the -.BR - cur, \"Such -.BR - a trial, -.BR - dear Sir, -.BR - With -.BR - no jury -.BR - or judge, -.BR - would be -.BR - wasting -.BR - our -.BR - breath.\" -.BR - \"I\'ll be -.BR - judge, I\'ll -.BR - be jury,\" -.BR - Said -.BR - cunning -.BR - old Fury: -.BR - \"I\'ll -.BR - try the -.BR - whole -.BR - cause, -.BR - and -.BR - condemn -.BR - you -.BR - to -.BR - death.\"\' -.BR - -.SH -9.6.3 GROUP - -.BR -.B basic markup: - - -.nf - group{ -.BR - Your grouped text here -.BR - }group -.BR - A group is treated as an object and given a single object number. -.fi - -.BR -.B markup example: - - -.nf - group{ -.BR - \'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 -.BR - mouse, That he -.BR - met in the -.BR - house, -.BR - \"Let us -.BR - both go to -.BR - law: I will -.BR - prosecute -.BR - YOU. \-\-Come, -.BR - I\'ll take no -.BR - denial; We -.BR - must have a -.BR - trial: For -.BR - really this -.BR - morning I\'ve -.BR - nothing -.BR - to do.\" -.BR - Said the -.BR - mouse to the -.BR - cur, \"Such -.BR - a trial, -.BR - dear Sir, -.BR - With -.BR - no jury -.BR - or judge, -.BR - would be -.BR - wasting -.BR - our -.BR - breath.\" -.BR - \"I\'ll be -.BR - judge, I\'ll -.BR - be jury,\" -.BR - Said -.BR - cunning -.BR - old Fury: -.BR - \"I\'ll -.BR - try the -.BR - whole -.BR - cause, -.BR - and -.BR - condemn -.BR - you -.BR - to -.BR - death.\"\' -.BR - -.SH -9.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 -9.7 BOOK INDEX - -.BR -To make an index append to paragraph the book index term relates to it, using -an equal sign and curly braces. - -.BR -Currently two levels are provided, a main term and if needed a sub\-term. -Sub\-terms are separated from the main term by a colon. - - -.nf - Paragraph containing main term and sub\-term. - ={Main term:sub\-term} -.fi - -.BR -The index syntax starts on a new line, but there should not be an empty line -between paragraph and index markup. - -.BR -The structure of the resulting index would be: - - -.nf - Main term, 1 - sub\-term, 1 -.fi - -.BR -Several terms may relate to a paragraph, they are separated by a semicolon. If -the term refers to more than one paragraph, indicate the number of paragraphs. - - -.nf - Paragraph containing main term, second term and sub\-term. - ={first term; second term: sub\-term} -.fi - -.BR -The structure of the resulting index would be: - - -.nf - First term, 1, - Second term, 1, - sub\-term, 1 -.fi - -.BR -If multiple sub\-terms appear under one paragraph, they are separated under the -main term heading from each other by a pipe symbol. - - -.nf - Paragraph containing main term, second term and sub\-term. - ={Main term:sub\-term+1|second sub\-term - A paragraph that continues discussion of the first sub\-term -.fi - -.BR -The plus one in the example provided indicates the first sub\-term spans one -additional paragraph. The logical structure of the resulting index would be: - - -.nf - Main term, 1, - sub\-term, 1\-3, - second sub\-term, 1, -.fi - -.SH -10. 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 - << filename.ssi - <<{filename.ssi} - % using textlink alternatives - << |filename.ssi|@|^| -.fi - -.SH -MARKUP SYNTAX HISTORY -.BR - -.SH -11. 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 -* sisu \-\-query=[sisu \ version \ [0.38] or \'history] - -.BR -provides a short history of changes to -.B SiSU -markup - -.BR -.B 0.57 -(2007w34/4) -.B SiSU -0.57 is the same as 0.42 with the introduction of some a shortcut to use the -headers @title and @creator in the first heading [expanded \ using \ the \ -contents \ of \ the \ headers \ @title: \ and \ @author:] - - -.nf - :A~ @title by @author -.fi - -.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 SiSU -0.42 is the same as 0.38 with the introduction of some additional endnote -types, - -.BR -Introduces some variations on endnotes, in particular the use of the asterisk - - -.nf - ~{* for example for describing an author }~ and ~{** for describing a second author }~ -.fi - -.BR -* for example for describing an author - -.BR -** for describing a second author - -.BR -and - - -.nf - ~[* \ my \ note \ ]~ or ~[+ \ another \ note \ ]~ -.fi - -.BR -which numerically increments an asterisk and plus respectively - -.BR -*1 my note +1 another note - -.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 SiSU -0.38 introduced alternative experimental header and heading/structure -markers, - - -.nf - @headername: and headers :A~ :B~ :C~ 1~ 2~ 3~ -.fi - -.BR -as the equivalent of: - - -.nf - 0~headername and headers 1~ 2~ 3~ 4~ 5~ 6~ -.fi - -.BR -The internal document markup of -.B SiSU -0.16 remains valid and standard Though note that -.B SiSU -0.37 introduced a new file naming convention - -.BR -.B SiSU -has in effect two sets of levels to be considered, using 0.38 notation A\-C -headings/levels, pre\-ordinary paragraphs /pre\-substantive text, and 1\-3 -headings/levels, levels which are followed by ordinary text. This may be -conceptualised as levels A,B,C, 1,2,3, and using such letter number notation, -in effect: A must exist, optional B and C may follow in sequence (not strict) 1 -must exist, optional 2 and 3 may follow in sequence i.e. there are two -independent heading level sequences A,B,C and 1,2,3 (using the 0.16 standard -notation 1,2,3 and 4,5,6) on the positive side: the 0.38 A,B,C,1,2,3 -alternative makes explicit an aspect of structuring documents in -.B SiSU -that is not otherwise obvious to the newcomer (though it appears more -complicated, is more in your face and likely to be understood fairly quickly); -the substantive text follows levels 1,2,3 and it is \'nice\' to do most work in -those levels - -.BR -.B 0.37 -(2006w09/7) introduced new file naming convention, \.sst (text), \.ssm -(master), \.ssi (insert), markup syntax unchanged - -.BR -.B SiSU -0.37 introduced new file naming convention, using the file extensions \.sst - \.ssm and \.ssi to replace \.s1 \.s2 \.s3 \.r1 \.r2 \.r3 and \.si - -.BR -this is captured by the following file \'rename\' instruction: - - -.nf - rename \'s/\.s[123]$/\.sst/\' *.s{1,2,3} - rename \'s/\.r[123]$/\.ssm/\' *.r{1,2,3} - rename \'s/\.si$/\.ssi/\' *.si -.fi - -.BR -The internal document markup remains unchanged, from -.B SiSU -0.16 - -.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 - -.BR -.B SiSU -0.16 (0.15 development branch) introduced the use of - -.BR -the header 0~ and headings/structure 1~ 2~ 3~ 4~ 5~ 6~ - -.BR -in place of the 0.1 header, heading/structure notation - -.BR -.B SiSU -0.1 headers and headings structure represented by header 0{~ and -headings/structure 1{ 2{ 3{ 4{~ 5{ 6{ - -.SH -12. SISU FILETYPES -.BR - -.BR -.B SiSU -has plaintext and binary filetypes, and can process either type of document. - -.SH -12.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 -12.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 -12.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 [^17] - -.BR - - -.BR - - -.SH -12.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 -12.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 -13. EXPERIMENTAL ALTERNATIVE INPUT REPRESENTATIONS -.BR - -.SH -13.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 -13.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 -13.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 -13.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 -14. CONFIGURATION -.BR - -.SH -14.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 -14.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 -15. 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 -15.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 -15.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 -15.3 SITE SKIN - -.BR -A site skin, modifies the program default skin. - -.SH -15.4 SAMPLE SKINS - -.BR -With -.B SiSU -installed sample skins may be found in: - -.BR - /etc/sisu/skin/doc and - /usr/share/doc/sisu/v2/sisu_markup_samples/samples/_sisu/skin/doc - -.BR -(or equivalent directory) and if sisu\-markup\-samples is installed also under: - -.BR - /usr/share/doc/sisu\-markup\-samples/v2/samples/_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 -16. 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.[^18] - -.SH -17. ORGANISING CONTENT -.BR - -.SH -17.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 - -.SH -18. 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 -18.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 -18.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 -19. MARKUP AND OUTPUT EXAMPLES -.BR - -.SH -19.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 -20. 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 -21. SQL -.BR - -.SH -21.1 POPULATING SQL TYPE DATABASES - -.BR -.B SiSU -feeds sisu markupd documents into sql type databases PostgreSQL[^19] and/or -SQLite[^20] 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 -22. POSTGRESQL -.BR - -.SH -22.1 NAME - -.BR -.B SiSU -\- Structured information, Serialized Units \- a document publishing system, -postgresql dependency package - -.SH -22.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 -22.3 SYNOPSIS - -.BR - sisu \-D [instruction] [filename/wildcard \ if \ required] - -.BR - sisu \-D \-\-pg \-\-[instruction] [filename/wildcard \ if \ required] - -.SH -22.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 -22.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 -22.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 -23. SQLITE -.BR - -.SH -23.1 NAME - -.BR -.B SiSU -\- Structured information, Serialized Units \- a document publishing system. - -.SH -23.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 -23.3 SYNOPSIS - -.BR - sisu \-d [instruction] [filename/wildcard \ if \ required] - -.BR - sisu \-d \-\-(sqlite|pg) \-\-[instruction] [filename/wildcard \ if \ - required] - -.SH -23.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 -23.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 -23.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 -24. INTRODUCTION -.BR - -.SH -24.1 SEARCH \- DATABASE FRONTEND SAMPLE, UTILISING DATABASE AND SISU FEATURES, -INCLUDING OBJECT CITATION NUMBERING (BACKEND CURRENTLY POSTGRESQL) - -.BR -Sample search frontend [^21] A small database and -sample query front\-end (search from) that makes use of the citation system, -.I object citation numbering -to demonstrates functionality.[^22] - -.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, EPUB, -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.[^23] - -.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 -24.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 -25. HYPERESTRAIER -.BR - -.BR -See the documentation for hyperestraier: - -.BR - - -.BR - /usr/share/doc/hyperestraier/index.html - -.BR - man estcmd - -.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 -26. SISU_WEBRICK -.BR - -.SH -26.1 NAME - -.BR -.B SiSU -\- Structured information, Serialized Units \- a document publishing system - -.SH -26.2 SYNOPSIS - -.BR -sisu_webrick [port] - -.BR -or - -.BR -sisu \-W [port] - -.SH -26.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 -26.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 -26.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 -26.6 FURTHER INFORMATION - -.BR -For more information on -.B SiSU -see: - -.BR -or man sisu - -.SH -26.7 AUTHOR - -.BR -Ralph Amissah ralph@amissah.com or ralph.amissah@gmail.com - -.SH -26.8 SEE ALSO - -.BR - sisu(1) - -.BR - sisu_vim(7) - -.BR - sisu(8) - -.SH -27. 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 -28. 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 -28.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 -28.2 CONFIGURATION - -.BR -[expand \ on \ the \ setting \ up \ of \ an \ ssh\-agent \ / \ keychain] - -.SH -29. 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 -30. QUICKSTART \- GETTING STARTED HOWTO -.BR - -.SH -30.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 -30.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 -.BR - 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 -.BR - deb http://ftp.fi.debian.org/debian/ unstable main non\-free contrib -.BR - deb\-src http://ftp.fi.debian.org/debian/ unstable main non\-free contrib -.BR - d -.fi - -.BR -The aptitude commands become: - - -.nf - aptitude update -.BR - 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 -30.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 -30.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, EPUB, 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)[^24] 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 -30.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 -30.2.1 BASIC TEXT, PLAINTEXT, HTML, XML, ODF, EPUB - -.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 -30.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 -30.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 -30.3 GETTING HELP - -.SH -30.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 [^25] - -.BR -* sisu.8 [^26] - -.BR -* man directory [^27] - -.SH -30.3.2 BUILT IN HELP - -.BR -sisu \-\-help - -.BR -sisu \-\-help \-\-env - -.BR -sisu \-\-help \-\-commands - -.BR -sisu \-\-help \-\-markup - -.SH -30.3.3 THE HOME PAGE - -.BR - - -.BR - - -.SH -30.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[^28] 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 -31. EDITOR FILES, SYNTAX HIGHLIGHTING -.BR - -.BR -The directory: - -.BR - \./data/sisu/v2/conf/editor\-syntax\-etc/ - -.BR - /usr/share/sisu/v2/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/v1/conf/editor\-syntax\-etc/emacs\") - -.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 -32. 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 -33. 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, epub, -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 - * epub - -.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, EPUB, 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, epub in 2009 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, EPUB, 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 -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 -.B sisu generated output \- links to html - -.BR - - -.BR -.B help sources lists - -.BR -Alternative sources for this help sources page listed here: - -.BR - man sisu_help_sources - -.BR - - -.SH -34.1 MAN PAGES - -.SH -34.1.1 MAN - -.BR - man sisu - -.BR - man 7 sisu_complete - -.BR - man 7 sisu_pdf - -.BR - man 7 sisu_postgresql - -.BR - man 7 sisu_sqlite - -.BR - man sisu_termsheet - -.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, odf and epub which may be also be accessed via the html pages[^28] - -.SH -34.2.1 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.3 MAN2HTML - -.SH -34.3.1 LOCALLY INSTALLED - -.BR - - -.BR - - -.BR - - -.BR - /usr/share/doc/sisu/v2/html/sisu.1.html - -.BR - /usr/share/doc/sisu/v2/html/sisu_pdf.7.html - -.BR - /usr/share/doc/sisu/v2/html/sisu_postgresql.7.html - -.BR - /usr/share/doc/sisu/v2/html/sisu_sqlite.7.html - -.BR - /usr/share/doc/sisu/v2/html/sisu_webrick.1.html - -.SH -34.3.2 WWW.JUS.UIO.NO/SISU - -.BR - - -.BR - - -.BR - - -.BR - - -.BR - - -.BR - - -.BR - - -.TP -.BI 1. -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 2. -i.e. the html, pdf, epub, 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. - -.BR -.TP -.BI 3. -the different heading levels -.TP -.BI 4. -units of text, primarily paragraphs and headings, also any tables, poems, -code-blocks -.TP -.BI 5. -Specification submitted by Adobe to ISO to become a full open ISO -specification - -.TP -.BI 6. -ISO standard ISO/IEC 26300:2006 - -.BR -.TP -.BI 7. -An open standard format for e-books - -.BR -.TP -.BI *1. -square brackets -.TP -.BI *2. -square brackets -.TP -.BI +1. -square brackets -.TP -.BI 8. - -.TP -.BI 9. - -.TP -.BI 10. -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 11. -files should be prepared using UTF-8 character encoding -.TP -.BI 12. -a footnote or endnote -.TP -.BI 13. -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 14. - -.TP -.BI 15. - -.TP -.BI 16. -Table from the Wealth of Networks by Yochai Benkler - -.TP -.BI 17. -\.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 19. - - - -.TP -.BI 20. - - -.TP -.BI 21. - -.TP -.BI 22. -(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 23. -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 24. -There is nothing to stop MySQL support being added in future. -.TP -.BI 25. - -.TP -.BI 26. - -.TP -.BI 27. - -.TP -.BI 28. -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 29. -named index.html or more extensively through sisu_manifest.html - -.SH SEE ALSO -\fIsisu\fR(1), -.br -\fIsisu\-epub\fR(1), -.br -\fIsisu\-harvest\fR(1), -.br -\fIsisu\-html\fR(1), -.br -\fIsisu\-odf\fR(1), -.br -\fIsisu\-pdf\fR(1), -.br -\fIsisu\-pg\fR(1), -.br -\fIsisu\-sqlite\fR(1), -.br -\fIsisu\-txt\fR(1). -.br -\fIsisu_vim\fR(7) -.br -\fIsisu\fR(8) - -.SH HOMEPAGE -More information about \fBSiSU\fR can be found at <\fIhttp://www.jus.uio.no/sisu/\fR>. - -.SH AUTHOR -\fBSiSU\fR was written by Ralph Amissah <\fIralph@amissah.com\fR>. -- cgit v1.2.3