diff options
| author | Ralph Amissah <ralph@amissah.com> | 2008-09-15 21:52:19 -0400 |
|---|---|---|
| committer | Ralph Amissah <ralph@amissah.com> | 2008-09-15 21:52:19 -0400 |
| commit | 87a7cfcd56eed6746b1500c88df3fc3e76a81668 (patch) | |
| tree | 9e653d09f0e8c130273ef5ef3e7be0daf12d6007 /data | |
| parent | dal_idx, and concordance, letter list for navigation (diff) | |
various small fixes
* html segments, name more accurately
* rough description of how book index markup works
* clean out book index from these outputs
* book markup sample, free as in freedom, start doing book index, only letter "A" done so far
* texpdf, url matching, special characters
* # Please enter the commit message for your changes.
Diffstat (limited to 'data')
3 files changed, 1097 insertions, 944 deletions
diff --git a/data/doc/sisu/html/sisu.1.html b/data/doc/sisu/html/sisu.1.html index f7b70fcd..1848611b 100644 --- a/data/doc/sisu/html/sisu.1.html +++ b/data/doc/sisu/html/sisu.1.html @@ -10,13 +10,13 @@ <h2><a name='sect0' href='#toc0'>Name</a></h2> sisu - documents: markup, structuring, publishing in multiple standard -formats, and search +formats, and search <h2><a name='sect1' href='#toc1'>Synopsis</a></h2> sisu [-abcDdFHhIiMmNnopqRrSsTtUuVvwXxYyZz0-9] [filename/wildcard ] sisu [-Ddcv] [instruction] sisu [-CcFLSVvW] SISU - -MANUAL, RALPH AMISSAH -<p> WHAT IS SISU? -<p> 1. INTRODUCTION - WHAT IS SISU? +MANUAL, RALPH AMISSAH +<p> WHAT IS SISU? +<p> 1. INTRODUCTION - WHAT IS SISU? <p> <b>SiSU</b> is a framework for document structuring, publishing (in multiple open standard formats) and search, comprising of: (a) a lightweight document @@ -24,13 +24,13 @@ 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. +system for the citation of text within a document. <p> <b>SiSU</b> is developed under an open source, software libre license (GPL3). Its use case for development is to cope with medium to large document sets with evolving markup related technologies, which should be prepared once, and for which you want multiple output formats that can be updated and a common mechanism for cross-output-format -citation, and search. +citation, and search. <p> <b>SiSU</b> both defines a markup syntax and provides an engine that produces open standards format outputs from documents prepared with <b>SiSU</b> markup. From a single lightly prepared document sisu custom builds @@ -42,7 +42,7 @@ of representation of the document. Significantly <b>SiSU</b> markup is more spar than html and outputs which include html, LaTeX, landscape and portrait pdfs, Open Document Format (ODF), all of which can be added to and updated. <b>SiSU</b> is also able to populate SQL type databases at an object level, which -means that searches can be made with that degree of granularity. +means that searches can be made with that degree of granularity. <p> 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 @@ -59,14 +59,14 @@ 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 works (finalized texts as opposed to works that are frequently changed or updated) for which it provides a fixed -means of reference of content. +means of reference of content. <p> In preparing a <b>SiSU</b> 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. +of output requested. <p> <b>SiSU</b> works with an abstraction of the document based on its structure which is comprised of its structure (or frame)[^3] and the objects[^4] it contains, which enables <b>SiSU</b> to represent the document @@ -80,7 +80,7 @@ pages; and in publishing in different formats, html, landscape and portrait pdf etc. again page numbers are of no use to cite text in a manner that is relevant against the different output types. Dealing with documents at an object level together with object numbering also has implications for -search. +search. <p> One of the challenges of maintaining documents is to keep them in a format that would allow users to use them without depending on a proprietary software popular at the time. Consider the ease of dealing with legacy proprietary @@ -104,38 +104,38 @@ and the archival of documents), and existing output to be updated (html has evolved and the related module has been updated repeatedly over the years, presumably when the World Wide Web Consortium (w3c) finalises html 5 which is currently under development, the html module will again be updated -allowing all existing documents to be regenerated as html 5). +allowing all existing documents to be regenerated as html 5). <p> 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. +like Lucene and Hyperestraier. <p> <b>SiSU</b> also provides other features such as concordance files and document content certificates, and the working against an abstraction of document structure has further possibilities for the research and development of other document representations, the availability of objects is useful for example for topic maps and the commercial law thesaurus by Vikki Rogers and Al Krtizer, together with the flexibility -of <b>SiSU</b> offers great possibilities. +of <b>SiSU</b> offers great possibilities. <p> <b>SiSU</b> is primarily for published works, which can take advantage of the citation system to reliably reference its documents. <b>SiSU</b> 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</b> +the substance of content prepared in <b>SiSU</b> <p> <<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a> -> +> <p> 2. -COMMANDS SUMMARY -<p> 2.1 SYNOPSIS +COMMANDS SUMMARY +<p> 2.1 SYNOPSIS <p> <b>SiSU</b> - Structured information, Serialized -Units - a document publishing system +Units - a document publishing system <p> sisu [ -abcDdFHhIiMmNnopqRrSsTtUuVvwXxYyZz0-9 - ] [ filename/ wildcard ] -<p> sisu [ -Ddcv ] [ instruction ] + ] [ filename/ wildcard ] +<p> sisu [ -Ddcv ] [ instruction ] <p> sisu [ -CcFLSVvW - ] + ] <p> Note: commands should be issued from within the directory that contains -the marked up files, cd to markup directory. -<p> 2.2 DESCRIPTION +the marked up files, cd to markup directory. +<p> 2.2 DESCRIPTION <p> <b>SiSU</b> <b>SiSU</b> is a document publishing system, that from a simple single marked-up document, produces multiple of output formats including: plaintext, html, LaTeX, @@ -143,8 +143,8 @@ pdf, xhtml, XML, info, and SQL (PostgreSQL and SQLite), which share numbered text objects ( structure information. For more see: <<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a> > -<p> 2.3 DOCUMENT PROCESSING COMMAND FLAGS -<p> +<p> 2.3 DOCUMENT PROCESSING COMMAND FLAGS +<p> <dl> <dt><b>-a [filename/wildcard]</b> </dt> @@ -153,12 +153,12 @@ 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 (Options include: --endnotes for endnotes --footnotes for footnotes at the end of each paragraph --unix for unix linefeed -(default) --msdos for msdos linefeed) +(default) --msdos for msdos linefeed) <p> </dd> <dt><b>-b [filename/wildcard]</b> </dt> <dd>produces xhtml/XML -output for browser viewing (sax parsing). +output for browser viewing (sax parsing). <p> </dd> <dt><b>-C [--init-site]</b> </dt> @@ -168,7 +168,7 @@ 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. +is used. <p> </dd> <dt><b>-CC</b> </dt> @@ -177,7 +177,7 @@ 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. +files such as css and dtd files are updated if -CC is used. <p> </dd> <dt><b>-c [filename/wildcard]</b> @@ -185,14 +185,14 @@ files such as css and dtd files are updated if -CC is used. <dd>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). +screen output will be without colour). <p> </dd> <dt><b>-D [instruction] [filename]</b> </dt> <dd>database postgresql ( --pgsql may be used instead) possible instructions, include: --createdb; --create; --dropall; --import [filename]; --update [filename]; --remove -[filename]; see database section below. +[filename]; see database section below. <p> </dd> <dt><b>-d [--db-[database type (sqlite|pg)]] @@ -201,7 +201,7 @@ postgresql ( --pgsql may be used instead) possible instructions, include: --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. +below. <p> </dd> <dt><b>-F [--webserv=webrick]</b> </dt> @@ -217,13 +217,13 @@ 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 -<p>on setting up hyperestraier for sisu +<p>on setting up hyperestraier for sisu <p> </dd> <dt><b>-H [filename/wildcard]</b> </dt> <dd>produces html without link suffixes (.html .pdf etc.) ( an appropriately configured web -server. [behaviour switched after 0.35 see -h]. +server. [behaviour switched after 0.35 see -h]. <p> </dd> <dt><b>-h [filename/wildcard]</b> </dt> @@ -231,34 +231,34 @@ server. [behaviour switched after 0.35 see -h]. html (with hardlinks i.e. with name suffixes in links/local urls). html, with internal document links that include the document suffix, i.e. whether it is .html or .pdf (required for browsing directly off a file system, and works -with most web servers). [behaviour switched after 0.35 see -H]. +with most web servers). [behaviour switched after 0.35 see -H]. <p> </dd> <dt><b>-I [filename/wildcard]</b> </dt> -<dd>produces texinfo and info file, (view with pinfo). +<dd>produces texinfo and info file, (view with pinfo). <p> </dd> <dt><b>-i [filename/wildcard]</b> </dt> -<dd>produces man page of file, not suitable for all outputs. +<dd>produces man page of file, not suitable for all outputs. <p> </dd> <dt><b>-L</b> </dt> <dd>prints license -information. +information. <p> </dd> <dt><b>-M [filename/wildcard/url]</b> </dt> <dd>maintenance mode files created for -processing preserved and their locations indicated. (also see -V) +processing preserved and their locations indicated. (also see -V) <p> </dd> <dt><b>-m [filename/wildcard/url]</b> </dt> <dd>assumed for most other flags, creates new meta-markup file, (the metaverse ) that is used in all subsequent processing of other output. This step is -assumed for most processing flags. To skip it see -n +assumed for most processing flags. To skip it see -n <p> </dd> <dt><b>-N [filename/wildcard/url]</b> @@ -266,18 +266,18 @@ assumed for most processing flags. To skip it see -n <dd>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. +that produced it) (digest.txt). -NV for verbose digest output to screen. <p> </dd> <dt><b>-n [filename/wildcard/url]</b> </dt> <dd>skip meta-markup (building of -m which is otherwise -assumed by most processing flags. +assumed by most processing flags. <p> </dd> <dt><b>-o [filename/wildcard/url]</b> </dt> <dd>output basic -document in opendocument file format (opendocument.odt). +document in opendocument file format (opendocument.odt). <p> </dd> <dt><b>-p [filename/wildcard]</b> @@ -285,12 +285,12 @@ document in opendocument file format (opendocument.odt). <dd>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). +’legal’ and book sizes ’A5’ and ’B5’ (system defaults to A4). <p> </dd> <dt><b>-q [filename/wildcard]</b> </dt> -<dd>quiet less output to screen. +<dd>quiet less output to screen. <p> </dd> <dt><b>-R [filename/wildcard]</b> </dt> @@ -299,7 +299,7 @@ to remote host using rsync. This requires that sisurc.yml has been provided with information on hostname and username, and that you have your 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 +used together with other flags, it is not). Also see -r <p> </dd> <dt><b>-r [filename/wildcard]</b> @@ -307,7 +307,7 @@ used together with other flags, it is not). Also see -r <dd>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 -<p>have your +<p>have your <p> </dd> <dt><b>-S</b> </dt> @@ -316,7 +316,7 @@ 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<br> - option is tested only with zsh). + option is tested only with zsh). <p> </dd> <dt><b>-S [filename/wildcard]</b> </dt> @@ -340,12 +340,12 @@ the individual files for sending). See the -S option without [filename/wildcard] <p> </dd> <dt><b>-s [filename/wildcard]</b> </dt> -<dd>copies sisu markup file to output directory. +<dd>copies sisu markup file to output directory. <p> </dd> <dt><b>-t [filename/wildcard (*.termsheet.rb)]</b> </dt> -<dd>standard form document builder, preprocessing feature +<dd>standard form document builder, preprocessing feature <p> </dd> @@ -357,35 +357,35 @@ 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 -<p>can be switched to file system paths in sisurc.yml +<p>can be switched to file system paths in sisurc.yml <p> </dd> <dt><b>-u [filename/wildcard]</b> </dt> <dd>provides url mapping of output files for the flags requested for processing, -<p>also see -U +<p>also see -U <p> </dd> <dt><b>-V</b> </dt> <dd>on its own, provides <b>SiSU</b> version and environment information -(sisu --help env) +(sisu --help env) <p> </dd> <dt><b>-V [filename/wildcard]</b> </dt> <dd>even more verbose than the -v flag. -(also see -M) +(also see -M) <p> </dd> <dt><b>-v</b> </dt> -<dd>on its own, provides <b>SiSU</b> version information +<dd>on its own, provides <b>SiSU</b> version information <p> </dd> <dt><b>-v [filename/wildcard]</b> </dt> <dd>provides verbose output of what is being built, where it is being built (and error messages if any), as with -u flag provides a url mapping of files -created for each of the processing flag requests. See also -V +created for each of the processing flag requests. See also -V <p> </dd> <dt><b>-W</b> </dt> @@ -393,7 +393,7 @@ created for each of the processing flag requests. See also -V 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 and search -H; also, note -F webrick ]. + using the -h option rather than and search -H; also, note -F webrick ]. <p> </dd> <dt><b>-w @@ -401,24 +401,24 @@ set to 8081 and can be changed in the resource configuration files. [tip: <dd>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) +sisurc.yml) <p> </dd> <dt><b>-X [filename/wildcard]</b> </dt> <dd>produces XML output with deep document -structure, in the nature of dom. +structure, in the nature of dom. <p> </dd> <dt><b>-x [filename/wildcard]</b> </dt> <dd>produces XML output -shallow structure (sax parsing). +shallow structure (sax parsing). <p> </dd> <dt><b>-Y [filename/wildcard]</b> </dt> <dd>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]) +[g,y,m announcement this week]) <p> </dd> <dt><b>-y [filename/wildcard]</b> </dt> @@ -438,41 +438,41 @@ combination of -[mMvVq]), will remove the related document output directory. <dt><b>-z [filename/wildcard]</b> </dt> <dd>produces php (zend) [this feature is disabled for - the time being] + the time being] <p> </dd> </dl> -3. COMMAND LINE MODIFIERS -<p> +3. COMMAND LINE MODIFIERS +<p> <dl> <dt><b>--no-ocn</b> </dt> <dd>[with -h -H or -p] switches off object citation numbering. Produce output without identifying numbers -in margins of html or LaTeX/pdf output. +in margins of html or LaTeX/pdf output. <p> </dd> <dt><b>--no-annotate</b> </dt> <dd>strips output text of -editor endnotes[^*1] denoted by asterisk or dagger/plus sign +editor endnotes[^*1] denoted by asterisk or dagger/plus sign <p> </dd> <dt><b>--no-asterisk</b> </dt> -<dd>strips output text of editor endnotes[^*2] denoted by asterisk sign +<dd>strips output text of editor endnotes[^*2] denoted by asterisk sign <p> </dd> <dt><b>--no-dagger</b> </dt> -<dd>strips output text of editor endnotes[^+1] denoted by dagger/plus sign +<dd>strips output text of editor endnotes[^+1] denoted by dagger/plus sign <p> </dd> </dl> -4. DATABASE COMMANDS -<p> dbi - database interface +4. DATABASE COMMANDS +<p> dbi - database interface <p> -D or --pgsql set for postgresql -d or --sqlite default set for sqlite -d is modifiable with --db=[database type - (pgsql or sqlite)] -<p> + (pgsql or sqlite)] +<p> <dl> <dt><b>-Dv --createall</b> </dt> @@ -483,13 +483,13 @@ created manually and given the same name as working directory, as requested) -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. + name (without path)]. Please use only alphanumerics and underscores. <p> </dd> <dt><b>-Dv --import</b> </dt> <dd>[filename/wildcard] imports data specified to postgresql db (rb.dbi) -[ -dv --import sqlite equivalent] +[ -dv --import sqlite equivalent] <p> </dd> <dt><b>-Dv --update</b> </dt> @@ -500,18 +500,18 @@ specified data to postgresql db (rb.dbi) [ -dv --update sqlite <dt><b>-D --remove</b> </dt> <dd>[filename/wildcard] removes specified data to postgresql db (rb.dbi) -[ -d --remove sqlite equivalent] +[ -d --remove sqlite equivalent] <p> </dd> <dt><b>-D --dropall</b> </dt> <dd>kills data --dropall sqlite equivalent] -<p> The v in e.g. -Dv is for verbose output. +<p> The v in e.g. -Dv is for verbose output. <p> </dd> </dl> 5. SHORTCUTS, SHORTHAND FOR MULTIPLE -FLAGS -<p> +FLAGS +<p> <dl> <dt><b>--update [filename/wildcard]</b> </dt> @@ -520,30 +520,30 @@ 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. +and just want to do the same again. <p> </dd> <dt><b>-0 to -5 [filename or wildcard]</b> </dt> <dd>Default shorthand mappings (note that the defaults can be changed/configured in -the sisurc.yml file): +the sisurc.yml file): <p> </dd> <dt><b>-0</b> </dt> <dd>-mNhwpAobxXyYv [this is the default action run when - no i.e. on ’sisu [filename]’] + no i.e. on ’sisu [filename]’] <p> </dd> <dt><b>-1</b> </dt> -<dd>-mNHwpy +<dd>-mNHwpy <p> </dd> <dt><b>-2</b> </dt> -<dd>-mNHwpaoy +<dd>-mNHwpaoy <p> </dd> <dt><b>-3</b> </dt> -<dd>-mNhwpAobxXyY +<dd>-mNhwpAobxXyY <p> </dd> <dt><b>-4</b> </dt> @@ -551,164 +551,164 @@ the sisurc.yml file): <p>- <p>- -<p>import +<p>import <p> </dd> <dt><b>-5</b> </dt> -<dd>-mNhwpAobxXDyY --update +<dd>-mNhwpAobxXDyY --update <p> add -v for verbose mode and -c for color, -e.g. sisu -2vc [filename or +e.g. sisu -2vc [filename or <p> consider -u for appended url info or -v for verbose -<p>output +<p>output <p> </dd> </dl> -5.1 COMMAND LINE WITH FLAGS - BATCH PROCESSING +5.1 COMMAND LINE WITH FLAGS - BATCH PROCESSING <p> In the data directory -run sisu -mh filename or wildcard eg. cisg.sst documents. +run sisu -mh filename or wildcard eg. cisg.sst documents. <p> 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. +as does any sisu command that is not recognised. Enter to escape. <p> 6. HELP - -<p> 6.1 SISU MANUAL + +<p> 6.1 SISU MANUAL <p> The most up to date information on sisu should be contained -in the sisu_manual, available at: +in the sisu_manual, available at: <p> <<a href='http://sisudoc.org/sisu/sisu_manual/'>http://sisudoc.org/sisu/sisu_manual/</a> ><br> - + <p> The manual can be generated from source, found respectively, either -within the <b>SiSU</b> tarball or installed locally at: +within the <b>SiSU</b> tarball or installed locally at: <p> ./data/doc/sisu/sisu_markup_samples/sisu_manual/<br> - + <p> /usr/share/doc/sisu/sisu_markup_samples/sisu_manual/<br> - -<p> move to the respective directory and type e.g.: + +<p> move to the respective directory and type e.g.: <p> sisu sisu_manual.ssm<br> - -<p> 6.2 SISU MAN PAGES + +<p> 6.2 SISU MAN PAGES <p> If <b>SiSU</b> is installed on your system usual man commands -should be available, try: +should be available, try: <p> man sisu<br> - + <p> man sisu_markup<br> - + <p> man sisu_commands<br> - + <p> Most <b>SiSU</b> 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</b> tarball at: +within the <b>SiSU</b> tarball at: <p> ./data/doc/sisu/sisu_manual/<br> - -<p> Once installed, directory equivalent to: + +<p> Once installed, directory equivalent to: <p> /usr/share/doc/sisu/sisu_manual/<br> - -<p> Available man pages are converted back to html using man2html: + +<p> Available man pages are converted back to html using man2html: <p> /usr/share/doc/sisu/html/<br> - + <p> ./data/doc/sisu/html/<br> - -<p> An online version of the sisu man page is available here: + +<p> An online version of the sisu man page is available here: <p> * various sisu man pages <<a href='http://www.jus.uio.no/sisu/man/'>http://www.jus.uio.no/sisu/man/</a> -> [^7] +> [^7] <p> * sisu.1 <<a href='http://www.jus.uio.no/sisu/man/sisu.1.html'>http://www.jus.uio.no/sisu/man/sisu.1.html</a> > -[^8] -<p> 6.3 SISU BUILT-IN INTERACTIVE HELP +[^8] +<p> 6.3 SISU BUILT-IN INTERACTIVE HELP <p> This is particularly useful for -getting the current sisu setup/environment information: +getting the current sisu setup/environment information: <p> sisu --help<br> - + <p> sisu --help [subject]<br> - + <p> sisu --help commands<br> - + <p> sisu --help markup<br> - + <p> sisu --help env [for feedback on the way your system is <br> setup with regard to sisu]<br> - + <p> sisu -V [environment information, same as above command]<br> - + <p> sisu (on its own provides version and some help information)<br> - + <p> Apart from real-time information on your current configuration the <b>SiSU</b> manual and man pages are likely to contain more up-to-date information than -the sisu interactive help (for example on commands and markup). +the sisu interactive help (for example on commands and markup). <p> 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. -<p> 6.4 HELP SOURCES +Enter to escape. +<p> 6.4 HELP SOURCES <p> For lists of alternative help sources, -see: -<p> <b>man page</b> +see: +<p> <b>man page</b> <p> man sisu_help_sources<br> - -<p> <b>man2html</b> + +<p> <b>man2html</b> <p> /usr/share/doc/sisu/sisu_manual/sisu_help_sources/index.html<br> - -<p> <b>sisu generated html</b> + +<p> <b>sisu generated html</b> <p> /usr/share/doc/sisu/html/sisu_help_sources/index.html<br> - + <p> <<a href='http://sisudoc.org/sisu/sisu_help_sources/index.html'>http://sisudoc.org/sisu/sisu_help_sources/index.html</a> ><br> - -<p> 7. INTRODUCTION TO SISU MARKUP[^9] -<p> 7.1 SUMMARY + +<p> 7. INTRODUCTION TO SISU MARKUP[^9] +<p> 7.1 SUMMARY <p> <b>SiSU</b> source documents -are plaintext (UTF-8)[^10] files +are plaintext (UTF-8)[^10] files <p> All paragraphs are separated by an empty -line. -<p> Markup is comprised of: +line. +<p> Markup is comprised of: <p> * 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) +from a particular level down) <p> * 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: +structure. Markup of substantive text includes: <p> * heading levels defines document structure<br> - + <p> * text basic attributes, italics, bold etc.<br> - + <p> * grouped text (objects), which are to be treated differently, such as code<br> blocks or poems.<br> - + <p> * footnotes/endnotes<br> - + <p> * linked text and images<br> - + <p> * paragraph actions, such as indent, bulleted, numbered-lists, etc.<br> - + <p> Some interactive help on markup is available, by typing sisu and selecting -<p>markup or sisu --help markup -<p> To check the markup in a file: +<p>markup or sisu --help markup +<p> To check the markup in a file: <p> sisu --identify [filename].sst<br> - -<p> For brief descriptive summary of markup history + +<p> For brief descriptive summary of markup history <p> sisu --query-history<br> - -<p> or if for a particular version: + +<p> or if for a particular version: <p> sisu --query-0.38<br> - -<p> 7.2 MARKUP EXAMPLES -<p> 7.2.1 ONLINE + +<p> 7.2 MARKUP EXAMPLES +<p> 7.2.1 ONLINE <p> Online markup examples are available together with the respective outputs produced from <<a href='http://www.jus.uio.no/sisu/SiSU/examples.html'>http://www.jus.uio.no/sisu/SiSU/examples.html</a> > or from <<a href='http://www.jus.uio.no/sisu/sisu_examples/'>http://www.jus.uio.no/sisu/sisu_examples/</a> -> +> <p> There is of course this document, which provides a cursory overview of sisu markup and the respective output produced: <<a href='http://www.jus.uio.no/sisu/sisu_markup/'>http://www.jus.uio.no/sisu/sisu_markup/</a> -> +> <p> Some example marked up files are available as html with syntax highlighting for viewing: <<a href='http://www.jus.uio.no/sisu/sample/syntax'>http://www.jus.uio.no/sisu/sample/syntax</a> > @@ -716,28 +716,28 @@ up files are available as html with syntax highlighting for viewing: <<a href <p> an alternative presentation of markup syntax: <<a href='http://www.jus.uio.no/sisu/sample/on_markup.txt'>http://www.jus.uio.no/sisu/sample/on_markup.txt</a> > -<p> 7.2.2 INSTALLED +<p> 7.2.2 INSTALLED <p> With <b>SiSU</b> 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: -<p>/usr/share/doc/sisu/sisu_markup_samples/non-free -<p> 8. MARKUP OF HEADERS +<p>/usr/share/doc/sisu/sisu_markup_samples/non-free +<p> 8. MARKUP OF HEADERS <p> Headers consist of semantic meta-data about a document, which can be used by any output module of the program; and may in addition include extra -processing instructions. +processing instructions. <p> 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: -<p> +in a line of text) followed by a space and the comment: +<p> <p> <br> <pre> % this would be a comment </pre> -<p> 8.1 SAMPLE HEADER +<p> 8.1 SAMPLE HEADER <p> This current document has a header similar to this -one (without the comments): -<p> +one (without the comments): +<p> <p> <br> <pre> % SiSU 0.57 @title: SiSU @@ -775,50 +775,50 @@ documents that request them, all documents in a directory, or be site-wide. { SiSU Download }http://www.jus.uio.no/sisu/SiSU/download.html { SiSU Changelog }http://www.jus.uio.no/sisu/SiSU/changelog.html </pre> -<p> 8.2 AVAILABLE HEADERS +<p> 8.2 AVAILABLE HEADERS <p> 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 -<p>Dublin Core meta tags are available +<p>Dublin Core meta tags are available <p> <b>@indentifier:</b> information or instructions -<p> where the information +<p> where the information <p> 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. +is used to describe document structure, and can be useful to know. <p> This -<p>is a sample header +<p>is a sample header <p> <b>% SiSU 0.38</b> [declared file-type identifier with markup - version] -<p> + version] +<p> <p> <b>@title:</b> [title text] This is the title of the document and used as such, this header is the only one that is<br> - <i>mandatory</i> -<p> <b>@subtitle:</b> The Subtitle if any + <i>mandatory</i> +<p> <b>@subtitle:</b> The Subtitle if any <p> <b>@creator:</b> [or @author:] Name -<p>of Author -<p> <b>@subject:</b> (whatever your subject) -<p> <b>@description:</b> +<p>of Author +<p> <b>@subject:</b> (whatever your subject) +<p> <b>@description:</b> <p> <b>@publisher:</b> -<p> <b>@contributor:</b> -<p> <b>@translator:</b> [or @translated_by:] +<p> <b>@contributor:</b> +<p> <b>@translator:</b> [or @translated_by:] <p> <b>@illustrator:</b> [or - @illustrated_by:] -<p> <b>@prepared_by:</b> [or @digitized_by:] + @illustrated_by:] +<p> <b>@prepared_by:</b> [or @digitized_by:] <p> <b>@date: 2000-08-27</b> -[ also @date.created: @date.issued: @date.available: @date.valid: ] -<p> +[ also @date.created: @date.issued: @date.available: @date.valid: ] +<p> <p> <b>@type: -<p>article</b> -<p> <b>@format:</b> -<p> <b>@identifier:</b> -<p> <b>@source:</b> +<p>article</b> +<p> <b>@format:</b> +<p> <b>@identifier:</b> +<p> <b>@source:</b> <p> <b>@language:</b> [or @language.document:] [country code for language if available, or language, English, en is the default setting] (en - English, fr - French, de - German, it - Italian, es @@ -826,50 +826,50 @@ used as such, this header is the only one that is<br> is - Icelandic, nl - Dutch, et - Estonian, hu - Hungarian, pl - Polish, ro - Romanian, ru - Russian, el - Greek, uk - Ukranian, tr - Turkish, sk - Slovak, sl - Slovenian, hr - Croatian, cs - Czech, bg - Bul garian ) [however, encodings - are not available for all of the languages listed.] + are not available for all of the languages listed.] <p> [@language.original: - original language in which the work was published] + original language in which the work was published] <p> <b>@papersize:</b> (A4|US_letter|book_B5|book_A5|US_legal) -<p> <b>@relation:</b> -<p> <b>@coverage:</b> +<p> <b>@relation:</b> +<p> <b>@coverage:</b> <p> <b>@rights:</b> Copyright (c) Name of Right Holder, all rights reserved, or as granted: public domain, copyleft, creative commons -variant, etc. -<p> <b>@owner:</b> +variant, etc. +<p> <b>@owner:</b> <p> <b>@keywords:</b> text document generation processing management latex pdf structured xml citation [your keywords here, used - for example by rss feeds, + for example by rss feeds, <p> <b>@abstract:</b> [paper abstract, placed after table - of contents] -<p> <b>@comment:</b> [...] + of contents] +<p> <b>@comment:</b> [...] <p> <b>@catalogue:</b> loc=[Library of Congress classification]; dewey=[Dewey rss feeds, isbn=[ISBN]; pg=[Project Gutenberg text number] -<p> <b>@classify_loc:</b> [Library of Congress classification] +<p> <b>@classify_loc:</b> [Library of Congress classification] <p> <b>@classify_dewey:</b> -[Dewey classification] -<p> <b>@classify_isbn:</b> [ISBN] +[Dewey classification] +<p> <b>@classify_isbn:</b> [ISBN] <p> <b>@classify_pg:</b> [Project - Gutenberg text number] + Gutenberg text number] <p> <b>@prefix:</b> [prefix is placed just after table of - contents] + contents] <p> <b>@prefix_a:</b> [prefix is placed just before table of contents - - not -<p> <b>@prefix_b:</b> + - not +<p> <b>@prefix_b:</b> <p> <b>@rcs:</b> $Id: sisu_markup.sst,v 1.2 2007/09/08 17:12:47 ralph Exp $ [used by rcs or cvs to embed version (revision control) information into document, rcs or cvs can usefully provide a history of updates to - a document ] + a document ] <p> <b>@structure:</b> PART; CHAPTER; SECTION; ARTICLE; none; none; optional, document structure can be defined by words to match or regular expression (the regular expression is assumed to start at the beginning of a line of text i.e. ^) default markers :A~ to :C~ and 1~ to 6~ can be used within text instead, without this header tag, and may be used to supplement the instructions provided in this header tag if provided (@structure: is -a synonym for @toc:) +a synonym for @toc:) <p> <b>@level:</b> newpage=3; breakpage=4 [paragraph level, - used by latex to breakpages, the page is optional eg. in newpage] + used by latex to breakpages, the page is optional eg. in newpage] <p> <b>@markup:</b> information on the markup used, e.g. new=1,2,3; break=4; num_top=4 [or is newpage=1,2,3; breakpage=4; num_top=4] newpage and breakpage, heading level, @@ -883,17 +883,17 @@ page for both single and double column texts. num_top=4 [auto-number docum is provided within document, without the repetition of a number in a header.] [In 0.38 notation, you would map to the equivalent levels, the examples provided would map to the following new=A,B,C; break=1; num_top=1 [or newpage=A,B,C; -breakpage=1; num_top=1] see headings] +breakpage=1; num_top=1] see headings] <p> <b>@bold:</b> [regular expression of words/phrases - to be made bold] + to be made bold] <p> <b>@italics:</b> [regular expression of words/phrases to italicise] <p> <b>@vocabulary:</b> name of taxonomy/vocabulary/wordlist to use against document <p> <b>@skin:</b> skin_doc_[name_of_desired_document_skin] skins change default settings related to the appearance of documents generated, such as the -urls of the home site, and the icon/logo for the document or site. -<p> +urls of the home site, and the icon/logo for the document or site. +<p> <dl> <dt><b>@man: @@ -903,56 +903,56 @@ formats, and search; synopsis=sisu [-abcDdFHhIiMmNnopqRrSsTtUuVvwXxYyZz0-9] [filename/wildcard ] sisu [-Ddcv] [instruction] sisu [-CcFLSVvW] the man page category number (default 1) and special tags used in preparing man -<p>page headings +<p>page headings <p> <b>@links:</b> { <b>SiSU</b> }<a href='http://www.jus.uio.no/sisu/;'>http://www.jus.uio.no/sisu/;</a> { FSF }<a href='http://www.fsf.org'>http://www.fsf.org</a> <p> <b>@promo:</b> sisu, ruby, search_libre_docs, open_society [places content in right pane in html, makes use of commented out sample in document and promo.yml, - commented out sample in document + commented out sample in document <p> </dd> </dl> -9. MARKUP OF SUBSTANTIVE TEXT +9. MARKUP OF SUBSTANTIVE TEXT <p> 9.1 HEADING -<p>LEVELS +<p>LEVELS <p> 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) +into another) <p> <b>:A~ [heading text]</b> Top level heading [this usually has similar content to the ] NOTE: the heading levels described here are in -0.38 notation, see heading +0.38 notation, see heading <p> <b>:B~ [heading text]</b> Second level heading [this - is a heading level divider] + is a heading level divider] <p> <b>:C~ [heading text]</b> Third level heading [this - is a heading level divider] + is a heading level divider] <p> <b>1~ [heading text]</b> 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 -<p>form 1~my_filename_for_this_segment +<p>form 1~my_filename_for_this_segment <p> <b>2~ [heading text]</b> 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. -<p> +that would normally be marked 1.1 or 1.2 or 1.3 or 2.1 etc. in a document. +<p> <b>3~ [heading text]</b> 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 -<p> +<p> <p> <br> <pre> 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) </pre> -<p> 9.2 FONT ATTRIBUTES -<p> <b>markup example:</b> -<p> +<p> 9.2 FONT ATTRIBUTES +<p> <b>markup example:</b> +<p> <p> <br> <pre> normal text !{emphasis}! *{bold text}* _{underscore}_ /{italics}/ normal text @@ -960,192 +960,192 @@ html segments are made) *{bold text}* _{underscore}_ /{italics}/ - + ^{superscript}^ ,{subscript}, +{inserted text}+ -{strikethrough}- </pre> -<p> <b>resulting output:</b> +<p> <b>resulting output:</b> <p> normal text <b>emphasis</b> <b>bold text</b> <i>underscore</i> <i>italics</i> <cite>citation</cite> ^superscript^ [subscript] <ins>inserted text</ins> <del>strikethrough</del> -<p> normal text -<p> -<p> <b>bold text</b> -<p> <i>underscore</i> -<p> <i>italics</i> -<p> <cite>citation</cite> +<p> normal text +<p> +<p> <b>bold text</b> +<p> <i>underscore</i> +<p> <i>italics</i> +<p> <cite>citation</cite> <p> - ^superscript^ -<p> [subscript] -<p> <ins>inserted text</ins> + ^superscript^ +<p> [subscript] +<p> <ins>inserted text</ins> <p> <del>strikethrough</del> -<p> 9.3 INDENTATION AND BULLETS -<p> <b>markup example:</b> -<p> +<p> 9.3 INDENTATION AND BULLETS +<p> <b>markup example:</b> +<p> <p> <br> <pre> ordinary paragraph _1 indent paragraph one step _2 indent paragraph two steps _9 indent paragraph nine steps </pre> -<p> -<p> <b>resulting output:</b> -<p> ordinary paragraph +<p> +<p> <b>resulting output:</b> +<p> ordinary paragraph <p> indent paragraph one step<br> - + <p> indent paragraph two steps<br> - + <p> indent paragraph nine steps<br> - -<p> <b>markup example:</b> -<p> + +<p> <b>markup example:</b> +<p> <p> <br> <pre> _* bullet text _1* bullet text, first indent _2* bullet text, two step indent </pre> -<p> <b>resulting output:</b> -<p> * bullet text +<p> <b>resulting output:</b> +<p> * bullet text <p> * bullet text, first indent<br> - + <p> * bullet text, two step indent<br> - + <p> Numbered List (not to be confused with headings/titles, (document structure)) -<p> <b>markup example:</b> -<p> +<p> <b>markup example:</b> +<p> <p> <br> <pre> # numbered list numbered list 1., 2., 3, etc. _# numbered list numbered list indented a., b., c., d., etc. </pre> -<p> 9.4 FOOTNOTES / ENDNOTES +<p> 9.4 FOOTNOTES / ENDNOTES <p> Footnotes and endnotes not distinguished in markup. They are automatically numbered. Depending on the output file format (html, odf, pdf etc.), the document output selected will have either footnotes -or endnotes. -<p> <b>markup example:</b> -<p> +or endnotes. +<p> <b>markup example:</b> +<p> <p> <br> <pre> ~{ a footnote or endnote }~ </pre> -<p> <b>resulting output:</b> -<p> [^11] -<p> <b>markup example:</b> -<p> +<p> <b>resulting output:</b> +<p> [^11] +<p> <b>markup example:</b> +<p> <p> <br> <pre> normal text~{ self contained endnote marker & endnote in one }~ continues </pre> -<p> <b>resulting output:</b> -<p> normal text[^12] continues -<p> <b>markup example:</b> -<p> +<p> <b>resulting output:</b> +<p> normal text[^12] continues +<p> <b>markup example:</b> +<p> <p> <br> <pre> normal text ~{* unnumbered asterisk footnote/endnote, insert multiple asterisks if required }~ continues normal text ~{** another unnumbered asterisk footnote/endnote }~ continues </pre> -<p> <b>resulting output:</b> -<p> normal text [^*] continues +<p> <b>resulting output:</b> +<p> normal text [^*] continues <p> normal text [^**] continues -<p> -<p> <b>markup example:</b> -<p> +<p> +<p> <b>markup example:</b> +<p> <p> <br> <pre> normal text ~[* editors notes, numbered asterisk footnote/endnote series ]~ continues normal text ~[+ editors notes, numbered asterisk footnote/endnote series ]~ continues </pre> -<p> <b>resulting output:</b> -<p> normal text [^*3] continues +<p> <b>resulting output:</b> +<p> normal text [^*3] continues <p> normal text [^+2] continues -<p> -<p> <b>Alternative endnote pair notation for footnotes/endnotes:</b> -<p> +<p> +<p> <b>Alternative endnote pair notation for footnotes/endnotes:</b> +<p> <p> <br> <pre> % note the endnote marker normal text~^ continues ^~ endnote text following the paragraph in which the marker occurs </pre> -<p> the standard and pair notation cannot be mixed in the same document +<p> the standard and pair notation cannot be mixed in the same document <p> -<p>9.5 LINKS -<p> 9.5.1 NAKED URLS WITHIN TEXT, DEALING WITH URLS +<p>9.5 LINKS +<p> 9.5.1 NAKED URLS WITHIN TEXT, DEALING WITH URLS <p> urls are found within text and marked up automatically. A url within text is automatically hyperlinked to itself and by default decorated with angled braces, unless they are contained within a code block (in which case they are passed as normal text), or escaped by a preceding underscore (in which case the decoration -is omitted). -<p> <b>markup example:</b> -<p> +is omitted). +<p> <b>markup example:</b> +<p> <p> <br> <pre> normal text http://www.jus.uio.no/sisu continues </pre> -<p> <b>resulting output:</b> +<p> <b>resulting output:</b> <p> normal text <<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a> -> continues +> continues <p> An -<p>escaped url without decoration -<p> <b>markup example:</b> -<p> +<p>escaped url without decoration +<p> <b>markup example:</b> +<p> <p> <br> <pre> normal text http://www.jus.uio.no/sisu continues deb http://www.jus.uio.no/sisu/archive unstable main non-free </pre> -<p> <b>resulting output:</b> +<p> <b>resulting output:</b> <p> normal text <a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a> - continues + continues <p> deb <p><a href='http://www.jus.uio.no/sisu/archive'>http://www.jus.uio.no/sisu/archive</a> - unstable main non-free + unstable main non-free <p> where a code block is used there is neither decoration nor hyperlinking, code blocks are discussed -<p>later in this document -<p> <b>resulting output:</b> -<p> +<p>later in this document +<p> <b>resulting output:</b> +<p> <p> <br> <pre> 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 </pre> -<p> To link text or an image to a url the markup is as follows +<p> To link text or an image to a url the markup is as follows <p> <b>markup example:</b> -<p> +<p> <p> <br> <pre> about { SiSU }http://url.org markup </pre> -<p> 9.5.2 LINKING TEXT -<p> <b>resulting output:</b> +<p> 9.5.2 LINKING TEXT +<p> <b>resulting output:</b> <p> about SiSU <<a href='http://www.jus.uio.no/sisu/'>http://www.jus.uio.no/sisu/</a> > -<p>markup +<p>markup <p> A shortcut notation is available so the url link may also be provided -<p>automatically as a footnote -<p> <b>markup example:</b> -<p> +<p>automatically as a footnote +<p> <b>markup example:</b> +<p> <p> <br> <pre> about {~^ SiSU }http://url.org markup </pre> -<p> <b>resulting output:</b> +<p> <b>resulting output:</b> <p> about SiSU <<a href='http://www.jus.uio.no/sisu/'>http://www.jus.uio.no/sisu/</a> -> [^13] markup +> [^13] markup <p> -<p>9.5.3 LINKING IMAGES -<p> <b>markup example:</b> -<p> +<p>9.5.3 LINKING IMAGES +<p> <b>markup example:</b> +<p> <p> <br> <pre> [ tux.png ] % various url linked images @@ -1153,37 +1153,37 @@ is used there is neither decoration nor hyperlinking, code blocks are discussed [ GnuDebianLinuxRubyBetterWay.png ] {~^ ruby_logo.png </pre> -<p> <b>resulting output:</b> -<p> [ tux.png ] -<p> tux.png 64x80 +<p> <b>resulting output:</b> +<p> [ tux.png ] +<p> tux.png 64x80 <p> [ ruby_logo (png missing) - ] [^14] -<p> GnuDebianLinuxRubyBetterWay.png 100x101 and Ruby + ] [^14] +<p> GnuDebianLinuxRubyBetterWay.png 100x101 and Ruby <p> <b>linked url footnote -<p>shortcut</b> -<p> +<p>shortcut</b> +<p> <p> <br> <pre> {~^ [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 </pre> -<p> +<p> <p> <br> <pre> text marker *~name </pre> <p> 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. -<p> 9.6 GROUPED TEXT +auto-heading numbering, without further intervention. +<p> 9.6 GROUPED TEXT <p> 9.6.1 -<p>TABLES -<p> Tables may be prepared in two either of two forms +<p>TABLES +<p> Tables may be prepared in two either of two forms <p> <b>markup example:</b> -<p> +<p> <p> <br> <pre> table{ c3; 40; 30; 30; This is a table @@ -1194,14 +1194,14 @@ auto-heading numbering, without further intervention. column three of row two, and so on }table </pre> -<p> <b>resulting output:</b> +<p> <b>resulting output:</b> <p> [table omitted, see other document formats]<br> - + <p> a second form may be easier to work with in cases where there is not -<p>much information in each column -<p> <b>markup example:</b> [^15] -<p> +<p>much information in each column +<p> <b>markup example:</b> [^15] +<p> <p> <br> <pre> !_ Table 3.1: Contributors to Wikipedia, January 2001 - June 2005 {table~h 24; 12; 12; 12; 12; 12; 12;} @@ -1213,38 +1213,38 @@ auto-heading numbering, without further intervention. 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| + 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| + 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. </pre> -<p> <b>resulting output:</b> +<p> <b>resulting output:</b> <p> <b>Table 3.1: Contributors to Wikipedia, January 2001 -- June 2005</b> +- June 2005</b> <p> [table omitted, see other document formats]<br> - + <p> * Contributed at least ten times; ** at least 5 times in last month; -*** more than 100 times in last month. -<p> 9.6.2 POEM -<p> <b>basic markup:</b> -<p> +*** more than 100 times in last month. +<p> 9.6.2 POEM +<p> <b>basic markup:</b> +<p> <p> <br> <pre> poem{ Your poem here }poem Each verse in a poem is given a separate object number. </pre> -<p> <b>markup example:</b> -<p> +<p> <b>markup example:</b> +<p> <p> <br> <pre> poem{ ’Fury said to a mouse, That he met in the house, - + both go to law: I will prosecute @@ -1269,13 +1269,13 @@ auto-heading numbering, without further intervention. wasting our breath. - + judge, I’ll be jury, Said cunning old Fury: - + try the whole cause, @@ -1286,8 +1286,8 @@ auto-heading numbering, without further intervention. death. }poem </pre> -<p> <b>resulting output:</b> -<p> +<p> <b>resulting output:</b> +<p> <p> ’Fury said to a<br> mouse, That he<br> met in the<br> @@ -1332,25 +1332,25 @@ auto-heading numbering, without further intervention. you<br> to<br> death.<br> - -<p> 9.6.3 GROUP -<p> <b>basic markup:</b> -<p> + +<p> 9.6.3 GROUP +<p> <b>basic markup:</b> +<p> <p> <br> <pre> group{ Your grouped text here }group A group is treated as an object and given a single object number. </pre> -<p> <b>markup example:</b> -<p> +<p> <b>markup example:</b> +<p> <p> <br> <pre> group{ ’Fury said to a mouse, That he met in the house, - + both go to law: I will prosecute @@ -1375,13 +1375,13 @@ auto-heading numbering, without further intervention. wasting our breath. - + judge, I’ll be jury, Said cunning old Fury: - + try the whole cause, @@ -1392,8 +1392,8 @@ auto-heading numbering, without further intervention. death. }group </pre> -<p> <b>resulting output:</b> -<p> +<p> <b>resulting output:</b> +<p> <p> ’Fury said to a<br> mouse, That he<br> met in the<br> @@ -1438,25 +1438,25 @@ auto-heading numbering, without further intervention. you<br> to<br> death.<br> - -<p> 9.6.4 CODE + +<p> 9.6.4 CODE <p> Code tags are used to escape regular sisu markup, and have been used extensively within this document to provide examples of <b>SiSU</b> markup. You cannot however use code tags to escape code tags. They are however -used in the same way as group or poem tags. +used in the same way as group or poem tags. <p> A code-block is treated as an object and given a single object number. [an more than 100 times in last month. option to number each line of code may be considered at more than -100 times in last month. some later time] +100 times in last month. some later time] <p> <b>use of code tags instead of -poem compared, resulting output:</b> -<p> +poem compared, resulting output:</b> +<p> <p> <br> <pre> ’Fury said to a mouse, That he met in the house, - + both go to law: I will prosecute @@ -1481,13 +1481,13 @@ poem compared, resulting output:</b> wasting our breath. - + judge, I’ll be jury, Said cunning old Fury: - + try the whole cause, @@ -1497,7 +1497,59 @@ poem compared, resulting output:</b> to death. </pre> -<p> 10. COMPOSITE DOCUMENTS MARKUP +<p> 9.7 BOOK INDEX +<p> To make an index append to paragraph the book index term +relates to it, using an equal sign and curly braces. +<p> 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. +<p> +<p> <br> +<pre> Paragraph containing main term and sub-term. + ={Main term:sub-term} +</pre> +<p> The index syntax starts on a new line, but there should not be an empty +line between paragraph and index markup. +<p> The structure of the resulting +index would be: +<p> +<p> <br> +<pre> Main term, 1 + sub-term, 1 +</pre> +<p> 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. + +<p> +<p> <br> +<pre> Paragraph containing main term, second term and sub-term. + ={first term; second term: sub-term} +</pre> +<p> The structure of the resulting index would be: +<p> +<p> <br> +<pre> First term, 1, + Second term, 1, + sub-term, 1 +</pre> +<p> If multiple sub-terms appear under one paragraph, they are separated under +the main term heading from each other by a pipe symbol. +<p> +<p> <br> +<pre> 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 +</pre> +<p> 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: +<p> +<p> <br> +<pre> Main term, 1, + sub-term, 1-3, + second sub-term, 1, +</pre> +<p> 10. COMPOSITE DOCUMENTS MARKUP <p> 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, @@ -1511,11 +1563,11 @@ within a master document <b>.sst</b> regular markup file, or <b>.ssi</b> (insert <p>A secondary file of the composite document is built prior to processing -<p>with the same prefix and the suffix <b>._sst</b> +<p>with the same prefix and the suffix <b>._sst</b> <p> basic markup for importing a -<p>document into a master document -<p> +<p>document into a master document +<p> <p> <br> <pre> << filename1.sst << filename2.ssi @@ -1525,83 +1577,83 @@ 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. -<p> +<p> <p> <br> <pre> << filename.ssi <<{filename.ssi} % using textlink alternatives << |filename.ssi|@|^| </pre> -<p> MARKUP SYNTAX HISTORY +<p> MARKUP SYNTAX HISTORY <p> 11. NOTES RELATED TO FILES-TYPES AND MARKUP SYNTAX - + <p> 0.38 is substantially current, depreciated 0.16 supported, though file -<p>names were changed at 0.37 +<p>names were changed at 0.37 <p> * sisu --query=[sisu version [0.38] or ’history] -<p> provides a short history of changes to <b>SiSU</b> markup +<p> provides a short history of changes to <b>SiSU</b> markup <p> <b>0.57</b> (2007w34/4) <b>SiSU</b> 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 and @author:] -<p> + the and @author:] +<p> <p> <br> <pre> :A~ @title by @author </pre> <p> <b>0.52</b> (2007w14/6) declared document type identifier at start of text/document: <p> .B SiSU<br> - 0.52 -<p> or, backward compatible using the comment marker: + 0.52 +<p> or, backward compatible using the comment marker: <p> %<br> - <b>SiSU</b> 0.38 + <b>SiSU</b> 0.38 <p> variations include ’ <b>SiSU</b> (text|master|insert) [version]’ and ’sisu-[version]’ -<p> <b>0.51</b> (2007w13/6) skins changed (simplified), markup unchanged +<p> <b>0.51</b> (2007w13/6) skins changed (simplified), markup unchanged <p> <b>0.42</b> (2006w27/4) -* (asterisk) type endnotes, used e.g. in relation to author +* (asterisk) type endnotes, used e.g. in relation to author <p> <b>SiSU</b> 0.42 is the same as 0.38 with the introduction of some additional endnote types, <p> Introduces some variations on endnotes, in particular the use of the -<p>asterisk -<p> +<p>asterisk +<p> <p> <br> <pre> ~{* for example for describing an author }~ and ~{** for describing a second author }~ </pre> -<p> * for example for describing an author +<p> * for example for describing an author <p> ** for describing a second author -<p> and -<p> +<p> and +<p> <p> <br> <pre> ~[* my note ]~ or ~[+ another note ]~ </pre> -<p> which numerically increments an asterisk and plus respectively +<p> which numerically increments an asterisk and plus respectively <p> *1 my -<p>note +1 another note +<p>note +1 another note <p> <b>0.38</b> (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) +structure markup, :A,:B,:C,1,2,3 (maps to previous 1,2,3,4,5,6) <p> <b>SiSU</b> 0.38 introduced alternative experimental header and heading/structure markers, -<p> +<p> <p> <br> <pre> @headername: and headers :A~ :B~ :C~ 1~ 2~ 3~ </pre> -<p> as the equivalent of: -<p> +<p> as the equivalent of: +<p> <p> <br> <pre> 0~headername and headers 1~ 2~ 3~ 4~ 5~ 6~ </pre> <p> The internal document markup of <b>SiSU</b> 0.16 remains valid and standard Though -<p>note that <b>SiSU</b> 0.37 introduced a new file naming convention +<p>note that <b>SiSU</b> 0.37 introduced a new file naming convention <p> <b>SiSU</b> 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 @@ -1617,45 +1669,45 @@ 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 <p> <b>0.37</b> (2006w09/7) introduced new file naming convention, .sst (text), .ssm -(master), .ssi (insert), markup syntax unchanged +(master), .ssi (insert), markup syntax unchanged <p> <b>SiSU</b> 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> - -<p> this is captured by the following file ’rename’ instruction: -<p> + +<p> this is captured by the following file ’rename’ instruction: +<p> <p> <br> <pre> rename ’s/.s[123]$/.sst/’ *.s{1,2,3} rename ’s/.r[123]$/.ssm/’ *.r{1,2,3} rename ’s/.si$/.ssi/’ *.si </pre> -<p> The internal document markup remains unchanged, from <b>SiSU</b> 0.16 +<p> The internal document markup remains unchanged, from <b>SiSU</b> 0.16 <p> <b>0.35</b> (2005w52/3) -sisupod, zipped content file introduced +sisupod, zipped content file introduced <p> <b>0.23</b> (2005w36/2) utf-8 for markup -<p>file +<p>file <p> <b>0.22</b> (2005w35/3) image dimensions may be omitted if rmagick is available -<p>to be relied upon -<p> <b>0.20.4</b> (2005w33/4) header 0~links +<p>to be relied upon +<p> <b>0.20.4</b> (2005w33/4) header 0~links <p> <b>0.16</b> (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 -<p>marker -<p> <b>SiSU</b> 0.16 (0.15 development branch) introduced the use of +<p>marker +<p> <b>SiSU</b> 0.16 (0.15 development branch) introduced the use of <p> the -header 0~ and headings/structure 1~ 2~ 3~ 4~ 5~ 6~ +header 0~ and headings/structure 1~ 2~ 3~ 4~ 5~ 6~ <p> in place of the 0.1 -header, heading/structure notation +header, heading/structure notation <p> <b>SiSU</b> 0.1 headers and headings structure -represented by header 0{~ and headings/structure 1{ 2{ 3{ 4{~ 5{ 6{ +represented by header 0{~ and headings/structure 1{ 2{ 3{ 4{~ 5{ 6{ <p> 12. -SISU FILETYPES +SISU FILETYPES <p> <b>SiSU</b> has plaintext and binary filetypes, and can process -either type of document. -<p> 12.1 .SST .SSM .SSI MARKED UP PLAIN TEXT +either type of document. +<p> 12.1 .SST .SSM .SSI MARKED UP PLAIN TEXT <p> <b>SiSU</b> documents are prepared as plain-text (utf-8) files with <b>SiSU</b> markup. They may make reference to and contain images (for example), which are stored in the directory @@ -1664,259 +1716,259 @@ 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> - + <p> <b>SiSU</b> 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. -<p> <b>SiSU</b> source markup can be shared with the command: +<p> <b>SiSU</b> source markup can be shared with the command: <p> sisu -s [filename]<br> - -<p> 12.1.1 SISU TEXT - REGULAR FILES (.SST) + +<p> 12.1.1 SISU TEXT - REGULAR FILES (.SST) <p> The most common form of document -in <b>SiSU</b> , see the section on <b>SiSU</b> markup. +in <b>SiSU</b> , see the section on <b>SiSU</b> markup. <p> <<a href='http://www.jus.uio.no/sisu/sisu_markup'>http://www.jus.uio.no/sisu/sisu_markup</a> > <p> <<a href='http://www.jus.uio.no/sisu/sisu_manual'>http://www.jus.uio.no/sisu/sisu_manual</a> -> -<p> 12.1.2 SISU MASTER FILES (.SSM) +> +<p> 12.1.2 SISU MASTER FILES (.SSM) <p> Composite documents which incorporate other <b>SiSU</b> documents which may be either regular <b>SiSU</b> text .sst which may be generated independently, or inserts prepared solely for the purpose of being incorporated into one or more master documents. <p> The mechanism by which master files incorporate other documents is described -as one of the headings under under <b>SiSU</b> markup in the <b>SiSU</b> manual. +as one of the headings under under <b>SiSU</b> markup in the <b>SiSU</b> manual. <p> 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. +contain other documents. <p> Note: a secondary file of the composite document is built prior to processing with the same prefix and the suffix ._sst [^16] <p> <<a href='http://www.jus.uio.no/sisu/sisu_markup'>http://www.jus.uio.no/sisu/sisu_markup</a> -> +> <p> <<a href='http://www.jus.uio.no/sisu/sisu_manual'>http://www.jus.uio.no/sisu/sisu_manual</a> > -<p> 12.1.3 SISU INSERT FILES (.SSI) +<p> 12.1.3 SISU INSERT FILES (.SSI) <p> Inserts are documents prepared solely for the purpose of being incorporated into one or more master documents. They resemble regular <b>SiSU</b> text files except they are ignored by the <b>SiSU</b> 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. +it is not intended that the file should be processed on its own. <p> 12.2 SISUPOD, -ZIPPED BINARY CONTAINER (SISUPOD.ZIP, .SSP) +ZIPPED BINARY CONTAINER (SISUPOD.ZIP, .SSP) <p> A sisupod is a zipped <b>SiSU</b> text file or set of <b>SiSU</b> text files and any associated images that they -contain (this will be extended to include sound and multimedia-files) -<p> +contain (this will be extended to include sound and multimedia-files) +<p> <b>SiSU</b> 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. +into a pod. <p> 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</b> documents. +of a whole directory of prepared <b>SiSU</b> documents. <p> The command to create -a sisupod is: +a sisupod is: <p> sisu -S [filename]<br> - -<p> Alternatively, make a pod of the contents of a whole directory: -<p> + +<p> Alternatively, make a pod of the contents of a whole directory: +<p> sisu -S<br> - + <p> <b>SiSU</b> processing can be done directly against a sisupod; which may be -located locally or on a remote server for which a url is provided. +located locally or on a remote server for which a url is provided. <p> <<a href='http://www.jus.uio.no/sisu/sisu_commands'>http://www.jus.uio.no/sisu/sisu_commands</a> > <p> <<a href='http://www.jus.uio.no/sisu/sisu_manual'>http://www.jus.uio.no/sisu/sisu_manual</a> -> +> <p> 13. EXPERIMENTAL ALTERNATIVE INPUT -REPRESENTATIONS -<p> 13.1 ALTERNATIVE XML +REPRESENTATIONS +<p> 13.1 ALTERNATIVE XML <p> <b>SiSU</b> 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. +handled with care. <p> <b>convert from sst to simple xml representations (sax, -dom and node):</b> +dom and node):</b> <p> sisu --to-sax [filename/wildcard] or sisu --to-sxs [filename/wildcard]<br> - + <p> sisu --to-dom [filename/wildcard] or sisu --to-sxd [filename/wildcard]<br> - + <p> sisu --to-node [filename/wildcard] or sisu --to-sxn [filename/wildcard]<br> - -<p> + +<p> <p> <b>convert to sst from any sisu xml representation (sax, dom and node):</b> <p> sisu --from-xml2sst [filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]]<br> - -<p> or the same: + +<p> or the same: <p> sisu --from-sxml [filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]]<br> - -<p> 13.1.1 XML SAX REPRESENTATION + +<p> 13.1.1 XML SAX REPRESENTATION <p> To convert from sst to simple xml (sax) -representation: +representation: <p> sisu --to-sax [filename/wildcard] or sisu --to-sxs [filename/wildcard]<br> - -<p> To convert from any sisu xml representation back to sst + +<p> To convert from any sisu xml representation back to sst <p> sisu --from-xml2sst [filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]]<br> - -<p> or the same: + +<p> or the same: <p> sisu --from-sxml [filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]]<br> - -<p> 13.1.2 XML DOM REPRESENTATION + +<p> 13.1.2 XML DOM REPRESENTATION <p> To convert from sst to simple xml (dom) -representation: +representation: <p> sisu --to-dom [filename/wildcard] or sisu --to-sxd [filename/wildcard]<br> - -<p> To convert from any sisu xml representation back to sst + +<p> To convert from any sisu xml representation back to sst <p> sisu --from-xml2sst [filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]]<br> - -<p> or the same: + +<p> or the same: <p> sisu --from-sxml [filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]]<br> - -<p> 13.1.3 XML NODE REPRESENTATION + +<p> 13.1.3 XML NODE REPRESENTATION <p> To convert from sst to simple xml (node) -representation: +representation: <p> sisu --to-node [filename/wildcard] or sisu --to-sxn [filename/wildcard]<br> - -<p> To convert from any sisu xml representation back to sst + +<p> To convert from any sisu xml representation back to sst <p> sisu --from-xml2sst [filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]]<br> - -<p> or the same: + +<p> or the same: <p> sisu --from-sxml [filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]]<br> - -<p> 14. CONFIGURATION -<p> 14.1 DETERMINING THE CURRENT CONFIGURATION + +<p> 14. CONFIGURATION +<p> 14.1 DETERMINING THE CURRENT CONFIGURATION <p> Information on the current configuration of <b>SiSU</b> should be available with the help -command: +command: <p> sisu -v<br> - -<p> which is an alias for: + +<p> which is an alias for: <p> sisu --help env<br> - + <p> Either of these should be executed from within a directory that contains -sisu markup source documents. -<p> 14.2 CONFIGURATION FILES (CONFIG.YML) +sisu markup source documents. +<p> 14.2 CONFIGURATION FILES (CONFIG.YML) <p> <b>SiSU</b> 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. +output should be placed. <p> The <b>SiSU</b> configuration file is a yaml file, which -means indentation is significant. +means indentation is significant. <p> <b>SiSU</b> resource configuration is determined -by looking at the following files if they exist: +by looking at the following files if they exist: <p> ./_sisu/sisurc.yml<br> - + <p> ~/.sisu/sisurc.yml<br> - + <p> /etc/sisu/sisurc.yml<br> - -<p> The search is in the order listed, and the first one found is used. + +<p> The search is in the order listed, and the first one found is used. <p> In the absence of instructions in any of these it falls back to the internal -program defaults. +program defaults. <p> Configuration determines the output and processing directories -and the database access details. +and the database access details. <p> If <b>SiSU</b> is installed a sample sisurc.yml -<p>may be found in /etc/sisu/sisurc.yml -<p> 15. SKINS +<p>may be found in /etc/sisu/sisurc.yml +<p> 15. SKINS <p> Skins modify the default appearance of document output on a document, directory, or site wide basis. -Skins are looked for in the following locations: +Skins are looked for in the following locations: <p> ./_sisu/skin<br> - + <p> ~/.sisu/skin<br> - + <p> /etc/sisu/skin<br> - + <p> <b>Within the skin directory</b> are the following the default sub-directories -for document skins: +for document skins: <p> ./skin/doc<br> - + <p> ./skin/dir<br> - + <p> ./skin/site<br> - + <p> A skin is placed in the appropriate directory and the file named skin_[name].rb <p> The skin itself is a ruby file which modifies the default appearances -set in the program. -<p> 15.1 DOCUMENT SKIN +set in the program. +<p> 15.1 DOCUMENT SKIN <p> Documents take on a document skin, -if the header of the document specifies a skin to be used. -<p> +if the header of the document specifies a skin to be used. +<p> <p> <br> <pre> @skin: skin_united_nations </pre> -<p> 15.2 DIRECTORY SKIN +<p> 15.2 DIRECTORY SKIN <p> 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). +directory). <p> 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. -<p> 15.3 SITE SKIN -<p> A site skin, modifies the program default skin. +<p> 15.3 SITE SKIN +<p> A site skin, modifies the program default skin. <p> 15.4 SAMPLE -<p>SKINS -<p> With <b>SiSU</b> installed sample skins may be found in: +<p>SKINS +<p> With <b>SiSU</b> installed sample skins may be found in: <p> /etc/sisu/skin/doc and<br> /usr/share/doc/sisu/sisu_markup_samples/dfsg/_sisu/skin/doc<br> - + <p> (or equivalent directory) and if sisu-markup-samples is installed also -under: +under: <p> /usr/share/doc/sisu/sisu_markup_samples/non-free/_sisu/skin/doc<br> - + <p> Samples of list.yml and promo.yml (which are used to create the right -column list) may be found in: +column list) may be found in: <p> /usr/share/doc/sisu/sisu_markup_samples/dfsg/_sisu/skin/yml (or equivalent<br> directory)<br> - -<p> 16. CSS - CASCADING STYLE SHEETS (FOR HTML, XHTML AND XML) + +<p> 16. CSS - CASCADING STYLE SHEETS (FOR HTML, XHTML AND XML) <p> CSS files to modify the appearance of <b>SiSU</b> 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<br> - output directories with the command sisu -CC. + output directories with the command sisu -CC. <p> 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. -<p> HTML: html.css -<p> XML DOM: dom.css -<p> XML SAX: sax.css -<p> XHTML: xhtml.css +<p> HTML: html.css +<p> XML DOM: dom.css +<p> XML SAX: sax.css +<p> XHTML: xhtml.css <p> - The default homepage may use homepage.css or html.css + The default homepage may use homepage.css or html.css <p> 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.[^17] -<p> 17. ORGANISING CONTENT +is looked for in a skin.[^17] +<p> 17. ORGANISING CONTENT <p> 17.1 DIRECTORY STRUCTURE -<p>AND MAPPING +<p>AND MAPPING <p> 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 @@ -1924,7 +1976,7 @@ 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) +the filetype identifier stripped (.sst .ssm) <p> 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 @@ -1940,45 +1992,45 @@ 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. -<p> 17.2 ORGANISING CONTENT -<p> 18. HOMEPAGES +<p> 17.2 ORGANISING CONTENT +<p> 18. HOMEPAGES <p> <b>SiSU</b> is about the ability to auto-generate documents. Home pages are regarded as custom built items, and are not created by <b>SiSU</b> <b>SiSU</b> 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: +in one of two ways as part of a site’s configuration, these being: <p> 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) -<p> 2. through providing what you want as the home page in a skin, +<p> 2. through providing what you want as the home page in a skin, <p> 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. +structure and organisation of content. <p> 18.1 HOME PAGE AND OTHER CUSTOM BUILT -<p>PAGES IN A SUB-DIRECTORY +<p>PAGES IN A SUB-DIRECTORY <p> 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: +output directory with the command: <p> sisu -CC<br> - -<p> 18.2 HOME PAGE WITHIN A SKIN + +<p> 18.2 HOME PAGE WITHIN A SKIN <p> Skins are described in a separate section, but basically are a file written in the programming language <b>Ruby</b> 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. +respect to individual documents, a directories contents or for a site. <p> 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 -<p>poems in skin_poems.rb -<p> +<p>poems in skin_poems.rb +<p> <p> <br> <pre> class Home def homepage @@ -1994,20 +2046,20 @@ index.html end end </pre> -<p> 19. MARKUP AND OUTPUT EXAMPLES -<p> 19.1 MARKUP EXAMPLES +<p> 19. MARKUP AND OUTPUT EXAMPLES +<p> 19.1 MARKUP EXAMPLES <p> Current markup examples and document output samples are provided at <<a href='http://www.jus.uio.no/sisu/SiSU/examples.html'>http://www.jus.uio.no/sisu/SiSU/examples.html</a> > <p> Some markup with syntax highlighting may be found under <<a href='http://www.jus.uio.no/sisu/sample/syntax'>http://www.jus.uio.no/sisu/sample/syntax</a> > -but is not as up to date. +but is not as up to date. <p> 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. +to be taken into account by the program in generating its output are. <p> 20. -SISU SEARCH - INTRODUCTION +SISU SEARCH - INTRODUCTION <p> <b>SiSU</b> output can easily and conveniently be indexed by a number of standalone indexing tools, such as Lucene, Hyperestraier. @@ -2015,28 +2067,28 @@ indexed by a number of standalone indexing tools, such as Lucene, Hyperestraier. 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. +html output, which has richer text markup. <p> In addition to this <b>SiSU</b> 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. -<p> 21. SQL +or in various output formats. +<p> 21. SQL <p> 21.1 POPULATING SQL TYPE DATABASES <p> <b>SiSU</b> feeds sisu markupd documents into sql type databases PostgreSQL[^18] and/or SQLite[^19] database together with information related to document -structure. +structure. <p> 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: +are (currently) streamed to four tables: <p> * one containing semantic (and other) headers, including, title, author,<br> subject, (the Dublin Core...);<br> - + <p> * another the substantive texts by individual<br> along with structural information, each paragraph being identifiable by its<br> @@ -2044,25 +2096,25 @@ by its<br> substantive text of each paragraph quite naturally being searchable (both in<br> formatted and clean text versions for searching); and<br> - + <p> * a third containing endnotes cross-referenced back to the paragraph from<br> which they are referenced (both in formatted and clean text versions for<br> searching).<br> - + <p> * a fourth table with a one to one relation with the headers table contains<br> full text versions of output, eg. pdf, html, xml, and ascii.<br> - -<p> There is of course the possibility to add further structures. + +<p> There is of course the possibility to add further structures. <p> At this level <b>SiSU</b> 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. +so as to facilitate ease of searching. <p> Being able to search a relational database at an object level with the <b>SiSU</b> citation system is an effective way of locating content generated by <b>SiSU</b> object numbers, and all versions @@ -2072,158 +2124,158 @@ 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). +Dublin Core is incorporated it is easy to make use of that as well). <p> 22. -POSTGRESQL -<p> 22.1 NAME +POSTGRESQL +<p> 22.1 NAME <p> <b>SiSU</b> - Structured information, Serialized Units -- a document publishing system, postgresql dependency package +- a document publishing system, postgresql dependency package <p> 22.2 DESCRIPTION <p> 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</b> to populate a postgresql database, this being -part of <b>SiSU</b> - man sisu). -<p> 22.3 SYNOPSIS +part of <b>SiSU</b> - man sisu). +<p> 22.3 SYNOPSIS <p> sisu -D [instruction] [filename/wildcard if required]<br> - + <p> sisu -D --pg --[instruction] [filename/wildcard if required]<br> - -<p> 22.4 COMMANDS + +<p> 22.4 COMMANDS <p> 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 +postgresql, alternatively --sqlite or --pgsql may be used <p> <b>-D or --pgsql</b> may -be used interchangeably. -<p> 22.4.1 CREATE AND DESTROY DATABASE -<p> +be used interchangeably. +<p> 22.4.1 CREATE AND DESTROY DATABASE +<p> <dl> <dt><b>--pgsql --createall</b> </dt> <dd>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) +the same name as working directory, as requested) (rb.dbi) <p> </dd> <dt><b>sisu -D --createdb</b> </dt> <dd> -<p>creates database where no database existed before +<p>creates database where no database existed before <p> </dd> <dt><b>sisu -D --create</b> </dt> <dd>creates -<p>database tables where no database tables existed before +<p>database tables where no database tables existed before <p> </dd> <dt><b>sisu -D --Dropall</b> </dt> <dd>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). +of the same name). <p> </dd> <dt><b>sisu -D --recreate</b> </dt> <dd>destroys existing database and builds -<p>a new empty database structure +<p>a new empty database structure <p> </dd> </dl> -22.4.2 IMPORT AND REMOVE DOCUMENTS -<p> +22.4.2 IMPORT AND REMOVE DOCUMENTS +<p> <dl> <dt><b>sisu -D --import -v [filename/wildcard]</b> </dt> <dd>populates database with the contents of the file. Imports documents(s) specified to a postgresql database (at an -object level). +object level). <p> </dd> <dt><b>sisu -D --update -v [filename/wildcard]</b> </dt> <dd>updates file contents -<p>in database +<p>in database <p> </dd> <dt><b>sisu -D --remove -v [filename/wildcard]</b> </dt> <dd>removes specified document -from postgresql database. +from postgresql database. <p> </dd> </dl> -23. SQLITE -<p> 23.1 NAME +23. SQLITE +<p> 23.1 NAME <p> <b>SiSU</b> - Structured information, -Serialized Units - a document publishing system. -<p> 23.2 DESCRIPTION +Serialized Units - a document publishing system. +<p> 23.2 DESCRIPTION <p> 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</b> -to populate an sqlite database, this being part of <b>SiSU</b> - man sisu). +to populate an sqlite database, this being part of <b>SiSU</b> - man sisu). <p> 23.3 -<p>SYNOPSIS +<p>SYNOPSIS <p> sisu -d [instruction] [filename/wildcard if required]<br> - + <p> sisu -d --(sqlite|pg) --[instruction] [filename/wildcard if <br> required]<br> - -<p> 23.4 COMMANDS + +<p> 23.4 COMMANDS <p> 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 +postgresql, alternatively --sqlite or --pgsql may be used <p> <b>-d or --sqlite</b> may -be used interchangeably. -<p> 23.4.1 CREATE AND DESTROY DATABASE -<p> +be used interchangeably. +<p> 23.4.1 CREATE AND DESTROY DATABASE +<p> <dl> <dt><b>--sqlite --createall</b> </dt> <dd>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) +same name as working directory, as requested) (rb.dbi) <p> </dd> <dt><b>sisu -d --createdb</b> </dt> <dd> -<p>creates database where no database existed before +<p>creates database where no database existed before <p> </dd> <dt><b>sisu -d --create</b> </dt> <dd>creates -<p>database tables where no database tables existed before +<p>database tables where no database tables existed before <p> </dd> <dt><b>sisu -d --dropall</b> </dt> <dd>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). +of the same name). <p> </dd> <dt><b>sisu -d --recreate</b> </dt> <dd>destroys existing database and builds -<p>a new empty database structure +<p>a new empty database structure <p> </dd> </dl> -23.4.2 IMPORT AND REMOVE DOCUMENTS -<p> +23.4.2 IMPORT AND REMOVE DOCUMENTS +<p> <dl> <dt><b>sisu -d --import -v [filename/wildcard]</b> </dt> <dd>populates database with the contents of the file. Imports documents(s) specified to an sqlite database (at an object -level). +level). <p> </dd> <dt><b>sisu -d --update -v [filename/wildcard]</b> </dt> @@ -2233,13 +2285,13 @@ level). <dt><b>sisu -d --remove -v [filename/wildcard]</b> </dt> <dd>removes specified document from sqlite -database. +database. <p> </dd> </dl> -24. INTRODUCTION +24. INTRODUCTION <p> 24.1 SEARCH - DATABASE FRONTEND SAMPLE, UTILISING DATABASE AND SISU FEATURES, INCLUDING OBJECT CITATION NUMBERING (BACKEND -CURRENTLY POSTGRESQL) +CURRENTLY POSTGRESQL) <p> Sample search frontend <<a href='http://search.sisudoc.org'>http://search.sisudoc.org</a> > [^20] A small database and sample query front-end (search from) that makes @@ -2250,24 +2302,24 @@ locations within each document the matches are found. These results are relevant across all outputs using object citation numbering, which includes html, XML, LaTeX, PDF and indeed the SQL database. You can then refer to one of the other outputs or in the SQL database expand the text within -the matched objects (paragraphs) in the documents matched. +the matched objects (paragraphs) in the documents matched. <p> 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.[^22] -<p> +the search criteria.[^22] +<p> <dl> <dt><b>sisu -F --webserv-webrick</b> </dt> <dd>builds a cgi web search -<p>frontend for the database created +<p>frontend for the database created <p> The following is feedback on the setup -on a machine provided by the help command: +on a machine provided by the help command: <p> sisu --help sql<br> - -<p> + +<p> <p> <br> <pre> Postgresql user: ralph @@ -2278,237 +2330,237 @@ on a machine provided by the help command: current db set: /home/ralph/sisu_www/sisu/sisu_sqlite.db dbi connect DBI:SQLite:/home/ralph/sisu_www/sisu/sisu_sqlite.db </pre> -<p> Note on databases built +<p> Note on databases built <p> 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 + is <p> </dd> </dl> -24.2 SEARCH FORM -<p> +24.2 SEARCH FORM +<p> <dl> <dt><b>sisu -F</b> </dt> <dd>generates a sample search form, which must -<p>be copied to the web-server cgi directory +<p>be copied to the web-server cgi directory <p> </dd> <dt><b>sisu -F --webserv-webrick</b> </dt> <dd>generates a sample search form for use with the webrick server, which must be copied -<p>to the web-server cgi directory +<p>to the web-server cgi directory <p> </dd> <dt><b>sisu -Fv</b> </dt> <dd>as above, and provides some information -<p>on setting up hyperestraier +<p>on setting up hyperestraier <p> </dd> <dt><b>sisu -W</b> </dt> <dd>starts the webrick server which should -<p>be available wherever sisu is properly installed +<p>be available wherever sisu is properly installed <p> The generated search -<p>form must be copied manually to the webserver directory as instructed +<p>form must be copied manually to the webserver directory as instructed <p> </dd> </dl> -25. HYPERESTRAIER -<p> See the documentation for hyperestraier: +25. HYPERESTRAIER +<p> See the documentation for hyperestraier: <p> <<a href='http://hyperestraier.sourceforge.net/'>http://hyperestraier.sourceforge.net/</a> ><br> - + <p> /usr/share/doc/hyperestraier/index.html<br> - + <p> man estcmd<br> - -<p> on sisu_hyperestraier: + +<p> on sisu_hyperestraier: <p> man sisu_hyperestraier<br> - + <p> /usr/share/doc/sisu/sisu_markup/sisu_hyperestraier/index.html<br> - + <p> NOTE: the examples that follow assume that sisu output is placed in -<p>the directory /home/ralph/sisu_www +<p>the directory /home/ralph/sisu_www <p> (A) to generate the index within the -webserver directory to be indexed: +webserver directory to be indexed: <p> estcmd gather -sd [index name] [directory path to index]<br> - + <p> the following are examples that will need to be tailored according to -your needs: +your needs: <p> cd /home/ralph/sisu_www<br> - + <p> estcmd gather -sd casket /home/ralph/sisu_www<br> - + <p> you may use the ’find’ command together with ’egrep’ to limit indexing to particular document collection directories within the web server directory: <p> find /home/ralph/sisu_www -type f | egrep<br> ’/home/ralph/sisu_www/sisu/.+?.html$’ |estcmd gather -sd casket -<br> - + <p> Check which directories in the webserver/output directory (~/sisu_www or elsewhere depending on configuration) you wish to include in the search -index. +index. <p> 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. +these duplicate information held in other html output e.g. <p> find /home/ralph/sisu_www -type f | egrep<br> ’/sisu_www/(sisu|bookmarks)/.+?.html$’ | egrep -v<br> ’(doc|concordance).html$’ |estcmd gather -sd casket -<br> - + <p> from your current document preparation/markup directory, you would construct -a rune along the following lines: +a rune along the following lines: <p> find /home/ralph/sisu_www -type f | egrep ’/home/ralph/sisu_www/([specify <br> first directory for inclusion]|[specify second directory for <br> inclusion]|[another directory for inclusion? ...])/.+?.html$’ |<br> egrep -v ’(doc|concordance).html$’ |estcmd gather -sd<br> /home/ralph/sisu_www/casket -<br> - -<p> (B) to set up the search form + +<p> (B) to set up the search form <p> (i) copy estseek.cgi to your cgi directory -and set file permissions to 755: +and set file permissions to 755: <p> sudo cp -vi /usr/lib/estraier/estseek.cgi /usr/lib/cgi-bin<br> - + <p> sudo chmod -v 755 /usr/lib/cgi-bin/estseek.cgi<br> - + <p> sudo cp -v /usr/share/hyperestraier/estseek.* /usr/lib/cgi-bin<br> - + <p> [see estraier documentation for paths]<br> - + <p> (ii) edit estseek.conf, with attention to the lines starting ’indexname:’ -and ’replace:’: +and ’replace:’: <p> indexname: /home/ralph/sisu_www/casket<br> - + <p> replace: ^file:///home/ralph/sisu_www{{!}}<a href='http://localhost'>http://localhost</a> <br> - + <p> replace: /index.html?${{!}}/<br> - -<p> (C) to test using webrick, start webrick: + +<p> (C) to test using webrick, start webrick: <p> sisu -W<br> - + <p> and try open the url: <<a href='http://localhost:8081/cgi-bin/estseek.cgi'>http://localhost:8081/cgi-bin/estseek.cgi</a> -> +> <p> 26. SISU_WEBRICK - -<p> 26.1 NAME + +<p> 26.1 NAME <p> <b>SiSU</b> - Structured information, Serialized Units - a document -<p>publishing system -<p> 26.2 SYNOPSIS -<p> sisu_webrick [port] -<p> or +<p>publishing system +<p> 26.2 SYNOPSIS +<p> sisu_webrick [port] +<p> or <p> sisu -W [port] -<p> 26.3 DESCRIPTION +<p> 26.3 DESCRIPTION <p> sisu_webrick is part of <b>SiSU</b> (man sisu) sisu_webrick starts <b>Ruby</b> ’s Webrick web-server and points it to the directories to which <b>SiSU</b> output is written, providing a list of these directories (assuming -<b>SiSU</b> is in use and they exist). +<b>SiSU</b> is in use and they exist). <p> 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). -<p> 26.4 SUMMARY OF MAN PAGE +on your system). +<p> 26.4 SUMMARY OF MAN PAGE <p> 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] +with the -W flag: sisu -W [port] <p> where no port is given and settings are -<p>unchanged the default port is 8081 +<p>unchanged the default port is 8081 <p> 26.5 DOCUMENT PROCESSING COMMAND FLAGS <p> sisu -W [port] starts <b>Ruby</b> Webrick web-server, serving <b>SiSU</b> output directories, on the port provided, or if no port is provided and the defaults have not -<p>been changed in ~/.sisu/sisurc.yaml then on port 8081 +<p>been changed in ~/.sisu/sisurc.yaml then on port 8081 <p> 26.6 FURTHER INFORMATION <p> For more information on <b>SiSU</b> see: <<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a> -> +> <p> or man sisu -<p> 26.7 AUTHOR -<p> Ralph Amissah ralph@amissah.com or ralph.amissah@gmail.com +<p> 26.7 AUTHOR +<p> Ralph Amissah ralph@amissah.com or ralph.amissah@gmail.com <p> -<p>26.8 SEE ALSO +<p>26.8 SEE ALSO <p> <a href='http:~/bin/man2html?sisu:1'>sisu(1)</a> <br> - + <p> <a href='http:~/bin/man2html?sisu_vim:7'>sisu_vim(7)</a> <br> - + <p> <a href='http:~/bin/man2html?sisu:8'>sisu(8)</a> <br> - -<p> 27. REMOTE SOURCE DOCUMENTS + +<p> 27. REMOTE SOURCE DOCUMENTS <p> <b>SiSU</b> 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</b> documents can either be sisu marked up files in plaintext .sst or .ssm or; -zipped sisu files, sisupod.zip or filename.ssp +zipped sisu files, sisupod.zip or filename.ssp <p> <b>.sst / .ssm - sisu text files</b> <p> <b>SiSU</b> 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. -<p> +parts (such as images) will be downloaded and generated locally. +<p> <p> <br> <pre> sisu -3 http://[provide url to valid .sst or .ssm file] </pre> <p> Any of the source documents in the sisu examples page can be used in this way, see <<a href='http://www.jus.uio.no/sisu/SiSU/examples.html'>http://www.jus.uio.no/sisu/SiSU/examples.html</a> > and use the url -for the desired document. +for the desired document. <p> NOTE: to set up a remote machine to serve <b>SiSU</b> documents in this way, images should be in the directory relative to the -<p>document source ../_sisu/image -<p> <b>sisupod - zipped sisu files</b> +<p>document source ../_sisu/image +<p> <b>sisupod - zipped sisu files</b> <p> 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. +parts to the document such as images. <p> <b>SiSU</b> 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. -<p> +locally. +<p> <p> <br> <pre> sisu -3 http://[provide url to valid sisupod.zip or .ssp file] </pre> <p> Any of the source documents in the sisu examples page can be used in this way, see <<a href='http://www.jus.uio.no/sisu/SiSU/examples.html'>http://www.jus.uio.no/sisu/SiSU/examples.html</a> > and use the url -for the desired document. -<p> REMOTE DOCUMENT OUTPUT -<p> 28. REMOTE OUTPUT -<p> +for the desired document. +<p> REMOTE DOCUMENT OUTPUT +<p> 28. REMOTE OUTPUT +<p> Once properly configured <b>SiSU</b> output can be automatically posted once generated -to a designated remote machine using either rsync, or scp. +to a designated remote machine using either rsync, or scp. <p> 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. -<p> +may be used in conjunction with other processing flags, e.g. +<p> <p> <br> <pre> sisu -3R sisu_remote.sst </pre> -<p> 28.1 COMMANDS -<p> +<p> 28.1 COMMANDS +<p> <dl> <dt><b>-R [filename/wildcard]</b> </dt> @@ -2517,7 +2569,7 @@ host using rsync. This requires that sisurc.yml has been provided with informati on hostname and username, and that you have your 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 +with other flags, it is not). Also see -r <p> </dd> <dt><b>-r [filename/wildcard]</b> </dt> @@ -2525,45 +2577,45 @@ with other flags, it is not). Also see -r 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 -<p>your +<p>your <p> </dd> </dl> -28.2 CONFIGURATION +28.2 CONFIGURATION <p> [expand on the setting up of an ssh-agent / keychain] -<p> 29. REMOTE SERVERS +<p> 29. REMOTE SERVERS <p> As <b>SiSU</b> is generally operated using the command line, and works within a Unix type environment, <b>SiSU</b> 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. +they would be on your local machine. <p> 30. QUICKSTART - GETTING STARTED HOWTO - -<p> 30.1 INSTALLATION + +<p> 30.1 INSTALLATION <p> Installation is currently most straightforward and tested on the <b>Debian</b> platform, as there are packages for the installation -of sisu and all requirements for what it does. +of sisu and all requirements for what it does. <p> 30.1.1 DEBIAN INSTALLATION <p> <b>SiSU</b> is available directly from the <b>Debian</b> Sid and testing archives (and possibly Ubuntu), assuming your /etc/apt/sources.list is set accordingly: -<p> +<p> <p> <br> <pre> aptitude update aptitude install sisu-complete </pre> <p> The following /etc/apt/sources.list setting permits the download of additional -markup samples: -<p> +markup samples: +<p> <p> <br> <pre> #/etc/apt/sources.list deb http://ftp.fi.debian.org/debian/ unstable main non-free contrib deb-src http://ftp.fi.debian.org/debian/ unstable main non-free contrib d </pre> -<p> The aptitude commands become: -<p> +<p> The aptitude commands become: +<p> <p> <br> <pre> aptitude update aptitude install sisu-complete sisu-markup-samples @@ -2572,308 +2624,308 @@ markup samples: <p>they will be available by adding the following to your /etc/apt/sources.list -<p> +<p> <p> <br> <pre> #/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 </pre> -<p> repeat the aptitude commands -<p> +<p> repeat the aptitude commands +<p> <p> <br> <pre> aptitude update aptitude install sisu-complete sisu-markup-samples </pre> <p> 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. -<p> 30.1.2 RPM INSTALLATION +will provide basic functionality. +<p> 30.1.2 RPM INSTALLATION <p> RPMs are provided though untested, they are prepared by running alien against the source -package, and against the debs. -<p> They may be downloaded from: +package, and against the debs. +<p> They may be downloaded from: <p> <<a href='http://www.jus.uio.no/sisu/SiSU/download.html#rpm'>http://www.jus.uio.no/sisu/SiSU/download.html#rpm</a> ><br> - -<p> as root type: + +<p> as root type: <p> rpm -i [rpm package name]<br> - -<p> 30.1.3 INSTALLATION FROM SOURCE + +<p> 30.1.3 INSTALLATION FROM SOURCE <p> To install <b>SiSU</b> from source check information -at: +at: <p> <<a href='http://www.jus.uio.no/sisu/SiSU/download.html#current'>http://www.jus.uio.no/sisu/SiSU/download.html#current</a> ><br> - -<p> * download the source package -<p> * Unpack the source + +<p> * download the source package +<p> * Unpack the source <p> 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: +steps are the same, download and unpack the source file: <p> For basic use <b>SiSU</b> is only dependent on the programming language in which it is written <b>Ruby</b> , and <b>SiSU</b> will be able to generate html, various XMLs, including ODF (and will also produce LaTeX). Dependencies required for further actions, though it relies on the installation of additional dependencies which the source tarball does not take care of, for things like using a database -(postgresql or sqlite)[^23] or converting LaTeX to pdf. -<p> <b>setup.rb</b> +(postgresql or sqlite)[^23] or converting LaTeX to pdf. +<p> <b>setup.rb</b> <p> This is a standard ruby installer, using setup.rb is a three step process. In -the root directory of the unpacked <b>SiSU</b> as root type: -<p> +the root directory of the unpacked <b>SiSU</b> as root type: +<p> <p> <br> <pre> ruby setup.rb config ruby setup.rb setup #[and as root:] ruby setup.rb install </pre> -<p> further information on setup.rb is available from: +<p> further information on setup.rb is available from: <p> <<a href='http://i.loveruby.net/en/projects/setup/'>http://i.loveruby.net/en/projects/setup/</a> ><br> - + <p> <<a href='http://i.loveruby.net/en/projects/setup/doc/usage.html'>http://i.loveruby.net/en/projects/setup/doc/usage.html</a> ><br> - -<p> <b></b> -<p> The root directory of the unpacked <b>SiSU</b> as root type: + +<p> <b></b> +<p> The root directory of the unpacked <b>SiSU</b> as root type: <p> ruby install base<br> - -<p> or for a more complete installation: + +<p> or for a more complete installation: <p> ruby install<br> - -<p> or + +<p> or <p> ruby install base<br> - + <p> 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. +dependencies, such as tetex-extra are not taken care of for you. <p> Further -<p>information on +<p>information on <p> <<a href='http://make.rubyforge.org/'>http://make.rubyforge.org/</a> ><br> - + <p> <<a href='http://rubyforge.org/frs/?group_id=615'>http://rubyforge.org/frs/?group_id=615</a> ><br> - -<p> For a list of alternative actions you may type: + +<p> For a list of alternative actions you may type: <p> ruby install help<br> - + <p> ruby install -T<br> - -<p> 30.2 TESTING SISU, GENERATING OUTPUT + +<p> 30.2 TESTING SISU, GENERATING OUTPUT <p> To check which version of sisu -is installed: -<p> sisu -v +is installed: +<p> sisu -v <p> Depending on your mode of installation one or -a number of markup sample files may be found either in the directory: +a number of markup sample files may be found either in the directory: <p> - -<p> or -<p> -<p> change directory to the appropriate one: + +<p> or +<p> +<p> change directory to the appropriate one: <p> cd /usr/share/doc/sisu/sisu_markup_samples/dfsg -<p> 30.2.1 BASIC TEXT, PLAINTEXT, HTML, XML, ODF +<p> 30.2.1 BASIC TEXT, PLAINTEXT, HTML, XML, ODF <p> Having moved to the directory that contains the markup samples (see instructions above if necessary), -<p>choose a file and run sisu against it +<p>choose a file and run sisu against it <p> sisu -NhwoabxXyv free_as_in_freedom.rms_and_free_software.sam_williams.sst <p> this will generate html including a concordance file, opendocument text format, plaintext, XHTML and various forms of XML, and OpenDocument text -<p> 30.2.2 LATEX / PDF +<p> 30.2.2 LATEX / PDF <p> 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</b> ) +sisu-pdf in <b>Debian</b> ) <p> Having moved to the directory that contains the markup samples (see instructions above if necessary), choose a file and run sisu -<p>against it +<p>against it <p> sisu -pv free_as_in_freedom.rms_and_free_software.sam_williams.sst -<p> sisu -3 free_as_in_freedom.rms_and_free_software.sam_williams.sst +<p> sisu -3 free_as_in_freedom.rms_and_free_software.sam_williams.sst <p> should generate most available output formats: html including a concordance file, opendocument text format, plaintext, XHTML and various forms of XML, and -<p>OpenDocument text and pdf +<p>OpenDocument text and pdf <p> 30.2.3 RELATIONAL DATABASE - POSTGRESQL, SQLITE <p> Relational databases need some setting up - you must have permission to -create the database and write to it when you run sisu. +create the database and write to it when you run sisu. <p> Assuming you have -<p>the database installed and the requisite permissions +<p>the database installed and the requisite permissions <p> sisu --sqlite --recreate <p> sisu --sqlite -v --import free_as_in_freedom.rms_and_free_software.sam_williams.sst -<p> sisu --pgsql --recreate +<p> sisu --pgsql --recreate <p> sisu --pgsql -v --import free_as_in_freedom.rms_and_free_software.sam_williams.sst -<p> 30.3 GETTING HELP -<p> 30.3.1 THE MAN PAGES -<p> Type: +<p> 30.3 GETTING HELP +<p> 30.3.1 THE MAN PAGES +<p> Type: <p> man sisu<br> - + <p> The man pages are also available online, though not always kept as up -to date as within the package itself: +to date as within the package itself: <p> * sisu.1 <<a href='http://www.jus.uio.no/sisu/man/sisu.1'>http://www.jus.uio.no/sisu/man/sisu.1</a> > -[^24] +[^24] <p> * sisu.8 <<a href='http://www.jus.uio.no/sisu/man/sisu.8'>http://www.jus.uio.no/sisu/man/sisu.8</a> -> [^25] +> [^25] <p> * man directory <<a href='http://www.jus.uio.no/sisu/man'>http://www.jus.uio.no/sisu/man</a> -> [^26] -<p> 30.3.2 BUILT IN HELP -<p> sisu --help +> [^26] +<p> 30.3.2 BUILT IN HELP +<p> sisu --help <p> sisu <p>- <p>- -<p>help --env -<p> sisu --help --commands -<p> sisu --help --markup -<p> 30.3.3 THE HOME PAGE -<p> +<p>help --env +<p> sisu --help --commands +<p> sisu --help --markup +<p> 30.3.3 THE HOME PAGE +<p> <<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a> -> +> <p> <<a href='http://www.jus.uio.no/sisu/SiSU'>http://www.jus.uio.no/sisu/SiSU</a> -> +> <p> 30.4 MARKUP SAMPLES -<p> A number of markup samples (along with output) are available off: +<p> A number of markup samples (along with output) are available off: <p> <<a href='http://www.jus.uio.no/sisu/SiSU/examples.html'>http://www.jus.uio.no/sisu/SiSU/examples.html</a> > -<p> Additional markup samples are packaged separately in the file: -<p> <b>*</b> -<p> +<p> Additional markup samples are packaged separately in the file: +<p> <b>*</b> +<p> On <b>Debian</b> they are available in non-free[^27] to include them it is necessary to include non-free in your /etc/apt/source.list or obtain them from the -sisu home site. -<p> 31. EDITOR FILES, SYNTAX HIGHLIGHTING +sisu home site. +<p> 31. EDITOR FILES, SYNTAX HIGHLIGHTING <p> The directory: <p> ./data/sisu/conf/editor-syntax-etc/<br> - + <p> /usr/share/sisu/conf/editor-syntax-etc<br> - -<p> contains rudimentary sisu syntax highlighting files for: + +<p> contains rudimentary sisu syntax highlighting files for: <p> * (g)vim <<a href='http://www.vim.org'>http://www.vim.org</a> -> +> <p> package: sisu-vim<br> - -<p> status: largely done + +<p> status: largely done <p> there is a vim syntax highlighting and folds component<br> - + <p> * gedit <<a href='http://www.gnome.org/projects/gedit'>http://www.gnome.org/projects/gedit</a> -> +> <p> * gobby <<a href='http://gobby.0x539.de/'>http://gobby.0x539.de/</a> > <p> file: sisu.lang<br> - -<p> place in: + +<p> place in: <p> /usr/share/gtksourceview-1.0/language-specs<br> - -<p> or + +<p> or <p> ~/.gnome2/gtksourceview-1.0/language-specs<br> - + <p> status: very basic syntax highlighting<br> - + <p> comments: this editor features display line wrap and is used by Goby!<br> - + <p> * nano <<a href='http://www.nano-editor.org'>http://www.nano-editor.org</a> -> +> <p> file: nanorc<br> - -<p> save as: + +<p> save as: <p> ~/.nanorc<br> - + <p> status: basic syntax highlighting<br> - + <p> comments: assumes dark background; no display line-wrap; does line breaks<br> - + <p> * diakonos (an editor written in ruby) <<a href='http://purepistos.net/diakonos'>http://purepistos.net/diakonos</a> > -<p> file: diakonos.conf -<p> save as: +<p> file: diakonos.conf +<p> save as: <p> ~/.diakonos/diakonos.conf<br> - -<p> includes: + +<p> includes: <p> status: basic syntax highlighting<br> - -<p> comments: assumes dark background; no display line-wrap + +<p> comments: assumes dark background; no display line-wrap <p> * kate & kwrite <<a href='http://kate.kde.org'>http://kate.kde.org</a> -> +> <p> file: sisu.xml<br> - + <p> place in:<br> - + <p> /usr/share/apps/katepart/syntax<br> - + <p> or<br> - + <p> ~/.kde/share/apps/katepart/syntax<br> - + <p> [settings::configure kate::{highlighting,filetypes}]<br> - + <p> [tools::highlighting::{markup,scripts}:: .B SiSU ]<br> - + <p> * nedit <<a href='http://www.nedit.org'>http://www.nedit.org</a> -> +> <p> file: sisu_nedit.pats<br> - + <p> nedit -import sisu_nedit.pats<br> - + <p> status: a very clumsy first attempt [not really done]<br> - + <p> comments: this editor features display line wrap<br> - + <p> * emacs <<a href='http://www.gnu.org/software/emacs/emacs.html'>http://www.gnu.org/software/emacs/emacs.html</a> -> +> <p> files: sisu-mode.el<br> - + <p> to file ~/.emacs add the following 2 lines:<br> - + <p> (add-to-list ’load-path<br> - + <p> (require ’sisu-mode.el)<br> - + <p> [not done / not yet included]<br> - + <p> * vim & gvim <<a href='http://www.vim.org'>http://www.vim.org</a> -> +> <p> files:<br> - + <p> package is the most comprehensive sisu syntax highlighting and editor<br> environment provided to date (is for vim/ gvim, and is separate from the<br> contents of this directory)<br> - + <p> status: this includes: syntax highlighting; vim folds; some error checking<br> - + <p> comments: this editor features display line wrap<br> - -<p> NOTE: + +<p> NOTE: <p> [ .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] -<p> 32. HOW DOES SISU WORK? + sisu markup] +<p> 32. HOW DOES SISU WORK? <p> <b>SiSU</b> 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 @@ -2891,12 +2943,12 @@ 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). -<p> 33. SUMMARY OF FEATURES +create new ones). +<p> 33. SUMMARY OF FEATURES <p> * 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 headers -are optional. +are optional. <p> * 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]. @@ -2910,36 +2962,36 @@ may also contain processing instructions. <b>SiSU</b> markup is primarily an abs 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 paper publication, sql search etc.] (html, -xml, odf, latex, pdf, sql) +xml, odf, latex, pdf, sql) <p> * 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: +are: <p> * html - both as a single scrollable text and a segmented document<br> - + <p> * xhtml<br> - + <p> * XML - both in sax and dom style xml structures for further development as<br> required<br> - + <p> * ODF - open document format, the iso standard for document storage<br> - + <p> * LaTeX - used to generate pdf<br> - + <p> * pdf (via LaTeX)<br> - + <p> * sql - population of an sql database, (at the same object level that is<br> used to cite text within a document)<br> - + <p> 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)) +level, making possible granular search (and related possibilities)) <p> * ensuring content can be cited in a meaningful way regardless of selected output format. Online publishing (and publishing in multiple document formats) @@ -2950,23 +3002,23 @@ the text within a document, (which can be utilized for citation and by search engines). The outputs share a common numbering system that is meaningful (to man and machine) across all digital outputs whether paper, screen, or database oriented, (pdf, HTML, xml, sqlite, postgresql), this numbering -system can be used to reference content. +system can be used to reference content. <p> * 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]. + well with search indexing tools like hyperestraier]. <p> * 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 (open document text) module in 2006 and in future html5 output sometime in future, without modification of -<p>existing prepared texts +<p>existing prepared texts <p> * SQL search aside, documents are generated as -required and static once generated. +required and static once generated. <p> * 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 @@ -2974,7 +3026,7 @@ output formats, updated technology document presentations/representations) <p> * document source (plaintext utf-8) if shared on the net may be used as -<p>input and processed locally to produce the different document outputs +<p>input and processed locally to produce the different document outputs <p> * document source may be bundled together (automatically) with associated documents (multiple language versions or master document with inclusions) @@ -2987,232 +3039,232 @@ and images and sent as a zip file called a sisupod, if shared on the net <p> * for basic document generation, the only software dependency is <b>Ruby</b> , and a few standard Unix tools (this covers plaintext, HTML, XML, ODF, LaTeX). To use a database you of course need that, and to convert the LaTeX -generated to pdf, a latex processor like tetex or texlive. +generated to pdf, a latex processor like tetex or texlive. <p> * as a developers -<p>tool it is flexible and extensible +<p>tool it is flexible and extensible <p> Syntax highlighting for <b>SiSU</b> markup -is available for a number of text editors. +is available for a number of text editors. <p> <b>SiSU</b> 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 -<p>search of content +<p>search of content <p> 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)... +viewing (e.g. html, xml, pdf), or paper publication (e.g. pdf)... <p> 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. +of how the objects relate to each other to form a document. <p> 34. HELP SOURCES - + <p> For a summary of alternative ways to get help on <b>SiSU</b> try one of the -following: -<p> <b>man page</b> +following: +<p> <b>man page</b> <p> man sisu_help<br> - -<p> <b>man2html</b> + +<p> <b>man2html</b> <p> <<a href='http://www.jus.uio.no/sisu/man/sisu_help.1.html'>http://www.jus.uio.no/sisu/man/sisu_help.1.html</a> ><br> - -<p> <b>sisu generated output - links to html</b> + +<p> <b>sisu generated output - links to html</b> <p> <<a href='http://sisudoc.org/sisu/sisu_help/index.html'>http://sisudoc.org/sisu/sisu_help/index.html</a> ><br> - -<p> <b>help sources lists</b> + +<p> <b>help sources lists</b> <p> Alternative sources for this help sources page -listed here: +listed here: <p> man sisu_help_sources<br> - + <p> <<a href='http://sisudoc.org/sisu/sisu_help_sources/index.html'>http://sisudoc.org/sisu/sisu_help_sources/index.html</a> ><br> - -<p> 34.1 MAN PAGES -<p> 34.1.1 MAN + +<p> 34.1 MAN PAGES +<p> 34.1.1 MAN <p> man sisu<br> - + <p> man 7 sisu_complete<br> - + <p> man 7 sisu_pdf<br> - + <p> man 7 sisu_postgresql<br> - + <p> man 7 sisu_sqlite<br> - + <p> man sisu_termsheet<br> - + <p> man sisu_webrick<br> - -<p> 34.2 SISU GENERATED OUTPUT - LINKS TO HTML + +<p> 34.2 SISU GENERATED OUTPUT - LINKS TO HTML <p> Note <b>SiSU</b> documentation is prepared in <b>SiSU</b> and output is available in multiple formats including amongst others html, pdf, and odf which may be also be accessed via the -html pages[^28] -<p> 34.2.1 WWW.SISUDOC.ORG +html pages[^28] +<p> 34.2.1 WWW.SISUDOC.ORG <p> <<a href='http://sisudoc.org/sisu/sisu_manual/index.html'>http://sisudoc.org/sisu/sisu_manual/index.html</a> > <p> <<a href='http://sisudoc.org/sisu/sisu_manual/index.html'>http://sisudoc.org/sisu/sisu_manual/index.html</a> ><br> - + <p> <<a href='http://sisudoc.org/sisu/sisu_commands/index.html'>http://sisudoc.org/sisu/sisu_commands/index.html</a> ><br> - + <p> <<a href='http://sisudoc.org/sisu/sisu_complete/index.html'>http://sisudoc.org/sisu/sisu_complete/index.html</a> ><br> - + <p> <<a href='http://sisudoc.org/sisu/sisu_configuration/index.html'>http://sisudoc.org/sisu/sisu_configuration/index.html</a> ><br> - + <p> <<a href='http://sisudoc.org/sisu/sisu_description/index.html'>http://sisudoc.org/sisu/sisu_description/index.html</a> ><br> - + <p> <<a href='http://sisudoc.org/sisu/sisu_examples/index.html'>http://sisudoc.org/sisu/sisu_examples/index.html</a> ><br> - + <p> <<a href='http://sisudoc.org/sisu/sisu_faq/index.html'>http://sisudoc.org/sisu/sisu_faq/index.html</a> ><br> - + <p> <<a href='http://sisudoc.org/sisu/sisu_filetypes/index.html'>http://sisudoc.org/sisu/sisu_filetypes/index.html</a> ><br> - + <p> <<a href='http://sisudoc.org/sisu/sisu_help/index.html'>http://sisudoc.org/sisu/sisu_help/index.html</a> ><br> - + <p> <<a href='http://sisudoc.org/sisu/sisu_help_sources/index.html'>http://sisudoc.org/sisu/sisu_help_sources/index.html</a> ><br> - + <p> <<a href='http://sisudoc.org/sisu/sisu_howto/index.html'>http://sisudoc.org/sisu/sisu_howto/index.html</a> ><br> - + <p> <<a href='http://sisudoc.org/sisu/sisu_introduction/index.html'>http://sisudoc.org/sisu/sisu_introduction/index.html</a> ><br> - + <p> <<a href='http://sisudoc.org/sisu/sisu_manual/index.html'>http://sisudoc.org/sisu/sisu_manual/index.html</a> ><br> - + <p> <<a href='http://sisudoc.org/sisu/sisu_markup/index.html'>http://sisudoc.org/sisu/sisu_markup/index.html</a> ><br> - + <p> <<a href='http://sisudoc.org/sisu/sisu_output_overview/index.html'>http://sisudoc.org/sisu/sisu_output_overview/index.html</a> ><br> - + <p> <<a href='http://sisudoc.org/sisu/sisu_pdf/index.html'>http://sisudoc.org/sisu/sisu_pdf/index.html</a> ><br> - + <p> <<a href='http://sisudoc.org/sisu/sisu_postgresql/index.html'>http://sisudoc.org/sisu/sisu_postgresql/index.html</a> ><br> - + <p> <<a href='http://sisudoc.org/sisu/sisu_quickstart/index.html'>http://sisudoc.org/sisu/sisu_quickstart/index.html</a> ><br> - + <p> <<a href='http://sisudoc.org/sisu/sisu_remote/index.html'>http://sisudoc.org/sisu/sisu_remote/index.html</a> ><br> - + <p> <<a href='http://sisudoc.org/sisu/sisu_search/index.html'>http://sisudoc.org/sisu/sisu_search/index.html</a> ><br> - + <p> <<a href='http://sisudoc.org/sisu/sisu_skin/index.html'>http://sisudoc.org/sisu/sisu_skin/index.html</a> ><br> - + <p> <<a href='http://sisudoc.org/sisu/sisu_sqlite/index.html'>http://sisudoc.org/sisu/sisu_sqlite/index.html</a> ><br> - + <p> <<a href='http://sisudoc.org/sisu/sisu_syntax_highlighting/index.html'>http://sisudoc.org/sisu/sisu_syntax_highlighting/index.html</a> ><br> - + <p> <<a href='http://sisudoc.org/sisu/sisu_vim/index.html'>http://sisudoc.org/sisu/sisu_vim/index.html</a> ><br> - + <p> <<a href='http://sisudoc.org/sisu/sisu_webrick/index.html'>http://sisudoc.org/sisu/sisu_webrick/index.html</a> ><br> - -<p> 34.3 MAN2HTML -<p> 34.3.1 LOCALLY INSTALLED + +<p> 34.3 MAN2HTML +<p> 34.3.1 LOCALLY INSTALLED <p> <file:///usr/share/doc/sisu/html/sisu.1.html> -<p> <file:///usr/share/doc/sisu/html/sisu_help.1.html> +<p> <file:///usr/share/doc/sisu/html/sisu_help.1.html> <p> <file:///usr/share/doc/sisu/html/sisu_help_sources.1.html> <p> /usr/share/doc/sisu/html/sisu.1.html<br> - + <p> /usr/share/doc/sisu/html/sisu_pdf.7.html<br> - + <p> /usr/share/doc/sisu/html/sisu_postgresql.7.html<br> - + <p> /usr/share/doc/sisu/html/sisu_sqlite.7.html<br> - + <p> /usr/share/doc/sisu/html/sisu_webrick.1.html<br> - -<p> 34.3.2 WWW.JUS.UIO.NO/SISU + +<p> 34.3.2 WWW.JUS.UIO.NO/SISU <p> <<a href='http://www.jus.uio.no/sisu/man/sisu.1.html'>http://www.jus.uio.no/sisu/man/sisu.1.html</a> -> +> <p> <<a href='http://www.jus.uio.no/sisu/man/sisu.1.html'>http://www.jus.uio.no/sisu/man/sisu.1.html</a> ><br> - + <p> <<a href='http://www.jus.uio.no/sisu/man/sisu_complete.7.html'>http://www.jus.uio.no/sisu/man/sisu_complete.7.html</a> ><br> - + <p> <<a href='http://www.jus.uio.no/sisu/man/sisu_pdf.7.html'>http://www.jus.uio.no/sisu/man/sisu_pdf.7.html</a> ><br> - + <p> <<a href='http://www.jus.uio.no/sisu/man/sisu_postgresql.7.html'>http://www.jus.uio.no/sisu/man/sisu_postgresql.7.html</a> ><br> - + <p> <<a href='http://www.jus.uio.no/sisu/man/sisu_sqlite.7.html'>http://www.jus.uio.no/sisu/man/sisu_sqlite.7.html</a> ><br> - + <p> <<a href='http://www.jus.uio.no/sisu/man/sisu_webrick.1.html'>http://www.jus.uio.no/sisu/man/sisu_webrick.1.html</a> ><br> - -<p> DOCUMENT INFORMATION (METADATA) -<p> METADATA + +<p> DOCUMENT INFORMATION (METADATA) +<p> METADATA <p> Document Manifest @ <<a href='http://sisudoc.org/sisu_manual/sisu/sisu_manifest.html'>http://sisudoc.org/sisu_manual/sisu/sisu_manifest.html</a> > -<p> <b>Dublin Core</b> (DC) +<p> <b>Dublin Core</b> (DC) <p> <i>DC</i> tags included with this document are provided here. -<p> DC Title: <i>SiSU</i> - Manual -<p> DC Creator: <i>Ralph</i> Amissah -<p> DC Rights: 3 +<p> DC Title: <i>SiSU</i> - Manual +<p> DC Creator: <i>Ralph</i> Amissah +<p> DC Rights: 3 <p> DC Type: -<p><i>information</i> -<p> DC Date created: <i>2002-08-28</i> -<p> DC Date issued: <i>2002-08-28</i> +<p><i>information</i> +<p> DC Date created: <i>2002-08-28</i> +<p> DC Date issued: <i>2002-08-28</i> <p> DC -Date available: <i>2002-08-28</i> -<p> DC Date modified: <i>2008-05-22</i> +Date available: <i>2002-08-28</i> +<p> DC Date modified: <i>2008-05-22</i> <p> DC Date: <i>2008-05-22</i> -<p> <b>Version Information</b> -<p> Sourcefile: <i>sisu.ssm.sst</i> +<p> <b>Version Information</b> +<p> Sourcefile: <i>sisu.ssm.sst</i> <p> Filetype: <i>SiSU</i> text insert -<p>0.67 +<p>0.67 <p> Sourcefile Digest, MD5(sisu.ssm.sst)= <i>7fbab3b7c0fd0ed2e128585c2982c5c8</i> <p> Skin_Digest: MD5(skin_sisu_manual.rb)= <i>072b2584bedea82ea8a416587b9fa244</i> -<p> <b>Generated</b> +<p> <b>Generated</b> <p> Document (metaverse) last generated: <i>Mon</i> Jul 21 02:54:34 <p>- -<p>0400 2008 -<p> Generated by: <i>SiSU</i> <i>0.68.0</i> of 2008w29/1 (2008-07-21) +<p>0400 2008 +<p> Generated by: <i>SiSU</i> <i>0.68.0</i> of 2008w29/1 (2008-07-21) <p> Ruby version: -<i>ruby</i> 1.8.7 (2008-06-20 patchlevel 22) [i486-linux] -<p> +<i>ruby</i> 1.8.7 (2008-06-20 patchlevel 22) [i486-linux] +<p> <ol> <b>.</b><li>objects include: headings, paragraphs, verse, tables, images, but not footnotes/endnotes which are @@ -3291,7 +3343,7 @@ being added in future. </li><b>.</b><li><<a href='http://www.jus.uio.no/sisu/ that everything distributed within <b>Debian</b> can be changed - and the documents are authors’ works that while freely distributable are not freely changeable. </li><b>.</b><li> -<p>named index.html or more extensively through sisu_manifest.html +<p>named index.html or more extensively through sisu_manifest.html <p> </dd> <dt>Other versions diff --git a/data/doc/sisu/sisu_markup_samples/dfsg/free_as_in_freedom.richard_stallman_crusade_for_free_software.sam_williams.sst b/data/doc/sisu/sisu_markup_samples/dfsg/free_as_in_freedom.richard_stallman_crusade_for_free_software.sam_williams.sst index 23cad62a..58009f0e 100644 --- a/data/doc/sisu/sisu_markup_samples/dfsg/free_as_in_freedom.richard_stallman_crusade_for_free_software.sam_williams.sst +++ b/data/doc/sisu/sisu_markup_samples/dfsg/free_as_in_freedom.richard_stallman_crusade_for_free_software.sam_williams.sst @@ -6,7 +6,7 @@ @author: Sam Williams -@rights: Copyright Sam Williams 2002, published under the GNU Free Documentation License. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Document License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being no invariant sections, with the Front-Cover Texts being no invariant sections, and with the Back-Cover Texts being no invariant sections. A copy of the license is included in Appendix C, GNU Free Documentation License. All images are to be included verbatim when the document is copied, distributed, or modified under the terms of the GFDL. +@rights: Copyright (C) Sam Williams 2002, published under the GNU Free Documentation License. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Document License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being no invariant sections, with the Front-Cover Texts being no invariant sections, and with the Back-Cover Texts being no invariant sections. A copy of the license is included in Appendix C, GNU Free Documentation License. All images are to be included verbatim when the document is copied, distributed, or modified under the terms of the GFDL. @language: US @@ -20,6 +20,7 @@ {@ Amazon.com}http://www.amazon.com/gp/product/0596002874 {@ Barnes & Noble}http://search.barnesandnoble.com/booksearch/isbnInquiry.asp?isbn=0596002874 {The Wealth of Networks, Yochai Benkler @ SiSU}http://www.jus.uio.no/sisu/the_wealth_of_networks.yochai_benkler +{Two Bits, Christopher Kelty @ SiSU}http://www.jus.uio.no/sisu/two_bits.christopher_kelty {Free For All, Peter Wayner @ SiSU}http://www.jus.uio.no/sisu/free_for_all.peter_wayner {Free Culture, Lawrence Lessig @ SiSU}http://www.jus.uio.no/sisu/free_culture.lawrence_lessig {The Cathedral and the Bazaar, Eric S. Raymond @ SiSU }http://www.jus.uio.no/sisu/the_cathedral_and_the_bazaar.eric_s_raymond @@ -98,6 +99,7 @@ The Aeneid The new printer was jammed, again. Richard M. Stallman, a staff software programmer at the Massachusetts Institute of Technology's Artificial Intelligence Laboratory (AI Lab), discovered the malfunction the hard way. An hour after sending off a 50-page file to the office laser printer, Stallman, 27, broke off a productive work session to retrieve his documents. Upon arrival, he found only four pages in the printer's tray. To make matters even more frustrating, the four pages belonged to another user, meaning that Stallman's print job and the unfinished portion of somebody else's print job were still trapped somewhere within the electrical plumbing of the lab's computer network. +={AI Lab (Artificial Intelligence Laboratory)} Waiting for machines is an occupational hazard when you're a software programmer, so Stallman took his frustration with a grain of salt. Still, the difference between waiting for a machine and waiting on a machine is a sizable one. It wasn't the first time he'd been forced to stand over the printer, watching pages print out one by one. As a person who spent the bulk of his days and nights improving the efficiency of machines and the software programs that controlled them, Stallman felt a natural urge to open up the machine, look at the guts, and seek out the root of the problem. @@ -132,10 +134,12 @@ After the first few printer jams, Stallman comforted himself with the memory of Taking advantage of his access to the Harvard computer lab, Stallman dropped in, made a copy of the cross-network source code, and brought it back to the AI Lab. He then rewrote the source code to make it more suitable for the AI Lab's operating system. With no muss and little fuss, the AI Lab shored up a major gap in its software infrastructure. Stallman even added a few features not found in the original Harvard program, making the program even more useful. "We wound up using it for several years," Stallman says. From the perspective of a 1970s-era programmer, the transaction was the software equivalent of a neighbor stopping by to borrow a power tool or a cup of sugar from a neighbor. The only difference was that in borrowing a copy of the software for the AI Lab, Stallman had done nothing to deprive Harvard hackers the use of their original program. If anything, Harvard hackers gained in the process, because Stallman had introduced his own additional features to the program, features that hackers at Harvard were perfectly free to borrow in return. Although nobody at Harvard ever came over to borrow the program back, Stallman does recall a programmer at the private engineering firm, Bolt, Beranek & Newman, borrowing the program and adding a few additional features, which Stallman eventually reintegrated into the AI Lab's own source-code archive. +={AI Lab (Artificial Intelligence Laboratory):borrowing source code for} "A program would develop the way a city develops," says Stallman, recalling the software infrastructure of the AI Lab. "Parts would get replaced and rebuilt. New things would get added on. But you could always look at a certain part and say, `Hmm, by the style, I see this part was written back in the early 60s and this part was written in the mid-1970s.'" Through this simple system of intellectual accretion, hackers at the AI Lab and other places built up robust creations. On the west coast, computer scientists at UC Berkeley, working in cooperation with a few low-level engineers at AT&T, had built up an entire operating system using this system. Dubbed Unix, a play on an older, more academically respectable operating system called Multics, the software system was available to any programmer willing to pay for the cost of copying the program onto a new magnetic tape and shipping it. Not every programmer participating in this culture described himself as a hacker, but most shared the sentiments of Richard M. Stallman. If a program or software fix was good enough to solve your problems, it was good enough to solve somebody else's problems. Why not share it out of a simple desire for good karma? +={AT&T} The fact that Xerox had been unwilling to share its source-code files seemed a minor annoyance at first. In tracking down a copy of the source-code files, Stallman says he didn't even bother contacting Xerox. "They had already given us the laser printer," Stallman says. "Why should I bug them for more?" @@ -204,6 +208,7 @@ In an information economy increasingly dependent on software and increasingly be They've also come to rely upon it as a strategic weapon in the hacker community's perennial war against Microsoft, the Redmond, Washington-based company that, for better or worse, has dominated the PC-software marketplace since the late 1980s. As owner of the popular Windows operating system, Microsoft stands to lose the most in an industry-wide shift to the GPL license. Almost every line of source code in the Windows colossus is protected by copyrights reaffirming the private nature of the underlying source code or, at the very least, reaffirming Microsoft's legal ability to treat it as such. From the Microsoft viewpoint, incorporating programs protected by the "viral" GPL into the Windows colossus would be the software equivalent of Superman downing a bottle of Kryptonite pills. Rival companies could suddenly copy, modify, and sell improved versions of Windows, rendering the company's indomitable position as the No. 1 provider of consumer-oriented software instantly vulnerable. Hence the company's growing concern over the GPL's rate of adoption. Hence the recent Mundie speech blasting the GPL and the " open source" approach to software development and sales. And hence Stallman's decision to deliver a public rebuttal to that speech on the same campus here today. 20 years is a long time in the software industry. Consider this: in 1980, when Richard Stallman was cursing the AI Lab's Xerox laser printer, Microsoft, the company modern hackers view as the most powerful force in the worldwide software industry, was still a privately held startup. IBM, the company hackers used to regard as the most powerful force in the worldwide software industry, had yet to to introduce its first personal computer, thereby igniting the current low-cost PC market. Many of the technologies we now take for granted-the World Wide Web, satellite television, 32-bit video-game consoles-didn't even exist. The same goes for many of the companies that now fill the upper echelons of the corporate establishment, companies like AOL, Sun Microsystems, Amazon.com, Compaq, and Dell. The list goes on and on. +={Amazon.com;AOL (America OnLine)} The fact that the high-technology marketplace has come so far in such little time is fuel for both sides of the GPL debate. GPL-proponents point to the short lifespan of most computer hardware platforms. Facing the risk of buying an obsolete product, consumers tend to flock to companies with the best long-term survival. As a result, the software marketplace has become a winner-take-all arena.~{ See Shubha Ghosh, "Revealing the Microsoft Windows Source Code," Gigalaw.com (January, 2000).<br> http://www.gigalaw.com/articles/ghosh-2000-01-p1.html }~ The current, privately owned software environment, GPL-proponents say, leads to monopoly abuse and stagnation. Strong companies suck all the oxygen out of the marketplace for rival competitors and innovative startups. @@ -221,7 +226,7 @@ If the last two decades have brought dramatic changes to the software marketplac The crowd is filled with visitors who share Stallman's fashion and grooming tastes. Many come bearing laptop computers and cellular modems, all the better to record and transmit Stallman's words to a waiting Internet audience. The gender ratio is roughly 15 males to 1 female, and 1 of the 7 or 8 females in the room comes in bearing a stuffed penguin, the official Linux mascot, while another carries a stuffed teddy bear. -{free_as_in_freedom_01_rms.png 381x321 "Richard Stallman, circa 2000. 'I decided I would develop a free software operating system or die trying ... of old age of course.' Photo courtesy of http://www.stallman.org " }http://www.free-culture.cc/ +{free_as_in_freedom_01_rms.png 381x321 "Richard Stallman, circa 2000. 'I decided I would develop a free software operating system or die trying ... of old age of course.' Photo courtesy of http://www.stallman.org " }http://en.wikipedia.org/wiki/Richard_stallman Agitated, Stallman leaves his post at the front of the room and takes a seat in a front-row chair, tapping a few commands into an already-opened laptop. For the next 10 minutes Stallman is oblivious to the growing number of students, professors, and fans circulating in front of him at the foot of the auditorium stage. @@ -338,6 +343,7 @@ Seth Breidbart, a fellow Columbia Science Honors Program alumnus, offers bolster "It's hard to describe," Breidbart says. "It wasn't like he was unapproachable. He was just very intense. [He was] very knowledgeable but also very hardheaded in some ways." Such descriptions give rise to speculation: are judgment-laden adjectives like "intense" and "hardheaded" simply a way to describe traits that today might be categorized under juvenile behavioral disorder? A December, 2001, Wired magazine article titled "The Geek Syndrome" paints the portrait of several scientifically gifted children diagnosed with high-functioning autism or Asperger Syndrome. In many ways, the parental recollections recorded in the Wired article are eerily similar to the ones offered by Lippman. Even Stallman has indulged in psychiatric revisionism from time to time. During a 2000 profile for the Toronto Star, Stallman described himself to an interviewer as "borderline autistic,"~{ See Judy Steed, Toronto Star, BUSINESS, (October 9, 2000): C03.<br>His vision of free software and social cooperation stands in stark contrast to the isolated nature of his private life. A Glenn Gould-like eccentric, the Canadian pianist was similarly brilliant, articulate, and lonely. Stallman considers himself afflicted, to some degree, by autism: a condition that, he says, makes it difficult for him to interact with people. }~ a description that goes a long way toward explaining a lifelong tendency toward social and emotional isolation and the equally lifelong effort to overcome it. +={Asperger Syndrome+1;autism+5} Such speculation benefits from the fast and loose nature of most so-called " behavioral disorders" nowadays, of course. As Steve Silberman, author of " The Geek Syndrome," notes, American psychiatrists have only recently come to accept Asperger Syndrome as a valid umbrella term covering a wide set of behavioral traits. The traits range from poor motor skills and poor socialization to high intelligence and an almost obsessive affinity for numbers, computers, and ordered systems.~{ See Steve Silberman, "The Geek Syndrome," Wired (December, 2001).<br> http://www.wired.com/wired/archive/9.12/aspergers_pr.html }~ Reflecting on the broad nature of this umbrella, Stallman says its possible that, if born 40 years later, he might have merited just such a diagnosis. Then again, so would many of his computer-world colleagues. @@ -376,6 +382,7 @@ For all the agony it produced, adolescence would have a encouraging effect on St Outside the home, Stallman saved the jokes for the adults who tended to indulge his gifted nature. One of the first was a summer-camp counselor who handed Stallman a print-out manual for the IBM 7094 computer during his 12th year. To a preteenager fascinated with numbers and science, the gift was a godsend.~{ Stallman, an atheist, would probably quibble with this description. Suffice it to say, it was something Stallman welcomed. See previous note 1: "As soon as I heard about computers, I wanted to see one and play with one." }~ By the end of summer, Stallman was writing out paper programs according to the 7094's internal specifications, anxiously anticipating getting a chance to try them out on a real machine. With the first personal computer still a decade away, Stallman would be forced to wait a few years before getting access to his first computer. His first chance finally came during his junior year of high school. Hired on at the IBM New York Scientific Center, a now-defunct research facility in downtown Manhattan, Stallman spent the summer after high-school graduation writing his first program, a pre-processor for the 7094 written in the programming language PL/I. "I first wrote it in PL/I, then started over in assembler language when the PL/I program was too big to fit in the computer," he recalls. +={assembler language} After that job at the IBM Scientific Center, Stallman had held a laboratory-assistant position in the biology department at Rockefeller University. Although he was already moving toward a career in math or physics, Stallman's analytical mind impressed the lab director enough that a few years after Stallman departed for college, Lippman received an unexpected phone call. "It was the professor at Rockefeller," Lippman says. "He wanted to know how Richard was doing. He was surprised to learn that he was working in computers. He'd always thought Richard had a great future ahead of him as a biologist." @@ -393,7 +400,7 @@ By fall, Stallman was back within the mainstream population of New York City hig By the end of his first semester at Brandeis, things were falling into place. A 96 in English wiped away much of the stigma of the 60 earned 2 years before. For good measure, Stallman backed it up with top marks in American History, Advanced Placement Calculus, and Microbiology. The crowning touch was a perfect 100 in Physics. Though still a social outcast, Stallman finished his 11 months at Brandeis as the fourth-ranked student in a class of 789. -{free_as_in_freedom_02_rms_snr_year_report.png 381x286 "Stallman's senior-year transcript at Louis D. Brandeis H.S., November, 1969. Note turnaround in English class performance. 'He was forced to kowtow to a certain degree,' says his mother, 'but he did it.'" }http://www.free-culture.cc/ +{free_as_in_freedom_02_rms_snr_year_report.png 381x286 "Stallman's senior-year transcript at Louis D. Brandeis H.S., November, 1969. Note turnaround in English class performance. 'He was forced to kowtow to a certain degree,' says his mother, 'but he did it.'" }http://en.wikipedia.org/wiki/Richard_stallman Outside the classroom, Stallman pursued his studies with even more diligence, rushing off to fulfill his laboratory-assistant duties at Rockefeller University during the week and dodging the Vietnam protesters on his way to Saturday school at Columbia. It was there, while the rest of the Science Honors Program students sat around discussing their college choices, that Stallman finally took a moment to participate in the preclass bull session. @@ -494,12 +501,14 @@ For Stallman, the first taste of real computer programming at the IBM New York S Taking the manuals home, Stallman would examine machine specifications, compare them with other machines he already knew, and concoct a trial program, which he would then bring back to the lab along with the borrowed manual. Although some labs balked at the notion of a strange kid coming off the street and working on the lab machinery, most recognized competence when they saw it and let Stallman run the programs he had created. One day, near the end of freshman year, Stallman heard about a special laboratory near MIT. The laboratory was located on the ninth floor an off-campus building in Tech Square, the newly built facility dedicated to advanced research. According to the rumors, the lab itself was dedicated to the cutting-edge science of artificial intelligence and boasted the cutting-edge machines and software programs to match. +={artificial intelligence} Intrigued, Stallman decided to pay a visit. The trip was short, about 2 miles on foot, 10 minutes by train, but as Stallman would soon find out, MIT and Harvard can feel like opposite poles of the same planet. With its maze-like tangle of interconnected office buildings, the Institute's campus offered an aesthetic yin to Harvard's spacious colonial-village yang. The same could be said for the student body, a geeky collection of ex-high school misfits known more for its predilection for pranks than its politically powerful alumni. The yin-yang relationship extended to the AI Lab as well. Unlike Harvard computer labs, there was no grad-student gatekeeper, no clipboard waiting list for terminal access, no explicit atmosphere of "look but don't touch." Instead, Stallman found only a collection of open terminals and robotic arms, presumably the artifacts of some A.I. experiment. +={AI Lab (Artificial Intelligence Laboratory)+40} Although the rumors said anybody could sit down at the terminals, Stallman decided to stick with the original plan. When he encountered a lab employee, he asked if the lab had any spare manuals it could loan to an inquisitive student. "They had some, but a lot of things weren't documented," Stallman recalls. "They were hackers after all." @@ -511,9 +520,10 @@ To get a taste of "bureaucratic and stuffy," Stallman need only visit the comput Stallman quickly learned that the AI Lab's first-come, first-served policy owed much to the efforts of a vigilant few. Many were holdovers from the days of Project MAC, the Department of Defense-funded research program that had given birth to the first time-share operating systems. A few were already legends in the computing world. There was Richard Greenblatt, the lab's in-house Lisp expert and author of MacHack, the computer chess program that had once humbled A.I. critic Hubert Dreyfus. There was Gerald Sussman, original author of the robotic block-stacking program HACKER. And there was Bill Gosper, the in-house math whiz already in the midst of an 18-month hacking bender triggered by the philosophical implications of the computer game LIFE.~{ See Steven Levy, Hackers (Penguin USA [paperback], 1984): 144.<br>Levy devotes about five pages to describing Gosper's fascination with LIFE, a math-based software game first created by British mathematician John Conway. I heartily recommend this book as a supplement, perhaps even a prerequisite, to this one. }~ -Members of the tight-knit group called themselves " hackers." Over time, they extended the "hacker" description to Stallman as well. In the process of doing so, they inculcated Stallman in the ethical traditions of the "hacker ethic ." To be a hacker meant more than just writing programs, Stallman learned. It meant writing the best possible programs. It meant sitting at a terminal for 36 hours straight if that's what it took to write the best possible programs. Most importantly, it meant having access to the best possible machines and the most useful information at all times. Hackers spoke openly about changing the world through software, and Stallman learned the instinctual hacker disdain for any obstacle that prevented a hacker from fulfilling this noble cause. Chief among these obstacles were poor software, academic bureaucracy, and selfish behavior. +Members of the tight-knit group called themselves "hackers." Over time, they extended the "hacker" description to Stallman as well. In the process of doing so, they inculcated Stallman in the ethical traditions of the "hacker ethic ." To be a hacker meant more than just writing programs, Stallman learned. It meant writing the best possible programs. It meant sitting at a terminal for 36 hours straight if that's what it took to write the best possible programs. Most importantly, it meant having access to the best possible machines and the most useful information at all times. Hackers spoke openly about changing the world through software, and Stallman learned the instinctual hacker disdain for any obstacle that prevented a hacker from fulfilling this noble cause. Chief among these obstacles were poor software, academic bureaucracy, and selfish behavior. -Stallman also learned the lore, stories of how hackers, when presented with an obstacle, had circumvented it in creative ways. Stallman learned about " lock hacking," the art of breaking into professors' offices to "liberate" sequestered terminals. Unlike their pampered Harvard counterparts, MIT faculty members knew better than to treat the AI Lab's terminal as private property. If a faculty member made the mistake of locking away a terminal for the night, hackers were quick to correct the error. Hackers were equally quick to send a message if the mistake repeated itself. "I was actually shown a cart with a heavy cylinder of metal on it that had been used to break down the door of one professor's office,"~{ Gerald Sussman, an MIT faculty member and hacker whose work at the AI Lab predates Stallman's, disputes this memory. According to Sussman, the hackers never broke any doors to retrieve terminals. }~ Stallman says. +Stallman also learned the lore, stories of how hackers, when presented with an obstacle, had circumvented it in creative ways. Stallman learned about "lock hacking," the art of breaking into professors' offices to "liberate" sequestered terminals. Unlike their pampered Harvard counterparts, MIT faculty members knew better than to treat the AI Lab's terminal as private property. If a faculty member made the mistake of locking away a terminal for the night, hackers were quick to correct the error. Hackers were equally quick to send a message if the mistake repeated itself. "I was actually shown a cart with a heavy cylinder of metal on it that had been used to break down the door of one professor's office,"~{ Gerald Sussman, an MIT faculty member and hacker whose work at the AI Lab predates Stallman's, disputes this memory. According to Sussman, the hackers never broke any doors to retrieve terminals. }~ Stallman says. +={AI Lab (Artificial Intelligence Laboratory):lock hacking at+31} Such methods, while lacking in subtlety, served a purpose. Although professors and administrators outnumbered hackers two-to-one inside the AI Lab, the hacker ethic prevailed. Indeed, by the time of Stallman's arrival at the AI Lab, hackers and the AI Lab administration had coevolved into something of a symbiotic relationship. In exchange for fixing the machines and keeping the software up and running, hackers earned the right to work on favorite pet projects. Often, the pet projects revolved around improving the machines and software programs even further. Like teenage hot-rodders, most hackers viewed tinkering with machines as its own form of entertainment. @@ -596,6 +606,7 @@ To call the Stallman gaze intense is an understatement. Stallman's eyes don't ju Maybe that's why most writers, when describing Stallman, tend to go for the religious angle. In a 1998 Salon.com article titled "The Saint of Free Software," Andrew Leonard describes Stallman's green eyes as "radiating the power of an Old Testament prophet."~{ See Andrew Leonard, "The Saint of Free Software," Salon.com (August 1998).<br> http://www.salon.com/21st/feature/1998/08/cov_31feature.html }~ A 1999 Wired magazine article describes the Stallman beard as "Rasputin-like,"~{ See Leander Kahney, "Linux's Forgotten Man," Wired News (March 5, 1999).<br> http://www.wired.com/news/print/0,1294,18291,00.html }~ while a London Guardian profile describes the Stallman smile as the smile of "a disciple seeing Jesus."~{ See "Programmer on moral high ground; Free software is a moral issue for Richard Stallman believes in freedom and free software." London Guardian (November 6, 1999).<br>These are just a small sampling of the religious comparisons. To date, the most extreme comparison has to go to Linus Torvalds, who, in his autobiography-see Linus Torvalds and David Diamond, Just For Fun: The Story of an Accidentaly Revolutionary (HarperCollins Publishers, Inc., 2001): 58-writes "Richard Stallman is the God of Free Software."<br>Honorable mention goes to Larry Lessig, who, in a footnote description of Stallman in his book-see Larry Lessig, The Future of Ideas (Random House, 2001): 270-likens Stallman to Moses:<br>_1 ... as with Moses, it was another leader, Linus Torvalds, who finally carried the movement into the promised land by facilitating the development of the final part of the OS puzzle. Like Moses, too, Stallman is both respected and reviled by allies within the movement. He is [an] unforgiving, and hence for many inspiring, leader of a critically important aspect of modern culture. I have deep respect for the principle and commitment of this extraordinary individual, though I also have great respect for those who are courageous enough to question his thinking and then sustain his wrath.<br>In a final interview with Stallman, I asked him his thoughts about the religious comparisons. "Some people do compare me with an Old Testament prophent, and the reason is Old Testament prophets said certain social practices were wrong. They wouldn't compromise on moral issues. They couldn't be bought off, and they were usually treated with contempt." }~ Such analogies serve a purpose, but they ultimately fall short. That's because they fail to take into account the vulnerable side of the Stallman persona. Watch the Stallman gaze for an extended period of time, and you will begin to notice a subtle change. What appears at first to be an attempt to intimidate or hypnotize reveals itself upon second and third viewing as a frustrated attempt to build and maintain contact. If, as Stallman himself has suspected from time to time, his personality is the product of autism or Asperger Syndrome, his eyes certainly confirm the diagnosis. Even at their most high-beam level of intensity, they have a tendency to grow cloudy and distant, like the eyes of a wounded animal preparing to give up the ghost. +={Asperger Syndrome;autism} My own first encounter with the legendary Stallman gaze dates back to the March, 1999, LinuxWorld Convention and Expo in San Jose, California. Billed as a "coming out party" for the Linux software community, the convention also stands out as the event that reintroduced Stallman to the technology media. Determined to push for his proper share of credit, Stallman used the event to instruct spectators and reporters alike on the history of the GNU Project and the project's overt political objectives. @@ -616,6 +627,7 @@ Maybe that's why, when LinuxWorld follows up its first two shows with a third Li My second encounter with Stallman and his trademark gaze comes shortly after that third LinuxWorld show. Hearing that Stallman is going to be in Silicon Valley, I set up a lunch interview in Palo Alto, California. The meeting place seems ironic, not only because of the recent no-show but also because of the overall backdrop. Outside of Redmond, Washington, few cities offer a more direct testament to the economic value of proprietary software. Curious to see how Stallman, a man who has spent the better part of his life railing against our culture's predilection toward greed and selfishness, is coping in a city where even garage-sized bungalows run in the half-million-dollar price range, I make the drive down from Oakland. I follow the directions Stallman has given me, until I reach the headquarters of Art.net, a nonprofit "virtual artists collective." Located in a hedge-shrouded house in the northern corner of the city, the Art.net headquarters are refreshingly run-down. Suddenly, the idea of Stallman lurking in the heart of Silicon Valley doesn't seem so strange after all. +={Art.net} I find Stallman sitting in a darkened room, tapping away on his gray laptop computer. He looks up as soon as I enter the room, giving me a full blast of his 200-watt gaze. When he offers a soothing "Hello," I offer a return greeting. Before the words come out, however, his eyes have already shifted back to the laptop screen. @@ -780,6 +792,7 @@ The waiter, uncomprehending or fooled by the look of the bill, smiles and scurri 1~ Chapter 6 - The Emacs Commune The AI Lab of the 1970s was by all accounts a special place. Cutting-edge projects and top-flight researchers gave it an esteemed position in the world of computer science. The internal hacker culture and its anarchic policies lent a rebellious mystique as well. Only later, when many of the lab's scientists and software superstars had departed, would hackers fully realize the unique and ephemeral world they had once inhabited. +={AI Lab (Artificial Intelligence Laboratory)+17} "It was a bit like the Garden of Eden," says Stallman, summing up the lab and its software-sharing ethos in a 1998 Forbes article. "It hadn't occurred to us not to cooperate."~{ See Josh McHugh, "For the Love of Hacking," Forbes (August 10, 1998).<br> http://www.forbes.com/forbes/1998/0810/6203094a.html }~ @@ -874,6 +887,7 @@ Although Stallman had been powerless to head off Reid's sale, he did possess the Over time, Emacs became a sales tool for the hacker ethic. The flexibility Stallman and built into the software not only encouraged collaboration, it demanded it. Users who didn't keep abreast of the latest developments in Emacs evolution or didn't contribute their contributions back to Stallman ran the risk of missing out on the latest breakthroughs. And the breakthroughs were many. Twenty years later, users had modified Emacs for so many different uses-using it as a spreadsheet, calculator, database, and web browser-that later Emacs developers adopted an overflowing sink to represent its versatile functionality. "That's the idea that we wanted to convey," says Stallman. "The amount of stuff it has contained within it is both wonderful and awful at the same time." Stallman's AI Lab contemporaries are more charitable. Hal Abelson, an MIT grad student who worked with Stallman during the 1970s and would later assist Stallman as a charter boardmember of the Free Software Foundation, describes Emacs as "an absolutely brilliant creation." In giving programmers a way to add new software libraries and features without messing up the system, Abelson says, Stallman paved the way for future large-scale collaborative software projects. "Its structure was robust enough that you'd have people all over the world who were loosely collaborating [and] contributing to it," Abelson says. "I don't know if that had been done before."~{ In writing this chapter, I've elected to focus more on the social significance of Emacs than the software significance. To read more about the software side, I recommend Stallman's 1979 memo. I particularly recommend the section titled "Research Through Development of Installed Tools" (#SEC27). Not only is it accessible to the nontechnical reader, it also sheds light on how closely intertwined Stallman's political philosophies are with his software-design philosophies. A sample excerpt follows:<br>_1 EMACS could not have been reached by a process of careful design, because such processes arrive only at goals which are visible at the outset, and whose desirability is established on the bottom line at the outset. Neither I nor anyone else visualized an extensible editor until I had made one, nor appreciated its value until he had experienced it. EMACS exists because I felt free to make individually useful small improvements on a path whose end was not in sight. }~ +={Abelson, Hal} Guy Steele expresses similar admiration. Currently a research scientist for Sun Microsystems, he remembers Stallman primarily as a "brilliant programmer with the ability to generate large quantities of relatively bug-free code." Although their personalities didn't exactly mesh, Steele and Stallman collaborated long enough for Steele to get a glimpse of Stallman's intense coding style. He recalls a notable episode in the late 1970s when the two programmers banded together to write the editor's "pretty print" feature. Originally conceived by Steele, pretty print was another keystroke-triggerd feature that reformatted Emacs' source code so that it was both more readable and took up less space, further bolstering the program's WYSIWIG qualities. The feature was strategic enough to attract Stallman's active interest, and it wasn't long before Steele wrote that he and Stallman were planning an improved version. @@ -898,10 +912,13 @@ Anticipating a skeptical response on some readers' part, the author made sure to _1 I am Richard Stallman, inventor of the original much-imitated EMACS editor, now at the Artificial Intelligence Lab at MIT. I have worked extensively on compilers, editors, debuggers, command interpreters, the Incompatible Timesharing System and the Lisp Machine operating system. I pioneered terminal-independent display support in ITS. In addition I have implemented one crashproof file system and two window systems for Lisp machines. ^44^ As fate would have it, Stallman's fanciful GNU Project missed its Thanksgiving launch date. By January, 1984, however, Stallman made good on his promise and fully immersed himself in the world of Unix software development. For a software architect raised on ITS, it was like designing suburban shopping malls instead of Moorish palaces. Even so, building a Unix-like operating system had its hidden advantages. ITS had been powerful, but it also possessed an Achilles' heel: MIT hackers had designed it to take specific advantage of the DEC-built PDP line. When AI Lab administrators elected to phase out the lab's powerful PDP-10 machine in the early 1980s, the operating system that hackers once likened to a vibrant city became an instant ghost town. Unix, on the other hand, was designed for mobility and long-term survival. Originally developed by junior scientists at AT&T, the program had slipped out under corporate-management radar, finding a happy home in the cash-strapped world of academic computer systems. With fewer resources than their MIT brethren, Unix developers had customized the software to ride atop a motley assortment of hardware systems: everything from the 16-bit PDP-11-a machine considered fit for only small tasks by most AI Lab hackers-to 32-bit mainframes such as the VAX 11/780. By 1983, a few companies, most notably Sun Microsystems, were even going so far as to develop a new generation of microcomputers, dubbed "workstations," to take advantage of the increasingly ubiquitous operating system. +={AT&T} To facilitate this process, the developers in charge of designing the dominant Unix strains made sure to keep an extra layer of abstraction between the software and the machine. Instead of tailoring the operating system to take advantage of a specific machine's resources-as the AI Lab hackers had done with ITS and the PDP-10-Unix developers favored a more generic, off-the-rack approach. Focusing more on the interlocking standards and specifications that held the operating system's many subcomponents together, rather than the actual components themselves, they created a system that could be quickly modified to suit the tastes of any machine. If a user quibbled with a certain portion, the standards made it possible to pull out an individual subcomponent and either fix it or replace it with something better. Simply put, what the Unix approach lacked in terms of style or aesthetics, it more than made up for in terms of flexibility and economy, hence its rapid adoption.~{ See Marshall Kirk McKusick, "Twenty Years of Berkeley Unix," Open Sources (O'Reilly & Associates, Inc., 1999): 38. }~ +={abstraction:designing Unix} Stallman's decision to start developing the GNU system was triggered by the end of the ITS system that the AI Lab hackers had nurtured for so long. The demise of ITS had been a traumatic blow to Stallman. Coming on the heels of the Xerox laser printer episode, it offered further evidence that the AI Lab hacker culture was losing its immunity to business practices in the outside world. +={AI Lab (Artificial Intelligence Laboratory):ITS demise+3} Like the software code that composed it, the roots of ITS' demise stretched way back. Defense spending, long a major font for computer-science research, had dried up during the post-Vietnam years. In a desperate quest for new funds, laboratories and universities turned to the private sector. In the case of the AI Lab, winning over private investors was an easy sell. Home to some of the most ambitious computer-science projects of the post-war era, the lab became a quick incubator of technology. Indeed, by 1980, most of the lab's staff, including many hackers, were dividing its time between Institute and commercial projects. @@ -922,6 +939,7 @@ Cadging passwords and deliberately crashing the system in order to glean evidenc "There has been another attempt to seize power," Stallman wrote. "So far, the aristocratic forces have been defeated." To protect his identity, Stallman signed the message "Radio Free OZ." The disguise was a thin one at best. By 1982, Stallman's aversion to passwords and secrecy had become so well known that users outside the AI Laboratory were using his account as a stepping stone to the ARPAnet, the research-funded computer network that would serve as a foundation for today's Internet. One such "tourist" during the early 1980s was Don Hopkins, a California programmer who learned through the hacking grapevine that all an outsider needed to do to gain access to MIT's vaunted ITS system was to log in under the initials RMS and enter the same three-letter monogram when the system requested a password. +={ARPAnet+2} "I'm eternally grateful that MIT let me and many other people use their computers for free," says Hopkins. "It meant a lot to many people." @@ -930,12 +948,16 @@ This so-called "tourist" policy, which had been openly tolerated by MIT manageme "[When] passwords first appeared at the MIT AI Lab I [decided] to follow my belief that there should be no passwords," Stallman would later say. "Because I don't believe that it's really desirable to have security on a computer, I shouldn't be willing to help uphold the security regime." ^46^ Stallman's refusal to bow before the great and powerful Oz symbolized the growing tension between hackers and AI Lab management during the early 1980s. This tension paled in comparison to the conflict that raged within the hacker community itself. By the time the KL-10 arrived, the hacker community had already divided into two camps. The first centered around a software company called Symbolics, Inc. The second centered around Symbolics chief rival, Lisp Machines, Inc. (LMI). Both companies were in a race to market the Lisp Machine, a device built to take full advantage of the Lisp programming language. +={Symbolics+15} Created by artificial-intelligence research pioneer John McCarthy, a MIT artificial-intelligence researcher during the late 1950s, Lisp is an elegant language well-suited for programs charged with heavy-duty sorting and processing. The language's name is a shortened version of LISt Processing. Following McCarthy's departure to the Stanford Artificial Intelligence Laboratory, MIT hackers refined the language into a local dialect dubbed MACLISP. The "MAC" stood for Project MAC, the DARPA-funded research project that gave birth to the AI Lab and the Laboratory for Computer Science. Led by AI Lab arch-hacker Richard Greenblatt, AI Lab programmers during the 1970s built up an entire Lisp-based operating system, dubbed the Lisp Machine operating system. By 1980, the Lisp Machine project had generated two commercial spin-offs. Symbolics was headed by Russell Noftsker, a former AI Lab administrator, and Lisp Machines, Inc., was headed by Greenblatt. The Lisp Machine software was hacker-built, meaning it was owned by MIT but available for anyone to copy as per hacker custom. Such a system limited the marketing advantage of any company hoping to license the software from MIT and market it as unique. To secure an advantage, and to bolster the aspects of the operating system that customers might consider attractive, the companies recruited various AI Lab hackers and set them working on various components of the Lisp Machine operating system outside the auspices of the AI Lab. The most aggressive in this strategy was Symbolics. By the end of 1980, the company had hired 14 AI Lab staffers as part-time consultants to develop its version of the Lisp Machine. Apart from Stallman, the rest signed on to help LMI.~{ See H. P. Newquist, The Brain Makers: Genius, Ego, and Greed in the Quest for Machines that Think (Sams Publishing, 1994): 172. }~ +={AI Lab (Artificial Intelligence Laboratory):Symbolics and+10} + +% Symbolics AI Lab longer range marked At first, Stallman accepted both companies' attempt to commercialize the Lisp machine, even though it meant more work for him. Both licensed the Lisp Machine OS source code from MIT, and it was Stallman's job to update the lab's own Lisp Machine to keep pace with the latest innovations. Although Symbolics' license with MIT gave Stallman the right to review, but not copy, Symbolics' source code, Stallman says a "gentleman's agreement" between Symbolics management and the AI Lab made it possible to borrow attractive snippets in traditional hacker fashion. @@ -968,6 +990,7 @@ Stallman would have little opportunity to mourn. The Lisp Machine, despite all t Riding atop this microprocessor wave were hundreds-thousands-of commercial software programs, each protected by a patchwork of user licenses and nondisclosure agreements that made it impossible for hackers to review or share source code. The licenses were crude and ill-fitting, but by 1983 they had become strong enough to satisfy the courts and scare away would-be interlopers. Software, once a form of garnish most hardware companies gave away to make their expensive computer systems more flavorful, was quickly becoming the main dish. In their increasing hunger for new games and features, users were putting aside the traditional demand to review the recipe after every meal. Nowhere was this state of affairs more evident than in the realm of personal computer systems. Companies such as Apple Computer and Commodore were minting fresh millionaires selling machines with built-in operating systems. Unaware of the hacker culture and its distaste for binary-only software, many of these users saw little need to protest when these companies failed to attach the accompanying source-code files. A few anarchic adherents of the hacker ethic helped propel that ethic into this new marketplace, but for the most part, the marketplace rewarded the programmers speedy enough to write new programs and savvy enough to copyright them as legally protected works. +={Apple Computers} One of the most notorious of these programmers was Bill Gates, a Harvard dropout two years Stallman's junior. Although Stallman didn't know it at the time, seven years before sending out his message to the n et.unix-wizards newsgroup, Gates, a budding entrepreneur and general partner with the Albuquerque-based software firm Micro-Soft, later spelled as Microsoft, had sent out his own open letter to the software-developer community. Written in response to the PC users copying Micro-Soft's software programs, Gates' " Open Letter to Hobbyists" had excoriated the notion of communal software development. @@ -1032,6 +1055,7 @@ Forced to watch his work sink into the mire while his erstwhile employer struggl 1~ Chapter 8 - St. Ignucius The Maui High Performance Computing Center is located in a single-story building in the dusty red hills just above the town of Kihei. Framed by million-dollar views and the multimillion dollar real estate of the Silversword Golf Course, the center seems like the ultimate scientific boondoggle. Far from the boxy, sterile confines of Tech Square or even the sprawling research metropolises of Argonne, Illinois and Los Alamos, New Mexico, the MHPCC seems like the kind of place where scientists spend more time on their tans than their post-doctoral research projects. +={Argonne (Illinois)} The image is only half true. Although researchers at the MHPCC do take advantage of the local recreational opportunities, they also take their work seriously. According to Top500.org, a web site that tracks the most powerful supercomputers in the world, the IBM SP Power3 supercomputer housed within the MHPCC clocks in at 837 billion floating-point operations per second, making it one of 25 most powerful computers in the world. Co-owned and operated by the University of Hawaii and the U.S. Air Force, the machine divides its computer cycles between the number crunching tasks associated with military logistics and high-temperature physics research. @@ -1093,7 +1117,7 @@ As if to drive home this message, Stallman punctuates his speech with an unusual "I am St. Ignucius of the Church of Emacs," says Stallman, raising his right hand in mock-blessing. "I bless your computer, my child." -{free_as_in_freedom_03_rms_st_ignucius.png 188x209 "Stallman dressed as St. Ignucius. Photo by Wouter van Oortmerssen." }http://www.free-culture.cc/ +{free_as_in_freedom_03_rms_st_ignucius.png 188x209 "Stallman dressed as St. Ignucius. Photo by Wouter van Oortmerssen." }http://en.wikipedia.org/wiki/Richard_stallman The laughter turns into full-blown applause after a few seconds. As audience members clap, the computer disk on Stallman's head catches the glare of an overhead light, eliciting a perfect halo effect. In the blink of an eye, Stallman goes from awkward haole to Russian religious icon. @@ -1221,12 +1245,14 @@ The German sociologist Max Weber once proposed that all great religions are buil While not religious per se, the GNU GPL certainly qualifies as an interesting example of this "routinization" process at work in the modern, decentralized world of software development. Since its unveiling, programmers and companies who have otherwise expressed little loyalty or allegiance to Stallman have willingly accepted the GPL bargain at face value. A few have even accepted the GPL as a preemptive protective mechanism for their own software programs. Even those who reject the GPL contract as too compulsory, still credit it as influential. One hacker falling into this latter group was Keith Bostic, a University of California employee at the time of the GPL 1.0 release. Bostic's department, the Computer Systems Research Group (SRG), had been involved in Unix development since the late 1970s and was responsible for many key parts of Unix, including the TCP/IP networking protocol, the cornerstone of modern Internet communications. By the late 1980s, AT&T, the original owner of the Unix brand name, began to focus on commercializing Unix and began looking to the Berkeley Software Distribution, or BSD, the academic version of Unix developed by Bostic and his Berkeley peers, as a key source of commercial technology. +={AT&T+1} Although the Berkeley BSD source code was shared among researchers and commercial programmers with a source-code license, this commercialization presented a problem. The Berkeley code was intermixed with proprietary AT&T code. As a result, Berkeley distributions were available only to institutions that already had a Unix source license from AT&T. As AT&T raised its license fees, this arrangement, which had at first seemed innocuous, became increasingly burdensome. Hired in 1986, Bostic had taken on the personal project of porting BSD over to the Digital Equipment Corporation's PDP-11 computer. It was during this period, Bostic says, that he came into close interaction with Stallman during Stallman's occasional forays out to the west coast. "I remember vividly arguing copyright with Stallman while he sat at borrowed workstations at CSRG," says Bostic. "We'd go to dinner afterward and continue arguing about copyright over dinner." The arguments eventually took hold, although not in the way Stallman would have liked. In June, 1989, Berkeley separated its networking code from the rest of the AT&T-owned operating system and distributed it under a University of California license. The contract terms were liberal. All a licensee had to do was give credit to the university in advertisements touting derivative programs.~{ The University of California's "obnoxious advertising clause" would later prove to be a problem. Looking for a less restrictive alternative to the GPL, some hackers used the University of California, replacing "University of California" with the name of their own instution. The result: free software programs that borrowed from dozens of other programs would have to cite dozens of institutions in advertisements. In 1999, after a decade of lobbying on Stallman's part, the University of California agreed to drop this clause.<br>See "The BSD License Problem" at http://www.gnu.org/philosophy/bsd.html. }~ In contrast to the GPL, proprietary offshoots were permissible. Only one problem hampered the license's rapid adoption: the BSD Networking release wasn't a complete operating system. People could study the code, but it could only be run in conjunction with other proprietary-licensed code. +={AT&T+1} Over the next few years, Bostic and other University of California employees worked to replace the missing components and turn BSD into a complete, freely redistributable operating system. Although delayed by a legal challenge from Unix Systems Laboratories-the AT&T spin-off that retained ownership of the Unix brand name-the effort would finally bear fruit in the early 1990s. Even before then, however, many of the Berkeley utilities would make their way into Stallman's GNU Project. @@ -1269,6 +1295,7 @@ According to Stallman, improving software programs was secondary to building the Nevertheless, as GNU tools made their mark in the late 1980s, Stallman's AI Lab-honed reputation for design fastidiousness soon became legendary throughout the entire software-development community. Jeremy Allison, a Sun user during the late 1980s and programmer destined to run his own free software project, Samba, in the 1990s, recalls that reputation with a laugh. During the late 1980s, Allison began using Emacs. Inspired by the program's community-development model, Allison says he sent in a snippet of source code only to have it rejected by Stallman. +={Allison, Jeramy+1} "It was like the Onion headline," Allison says. "`Child's prayers to God answered: No.'" @@ -1276,7 +1303,8 @@ Stallman's growing stature as a software programmer, however, was balanced by hi A review of GNU Project "GNUsletters" of the late 1980s reflects the management tension. In January, 1987, Stallman announced to the world that the GNU Project was working to overhaul TRIX, a Unix kernel developed at MIT. A year later, in February of 1988, the GNU Project announced that it had shifted its attentions to Mach, a lightweight "micro-kernel" developed at Carnegie Mellon. All told, however, official GNU Project kernel development wouldn't commence until 1990.~{ See "HURD History."<br> http://www.gnu.org/software/hurd/history.html }~ -The delays in kernel development were just one of many concerns weighing on Stallman during this period. In 1989, Lotus Development Corporation filed suit against rival software company, Paperback Software International, for copying menu commands in Lotus' popular 1-2-3 Spreadsheet program. Lotus' suit, coupled with the Apple -Microsoft "look and feel" battle, provided a troublesome backdrop for the GNU Project. Although both suits fell outside the scope of the GNU Project, both revolved around operating systems and software applications developed for the personal computer, not Unix-compatible hardware systems-they threatened to impose a chilling effect on the entire culture of software development. Determined to do something, Stallman recruited a few programmer friends and composed a magazine ad blasting the lawsuits. He then followed up the ad by helping to organize a group to protest the corporations filing the suit. Calling itself the League of Programming Freedom, the group held protests outside the offices of Lotus, Inc. and the Boston courtroom hosting the Lotus trial. +The delays in kernel development were just one of many concerns weighing on Stallman during this period. In 1989, Lotus Development Corporation filed suit against rival software company, Paperback Software International, for copying menu commands in Lotus' popular 1-2-3 Spreadsheet program. Lotus' suit, coupled with the Apple-Microsoft "look and feel" battle, provided a troublesome backdrop for the GNU Project. Although both suits fell outside the scope of the GNU Project, both revolved around operating systems and software applications developed for the personal computer, not Unix-compatible hardware systems-they threatened to impose a chilling effect on the entire culture of software development. Determined to do something, Stallman recruited a few programmer friends and composed a magazine ad blasting the lawsuits. He then followed up the ad by helping to organize a group to protest the corporations filing the suit. Calling itself the League of Programming Freedom, the group held protests outside the offices of Lotus, Inc. and the Boston courtroom hosting the Lotus trial. +={Apple Computers} The protests were notable.~{ According to a League of Programming Freedom Press, the protests were notable for featuring the first hexadecimal protest chant:<br>1-2-3-4, toss the lawyers out the door;<br>5-6-7-8, innovate don't litigate;<br>9-A-B-C, 1-2-3 is not for me;<br>D-E-F-O, look and feel have got to go<br> http://lpf.ai.mit.edu/Links/prep.ai.mit.edu/demo.final.release }~ They document the evolving nature of software industry. Applications had quietly replaced operating systems as the primary corporate battleground. In its unfulfilled quest to build a free software operating system, the GNU Project seemed hopelessly behind the times. Indeed, the very fact that Stallman had felt it necessary to put together an entirely new group dedicated to battling the "look and feel" lawsuits reinforced that obsolescence in the eyes of some observers. @@ -1469,6 +1497,7 @@ Summarized Raymond, "I think Linus's cleverest and most consequential hack was n In summarizing the secrets of Torvalds' managerial success, Raymond himself had pulled off a coup. One of the audience members at the Linux Kongress was Tim O'Reilly, publisher of O'Reilly & Associates, a company specializing in software manuals and software-related books (and the publisher of this book). After hearing Raymond's Kongress speech, O'Reilly promptly invited Raymond to deliver it again at the company's inaugural Perl Conference later that year in Monterey, California. Although the conference was supposed to focus on Perl, a scripting language created by Unix hacker Larry Wall, O'Reilly assured Raymond that the conference would address other free software technologies. Given the growing commercial interest in Linux and Apache, a popular free software web server, O'Reilly hoped to use the event to publicize the role of free software in creating the entire infrastructure of the Internet. From web-friendly languages such as Perl and Python to back-room programs such as BIND (the Berkeley Internet Naming Daemon), a software tool that lets users replace arcane IP numbers with the easy-to-remember domain-name addresses (e.g., amazon.com), and sendmail, the most popular mail program on the Internet, free software had become an emergent phenomenon. Like a colony of ants creating a beautiful nest one grain of sand at a time, the only thing missing was the communal self-awareness. O'Reilly saw Raymond's speech as a good way to inspire that self-awareness, to drive home the point that free software development didn't start and end with the GNU Project. Programming languages, such as Perl and Python, and Internet software, such as BIND, sendmail, and Apache, demonstrated that free software was already ubiquitous and influential. He also assured Raymond an even warmer reception than the one at Linux Kongress. +={Apache web server} O'Reilly was right. "This time, I got the standing ovation before the speech," says Raymond, laughing. @@ -1477,8 +1506,10 @@ As predicted, the audience was stocked not only with hackers, but with other peo Intrigued by Raymond's speech and anxious to win back lost market share, Netscape executives took the message back to corporate headquarters. A few months later, in January, 1998, the company announced its plan to publish the source code of its flagship Navigator web browser in the hopes of enlisting hacker support in future development. When Netscape CEO Jim Barksdale cited Raymond's "Cathedral and the Bazaar" essay as a major influence upon the company's decision, the company instantly elevated Raymond to the level of hacker celebrity. Determined not to squander the opportunity, Raymond traveled west to deliver interviews, advise Netscape executives, and take part in the eventual party celebrating the publication of Netscape Navigator's source code. The code name for Navigator's source code was "Mozilla": a reference both to the program's gargantuan size-30 million lines of code-and to its heritage. Developed as a proprietary offshoot of Mosaic, the web browser created by Marc Andreessen at the University of Illinois, Mozilla was proof, yet again, that when it came to building new programs, most programmers preferred to borrow on older, modifiable programs. +={Andreessen, Marc} While in California, Raymond also managed to squeeze in a visit to VA Research, a Santa Clara-based company selling workstations with the GNU/Linux operating system preinstalled. Convened by Raymond, the meeting was small. The invite list included VA founder Larry Augustin, a few VA employees, and Christine Peterson, president of the Foresight Institute, a Silicon Valley think tank specializing in nanotechnology. +={Augustin, Larry} "The meeting's agenda boiled down to one item: how to take advantage of Netscape's decision so that other companies might follow suit?" Raymond doesn't recall the conversation that took place, but he does remember the first complaint addressed. Despite the best efforts of Stallman and other hackers to remind people that the word "free" in free software stood for freedom and not price, the message still wasn't getting through. Most business executives, upon hearing the term for the first time, interpreted the word as synonymous with "zero cost," tuning out any follow up messages in short order. Until hackers found a way to get past this cognitive dissonance, the free software movement faced an uphill climb, even after Netscape. @@ -1519,6 +1550,7 @@ Summing up his position at the 1999 LinuxWorld Convention and Expo, an event bil "Because we've shown how much we can do, we don't have to be desperate to work with companies or compromise our goals," Stallman said during a panel discussion. "Let them offer and we'll accept. We don't have to change what we're doing to get them to help us. You can take a single step towards a goal, then another and then more and more and you'll actually reach your goal. Or, you can take a half measure that means you don't ever take another step and you'll never get there." Even before the LinuxWorld show, however, Stallman was showing an increased willingness to alienate his more conciliatory peers. A few months after the Freeware Summit, O'Reilly hosted its second annual Perl Conference. This time around, Stallman was in attendance. During a panel discussion lauding IBM's decision to employ the free software Apache web server in its commercial offerings, Stallman, taking advantage of an audience microphone, disrupted the proceedings with a tirade against panelist John Ousterhout, creator of the Tcl scripting language. Stallman branded Ousterhout a "parasite" on the free software community for marketing a proprietary version of Tcl via Ousterhout's startup company, Scriptics. "I don't think Scriptics is necessary for the continued existence of Tcl," Stallman said to hisses from the fellow audience members. ^98^ +={Apache web server} "It was a pretty ugly scene," recalls Prime Time Freeware's Rich Morin. "John's done some pretty respectable things: Tcl, Tk, Sprite. He's a real contributor." @@ -1530,6 +1562,7 @@ http://www.opensource.org/docs/definition.html }~ Perens would later resign from the OSI, expressing regret that the organization had set itself up in opposition to Stallman and the FSF. Still, looking back on the need for a free software definition outside the Free Software Foundation's auspices, Perens understands why other hackers might still feel the need for distance. "I really like and admire Richard," says Perens. "I do think Richard would do his job better if Richard had more balance. That includes going away from free software for a couple of months." Stallman's monomaniacal energies would do little to counteract the public-relations momentum of open source proponents. In August of 1998, when chip-maker Intel purchased a stake in GNU/Linux vendor Red Hat, an accompanying New York Times article described the company as the product of a movement "known alternatively as free software and open source."~{ See Amy Harmon, "For Sale: Free Operating System," New York Times (September 28, 1998).<br> http://www.nytimes.com/library/tech/98/09/biztech/articles/28linux.html }~ Six months later, a John Markoff article on Apple Computer was proclaiming the company's adoption of the "open source" Apache server in the article headline.~{ See John Markoff, "Apple Adopts `Open Source' for its Server Computers," New York Times (March 17, 1999).<br> http://www.nytimes.com/library/tech/99/03/biztech/articles/17apple.html }~ +={Apache web server;Apple Computers:open source software and} Such momentum would coincide with the growing momentum of companies that actively embraced the "open source" term. By August of 1999, Red Hat, a company that now eagerly billed itself as "open source," was selling shares on Nasdaq. In December, VA Linux-formerly VA Research-was floating its own IPO to historical effect. Opening at $30 per share, the company's stock price exploded past the $300 mark in initial trading only to settle back down to the $239 level. Shareholders lucky enough to get in at the bottom and stay until the end experienced a 698% increase in paper wealth, a Nasdaq record. @@ -1702,6 +1735,7 @@ Moglen says that moment, more than any other, drove home the elemental simplicit Writing the biography of a living person is a bit like producing a play. The drama in front of the curtain often pales in comparison to the drama backstage. In The Autobiography of Malcolm X, Alex Haley gives readers a rare glimpse of that backstage drama. Stepping out of the ghostwriter role, Haley delivers the book's epilogue in his own voice. The epilogue explains how a freelance reporter originally dismissed as a "tool" and "spy" by the Nation of Islam spokesperson managed to work through personal and political barriers to get Malcolm X's life story on paper. +={Autobiography of Malcolm X, The (Haley)+1} While I hesitate to compare this book with The Autobiography of Malcolm X, I do owe a debt of gratitude to Haley for his candid epilogue. Over the last 12 months, it has served as a sort of instruction manual on how to deal with a biographical subject who has built an entire career on being disagreeable. From the outset, I envisioned closing this biography with a similar epilogue, both as an homage to Haley and as a way to let readers know how this book came to be. @@ -1775,6 +1809,7 @@ I made a few more suggestions with little effect. About the only thing I could g Before I signed off, Stallman suggested I tell the publisher that I'd promised Stallman that the work would be free. I told Stallman I couldn't agree to that statement but that I did view the book as unfinishable without his cooperation. Seemingly satisfied, Stallman hung up with his usual sign-off line: "Happy hacking." Henning and I met with Tracy the next day. Tracy said her company was willing to publish copyable excerpts in a unencrypted format but would limit the excerpts to 500 words. Henning informed her that this wouldn't be enough for me to get around my ethical obligation to Stallman. Tracy mentioned her own company's contractual obligation to online vendors such as Amazon.com. Even if the company decided to open up its e-book content this one time, it faced the risk of its partners calling it a breach of contract. Barring a change of heart in the executive suite or on the part of Stallman, the decision was up to me. I could use the interviews and go against my earlier agreement with Stallman, or I could plead journalistic ethics and back out of the verbal agreement to do the book. +={Amazon.com} Following the meeting, my agent and I relocated to a pub on Third Ave. I used his cell phone to call Stallman, leaving a message when nobody answered. Henning left for a moment, giving me time to collect my thoughts. When he returned, he was holding up the cell phone. @@ -1870,7 +1905,7 @@ Afterwards, when the dinner was complete and Sarah had departed, Stallman seemed Before parting, Stallman handed me his "pleasure card," a business card listing Stallman's address, phone number, and favorite pastimes ("sharing good books, good food and exotic music and dance") so that I might set up a final interview. -{free_as_in_freedom_04_rms_pleasure_card.png 355x207 "Stallman's 'pleasure' card, handed to me the night of our dinner." }http://www.free-culture.cc/ +{free_as_in_freedom_04_rms_pleasure_card.png 355x207 "Stallman's 'pleasure' card, handed to me the night of our dinner." }http://en.wikipedia.org/wiki/Richard_stallman The next day, over another meal of dim sum, Stallman seemed even more lovestruck than the night before. Recalling his debates with Currier House dorm maters over the benefits and drawbacks of an immortality serum, Stallman expressed hope that scientists might some day come up with the key to immortality. "Now that I'm finally starting to have happiness in my life, I want to have more," he said. @@ -1898,7 +1933,8 @@ A similar situation surrounds the terms "free software" and "open source." Again To understand the full meaning of the word " hacker," it helps to examine the word's etymology over the years. -The New Hacker Dictionary, an online compendium of software-programmer jargon, officially lists nine different connotations of the word "hack" and a similar number for "hacker." Then again, the same publication also includes an accompanying essay that quotes Phil Agre, an MIT hacker who warns readers not to be fooled by the word's perceived flexibility. "Hack has only one meaning," argues Agre. "An extremely subtle and profound one which defies articulation." +/{The New Hacker Dictionary}/, an online compendium of software-programmer jargon, officially lists nine different connotations of the word "hack" and a similar number for "hacker." Then again, the same publication also includes an accompanying essay that quotes Phil Agre, an MIT hacker who warns readers not to be fooled by the word's perceived flexibility. "Hack has only one meaning," argues Agre. "An extremely subtle and profound one which defies articulation." +={Agre, Phil} Regardless of the width or narrowness of the definition, most modern hackers trace the word back to MIT, where the term bubbled up as popular item of student jargon in the early 1950s. In 1990 the MIT Museum put together a journal documenting the hacking phenomenon. According to the journal, students who attended the institute during the fifties used the word "hack" the way a modern student might use the word "goof." Hanging a jalopy out a dormitory window was a "hack," but anything harsh or malicious-e.g., egging a rival dorm's windows or defacing a campus statue-fell outside the bounds. Implicit within the definition of "hack" was a spirit of harmless, creative fun. @@ -1921,6 +1957,7 @@ It is a testament to the original computer hackers' prodigious skill that later As the definition tightened, "computer" hacking acquired additional semantic overtones. To be a hacker, a person had to do more than write interesting software; a person had to belong to the hacker "culture" and honor its traditions the same way a medieval wine maker might pledge membership to a vintners' guild. The social structure wasn't as rigidly outlined as that of a guild, but hackers at elite institutions such as MIT, Stanford, and Carnegie Mellon began to speak openly of a "hacker ethic": the yet-unwritten rules that governed a hacker's day-to-day behavior. In the 1984 book Hackers, author Steven Levy, after much research and consultation, codified the hacker ethic as five core hacker tenets. In many ways, the core tenets listed by Levy continue to define the culture of computer hacking. Still, the guild-like image of the hacker community was undermined by the overwhelmingly populist bias of the software industry. By the early 1980s, computers were popping up everywhere, and programmers who once would have had to travel to top-rank institutions or businesses just to gain access to a machine suddenly had the ability to rub elbows with major-league hackers via the ARPAnet. The more these programmers rubbed elbows, the more they began to appropriate the anarchic philosophies of the hacker culture in places like MIT. Lost within the cultural transfer, however, was the native MIT cultural taboo against malicious behavior. As younger programmers began employing their computer skills to harmful ends-creating and disseminating computer viruses, breaking into military computer systems, deliberately causing machines such as MIT Oz, a popular ARPAnet gateway, to crash-the term "hacker" acquired a punk, nihilistic edge. When police and businesses began tracing computer-related crimes back to a few renegade programmers who cited convenient portions of the hacking ethic in defense of their activities, the word "hacker" began appearing in newspapers and magazine stories in a negative light. Although books like Hackers did much to document the original spirit of exploration that gave rise to the hacking culture, for most news reporters, "computer hacker" became a synonym for "electronic burglar." +={ARPAnet} Although hackers have railed against this perceived misusage for nearly two decades, the term's rebellious connotations dating back to the 1950s make it hard to discern the 15-year-old writing software programs that circumvent modern encryption programs from the 1960s college student, picking locks and battering down doors to gain access to the lone, office computer terminal. One person's creative subversion of authority is another person's security headache, after all. Even so, the central taboo against malicious or deliberately harmful behavior remains strong enough that most hackers prefer to use the term " cracker"-i.e., a person who deliberately cracks a computer security system to steal or vandalize data-to describe the subset of hackers who apply their computing skills maliciously. diff --git a/data/doc/sisu/sisu_markup_samples/sisu_manual/sisu_markup.sst b/data/doc/sisu/sisu_markup_samples/sisu_manual/sisu_markup.sst index 32659adf..09a8f427 100644 --- a/data/doc/sisu/sisu_markup_samples/sisu_manual/sisu_markup.sst +++ b/data/doc/sisu/sisu_markup_samples/sisu_manual/sisu_markup.sst @@ -39,7 +39,7 @@ { 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/ -% @prefix: +% @prefix: :A~? @title @creator @@ -1057,6 +1057,70 @@ code{ }code +2~ Book index + +To make an index append to paragraph the book index term relates to it, using an equal sign and curly braces. + +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. + +code{ + + Paragraph containing main term and sub-term. + ={Main term:sub-term} + +}code + +The index syntax starts on a new line, but there should not be an empty line between paragraph and index markup. + +The structure of the resulting index would be: + +code{ + + Main term, 1 + sub-term, 1 + +}code + +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. + +code{ + + Paragraph containing main term, second term and sub-term. + ={first term; second term: sub-term} + +}code + +The structure of the resulting index would be: + +code{ + + First term, 1, + Second term, 1, + sub-term, 1 + +}code + +If multiple sub-terms appear under one paragraph, they are separated under the main term heading from each other by a pipe symbol. + +code{ + + 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 + +}code + +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: + +code{ + + Main term, 1, + sub-term, 1-3, + second sub-term, 1, + +}code + 1~ Composite documents markup 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 *{.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 *{.sst}* regular markup file, or *{.ssi}* (insert/information) A secondary file of the composite document is built prior to processing with the same prefix and the suffix *{._sst}* @@ -1143,7 +1207,7 @@ and code{ -~[* my note ]~ or ~[+ another note ]~ +~[* my note ]~ or ~[+ another note ]~ }code |