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/man/sisu_filetypes.1 | 387 +++++++++++++++++++++ 1 file changed, 387 insertions(+) create mode 100644 data/doc/manuals_generated/sisu_manual/man/sisu_filetypes.1 (limited to 'data/doc/manuals_generated/sisu_manual/man/sisu_filetypes.1') diff --git a/data/doc/manuals_generated/sisu_manual/man/sisu_filetypes.1 b/data/doc/manuals_generated/sisu_manual/man/sisu_filetypes.1 new file mode 100644 index 00000000..d556f763 --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/man/sisu_filetypes.1 @@ -0,0 +1,387 @@ +.TH "sisu_filetypes" "1" "2007-09-16" "0.59.0" "SiSU" +.SH +SISU \- FILETYPES \ [0.58], +RALPH AMISSAH +.BR + +.SH +1. SISU FILETYPES +.BR + +.BR +.B SiSU +has plaintext and binary filetypes, and can process either type of document. + +.SH +1.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 +1.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 +1.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 \ [^1] + +.BR + + +.BR + + +.SH +1.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 +1.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 +2. EXPERIMENTAL ALTERNATIVE INPUT REPRESENTATIONS +.BR + +.SH +2.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 +2.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 +2.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 +2.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 +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ + + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- Filetypes \ [0.58] + +.BR +DC Creator: +.I Ralph Amissah + +.BR +DC Rights: +.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL +3 + +.BR +DC Type: +.I information + +.BR +DC Date created: +.I 2002\-08\-28 + +.BR +DC Date issued: +.I 2002\-08\-28 + +.BR +DC Date available: +.I 2002\-08\-28 + +.BR +DC Date modified: +.I 2007\-09\-16 + +.BR +DC Date: +.I 2007\-09\-16 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_filetypes.sst + +.BR +Filetype: +.I SiSU text 0.58 + +.BR +Sourcefile Digest, MD5(sisu_filetypes.sst)= +.I c0fc6ab6516fe919f331fd8517c9f7a6 + +.BR +Skin_Digest: +MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +.I 20fc43cf3eb6590bc3399a1aef65c5a9 + +.BR +.B Generated + +.BR +Document (metaverse) last generated: +.I Sun Sep 23 04:13:44 +0100 2007 + +.BR +Generated by: +.I SiSU +.I 0.59.0 +of 2007w38/0 (2007\-09\-23) + +.BR +Ruby version: +.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux] + +.TP +.BI 1. +.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 +Other versions of this document: +.TP +manifest: +.TP +html: +.TP +pdf: +.TP +pdf: +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_filetypes/sisu_filetypes.1 +.TP +at: +.TP +.TP +* Generated by: SiSU 0.59.0 of 2007w38/0 (2007-09-23) +.TP +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +.TP +* Last Generated on: Sun Sep 23 04:13:50 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu -- cgit v1.2.3