From 50d45c6deb0afd2e4222d2e33a45487a9d1fa676 Mon Sep 17 00:00:00 2001 From: Ralph Amissah Date: Sun, 23 Sep 2007 05:16:21 +0100 Subject: primarily todo with sisu documentation, changelog reproduced below: * start documenting sisu using sisu * sisu markup source files in data/doc/sisu/sisu_markup_samples/sisu_manual/ /usr/share/doc/sisu/sisu_markup_samples/sisu_manual/ * default output [sisu -3] in data/doc/manuals_generated/sisu_manual/ /usr/share/doc/manuals_generated/sisu_manual/ (adds substantially to the size of sisu package!) * help related edits * manpage, work on ability to generate manpages, improved * param, exclude footnote mark count when occurs within code block * plaintext changes made * shared_txt, line wrap visited * file:// link option introduced (in addition to existing https?:// and ftp://) a bit arbitrarily, diff here, [double check changes in sysenv and hub] * minor adjustments * html url match refinement * css added tiny_center * plaintext * endnotes fix * footnote adjustment to make more easily distinguishable from substantive text * flag -a only [flags -A -e -E dropped] controlled by modifiers --unix/msdos --footnote/endnote * defaults, homepage * renamed homepage (instead of index) implications for modifying skins, which need likewise to have any homepage entry renamed * added link to sisu_manual in homepage * css the css for the default homepage is renamed homepage.css (instead of index.css) [consider removing this and relying on html.css] * ruby version < ruby1.9 * place stop on installation and working with for now [ruby String.strip broken in ruby 1.9.0 (2007-09-10 patchlevel 0) [i486-linux], 2007-09-18:38/2] * debian/control restrict use to ruby > 1.8.4 and ruby < 1.9 * debian * debian/control restrict use to ruby > 1.8.4 and ruby < 1.9 * sisu-doc new sub-package for sisu documentation debian/control and sisu-doc.install --- .../sisu_manual/sisu_filetypes/plain.txt | 355 +++++++++++++++++++++ 1 file changed, 355 insertions(+) create mode 100644 data/doc/manuals_generated/sisu_manual/sisu_filetypes/plain.txt (limited to 'data/doc/manuals_generated/sisu_manual/sisu_filetypes/plain.txt') diff --git a/data/doc/manuals_generated/sisu_manual/sisu_filetypes/plain.txt b/data/doc/manuals_generated/sisu_manual/sisu_filetypes/plain.txt new file mode 100644 index 00000000..483adb0b --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/sisu_filetypes/plain.txt @@ -0,0 +1,355 @@ +SISU - FILETYPES [0.58], +RALPH AMISSAH +*************************************** + +1. SISU FILETYPES +----------------- + +*SiSU* has plaintext and binary filetypes, and can process either type of +document. + + +1.1 .SST .SSM .SSI MARKED UP PLAIN TEXT +....................................... + +*SiSU* documents are prepared as plain-text (utf-8) files with *SiSU* markup. +They may make reference to and contain images (for example), which are stored +in the directory beneath them _sisu/image. *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. + + +*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. + + +*SiSU* source markup can be shared with the command: + + + sisu -s [filename] + + +1.1.1 SISU TEXT - REGULAR FILES (.SST) +...................................... + +The most common form of document in *SiSU*, see the section on *SiSU* markup. + + + + + + + + +1.1.2 SISU MASTER FILES (.SSM) +.............................. + +Composite documents which incorporate other *SiSU* documents which may be +either regular *SiSU* text .sst which may be generated independently, or +inserts prepared solely for the purpose of being incorporated into one or more +master documents. + + +The mechanism by which master files incorporate other documents is described as +one of the headings under under *SiSU* markup in the *SiSU* manual. + + +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. + + +Note: a secondary file of the composite document is built prior to processing +with the same prefix and the suffix ._sst [^1] + + +- [1]: .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. + + + + + + + +1.1.3 SISU INSERT FILES (.SSI) +.............................. + +Inserts are documents prepared solely for the purpose of being incorporated +into one or more master documents. They resemble regular *SiSU* text files +except they are ignored by the *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. + + +1.2 SISUPOD, ZIPPED BINARY CONTAINER (SISUPOD.ZIP, .SSP) +........................................................ + +A sisupod is a zipped *SiSU* text file or set of *SiSU* text files and any +associated images that they contain (this will be extended to include sound and +multimedia-files) + + +*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. + + +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 *SiSU* documents. + + +The command to create a sisupod is: + + + sisu -S [filename] + + +Alternatively, make a pod of the contents of a whole directory: + + + sisu -S + + +*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. + + + + + + + + +2. EXPERIMENTAL ALTERNATIVE INPUT REPRESENTATIONS +------------------------------------------------- + +2.1 ALTERNATIVE XML +................... + +*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. + + +*convert from sst to simple xml representations (sax, dom and node):* + + + sisu --to-sax [filename/wildcard] or sisu --to-sxs [filename/wildcard] + + + sisu --to-dom [filename/wildcard] or sisu --to-sxd [filename/wildcard] + + + sisu --to-node [filename/wildcard] or sisu --to-sxn [filename/wildcard] + + +*convert to sst from any sisu xml representation (sax, dom and node):* + + + sisu --from-xml2sst [filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]] + + +or the same: + + + sisu --from-sxml [filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]] + + +2.1.1 XML SAX REPRESENTATION +............................ + +To convert from sst to simple xml (sax) representation: + + + sisu --to-sax [filename/wildcard] or sisu --to-sxs [filename/wildcard] + + +To convert from any sisu xml representation back to sst + + + sisu --from-xml2sst [filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]] + + +or the same: + + + sisu --from-sxml [filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]] + + +2.1.2 XML DOM REPRESENTATION +............................ + +To convert from sst to simple xml (dom) representation: + + + sisu --to-dom [filename/wildcard] or sisu --to-sxd [filename/wildcard] + + +To convert from any sisu xml representation back to sst + + + sisu --from-xml2sst [filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]] + + +or the same: + + + sisu --from-sxml [filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]] + + +2.1.3 XML NODE REPRESENTATION +............................. + +To convert from sst to simple xml (node) representation: + + + sisu --to-node [filename/wildcard] or sisu --to-sxn [filename/wildcard] + + +To convert from any sisu xml representation back to sst + + + sisu --from-xml2sst [filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]] + + +or the same: + + + sisu --from-sxml [filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]] + + +DOCUMENT INFORMATION (METADATA) +******************************* + +METADATA +-------- + +Document Manifest @ + + + +*Dublin Core* (DC) + + +/DC tags included with this document are provided here./ + + +DC Title: _SiSU - Filetypes [0.58]_ + + +DC Creator: _Ralph Amissah_ + + +DC Rights: _Copyright (C) Ralph Amissah 2007, part of SiSU documentation, +License GPL 3_ + + +DC Type: _information_ + + +DC Date created: _2002-08-28_ + + +DC Date issued: _2002-08-28_ + + +DC Date available: _2002-08-28_ + + +DC Date modified: _2007-09-16_ + + +DC Date: _2007-09-16_ + + +*Version Information* + + +Sourcefile: _sisu_filetypes.sst_ + + +Filetype: _SiSU text 0.58_ + + +Sourcefile Digest, MD5(sisu_filetypes.sst)= _c0fc6ab6516fe919f331fd8517c9f7a6_ + + +Skin_Digest: +MD5(/home/ralph/grotto/theatre/dbld/sisu-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +_20fc43cf3eb6590bc3399a1aef65c5a9_ + + +*Generated* + + +Document (metaverse) last generated: _Sun Sep 23 04:11:00 +0100 2007_ + + +Generated by: _SiSU_ _0.59.0_ of 2007w38/0 (2007-09-23) + + +Ruby version: _ ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux]_ + + + +============================================================================== + + title: SiSU - Filetypes [0.58] + + creator: Ralph Amissah + + rights: Copyright (C) Ralph Amissah 2007, part of SiSU documentation, + License GPL 3 + + type: information + + subject: ebook, epublishing, electronic book, electronic publishing, + electronic document, electronic citation, data structure, + citation systems, search + + date.created: 2002-08-28 + + date.issued: 2002-08-28 + + date.available: 2002-08-28 + + date.modified: 2007-09-16 + + date: 2007-09-16 + + + + + +============================================================================== +nil + +Other versions of this document: +manifest: + http://www.jus.uio.no/sisu/sisu_filetypes/sisu_manifest.html +html: + http://www.jus.uio.no/sisu/sisu_filetypes/toc.html +pdf: + http://www.jus.uio.no/sisu/sisu_filetypes/portrait.pdf + http://www.jus.uio.no/sisu/sisu_filetypes/landscape.pdf +plaintext (plain text): + http://www.jus.uio.no/sisu/sisu_filetypes/plain.txt +at: + http://www.jus.uio.no/sisu +* Generated by: SiSU 0.59.0 of 2007w38/0 (2007-09-23) +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +* Last Generated on: Sun Sep 23 04:11:50 +0100 2007 +* SiSU http://www.jus.uio.no/sisu -- cgit v1.2.3