diff options
| author | Ralph Amissah <ralph@amissah.com> | 2013-05-29 21:26:39 -0400 |
|---|---|---|
| committer | Ralph Amissah <ralph@amissah.com> | 2013-05-29 21:26:39 -0400 |
| commit | 2576dab17c3397d23c34dfead092bf51da18184d (patch) | |
| tree | aa8c1cdc010a1204e7cb3e3dfb862b684eed5d8d | |
| parent | debian/changelog (4.1.1-1) (diff) | |
| parent | v4 v5: help, documentation update, concentrate on man pages (diff) | |
Merge tag 'sisu_4.1.2' into debian/sid
SiSU 4.1.2
36 files changed, 776 insertions, 7722 deletions
diff --git a/data/doc/sisu/CHANGELOG_v4 b/data/doc/sisu/CHANGELOG_v4 index 78b7f0fe..5a39dd6f 100644 --- a/data/doc/sisu/CHANGELOG_v4 +++ b/data/doc/sisu/CHANGELOG_v4 @@ -23,6 +23,30 @@ v2 branch is removed; it is available in sisu =< 3.3.2 %% Reverse Chronological: +%% 4.1.2.orig.tar.xz (2013-05-29:21/3) +http://sources.sisudoc.org/gitweb/?p=code/sisu.git;a=shortlog;h=refs/tags/sisu_4.1.2 +http://sources.sisudoc.org/gitweb/?p=code/sisu.git;a=shortlog;h=refs/tags/debian/sisu_4.1.2-1 +http://www.jus.uio.no/sisu/pkg/src/sisu_4.1.2.orig.tar.xz + sisu_4.1.2.orig.tar.xz + sisu_4.1.2-1.dsc + +* help update, concentrate on man pages + * documentation, manpage update + * interactive help, out of date, removed + +* document version check, disable + * automatic check disabled + * check and correction of pre 0.38 markup removed + +* sysenv, version info moved here from help + +* cgi helper script sample search form generator, adjust/improve, adds settings: + db type --db-pq or db-sqlite + webserver for cgi script & db --webserv-search='' + webserver for sisu ouptut files --webserv-output='' + cgi search form link name --cgi-search-form-name='' + db user (pg) --db-user='' + %% 4.1.1.orig.tar.xz (2013-05-19:19/7) http://sources.sisudoc.org/gitweb/?p=code/sisu.git;a=shortlog;h=refs/tags/sisu_4.1.1 http://sources.sisudoc.org/gitweb/?p=code/sisu.git;a=shortlog;h=refs/tags/debian/sisu_4.1.1-1 diff --git a/data/doc/sisu/CHANGELOG_v5 b/data/doc/sisu/CHANGELOG_v5 index 7d77f8b2..7e788f54 100644 --- a/data/doc/sisu/CHANGELOG_v5 +++ b/data/doc/sisu/CHANGELOG_v5 @@ -23,6 +23,30 @@ v2 branch is removed; it is available in sisu =< 3.3.2 %% Reverse Chronological: +%% 5.0.2.orig.tar.xz (2013-05-29:21/3) +http://sources.sisudoc.org/gitweb/?p=code/sisu.git;a=shortlog;h=refs/tags/sisu_5.0.2 +http://sources.sisudoc.org/gitweb/?p=code/sisu.git;a=shortlog;h=refs/tags/debian/sisu_5.0.2-1 +http://www.jus.uio.no/sisu/pkg/src/sisu_5.0.2.orig.tar.xz + sisu_5.0.2.orig.tar.xz + sisu_5.0.2-1.dsc + +* help update, concentrate on man pages + * documentation, manpage update + * interactive help, out of date, removed + +* document version check, disable + * automatic check disabled + * check and correction of pre 0.38 markup removed + +* sysenv, version info moved here from help + +* cgi helper script sample search form generator, adjust/improve, adds settings: + db type --db-pq or db-sqlite + webserver for cgi script & db --webserv-search='' + webserver for sisu ouptut files --webserv-output='' + cgi search form link name --cgi-search-form-name='' + db user (pg) --db-user='' + %% 5.0.1.orig.tar.xz (2013-05-18:19/7) http://sources.sisudoc.org/gitweb/?p=code/sisu.git;a=shortlog;h=refs/tags/sisu_5.0.1 http://sources.sisudoc.org/gitweb/?p=code/sisu.git;a=shortlog;h=refs/tags/debian/sisu_5.0.1-1 diff --git a/data/doc/sisu/html/sisu.1.html b/data/doc/sisu/html/sisu.1.html index 56535d2e..6f4eb681 100644 --- a/data/doc/sisu/html/sisu.1.html +++ b/data/doc/sisu/html/sisu.1.html @@ -296,8 +296,7 @@ affects html (seg), epub) ; see also --inc-* </dd> match given string in directory (including language subdirectories). Alias -f, --glob, -G </dd> -<dt><b>-G [optional string part of filename]</b> -</dt> +<dt><b>-G [optional string part of filename]</b> </dt> <dd>see --find </dd> <dt><b>-g [filename/wildcard]</b> </dt> @@ -309,7 +308,7 @@ structure in a git repo (experimental and subject to change). Alias -g </dd> <dt><b>--glob [optional string part of filename]</b> </dt> -<dd>see --find</dd> +<dd>see --find </dd> <dt><b>-h [filename/wildcard]</b> </dt> <dd>see --html </dd> @@ -375,9 +374,8 @@ invoked by --dump & redirect). </dd> <dd>see --dal (document abstraction level/layer) </dd> <dt><b>--maintenance [filename/wildcard/url]</b> </dt> -<dd>maintenance mode, interim -processing files are preserved and their locations indicated. (also see --V). Aliases -M and --keep-processing-files. </dd> +<dd>maintenance mode, interim processing files are preserved and their locations +indicated. (also see -V). Aliases -M and --keep-processing-files. </dd> <dt><b>--manpage [filename/wildcard]</b> </dt> <dd>produces man page of file, not suitable for all outputs. Alias -i </dd> @@ -531,33 +529,39 @@ with other flags, it is not). Also see --scp. Alias -R </dd> <dt><b>-s [filename/wildcard]</b> </dt> <dd>see --source </dd> -<dt><b>--sample-search-form [--webserv=webrick]</b> </dt> -<dd>generate examples of (naive) cgi search form for <i>SQLite</i> and PgSQL depends -on your already having used sisu to populate an <i>SQLite</i> and/or PgSQL database, -(the <i>SQLite</i> version scans the output directories for existing sisu_sqlite -databases, so it is first necessary to create them, before generating the -search form) see -d -D and the database section below. If the optional parameter ---webserv=webrick is passed, the cgi examples created will be set up to use -the default port set for use by the webrick server, (otherwise the port -is left blank and the system setting used, usually 80). The samples are -dumped in the present work directory which must be writable, (with screen -instructions given that they be copied to the cgi-bin directory). Alias -F </dd> - -<dt><b>--scp [filename/wildcard]</b> </dt> -<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 have your "keys" and ssh agent in place. Also -see --rsync. Alias -r </dd> - -<dt><b>--sqlite --[instruction] [filename]</b> </dt> -<dd>database type set to -<i>SQLite,</i> this produces one of two possible databases, without additional -database related instructions it produces a discreet <i>SQLite</i> file for the -document processed; with additional instructions it produces a common <i>SQLite</i> -database of all processed documents that (come from the same document preparation -directory and as a result) share the same output directory base path (possible -instructions include: --createdb; --create; --dropall; --import [filename]; --update -[filename]; --remove [filename]); see database section below. Alias -d </dd> +<dt><b>--sample-search-form [--db=(pgsql|sqlite)] +[--webserv=webrick]</b> </dt> +<dd>generate examples of (naive) cgi search form for <i>SQLite</i> +or PgSQL depends on your already having used sisu to populate an <i>SQLite</i> +or PgSQL database, (the <i>SQLite</i> version scans the output directories for +existing sisu_sqlite databases, so it is first necessary to create them, +before generating the search form) see --sqlite & --pg and the database section +below. Optional additional parameters include: url location of webserver +search form and db: --webserv-search=’[url]’; location of webserver output: +--webserv-output=’[url]’; cgi search form link name: --cgi-search-form-name=’[name.cgi]’; +for pgsql, database user: --db-user=’[username]’. If the optional parameter --webserv=webrick +is passed, the cgi examples created will be set up to use the default port +set for use by the webrick server, (otherwise the port is left blank and +the system setting used, usually 80). The samples are dumped in the present +work directory which must be writable, (with screen instructions given +that they be copied to the cgi-bin directory). Alias -F </dd> + +<dt><b>--scp [filename/wildcard]</b> +</dt> +<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 +have your "keys" and ssh agent in place. Also see --rsync. Alias -r </dd> + +<dt><b>--sqlite --[instruction] +[filename]</b> </dt> +<dd>database type set to <i>SQLite,</i> this produces one of two possible +databases, without additional database related instructions it produces +a discreet <i>SQLite</i> file for the document processed; with additional instructions +it produces a common <i>SQLite</i> database of all processed documents that (come +from the same document preparation directory and as a result) share the +same output directory base path (possible instructions include: --createdb; +--create; --dropall; --import [filename]; --update [filename]; --remove [filename]); +see database section below. Alias -d </dd> <dt><b>--sisupod</b> </dt> <dd>produces a sisupod a zipped sisu directory of markup files including sisu @@ -566,23 +570,23 @@ and skins. Note: this only includes the configuration files or skins contained in is tested only with zsh). Alias -S </dd> <dt><b>--sisupod [filename/wildcard]</b> </dt> -<dd>produces -a zipped file of the prepared document specified along with associated -images, by default named sisupod.zip they may alternatively be named with -the filename extension .ssp This provides a quick way of gathering the relevant -parts of a sisu document which can then for example be emailed. A sisupod -includes sisu markup source file, (along with associated documents if a -master file, or available in multilingual versions), together with related -images and skin. <b>SiSU</b> commands can be run directly against a sisupod contained -in a local directory, or provided as a url on a remote site. As there is -a security issue with skins provided by other users, they are not applied -unless the flag --trust or --trusted is added to the command instruction, it -is recommended that file that are not your own are treated as untrusted. -The directory structure of the unzipped file is understood by sisu, and -sisu commands can be run within it. Note: if you wish to send multiple files, -it quickly becomes more space efficient to zip the sisu markup directory, -rather than the individual files for sending). See the -S option without -[filename/wildcard]. Alias -S </dd> +<dd>produces a zipped file of +the prepared document specified along with associated images, by default +named sisupod.zip they may alternatively be named with the filename extension +.ssp This provides a quick way of gathering the relevant parts of a sisu +document which can then for example be emailed. A sisupod includes sisu +markup source file, (along with associated documents if a master file, +or available in multilingual versions), together with related images and +skin. <b>SiSU</b> commands can be run directly against a sisupod contained in a +local directory, or provided as a url on a remote site. As there is a security +issue with skins provided by other users, they are not applied unless the +flag --trust or --trusted is added to the command instruction, it is recommended +that file that are not your own are treated as untrusted. The directory +structure of the unzipped file is understood by sisu, and sisu commands +can be run within it. Note: if you wish to send multiple files, it quickly +becomes more space efficient to zip the sisu markup directory, rather than +the individual files for sending). See the -S option without [filename/wildcard]. +Alias -S </dd> <dt><b>--source [filename/wildcard]</b> </dt> <dd>copies sisu markup file to output directory. Alias -s </dd> @@ -594,16 +598,15 @@ rather than the individual files for sending). See the -S option without <dd>see --txt </dd> <dt><b>--texinfo [filename/wildcard]</b> </dt> -<dd>produces texinfo and info file, (view with -pinfo). Alias -I </dd> +<dd>produces texinfo and info file, (view with pinfo). Alias -I </dd> <dt><b>--txt [filename/wildcard]</b> </dt> -<dd>produces <i>plaintext</i> with Unix linefeeds -and without markup, (object numbers are omitted), has footnotes at end -of each paragraph that contains them [ -A for equivalent dos (linefeed) -output file] [see -e for endnotes]. (Options include: --endnotes for endnotes ---footnotes for footnotes at the end of each paragraph --unix for unix linefeed -(default) --msdos for msdos linefeed). Alias -t </dd> +<dd>produces <i>plaintext</i> with Unix linefeeds and without markup, (object numbers +are omitted), has footnotes at end of each paragraph that contains them +[ -A for equivalent dos (linefeed) output file] [see -e for endnotes]. (Options +include: --endnotes for endnotes --footnotes for footnotes at the end of each +paragraph --unix for unix linefeed (default) --msdos for msdos linefeed). Alias +-t </dd> <dt><b>-U [filename/wildcard]</b> </dt> <dd>see --urls </dd> @@ -613,14 +616,13 @@ output file] [see -e for endnotes]. (Options include: --endnotes for endnotes requested for processing, also see -U </dd> <dt><b>--urls [filename/wildcard]</b> </dt> -<dd>prints url -output list/map for the available processing flags options and resulting -files that could be requested, (can be used to get a list of processing -options in relation to a file, together with information on the output -that would be produced), -u provides url output mapping for those flags -requested for processing. The default assumes sisu_webrick is running and -provides webrick url mappings where appropriate, but these can be switched -to file system paths in sisurc.yml. Alias -U </dd> +<dd>prints url output list/map for the available processing +flags options and resulting files that could be requested, (can be used +to get a list of processing options in relation to a file, together with +information on the output that would be produced), -u provides url output +mapping for those flags requested for processing. The default assumes sisu_webrick +is running and provides webrick url mappings where appropriate, but these +can be switched to file system paths in sisurc.yml. Alias -U </dd> <dt><b>-V</b> </dt> <dd>on its own, provides <b>SiSU</b> version @@ -872,49 +874,30 @@ sisu man pages <<a href='http://www.jus.uio.no/sisu/man/'>http://www.jus.uio. > [^10] <p> -<h2><a name='sect15' href='#toc15'>Sisu Built-in Interactive Help</a></h2> - -<p> This is particularly useful for getting -the current sisu setup/environment information: -<p> sisu --help -<p> sisu --help -[subject] -<p> sisu --help commands -<p> sisu --help markup -<p> sisu --help env [for -feedback on the way your system is setup with regard to sisu ]<br> - -<p> sisu -V [environment information, same as above command] -<p> sisu (on its -own provides version and some help information) -<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). -<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. -<h2><a name='sect16' href='#toc16'>Introduction -to Sisu Markup[^11]</a></h2> +<h2><a name='sect15' href='#toc15'>Sisu Built-in Interactive Help, [discontinued]</a></h2> + +<p> This fell out of date +and has been discontinued. +<h2><a name='sect16' href='#toc16'>Introduction to Sisu Markup[^11]</a></h2> <p> <h2><a name='sect17' href='#toc17'>Summary</a></h2> -<p> <b>SiSU</b> source documents are <i>plaintext</i> ( <i>UTF-8</i> -)[^12] files -<p> All paragraphs are separated by an empty 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) -<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: -<p> * heading levels defines document -structure<br> +<p> <b>SiSU</b> +source documents are <i>plaintext</i> ( <i>UTF-8</i> )[^12] files +<p> All paragraphs are +separated by an empty 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) +<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: +<p> * heading +levels defines document structure<br> <p> * text basic attributes, italics, bold etc.<br> @@ -2040,12 +2023,11 @@ if a .sst file is renamed .ssm without requiring any other documents; the .ssm marker flags that the document may 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 [^18] -<p> +with the same prefix and the suffix ._sst [^19] <h2><a name='sect49' href='#toc49'>Sisu Insert Files (.ssi)</a></h2> <p> - Inserts are documents prepared solely for the purpose of being incorporated +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 @@ -2170,7 +2152,7 @@ DOM: dom.css 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.[^19] +or equivalent.[^20] <p> <h2><a name='sect56' href='#toc56'>Organising Content - Directory Structure and Mapping</a></h2> @@ -2524,8 +2506,8 @@ or in various output formats. <h2><a name='sect75' href='#toc75'>Populating Sql Type Databases</a></h2> <p> <b>SiSU</b> feeds -sisu markupd documents into sql type databases <i>PostgreSQL</i> [^20] and/or <i>SQLite</i> -[^21] database together with information related to document structure. +sisu markupd documents into sql type databases <i>PostgreSQL</i> [^21] and/or <i>SQLite</i> +[^22] database together with information related to document 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 @@ -2687,14 +2669,14 @@ an sqlite database, this being part of <b>SiSU</b> - man sisu) . <h2><a name='sect86' href='#toc86'>Synopsis</a></h2> <p> sisu --d [instruction] [filename/wildcard if required] +-d [instruction] [filename/wildcard if required] <p> sisu -d --(sqlite|pg) --[instruction] -[filename/wildcard if required] +[filename/wildcard if required] <p> <h2><a name='sect87' href='#toc87'>Commands</a></h2> -<p> Mappings to two databases -are provided by default, postgresql and sqlite, the same commands are used +<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 @@ -2769,9 +2751,9 @@ and Sisu Features,</a></h2> INCLUDING OBJECT CITATION NUMBERING (BACKEND CURRENTLY POSTGRESQL) <p> Sample search frontend <<a href='http://search.sisudoc.org'>http://search.sisudoc.org</a> -> [^22] A small +> [^23] A small database and sample query front-end (search from) that makes use of the -citation system, .I object citation numbering to demonstrates functionality.[^23] +citation system, <i>object</i> citation numbering to demonstrates functionality.[^24] <p> <b>SiSU</b> can provide information on which documents are matched and at what locations within each document the matches are found. These results are @@ -2783,7 +2765,7 @@ the matched objects (paragraphs) in the documents matched. 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.[^24] +the search criteria.[^25] <p> <dl> @@ -3173,7 +3155,7 @@ or <<a href='http://www.jus.uio.no/sisu/'>http://www.jus.uio.no/sisu/</a> <li><a name='toc12' href='#sect12'>Help</a></li> <li><a name='toc13' href='#sect13'>Sisu Manual</a></li> <li><a name='toc14' href='#sect14'>Sisu Man Pages</a></li> -<li><a name='toc15' href='#sect15'>Sisu Built-in Interactive Help</a></li> +<li><a name='toc15' href='#sect15'>Sisu Built-in Interactive Help, [discontinued]</a></li> <li><a name='toc16' href='#sect16'>Introduction to Sisu Markup[^11]</a></li> <li><a name='toc17' href='#sect17'>Summary</a></li> <li><a name='toc18' href='#sect18'>Markup Examples</a></li> diff --git a/data/doc/sisu/html/sisu3.1.html b/data/doc/sisu/html/sisu3.1.html deleted file mode 120000 index 4b34bf93..00000000 --- a/data/doc/sisu/html/sisu3.1.html +++ /dev/null @@ -1 +0,0 @@ -sisu.1.html
\ No newline at end of file diff --git a/data/doc/sisu/html/sisu4.1.html b/data/doc/sisu/html/sisu4.1.html deleted file mode 100644 index f7268daa..00000000 --- a/data/doc/sisu/html/sisu4.1.html +++ /dev/null @@ -1,3237 +0,0 @@ -<!-- manual page source format generated by PolyglotMan v3.2, --> -<!-- available at http://polyglotman.sourceforge.net/ --> - -<html> -<head> -<title>"sisu"("1") manual page</title> -</head> -<body bgcolor='white'> -<a href='#toc'>Table of Contents</a><p> -<br> - -<h2><a name='sect0' href='#toc0'>Name</a></h2> -<br> -sisu - documents: markup, structuring, publishing in multiple standard formats, -and search <br> - -<h2><a name='sect1' href='#toc1'>Synopsis</a></h2> -<br> -sisu [-short-options|--long-options] [filename/wildcard] -<p> <br> -sisu [-abCcDdeFGghIikLMmNnoPpQqRrSsTtUuVvWwXxYyZ_0-9] [filename/wildcard] - -<p> <br> -sisu --txt --html --epub --odt --pdf --wordmap --sqlite --manpage --texinfo --sisupod --source ---qrcode [filename/wildcard] -<p> <br> -sisu [-Ddcv] [instruction] [filename/wildcard] -<p> <br> -sisu --pg (--createdb|update [filename/wildcard]|--dropall) -<p> <br> -sisu [operations] -<p> <br> -sisu [-CcFLSVvW] -<p> <br> -sisu (--configure|--webrick|--sample-search-form) -<h2><a name='sect2' href='#toc2'>Sisu - Manual,</a></h2> -RALPH AMISSAH -<p> -<h2><a name='sect3' href='#toc3'>What -is Sisu?</a></h2> - -<p> -<h2><a name='sect4' href='#toc4'>Introduction - What is Sisu?</a></h2> - -<p> -<p> <b>SiSU</b> is a framework for document -structuring, publishing (in multiple open standard formats) and search, -comprising of: (a) a lightweight document structure and presentation markup -syntax; and (b) an accompanying engine for generating standard document -format outputs from documents prepared in sisu markup syntax, which is -able to produce multiple standard outputs (including the population of -sql databases) that (can) share a common numbering system for the citation -of text within a document. -<p> <b>SiSU</b> is developed under an open source, software -libre license ( <i>GPLv3</i> ). Its use case for development is work with medium -to large document sets and cope with evolving document formats/ representation -technologies. Documents are prepared once, and generated as need be to update -the technical presentation or add additional output formats. Various output -formats (including search related output) share a common mechanism for -cross-output-format citation. -<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 -several standard output formats which share a common (text object) numbering -system for citation of content within a document (that also has implications -for search). The sisu engine works with an abstraction of the document’s -structure and content from which it is possible to generate different forms -of representation of the document. Significantly <b>SiSU</b> markup is more sparse -than html and outputs which include <i>HTML,</i> <i>EPUB,</i> <i>ODT</i> (Open Document Format -text), <i>LaTeX,</i> landscape and portrait <i>PDF,</i> all of which can be added to -and updated. <b>SiSU</b> is also able to populate <i>SQL</i> type databases at an object -level, which 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 desired output subsequently generated by running the sisu -engine against document source. Output representations if updated (in the -sisu engine) can be generated by re-running the engine against the prepared -source. Using <b>SiSU</b> markup applied to a document, <b>SiSU</b> custom builds (to -take advantage of the strengths of different ways of representing documents) -various standard open output formats including plain text, <i>HTML,</i> <i>XHTML,</i> -<i>XML,</i> <i>EPUB,</i> <i>ODT,</i> <i>LaTeX</i> or <i>PDF</i> files, and populate an <i>SQL</i> database with objects[^1] -(equating generally to paragraph-sized chunks) so searches may be performed -and matches returned with that degree of granularity ( e.g. your search criteria -is met by these documents and at these locations within each document). -Document output formats share a common object numbering system for locating -content. This is particularly suitable for "published" works (finalized -texts as opposed to works that are frequently changed or updated) for which -it provides a fixed means of reference of content. -<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. -<p> <b>SiSU</b> works with an abstraction of -the document based on its structure which is comprised of its headings[^3] -and objects[^4], which enables <b>SiSU</b> to represent the document in many different -ways, and to take advantage of the strengths of different ways of presenting -documents. The objects are numbered, and these numbers can be used to provide -a common basis for citing material within a document across the different -output format types. This is significant as page numbers are not well suited -to the digital age, in web publishing, changing a browser’s default font -or using a different browser can mean that text will appear on a different -page; and publishing in different formats, html, landscape and portrait -pdf etc. again page numbers are not useful to cite text. Dealing with documents -at an object level together with object numbering also has implications -for search that <b>SiSU</b> is able to take advantage of. -<p> One of the challenges -of maintaining documents is to keep them in a format that allows use of -them independently of proprietary platforms. Consider issues related to -dealing with legacy proprietary formats today and what guarantee you have -that old proprietary formats will remain (or can be read without proprietary -software/equipment) in 15 years time, or the way the way in which html -has evolved over its relatively short span of existence. <b>SiSU</b> provides the -flexibility of producing documents in multiple non-proprietary open formats -including <i>HTML,</i> <i>EPUB,</i> [^5] <i>ODT,</i> [^6] <i>PDF</i> [^7] <i>ODF,</i> [^8]. Whilst <b>SiSU</b> relies -on software, the markup is uncomplicated and minimalistic which guarantees -that future engines can be written to run against it. It is also easily -converted to other formats, which means documents prepared in <b>SiSU</b> can -be migrated to other document formats. Further security is provided by the -fact that the software itself, <b>SiSU</b> is available under <i>GPLv3</i> a licence -that guarantees that the source code will always be open, and free as in -libre, which means that that code base can be used, updated and further -developed as required under the terms of its license. Another challenge -is to keep up with a moving target. <b>SiSU</b> permits new forms of output to -be added as they become important, (Open Document Format text was added -in 2006 when it became an ISO standard for office applications and the -archival of documents), <i>EPUB</i> was introduced in 2009; and allows the technical -representations existing output to be updated ( <i>HTML</i> has evolved and the -related module has been updated repeatedly over the years, presumably when -the World Wide Web Consortium (w3c) finalises <i>HTML</i> 5 which is currently -under development, the <i>HTML</i> module will again be updated allowing all existing -documents to be regenerated as <i>HTML</i> 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. -<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 thesauri, together with the flexibility -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> -<p> <<a href='http://www.sisudoc.org/'>http://www.sisudoc.org/</a> -> -<p> <<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a> -> - -<h2><a name='sect5' href='#toc5'>Commands Summary</a></h2> - -<p> -<h2><a name='sect6' href='#toc6'>Description</a></h2> - -<p> <b>SiSU</b> is a document publishing system, that -from a simple single marked-up document, produces multiple output formats -including: <i>plaintext,</i> <i>HTML,</i> <i>XHTML,</i> <i>XML,</i> <i>EPUB,</i> <i>ODT</i> ( <i>OpenDocument</i> ( <i>ODF</i> -) text), <i>LaTeX,</i> <i>PDF,</i> info, and <i>SQL</i> ( <i>PostgreSQL</i> and <i>SQLite</i> ) , which share -text object numbers ("object citation numbering") and the same document -structure information. For more see: <<a href='http://sisudoc.org'>http://sisudoc.org</a> -> or <<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a> -> - -<h2><a name='sect7' href='#toc7'>Document Processing Command Flags</a></h2> - -<p> -<dl> - -<dt><b>-a [filename/wildcard]</b> </dt> -<dd>produces <i>plaintext</i> -with Unix linefeeds and without markup, (object numbers are omitted), has -footnotes at end of each paragraph that contains them [ -A for equivalent -dos (linefeed) output file] [see -e for endnotes]. (Options include: --endnotes -for endnotes --footnotes for footnotes at the end of each paragraph --unix -for unix linefeed (default) --msdos for msdos linefeed) </dd> - -<dt><b>-b [filename/wildcard]</b> -</dt> -<dd>see --xhtml </dd> - -<dt><b>--by-*</b> </dt> -<dd>see --output-by-* </dd> - -<dt><b>-C</b> </dt> -<dd>configure/initialise shared output directory -files initialize shared output directory (config files such as css and -dtd files are not updated if they already exist unless modifier is used). --C --init-site configure/initialise site more extensive than -C on its own, -shared output directory files/force update, existing shared output config -files such as css and dtd files are updated if this modifier is used. </dd> - -<dt><b>-CC</b> -</dt> -<dd>see --configure </dd> - -<dt><b>-c [filename/wildcard]</b> </dt> -<dd>see --color-toggle </dd> - -<dt><b>--color</b> </dt> -<dd>see --color-on </dd> - -<dt><b>--color-off</b> -</dt> -<dd>turn off color in output to terminal </dd> - -<dt><b>--color-on</b> </dt> -<dd>turn on color in output to -terminal </dd> - -<dt><b>--color-toggle [filename/wildcard]</b> </dt> -<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). Alias -c </dd> - -<dt><b>--configure</b> </dt> -<dd>configure/initialise shared output directory -files initialize shared output directory (config files such as css and -dtd files are not updated if they already exist unless modifier is used). -The equivalent of: -C --init-site configure/initialise site, more extensive -than -C on its own, shared output directory files/force update, existing -shared output config files such as css and dtd files are updated if -CC -is used. </dd> - -<dt><b>--concordance [filename/wildcard]</b> </dt> -<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). Alias -w </dd> - -<dt><b>-D [instruction] [filename]</b> </dt> -<dd>see ---pg </dd> - -<dt><b>-d [--db-[database type (sqlite|pg)]] --[instruction] [filename]</b> </dt> -<dd>see --sqlite -</dd> - -<dt><b>--dal [filename/wildcard/url]</b> </dt> -<dd>assumed for most other flags, creates new intermediate -files for processing (document abstraction) that is used in all subsequent -processing of other output. This step is assumed for most processing flags. -To skip it see -n. Alias -m </dd> - -<dt><b>--delete [filename/wildcard]</b> </dt> -<dd>see --zap </dd> - -<dt><b>--dump[=directory_path] -[filename/wildcard]</b> </dt> -<dd>places output in directory specified, if none is specified -in the current directory (pwd). Compare --redirect </dd> - -<dt><b>-e [filename/wildcard]</b> </dt> -<dd>see ---epub </dd> - -<dt><b>--epub [filename/wildcard]</b> </dt> -<dd>produces an epub document, [sisu version ->=2 ] (filename.epub). Alias -e </dd> - -<dt><b>--exc-*</b> </dt> -<dd>exclude output feature, overrides configuration -settings --exc-ocn, (exclude <i>object</i> citation numbering, (switches off <i>object</i> -citation numbering ) , affects html (seg, scroll), epub, xhtml, xml, pdf) -; --exc-toc, (exclude table of contents, affects html (scroll), epub, pdf) -; --exc-links-to-manifest, --exc-manifest-links, (exclude links to manifest, affects -html (seg, scroll)); --exc-search-form, (exclude search form, affects html -(seg, scroll), manifest); --exc-minitoc, (exclude mini table of contents, -affects html (seg), concordance, manifest); --exc-manifest-minitoc, (exclude -mini table of contents, affects manifest); --exc-html-minitoc, (exclude mini -table of contents, affects html (seg), concordance); --exc-html-navigation, -(exclude navigation, affects html (seg)); --exc-html-navigation-bar, (exclude -navigation bar, affects html (seg)); --exc-html-search-form, (exclude search -form, affects html (seg, scroll)); --exc-html-right-pane, (exclude right pane/column, -affects html (seg, scroll)); --exc-html-top-band, (exclude top band, affects -html (seg, scroll), concordance (minitoc forced on to provide seg navigation)); ---exc-segsubtoc (exclude sub table of contents, affects html (seg), epub) -; see also --inc-* </dd> - -<dt><b>-F [--webserv=webrick]</b> </dt> -<dd>see --sample-search-form </dd> - -<dt><b>-f [optional string -part of filename]</b> </dt> -<dd>see --find </dd> - -<dt><b>--find [optional string part of filename]</b> </dt> -<dd>without -match string, glob all .sst .ssm files in directory (including language subdirectories). -With match string, find files that match given string in directory (including -language subdirectories). Alias -f, --glob, -G </dd> - -<dt><b>-G [optional string part of filename]</b> -</dt> -<dd>see --find </dd> - -<dt><b>-g [filename/wildcard]</b> </dt> -<dd>see --git </dd> - -<dt><b>--git [filename/wildcard]</b> </dt> -<dd>produces -or updates markup source file structure in a git repo (experimental and -subject to change). Alias -g </dd> - -<dt><b>--glob [optional string part of filename]</b> </dt> -<dd>see ---find </dd> - -<dt><b>-h [filename/wildcard]</b> </dt> -<dd>see --html </dd> - -<dt><b>--harvest *.ss[tm]</b> </dt> -<dd>makes two lists of -sisu output based on the sisu markup documents in a directory: list of -author and authors works (year and titles), and; list by topic with titles -and author. Makes use of header metadata fields (author, title, date, topic_register). -Can be used with maintenance (-M) and remote placement (-R) flags. </dd> - -<dt><b>--help [topic]</b> -</dt> -<dd>provides help on the selected topic, where topics (keywords) include: list, -(com)mands, short(cuts), (mod)ifiers, (env)ironment, markup, syntax, headers, -headings, endnotes, tables, example, customise, skin, (dir)ectories, path, -(lang)uage, db, install, setup, (conf)igure, convert, termsheet, search, -sql, features, license. </dd> - -<dt><b>--html [filename/wildcard]</b> </dt> -<dd>produces html output, segmented -text with table of contents (toc.html and index.html) and the document in -a single file (scroll.html). Alias -h </dd> - -<dt><b>-I [filename/wildcard]</b> </dt> -<dd>see --texinfo </dd> - -<dt><b>-i -[filename/wildcard]</b> </dt> -<dd>see --manpage </dd> - -<dt><b>--inc-*</b> </dt> -<dd>include output feature, overrides -configuration settings, (usually the default if none set), has precedence -over --exc-* (exclude output feature). Some detail provided under --exc-*, see ---exc-* </dd> - -<dt><b>-j [filename/wildcard]</b> </dt> -<dd>copies images associated with a file for use -by html, xhtml & xml outputs (automatically invoked by --dump & redirect). </dd> - -<dt><b>-k</b> -</dt> -<dd>see --color-off </dd> - -<dt><b>--keep-processing-files [filename/wildcard/url]</b> </dt> -<dd>see --maintenance -</dd> - -<dt><b>-L</b> </dt> -<dd>prints license information. </dd> - -<dt><b>-M [filename/wildcard/url]</b> </dt> -<dd>see --maintenance -</dd> - -<dt><b>-m [filename/wildcard/url]</b> </dt> -<dd>see --dal (document abstraction level/layer) </dd> - -<dt><b>--machine -[filename/wildcard/url]</b> </dt> -<dd>see --dal (document abstraction level/layer) </dd> - -<dt><b>--maintenance -[filename/wildcard/url]</b> </dt> -<dd>maintenance mode, interim processing files are -preserved and their locations indicated. (also see -V). Aliases -M and --keep-processing-files. -</dd> - -<dt><b>--manpage [filename/wildcard]</b> </dt> -<dd>produces man page of file, not suitable for -all outputs. Alias -i </dd> - -<dt><b>-N [filename/wildcard/url]</b> </dt> -<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. </dd> - -<dt><b>-n [filename/wildcard/url]</b> </dt> -<dd>skip the -creation of intermediate processing files (document abstraction) if they -already exist, this skips the equivalent of -m which is otherwise assumed -by most processing flags. </dd> - -<dt><b>--no-*</b> </dt> -<dd>see --exc-* </dd> - -<dt><b>-o [filename/wildcard/url]</b> </dt> -<dd>see --odt -</dd> - -<dt><b>--odf [filename/wildcard/url]</b> </dt> -<dd>see --odt </dd> - -<dt><b>--odt [filename/wildcard/url]</b> </dt> -<dd>output -basic document in opendocument file format (opendocument.odt). Alias -o </dd> - -<dt><b>--output-by-*</b> -</dt> -<dd>select output directory structure from 3 alternatives: --output-by-language, -(language directory (based on language code) with filetype (html, epub, -pdf etc.) subdirectories); --output-by-filetype, (filetype directories with -language code as part of filename); --output-by-filename, (filename directories -with language code as part of filename). This is configurable. Alias --by-* -</dd> - -<dt><b>-P [language_directory/filename language_directory]</b> </dt> -<dd>see --po4a </dd> - -<dt><b>-p [filename/wildcard]</b> -</dt> -<dd>see --pdf </dd> - -<dt><b>--pdf [filename/wildcard]</b> </dt> -<dd>produces <i>LaTeX</i> pdf (portrait.pdf & landscape.pdf). -Default paper size is set in config file, or document header, or provided -with additional command line parameter, e.g. --papersize-a4 preset sizes include: -’A4’, U.S. ’letter’ and ’legal’ and book sizes ’A5’ and ’B5’ (system defaults to A4). -Alias -p </dd> - -<dt><b>--pg [instruction] [filename]</b> </dt> -<dd>database <i>PostgreSQL</i> ( --pgsql may be -used instead) possible instructions, include: --createdb; --create; --dropall; ---import [filename]; --update [filename]; --remove [filename]; see database section -below. Alias -D </dd> - -<dt><b>--po [language_directory/filename language_directory]</b> </dt> -<dd>see --po4a -</dd> - -<dt><b>--po4a [language_directory/filename language_directory]</b> </dt> -<dd>produces .pot and -po files for the file in the languages specified by the language directory. -<b>SiSU</b> markup is placed in subdirectories named with the language code, e.g. -en/ fr/ es/. The sisu config file must set the output directory structure -to multilingual. v3, experimental </dd> - -<dt><b>-Q [filename/wildcard]</b> </dt> -<dd>see --qrcode </dd> - -<dt><b>-q [filename/wildcard]</b> -</dt> -<dd>see --quiet </dd> - -<dt><b>--qrcode [filename/wildcard]</b> </dt> -<dd>generate QR code image of metadata -(used in manifest). v3 only. </dd> - -<dt><b>--quiet [filename/wildcard]</b> </dt> -<dd>quiet less output -to screen. </dd> - -<dt><b>-R [filename/wildcard]</b> </dt> -<dd>see --rsync </dd> - -<dt><b>-r [filename/wildcard]</b> </dt> -<dd>see --scp -</dd> - -<dt><b>--redirect[=directory_path] [filename/wildcard]</b> </dt> -<dd>places output in subdirectory -under specified directory, subdirectory uses the filename (without the -suffix). If no output directory is specified places the subdirectory under -the current directory (pwd). Compare --dump </dd> - -<dt><b>--rsync [filename/wildcard]</b> </dt> -<dd>copies -sisu output files to remote host using rsync. This requires that sisurc.yml -has been provided with information on hostname and username, and that you -have your "keys" and ssh agent in place. Note the behavior of rsync different -if -R is used with other flags from if used alone. Alone the rsync --delete -parameter is sent, useful for cleaning the remote directory (when -R is -used together with other flags, it is not). Also see --scp. Alias -R </dd> - -<dt><b>-S</b> </dt> -<dd>see --sisupod -</dd> - -<dt><b>-S [filename/wildcard]</b> </dt> -<dd>see --sisupod </dd> - -<dt><b>-s [filename/wildcard]</b> </dt> -<dd>see --source </dd> - -<dt><b>--sample-search-form -[--webserv=webrick]</b> </dt> -<dd>generate examples of (naive) cgi search form for <i>SQLite</i> -and PgSQL depends on your already having used sisu to populate an <i>SQLite</i> -and/or PgSQL database, (the <i>SQLite</i> version scans the output directories -for existing sisu_sqlite databases, so it is first necessary to create -them, before generating the search form) see -d -D and the database section -below. If the optional parameter --webserv=webrick is passed, the cgi examples -created will be set up to use the default port set for use by the webrick -server, (otherwise the port is left blank and the system setting used, -usually 80). The samples are dumped in the present work directory which -must be writable, (with screen instructions given that they be copied to -the cgi-bin directory). Alias -F </dd> - -<dt><b>--scp [filename/wildcard]</b> </dt> -<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 have your "keys" -and ssh agent in place. Also see --rsync. Alias -r </dd> - -<dt><b>--sqlite --[instruction] [filename]</b> -</dt> -<dd>database type set to <i>SQLite,</i> this produces one of two possible databases, -without additional database related instructions it produces a discreet -<i>SQLite</i> file for the document processed; with additional instructions it -produces a common <i>SQLite</i> database of all processed documents that (come -from the same document preparation directory and as a result) share the -same output directory base path (possible instructions include: --createdb; ---create; --dropall; --import [filename]; --update [filename]; --remove [filename]); -see database section below. Alias -d </dd> - -<dt><b>--sisupod</b> </dt> -<dd>produces a sisupod a zipped -sisu directory of markup files including sisu markup source files and the -directories local configuration file, images and skins. Note: this only -includes the configuration files or skins contained in is tested only -with zsh). Alias -S </dd> - -<dt><b>--sisupod [filename/wildcard]</b> </dt> -<dd>produces a zipped file of -the prepared document specified along with associated images, by default -named sisupod.zip they may alternatively be named with the filename extension -.ssp This provides a quick way of gathering the relevant parts of a sisu -document which can then for example be emailed. A sisupod includes sisu -markup source file, (along with associated documents if a master file, -or available in multilingual versions), together with related images and -skin. <b>SiSU</b> commands can be run directly against a sisupod contained in a -local directory, or provided as a url on a remote site. As there is a security -issue with skins provided by other users, they are not applied unless the -flag --trust or --trusted is added to the command instruction, it is recommended -that file that are not your own are treated as untrusted. The directory -structure of the unzipped file is understood by sisu, and sisu commands -can be run within it. Note: if you wish to send multiple files, it quickly -becomes more space efficient to zip the sisu markup directory, rather than -the individual files for sending). See the -S option without [filename/wildcard]. -Alias -S </dd> - -<dt><b>--source [filename/wildcard]</b> </dt> -<dd>copies sisu markup file to output directory. -Alias -s </dd> - -<dt><b>-T [filename/wildcard (*.termsheet.rb)]</b> </dt> -<dd>standard form document builder, -preprocessing feature </dd> - -<dt><b>-t [filename/wildcard]</b> </dt> -<dd>see --txt </dd> - -<dt><b>--texinfo [filename/wildcard]</b> -</dt> -<dd>produces texinfo and info file, (view with pinfo). Alias -I </dd> - -<dt><b>--txt [filename/wildcard]</b> -</dt> -<dd>produces <i>plaintext</i> with Unix linefeeds and without markup, (object numbers -are omitted), has footnotes at end of each paragraph that contains them -[ -A for equivalent dos (linefeed) output file] [see -e for endnotes]. (Options -include: --endnotes for endnotes --footnotes for footnotes at the end of each -paragraph --unix for unix linefeed (default) --msdos for msdos linefeed). Alias --t </dd> - -<dt><b>-U [filename/wildcard]</b> </dt> -<dd>see --urls </dd> - -<dt><b>-u [filename/wildcard]</b> </dt> -<dd>provides url mapping -of output files for the flags requested for processing, also see -U </dd> - -<dt><b>--urls -[filename/wildcard]</b> </dt> -<dd>prints url output list/map for the available processing -flags options and resulting files that could be requested, (can be used -to get a list of processing options in relation to a file, together with -information on the output that would be produced), -u provides url output -mapping for those flags requested for processing. The default assumes sisu_webrick -is running and provides webrick url mappings where appropriate, but these -can be switched to file system paths in sisurc.yml. Alias -U </dd> - -<dt><b>-V</b> </dt> -<dd>on its own, -provides <b>SiSU</b> version and environment information (sisu --help env) </dd> - -<dt><b>-V [filename/wildcard]</b> -</dt> -<dd>even more verbose than the -v flag. </dd> - -<dt><b>-v</b> </dt> -<dd>on its own, provides <b>SiSU</b> version information -</dd> - -<dt><b>-v [filename/wildcard]</b> </dt> -<dd>see --verbose </dd> - -<dt><b>--v3 [filename/wildcard]</b> </dt> -<dd>invokes the sisu -v3 document parser/generator. You may run sisu3 instead. </dd> - -<dt><b>--v4 [filename/wildcard]</b> -</dt> -<dd>invokes the sisu v4 document parser/generator. This is the default and is -normally omitted. </dd> - -<dt><b>--verbose [filename/wildcard]</b> </dt> -<dd>provides verbose output of -what is being generated, where output is placed (and error messages if -any), as with -u flag provides a url mapping of files created for each of -the processing flag requests. Alias -v </dd> - -<dt><b>-W</b> </dt> -<dd>see --webrick </dd> - -<dt><b>-w [filename/wildcard]</b> -</dt> -<dd>see --concordance </dd> - -<dt><b>--webrick</b> </dt> -<dd>starts ruby’ s webrick webserver points at sisu -output directories, the default port is set to 8081 and can be changed -in the resource configuration files. [tip: the webrick server requires link -suffixes, so html output should be created using the -h option rather than --H ; also, note -F webrick ]. Alias -W </dd> - -<dt><b>--wordmap [filename/wildcard]</b> </dt> -<dd>see --concordance -</dd> - -<dt><b>--xhtml [filename/wildcard]</b> </dt> -<dd>produces xhtml/ <i>XML</i> output for browser viewing -(sax parsing). Alias -b </dd> - -<dt><b>--xml-dom [filename/wildcard]</b> </dt> -<dd>produces <i>XML</i> output with -deep document structure, in the nature of dom. Alias -X </dd> - -<dt><b>--xml-sax [filename/wildcard]</b> -</dt> -<dd>produces <i>XML</i> output shallow structure (sax parsing). Alias -x </dd> - -<dt><b>-X [filename/wildcard]</b> -</dt> -<dd>see --xml-dom </dd> - -<dt><b>-x [filename/wildcard]</b> </dt> -<dd>see --xml-sax </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]) </dd> - -<dt><b>-y [filename/wildcard]</b> </dt> -<dd>produces an html -summary of output generated (hyperlinked to content) and document specific -metadata (sisu_manifest.html). This step is assumed for most processing flags. -</dd> - -<dt><b>-Z [filename/wildcard]</b> </dt> -<dd>see --zap </dd> - -<dt><b>--zap [filename/wildcard]</b> </dt> -<dd>Zap, if used with -other processing flags deletes output files of the type about to be processed, -prior to processing. If -Z is used as the lone processing related flag (or -in conjunction with a combination of -[mMvVq]), will remove the related -document output directory. Alias -Z </dd> -</dl> - -<h2><a name='sect8' href='#toc8'>Command Line Modifiers</a></h2> - -<p> -<dl> - -<dt><b>--no-ocn</b> </dt> -<dd>[with --html ---pdf or --epub] switches off <i>object</i> citation numbering. Produce output without -identifying numbers in margins of html or <i>LaTeX</i> /pdf output. </dd> - -<dt><b>--no-annotate</b> -</dt> -<dd>strips output text of editor endnotes[^*1] denoted by asterisk or dagger/plus -sign </dd> - -<dt><b>--no-asterisk</b> </dt> -<dd>strips output text of editor endnotes[^*2] denoted by asterisk -sign </dd> - -<dt><b>--no-dagger</b> </dt> -<dd>strips output text of editor endnotes[^+1] denoted by dagger/plus -sign </dd> -</dl> - -<h2><a name='sect9' href='#toc9'>Database Commands</a></h2> - -<p> <b>dbi - database interface</b> -<p> <b>-D or --pgsql</b> set for <i>PostgreSQL</i> -<b>-d or --sqlite</b> default set for <i>SQLite</i> -d is modifiable with --db=[database type -(PgSQL or <i>SQLite</i> ) ] -<dl> - -<dt><b>--pg -v --createall</b> </dt> -<dd>initial step, creates required relations -(tables, indexes) in existing <i>PostgreSQL</i> database (a database should be -created manually and given the same name as working directory, as requested) -(rb.dbi) [ -dv --createall <i>SQLite</i> equivalent] it may be necessary to run sisu --Dv --createdb initially NOTE: at the present time for <i>PostgreSQL</i> it may be -necessary to manually create the database. The command would be directory -name (without path)]. Please use only alphanumerics and underscores. </dd> - -<dt><b>--pg -v ---import</b> </dt> -<dd>[filename/wildcard] imports data specified to <i>PostgreSQL</i> db (rb.dbi) -[ -dv --import <i>SQLite</i> equivalent] </dd> - -<dt><b>--pg -v --update</b> </dt> -<dd>[filename/wildcard] updates/imports -specified data to <i>PostgreSQL</i> db (rb.dbi) [ -dv --update <i>SQLite</i> equivalent] -</dd> - -<dt><b>--pg --remove</b> </dt> -<dd>[filename/wildcard] removes specified data to <i>PostgreSQL</i> db (rb.dbi) -[ -d --remove <i>SQLite</i> equivalent] </dd> - -<dt><b>--pg --dropall</b> </dt> -<dd>kills data" and drops ( <i>PostgreSQL</i> -or <i>SQLite</i> ) db, tables & indexes [ -d --dropall <i>SQLite</i> equivalent] -<p> The -v -is for verbose output. </dd> -</dl> - -<h2><a name='sect10' href='#toc10'>Shortcuts, Shorthand for Multiple Flags</a></h2> - -<p> -<dl> - -<dt><b>--update [filename/wildcard]</b> -</dt> -<dd>Checks existing file output and runs the flags required to update this -output. This means that if only html and pdf output was requested on previous -runs, only the -hp files will be applied, and only these will be generated -this time, together with the summary. This can be very convenient, if you -offer different outputs of different files, and just want to do the same -again. </dd> - -<dt><b>-0 to -5 [filename or wildcard]</b> </dt> -<dd>Default shorthand mappings (for v3, -note that the defaults can be changed/configured in the sisurc.yml file): -</dd> - -<dt><b>-0</b> </dt> -<dd>-NQhewpotbxXyYv [this is the default action run when no options are give, -i.e. on ’sisu [filename]’] </dd> - -<dt><b>-1</b> </dt> -<dd>-Qhewpoty </dd> - -<dt><b>-2</b> </dt> -<dd>-NQhewpotbxXy </dd> - -<dt><b>-3</b> </dt> -<dd>-NQhewpotbxXyY </dd> - -<dt><b>-4</b> </dt> -<dd>-NQhewpotbxXDyY ---update </dd> - -<dt><b>-5</b> </dt> -<dd>-NQhewpotbxXDyYv --update -<p> add -v for verbose mode and -c to toggle -color state, e.g. sisu -2vc [filename or wildcard] -<p> consider -u for appended - -<p>url info or -v for verbose output -<p> </dd> -</dl> - -<h2><a name='sect11' href='#toc11'>Command Line with Flags - Batch Processing</a></h2> - -<p> - In the data directory run sisu -mh filename or wildcard eg. "sisu -h cisg.sst" -or "sisu -h *.{sst,ssm}" to produce html version of all documents. -<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. -<h2><a name='sect12' href='#toc12'>Help</a></h2> - -<p> - -<h2><a name='sect13' href='#toc13'>Sisu Manual</a></h2> - -<p> The most up to date information on sisu should be contained -in the sisu_manual, available at: -<p> <<a href='http://sisudoc.org/sisu/sisu_manual/'>http://sisudoc.org/sisu/sisu_manual/</a> -> - -<p> The manual can be generated from source, found respectively, either within -the <b>SiSU</b> tarball or installed locally at: -<p> -<p> /usr/share/doc/sisu/markup-samples/sisu_manual - -<p> move to the respective directory and type e.g.: -<p> sisu sisu_manual.ssm -<h2><a name='sect14' href='#toc14'>Sisu -Man Pages</a></h2> - -<p> If <b>SiSU</b> is installed on your system usual man commands should -be available, try: -<p> man sisu -<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: -<p> ./data/doc/sisu/markup-samples/sisu_manual<br> - -<p> Once installed, directory equivalent to: -<p> /usr/share/doc/sisu/markup-samples/sisu_manual<br> - -<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> * various -sisu man pages <<a href='http://www.jus.uio.no/sisu/man/'>http://www.jus.uio.no/sisu/man/</a> -> [^9] -<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> -> -[^10] -<p> -<h2><a name='sect15' href='#toc15'>Sisu Built-in Interactive Help</a></h2> - -<p> This is particularly useful for getting -the current sisu setup/environment information: -<p> sisu --help -<p> sisu --help -[subject] -<p> sisu --help commands -<p> sisu --help markup -<p> sisu --help env [for -feedback on the way your system is setup with regard to sisu ]<br> - -<p> sisu -V [environment information, same as above command] -<p> sisu (on its -own provides version and some help information) -<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). -<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. -<h2><a name='sect16' href='#toc16'>Introduction -to Sisu Markup[^11]</a></h2> - -<p> -<h2><a name='sect17' href='#toc17'>Summary</a></h2> - -<p> <b>SiSU</b> source documents are <i>plaintext</i> ( <i>UTF-8</i> -)[^12] files -<p> All paragraphs are separated by an empty 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) -<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: -<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 -<p> * paragraph actions, such as indent, bulleted, -numbered-lists, etc. -<p> Some interactive help on markup is available, by typing - -<p>sisu and selecting markup or sisu --help markup -<p> To check the markup in -a file: -<p> sisu --identify [filename].sst -<p> For brief descriptive summary of - -<p>markup history -<p> sisu --query-history -<p> or if for a particular version: -<p> -sisu --query-0.38 -<h2><a name='sect18' href='#toc18'>Markup Examples</a></h2> - -<p> -<h2><a name='sect19' href='#toc19'>Online</a></h2> - -<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> an alternative -presentation of markup syntax: /usr/share/doc/sisu/on_markup.txt.gz -<p> -<h2><a name='sect20' href='#toc20'>Installed</a></h2> - -<p> - With <b>SiSU</b> installed sample skins may be found in: /usr/share/doc/sisu/markup-samples -(or equivalent directory) and if sisu -markup-samples is installed also under: - -<p>/usr/share/doc/sisu/markup-samples-non-free -<p> -<h2><a name='sect21' href='#toc21'>Markup of Headers</a></h2> - -<p> -<p> Headers contain -either: semantic meta-data about a document, which can be used by any output -module of the program, or; 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> <br> -<pre>% this would be a comment -</pre> -<p> -<h2><a name='sect22' href='#toc22'>Sample Header</a></h2> - -<p> This current document is loaded by a master document that -has a header similar to this one: -<p> <br> -<pre>% SiSU master 4.0 -@title: SiSU - :subtitle: Manual -@creator: - :author: Amissah, Ralph -@publisher: [publisher name] -@rights: Copyright (C) Ralph Amissah 2007, part of SiSU documentation, -License GPL 3 -@classify: - :topic_register: SiSU:manual;electronic documents:SiSU:manual - :subject: ebook, epublishing, electronic book, electronic publishing, - electronic document, electronic citation, data structure, - citation systems, search -% used_by: manual -@date: - :published: 2008-05-22 - :created: 2002-08-28 - :issued: 2002-08-28 - :available: 2002-08-28 - :modified: 2010-03-03 -@make: - :num_top: 1 - :breaks: new=C; break=1 - :bold: /Gnu|Debian|Ruby|SiSU/ - :home_button_text: {SiSU}http://sisudoc.org; {git}http://git.sisudoc.org - :footer: {SiSU}http://sisudoc.org; {git}http://git.sisudoc.org - :manpage: name=sisu - documents: markup, structuring, publishing in multiple -standard formats, and search; - synopsis=sisu [-abcDdeFhIiMmNnopqRrSsTtUuVvwXxYyZz0-9] [filename/wildcard -] - . sisu [-Ddcv] [instruction] - . sisu [-CcFLSVvW] - . sisu --v4 [operations] - . sisu --v3 [operations] -@links: - { SiSU Homepage }http://www.sisudoc.org/ - { SiSU Manual }http://www.sisudoc.org/sisu/sisu_manual/ - { Book Samples & Markup Examples }http://www.jus.uio.no/sisu/SiSU/examples.html - { SiSU Download }http://www.jus.uio.no/sisu/SiSU/download.html - { SiSU Changelog }http://www.jus.uio.no/sisu/SiSU/changelog.html - { SiSU Git repo }http://git.sisudoc.org/?p=code/sisu.git;a=summary - { SiSU List Archives }http://lists.sisudoc.org/pipermail/sisu/ - { SiSU @ Debian }http://packages.qa.debian.org/s/sisu.html - { SiSU Project @ Debian }http://qa.debian.org/developer.php?login=sisu@lists.sisudoc.org - { SiSU @ Wikipedia }http://en.wikipedia.org/wiki/SiSU -</pre> -<p> -<h2><a name='sect23' href='#toc23'>Available Headers</a></h2> - -<p> Header tags appear at the beginning of a document and -provide meta information on the document (such as the <i>Dublin</i> Core ) , or -information as to how the document as a whole is to be processed. All header -instructions take the form @headername: or on the next line and indented -by once space :subheadername: All <i>Dublin</i> Core meta tags are available -<p> - <b>@indentifier:</b> information or instructions -<p> where the "identifier" is -a tag recognised by the program, and the "information" or "instructions" - -<p>belong to the tag/identifier specified -<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. - -<p> This is a sample header -<p> <br> -<pre>% SiSU 2.0 [declared file-type identifier with markup version] -</pre> -<p> <br> -<pre>@title: [title text] [this header is the only one that is mandatory] - :subtitle: [subtitle if any] - :language: English -</pre> -<p> <br> -<pre>@creator: - :author: [Lastname, First names] - :illustrator: [Lastname, First names] - :translator: [Lastname, First names] - :prepared_by: [Lastname, First names] -</pre> -<p> <br> -<pre>@date: - :published: [year or yyyy-mm-dd] - :created: [year or yyyy-mm-dd] - :issued: [year or yyyy-mm-dd] - :available: [year or yyyy-mm-dd] - :modified: [year or yyyy-mm-dd] - :valid: [year or yyyy-mm-dd] - :added_to_site: [year or yyyy-mm-dd] - :translated: [year or yyyy-mm-dd] -</pre> -<p> <br> -<pre>@rights: - :copyright: Copyright (C) [Year and Holder] - :license: [Use License granted] - :text: [Year and Holder] - :translation: [Name, Year] - :illustrations: [Name, Year] -</pre> -<p> <br> -<pre>@classify: - :topic_register: SiSU:markup sample:book;book:novel:fantasy - :type: - :subject: - :description: - :keywords: - :abstract: - :loc: [Library of Congress classification] - :dewey: [Dewey classification -</pre> -<p> <br> -<pre>@identify: - :isbn: [ISBN] - :oclc: -</pre> -<p> <br> -<pre>@links: { SiSU }http://www.sisudoc.org - { FSF }http://www.fsf.org -</pre> -<p> <br> -<pre>@make: - :num_top: 1 - :headings: [text to match for each level - (e.g. PART; Chapter; Section; Article; or another: none; BOOK|FIRST|SECOND; -none; CHAPTER;) - :breaks: new=:C; break=1 - :promo: sisu, ruby, sisu_search_libre, open_society - :bold: [regular expression of words/phrases to be made bold] - :italics: [regular expression of words/phrases to italicise] - :home_button_text: {SiSU}http://sisudoc.org; {git}http://git.sisudoc.org - :footer: {SiSU}http://sisudoc.org; {git}http://git.sisudoc.org -</pre> -<p> <br> -<pre>@original: - :language: [language] -</pre> -<p> <br> -<pre>@notes: - :comment: - :prefix: [prefix is placed just after table of contents] -</pre> -<p> -<h2><a name='sect24' href='#toc24'>Markup of Substantive Text</a></h2> - -<p> -<h2><a name='sect25' href='#toc25'>Heading Levels</a></h2> - -<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) -<p> <b>:A~ [heading -text]</b> Top level heading [this usually has similar content to the title -@title: ] NOTE: the heading levels described here are in 0.38 notation, - -<p>see heading -<p> <b>:B~ [heading text]</b> Second level heading [this is a heading -level divider] -<p> <b>:C~ [heading text]</b> Third level heading [this 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 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> <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> <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> -<h2><a name='sect26' href='#toc26'>Font Attributes</a></h2> - -<p> <b>markup example:</b> -<p> <br> -<pre>normal text, *{emphasis}*, !{bold text}!, /{italics}/, _{underscore}_, -"{citation}", -^{superscript}^, ,{subscript},, +{inserted text}+, -{strikethrough}-, #{monospace}# -normal text -*{emphasis}* [note: can be configured to be represented by bold, italics -or underscore] -!{bold text}! -/{italics}/ -_{underscore}_ -"{citation}" -^{superscript}^ -,{subscript}, -+{inserted text}+ --{strikethrough}- -#{monospace}# -</pre> -<p> <b>resulting output:</b> -<p> normal text, <b>emphasis,</b> <b>bold text</b> , <i>italics,</i> <i>underscore,</i> -"citation", ^superscript^, [subscript], ++inserted text++, --strikethrough--, - -<p>monospace -<p> normal text -<p> <b>emphasis</b> [note: can be configured to be represented -by bold, italics or underscore] -<p> <b>bold text</b> -<p> <i>italics</i> -<p> <i>underscore</i> -<p> "citation" - -<p> ^superscript^ -<p> [subscript] -<p> ++inserted text++ -<p> --strikethrough-- -<p> monospace - -<p> -<h2><a name='sect27' href='#toc27'>Indentation and Bullets</a></h2> - -<p> <b>markup example:</b> -<p> <br> -<pre>ordinary paragraph -_1 indent paragraph one step -_2 indent paragraph two steps -_9 indent paragraph nine steps -</pre> -<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> <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> * 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> <br> -<pre># numbered list numbered list 1., 2., 3, etc. -_# numbered list numbered list indented a., b., c., d., etc. -</pre> -<p> -<h2><a name='sect28' href='#toc28'>Hanging Indents</a></h2> - -<p> <b>markup example:</b> -<p> <br> -<pre>_0_1 first line no indent, -rest of paragraph indented one step -_1_0 first line indented, -rest of paragraph no indent -in each case level may be 0-9 -</pre> -<p> <b>resulting output:</b> -<p> first line no indent, rest of paragraph indented -one step; first line no indent, rest of paragraph indented one step; -first line no indent, rest of<br> - paragraph indented one step; first line no indent, rest of paragraph -indented<br> - one step; first line no indent, rest of paragraph indented one step; -first<br> - line no indent, rest of paragraph indented one step; first line no indent,<br> - rest of paragraph indented one step; first line no indent, rest of paragraph<br> - indented one step; first line no indent, rest of paragraph indented -one step;<br> - -<p> A regular paragraph. -<p> first line indented, rest of paragraph no indent -first line indented, rest of paragraph no indent first line indented, rest -of paragraph no indent first line indented, rest of paragraph no indent -first line indented, rest of paragraph no indent first line indented, rest -of paragraph no indent first line indented, rest of paragraph no indent -first line indented, rest of paragraph no indent first line indented, rest -of paragraph no indent first line indented, rest of paragraph no indent -first line indented, rest of paragraph no indent -<p> in each case level may - -<p>be 0-9 -<p> <b>live-build</b> A collection of scripts used to build customized Debian<br> - Livesystems.<br> - .I live-build<br> - was formerly known as live-helper, and even earlier known as live-package.<br> - -<p> <b>live-build</b> -<p> A collection of scripts used to build customized Debian<br> - Livesystems. live-build was formerly known as live-helper, and even earlier<br> - known as live-package.<br> - -<h2><a name='sect29' href='#toc29'>Footnotes / Endnotes</a></h2> - -<p> Footnotes and endnotes are marked up at the location -where they would be indicated within a text. They are automatically numbered. - -<p>The output type determines whether footnotes or endnotes will be produced - -<p> <b>markup example:</b> -<p> <br> -<pre>~{ a footnote or endnote }~ -</pre> -<p> <b>resulting output:</b> -<p> [^13] -<p> <b>markup example:</b> -<p> <br> -<pre>normal text~{ self contained endnote marker & endnote in one }~ continues -</pre> -<p> <b>resulting output:</b> -<p> normal text[^14] continues -<p> <b>markup example:</b> -<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> normal text [^**] continues - -<p> <b>markup example:</b> -<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> normal text [^+2] continues - -<p> <b>Alternative endnote pair notation for footnotes/endnotes:</b> -<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> - -<h2><a name='sect30' href='#toc30'>Links</a></h2> - -<p> -<h2><a name='sect31' href='#toc31'>Naked Urls Within Text, Dealing with Urls</a></h2> - -<p> urls found within text -are marked up automatically. A url within text is automatically hyperlinked -to itself and by default decorated with angled braces, unless they are -contained within a code block (in which case they are passed as normal -text), or escaped by a preceding underscore (in which case the decoration -is omitted). -<p> <b>markup example:</b> -<p> <br> -<pre>normal text http://www.sisudoc.org/ continues -</pre> -<p> <b>resulting output:</b> -<p> normal text <<a href='http://www.sisudoc.org/'>http://www.sisudoc.org/</a> -> continues -<p> An - -<p>escaped url without decoration -<p> <b>markup example:</b> -<p> <br> -<pre>normal text _http://www.sisudoc.org/ continues -deb _http://www.jus.uio.no/sisu/archive unstable main non-free -</pre> -<p> <b>resulting output:</b> -<p> normal text <_<a href='http://www.sisudoc.org/'>http://www.sisudoc.org/</a> -> continues -<p> deb -<_<a href='http://www.jus.uio.no/sisu/archive'>http://www.jus.uio.no/sisu/archive</a> -> 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> <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> -<h2><a name='sect32' href='#toc32'>Linking Text</a></h2> - -<p> To link text or an image to a url the markup is as follows - -<p> <b>markup example:</b> -<p> <br> -<pre>about { SiSU }http://url.org markup -</pre> -<p> <b>resulting output:</b> -<p> aboutSiSU <<a href='http://www.sisudoc.org/'>http://www.sisudoc.org/</a> -> markup -<p> A shortcut - -<p>notation is available so the url link may also be provided automatically - -<p>as a footnote -<p> <b>markup example:</b> -<p> <br> -<pre>about {~^ SiSU }http://url.org markup -</pre> -<p> <b>resulting output:</b> -<p> aboutSiSU <<a href='http://www.sisudoc.org/'>http://www.sisudoc.org/</a> -> [^15] markup -<p> Internal -document links to a tagged location, including an ocn -<p> <b>markup example:</b> - -<p> <br> -<pre>about { text links }#link_text -</pre> -<p> <b>resulting output:</b> -<p> about ⌠text links⌡⌈link_text⌋ -<p> Shared document - -<p>collection link -<p> <b>markup example:</b> -<p> <br> -<pre>about { SiSU book markup examples }:SiSU/examples.html -</pre> -<p> <b>resulting output:</b> -<p> about ⌠ <b>SiSU</b> book markup examples⌡⌈:SiSU/examples.html⌋ - -<p> -<h2><a name='sect33' href='#toc33'>Linking Images</a></h2> - -<p> <b>markup example:</b> -<p> <br> -<pre>{ tux.png 64x80 }image -% various url linked images -{tux.png 64x80 "a better way" }http://www.sisudoc.org/ -{GnuDebianLinuxRubyBetterWay.png 100x101 "Way Better - with Gnu/Linux, Debian -and Ruby" }http://www.sisudoc.org/ -{~^ ruby_logo.png "Ruby" }http://www.ruby-lang.org/en/ -</pre> -<p> <b>resulting output:</b> -<p> [ tux.png ] -<p> tux.png 64x80 "Gnu/Linux - a better way" -<<a href='http://www.sisudoc.org/'>http://www.sisudoc.org/</a> -> -<p> GnuDebianLinuxRubyBetterWay.png 100x101 "Way Better -- with Gnu/Linux, Debian and Ruby" <<a href='http://www.sisudoc.org/'>http://www.sisudoc.org/</a> -> -<p> ruby_logo.png -70x90 "Ruby" <<a href='http://www.ruby-lang.org/en/'>http://www.ruby-lang.org/en/</a> -> [^16] -<p> <b>linked url footnote shortcut</b> - -<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> <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. -<h2><a name='sect34' href='#toc34'>Link Shortcut for Multiple -Versions of a Sisu Document in the Same Directory</a></h2> -TREE -<p> <b>markup example:</b> - -<p> <br> -<pre>!_ /{"Viral Spiral"}/, David Bollier -{ "Viral Spiral", David Bollier [3sS]}viral_spiral.david_bollier.sst -</pre> -<p> <b></b> <i>Viral Spiral</i>, David Bollier -<p> "Viral Spiral", David Bollier <<a href='http://corundum/sisu_manual/en/manifest/viral_spiral.david_bollier.html'>http://corundum/sisu_manual/en/manifest/viral_spiral.david_bollier.html</a> -> - document manifest <<a href='http://corundum/sisu_manual/en/manifest/viral_spiral.david_bollier.html'>http://corundum/sisu_manual/en/manifest/viral_spiral.david_bollier.html</a> -><br> - ⌠html, segmented text⌡「<a href='http://corundum/sisu_manual/en/html/viral_spiral.david_bollier.html」'>http://corundum/sisu_manual/en/html/viral_spiral.david_bollier.html」</a> -<br> - ⌠html, scroll, document in one⌡「<a href='http://corundum/sisu_manual/en/html/viral_spiral.david_bollier.html」'>http://corundum/sisu_manual/en/html/viral_spiral.david_bollier.html」</a> -<br> - ⌠epub⌡「<a href='http://corundum/sisu_manual/en/epub/viral_spiral.david_bollier.epub」'>http://corundum/sisu_manual/en/epub/viral_spiral.david_bollier.epub」</a> -<br> - ⌠pdf, landscape⌡「<a href='http://corundum/sisu_manual/en/pdf/viral_spiral.david_bollier.pdf」'>http://corundum/sisu_manual/en/pdf/viral_spiral.david_bollier.pdf」</a> -<br> - ⌠pdf, portrait⌡「<a href='http://corundum/sisu_manual/en/pdf/viral_spiral.david_bollier.pdf」'>http://corundum/sisu_manual/en/pdf/viral_spiral.david_bollier.pdf」</a> -<br> - ⌠odf: odt, open document text⌡「<a href='http://corundum/sisu_manual/en/odt/viral_spiral.david_bollier.odt」'>http://corundum/sisu_manual/en/odt/viral_spiral.david_bollier.odt」</a> -<br> - ⌠xhtml scroll⌡「<a href='http://corundum/sisu_manual/en/xhtml/viral_spiral.david_bollier.xhtml」'>http://corundum/sisu_manual/en/xhtml/viral_spiral.david_bollier.xhtml」</a> -<br> - ⌠xml, sax⌡「<a href='http://corundum/sisu_manual/en/xml/viral_spiral.david_bollier.xml」'>http://corundum/sisu_manual/en/xml/viral_spiral.david_bollier.xml」</a> -<br> - ⌠xml, dom⌡「<a href='http://corundum/sisu_manual/en/xml/viral_spiral.david_bollier.xml」'>http://corundum/sisu_manual/en/xml/viral_spiral.david_bollier.xml」</a> -<br> - ⌠concordance⌡「<a href='http://corundum/sisu_manual/en/html/viral_spiral.david_bollier.html」'>http://corundum/sisu_manual/en/html/viral_spiral.david_bollier.html」</a> -<br> - ⌠dcc, document content certificate (digests)⌡「<a href='http://corundum/sisu_manual/en/digest/viral_spiral.david_bollier.txt」'>http://corundum/sisu_manual/en/digest/viral_spiral.david_bollier.txt」</a> -<br> - ⌠markup source text⌡「<a href='http://corundum/sisu_manual/en/src/viral_spiral.david_bollier.sst」'>http://corundum/sisu_manual/en/src/viral_spiral.david_bollier.sst」</a> -<br> - ⌠markup source (zipped) pod⌡「<a href='http://corundum/sisu_manual/en/pod/viral_spiral.david_bollier.sst.zip」'>http://corundum/sisu_manual/en/pod/viral_spiral.david_bollier.sst.zip」</a> -<br> - -<p> -<h2><a name='sect35' href='#toc35'>Grouped Text</a></h2> - -<p> -<h2><a name='sect36' href='#toc36'>Tables</a></h2> - -<p> Tables may be prepared in two either of two forms - -<p> <b>markup example:</b> -<p> <br> -<pre>table{ c3; 40; 30; 30; -This is a table -this would become column two of row one -column three of row one is here -And here begins another row -column two of row two -column three of row two, and so on -}table -</pre> -<p> <b>resulting output:</b> -<p> This is a table|this would become column two of row -one|column three of row one is here』And here begins another row|column -two of row two|column three of row two, and so on』 -<p> a second form may - -<p>be easier to work with in cases where there is not much information in - -<p>each column -<p> <b>markup example:</b> [^17] <br> -<pre>!_ Table 3.1: Contributors to Wikipedia, January 2001 - June 2005 -{table~h 24; 12; 12; 12; 12; 12; 12;} - |Jan. 2001|Jan. 2002|Jan. 2003|Jan. 2004|July 2004|June -2006 -Contributors* | 10| 472| 2,188| 9,653| -25,011| 48,721 -Active contributors** | 9| 212| 846| 3,228| - 8,442| 16,945 -Very active contributors*** | 0| 31| 190| 692| - 1,639| 3,016 -No. of English language articles| 25| 16,000| 101,000| 190,000| 320,000| - 630,000 -No. of articles, all languages | 25| 19,000| 138,000| 490,000| 862,000|1,600,000 -* Contributed at least ten times; ** at least 5 times in last month; *** -more than 100 times in last month. -</pre> -<p> <b>resulting output:</b> -<p> <b>Table 3.1: Contributors to Wikipedia, January 2001 -- June 2005</b> |Jan. 2001|Jan. 2002|Jan. 2003|Jan. 2004|July 2004|June 2006』Contributors*|10|472|2,188|9,653|25,011|48,721』Active -contributors**|9|212|846|3,228|8,442|16,945』Very active contributors***|0|31|190|692|1,639|3,016』No. -of English language articles|25|16,000|101,000|190,000|320,000|630,000』No. of -articles, all languages|25|19,000|138,000|490,000|862,000|1,600,000』 -<p> * Contributed -at least ten times; ** at least 5 times in last month; *** more than 100 -times in last month. -<p> -<h2><a name='sect37' href='#toc37'>Poem</a></h2> - -<p> <b>basic markup:</b> -<p> <br> -<pre>poem{ - Your poem here -}poem -Each verse in a poem is given an object number. -</pre> -<p> <b>markup example:</b> -<p> <br> -<pre>poem{ - ‘Fury said to a - mouse, That he - met in the - house, - "Let us - both go to - law: I will - prosecute - YOU. --Come, - I’ll take no - denial; We - must have a - trial: For - really this - morning I’ve - nothing - to do." - Said the - mouse to the - cur, "Such - a trial, - dear Sir, - With - no jury - or judge, - would be - wasting - our - breath." - "I’ll be - judge, I’ll - be jury," - Said - cunning - old Fury: - "I’ll - try the - whole - cause, - and - condemn - you - to - death."’ -}poem -</pre> -<p> <b>resulting output:</b> -<p> ‘Fury said to a<br> - mouse, That he<br> - met in the<br> - house,<br> - "Let us<br> - both go to<br> - law: I will<br> - prosecute<br> - YOU. --Come,<br> - I’ll take no<br> - denial; We<br> - must have a<br> - trial: For<br> - really this<br> - morning I’ve<br> - nothing<br> - to do."<br> - Said the<br> - mouse to the<br> - cur, "Such<br> - a trial,<br> - dear Sir,<br> - With<br> - no jury<br> - or judge,<br> - would be<br> - wasting<br> - our<br> - breath."<br> - "I’ll be<br> - judge, I’ll<br> - be jury,"<br> - Said<br> - cunning<br> - old Fury:<br> - "I’ll<br> - try the<br> - whole<br> - cause,<br> - and<br> - condemn<br> - you<br> - to<br> - death."’<br> - -<p> -<h2><a name='sect38' href='#toc38'>Group</a></h2> - -<p> <b>basic markup:</b> -<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> <br> -<pre>group{ - ‘Fury said to a - mouse, That he - met in the - house, - "Let us - both go to - law: I will - prosecute - YOU. --Come, - I’ll take no - denial; We - must have a - trial: For - really this - morning I’ve - nothing - to do." - Said the - mouse to the - cur, "Such - a trial, - dear Sir, - With - no jury - or judge, - would be - wasting - our - breath." - "I’ll be - judge, I’ll - be jury," - Said - cunning - old Fury: - "I’ll - try the - whole - cause, - and - condemn - you - to - death."’ -}group -</pre> -<p> <b>resulting output:</b> -<p> ‘Fury said to a<br> - mouse, That he<br> - met in the<br> - house,<br> - "Let us<br> - both go to<br> - law: I will<br> - prosecute<br> - YOU. --Come,<br> - I’ll take no<br> - denial; We<br> - must have a<br> - trial: For<br> - really this<br> - morning I’ve<br> - nothing<br> - to do."<br> - Said the<br> - mouse to the<br> - cur, "Such<br> - a trial,<br> - dear Sir,<br> - With<br> - no jury<br> - or judge,<br> - would be<br> - wasting<br> - our<br> - breath."<br> - "I’ll be<br> - judge, I’ll<br> - be jury,"<br> - Said<br> - cunning<br> - old Fury:<br> - "I’ll<br> - try the<br> - whole<br> - cause,<br> - and<br> - condemn<br> - you<br> - to<br> - death."’<br> - -<p> -<h2><a name='sect39' href='#toc39'>Code</a></h2> - -<p> Code tags code{ ... }code (used as with other group tags described -above) 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. -<p> A code-block is treated as an object and given a -single object number. [an option to number each line of code may be considered -at some later time] -<p> <b>use of code tags instead of poem compared, resulting -output:</b> -<p> <br> -<pre> ‘Fury said to a - mouse, That he - met in the - house, - "Let us - both go to - law: I will - prosecute - YOU. --Come, - I’ll take no - denial; We - must have a - trial: For - really this - morning I’ve - nothing - to do." - Said the - mouse to the - cur, "Such - a trial, - dear Sir, - With - no jury - or judge, - would be - wasting - our - breath." - "I’ll be - judge, I’ll - be jury," - Said - cunning - old Fury: - "I’ll - try the - whole - cause, - and - condemn - you - to - death."’ -</pre> -<p> From <b>SiSU</b> 2.7.7 on you can number codeblocks by placing a hash after the -opening code tag code{# as demonstrated here: -<p> <br> -<pre>1 | ‘Fury said to a -2 | mouse, That he -3 | met in the -4 | house, -5 | "Let us -6 | both go to -7 | law: I will -8 | prosecute -9 | YOU. --Come, -10 | I’ll take no -11 | denial; We -12 | must have a -13 | trial: For -14 | really this -15 | morning I’ve -16 | nothing -17 | to do." -18 | Said the -19 | mouse to the -20 | cur, "Such -21 | a trial, -22 | dear Sir, -23 | With -24 | no jury -25 | or judge, -26 | would be -27 | wasting -28 | our -29 | breath." -30 | "I’ll be -31 | judge, I’ll -32 | be jury," -33 | Said -34 | cunning -35 | old Fury: -36 | "I’ll -37 | try the -38 | whole -39 | cause, -40 | and -41 | condemn -42 | you -43 | to -44 | death."’ -</pre> -<p> -<h2><a name='sect40' href='#toc40'>Additional Breaks - Linebreaks Within Objects, Column and Page-breaks</a></h2> - -<p> -<h2><a name='sect41' href='#toc41'>Line-breaks</a></h2> - -<p> - To break a line within a "paragraph object", two backslashes \\ with a space -before and a space or newline after them may be used. -<p> <br> -<pre>To break a line within a "paragraph object", -two backslashes \\ with a space before -and a space or newline after them \\ -may be used. -</pre> -<p> The html break br enclosed in angle brackets (though undocumented) is -available in versions prior to 3.0.13 and 2.9.7 (it remains available for the -time being, but is depreciated). -<p> -<h2><a name='sect42' href='#toc42'>Page Breaks</a></h2> - -<p> Page breaks are only relevant -and honored in some output formats. A page break or a new page may be inserted -manually using the following markup on a line on its own: -<p> page new =\= -or breaks the page, starts a new page. -<p> page break -\- or breaks a column, -starts a new column, if using columns, else breaks the page, starts a new -page. -<p> <br> -<pre>-\\- -or -<:pb> -</pre> -<p> or -<p> <br> -<pre>=\\= -or -<:pn> -</pre> -<p> -<h2><a name='sect43' href='#toc43'>Book Index</a></h2> - -<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. <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> <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> <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> <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> <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> <br> -<pre> Main term, 1, - sub-term, 1-3, - second sub-term, 1, -</pre> -<p> -<h2><a name='sect44' href='#toc44'>Composite Documents Markup</a></h2> - -<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, or they -could be markup snippets, prepared so as to be easily available to be placed -within another text. If the calling document is a master document (built -from other documents), it should be named with the suffix <b>.ssm</b> Within this -document you would provide information on the other documents that should -be included within the text. These may be other documents that would be -processed in a regular way, or markup bits prepared only for inclusion -within a master document <b>.sst</b> regular markup file, or <b>.ssi</b> (insert/information) - -<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> basic markup for importing a - -<p>document into a master document -<p> <br> -<pre><< filename1.sst -<< filename2.ssi -</pre> -<p> The form described above should be relied on. Within the <i>Vim</i> editor it -results in the text thus linked becoming hyperlinked to the document it -is calling in which is convenient for editing. -<p> -<h2><a name='sect45' href='#toc45'>Sisu Filetypes</a></h2> - -<p> <b>SiSU</b> has -<i>plaintext</i> and binary filetypes, and can process either type of document. - -<p> -<h2><a name='sect46' href='#toc46'>.sst .ssm .ssi Marked Up Plain Text</a></h2> - -<p> -<dl> - -<dt><b>SiSU</b> </dt> -<dd>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 beneath them _sisu/image. -〔b¤SiSU <i>plaintext</i> markup files are of three types that may be distinguished -by the file extension used: regular text .sst; master documents, composite -documents that incorporate other text, which can be any regular text or -text insert; and inserts the contents of which are like regular text except -these are marked .ssi and are not processed. -<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> sisu -s [filename] -<p> </dd> -</dl> - -<h2><a name='sect47' href='#toc47'>Sisu Text - Regular Files (.sst)</a></h2> - -<p> -The most common form of document in <b>SiSU,</b> see the section on <b>SiSU</b> markup. - -<p> -<h2><a name='sect48' href='#toc48'>Sisu Master Files (.ssm)</a></h2> - -<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. -<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. -<p> Note: -a secondary file of the composite document is built prior to processing -with the same prefix and the suffix ._sst [^18] -<p> -<h2><a name='sect49' href='#toc49'>Sisu Insert Files (.ssi)</a></h2> - -<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. -<p> -<h2><a name='sect50' href='#toc50'>Sisupod, Zipped Binary Container -(sisupod.zip, .ssp)</a></h2> - -<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> -<dl> - -<dt><b>SiSU</b> </dt> -<dd><i>plaintext</i> 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. -<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. - -<p> The command to create a sisupod is: -<p> sisu -S [filename] -<p> Alternatively, -make a pod of the contents of a whole directory: -<p> sisu -S -<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. -<p> <<a href='http://www.sisudoc.org/sisu/sisu_commands'>http://www.sisudoc.org/sisu/sisu_commands</a> -> - -<p> <<a href='http://www.sisudoc.org/sisu/sisu_manual'>http://www.sisudoc.org/sisu/sisu_manual</a> -> -<p> </dd> -</dl> - -<h2><a name='sect51' href='#toc51'>Configuration</a></h2> - -<p> -<h2><a name='sect52' href='#toc52'>Configuration Files</a></h2> - -<p> - -<h2><a name='sect53' href='#toc53'>Config.yml</a></h2> - -<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. -<p> The <b>SiSU</b> configuration file is -a yaml file, which means indentation is significant. -<p> <b>SiSU</b> resource configuration -is determined by looking at the following files if they exist: -<p> ./_sisu/v4/sisurc.yml<br> - -<p> ./_sisu/sisurc.yml<br> - -<p> ~/.sisu/v4/sisurc.yml<br> - -<p> ~/.sisu/sisurc.yml<br> - -<p> /etc/sisu/v4/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> - In the absence of instructions in any of these it falls back to the internal -program defaults. -<p> Configuration determines the output and processing directories -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> -<h2><a name='sect54' href='#toc54'>Sisu_document_make</a></h2> - -<p> Most sisu document -headers relate to metadata, the exception is the @make: header which provides -processing related information. The default contents of the @make header -may be set by placing them in a file sisu_document_make. -<p> The search order -is as for resource configuration: -<p> ./_sisu/v4/sisu_document_make<br> - -<p> ./_sisu/sisu_document_make<br> - -<p> ~/.sisu/v4/sisu_document_make<br> - -<p> ~/.sisu/sisu_document_make<br> - -<p> /etc/sisu/v4/sisu_document_make<br> - -<p> /etc/sisu/sisu_document_make<br> - -<p> A sample sisu_document_make can be found in the _sisu/ directory under -along with the provided sisu markup samples. -<p> -<h2><a name='sect55' href='#toc55'>Css - Cascading Style Sheets -(for Html, Xhtml and Xml)</a></h2> - -<p> CSS files to modify the appearance of <b>SiSU</b> html, -<i>XHTML</i> or <i>XML</i> may be placed in the configuration directory: ./_sisu/css ; -~/.sisu/css or; /etc/sisu/css and these will be copied to the output directories -with the command sisu -CC. -<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> <i>HTML:</i> html. css -<p> <i>XML</i> -DOM: dom.css -<p> <i>XML</i> SAX: sax.css -<p> <i>XHTML:</i> xhtml. css -<p> 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.[^19] -<p> -<h2><a name='sect56' href='#toc56'>Organising Content - Directory Structure and Mapping</a></h2> - -<p> - <b>SiSU</b> v3 has new options for the source directory tree, and output directory -structures of which there are 3 alternatives. -<p> -<h2><a name='sect57' href='#toc57'>Document Source Directory</a></h2> - -<p> - The document source directory is the directory in which sisu processing -commands are given. It contains the sisu source files (.sst .ssm .ssi), or -(for sisu v3 may contain) subdirectories with language codes which contain -the sisu source files, so all English files would go in subdirectory en/, -French in fr/, Spanish in es/ and so on. ISO 639-1 codes are used (as varied -by po4a). A list of available languages (and possible sub-directory names) -can be obtained with the command "sisu --help lang" The list of languages -is limited to langagues supported by XeTeX polyglosia. -<p> -<h2><a name='sect58' href='#toc58'>General Directories</a></h2> - -<p> -<br> -<pre>% files stored at this level e.g. sisu_manual.sst or -% for sisu v3 may be under language sub-directories -% e.g. - ./subject_name/en - ./subject_name/fr - ./subject_name/es - ./subject_name/_sisu - ./subject_name/_sisu/css - ./subject_name/_sisu/image -</pre> -<p> -<h2><a name='sect59' href='#toc59'>Document Output Directory Structures</a></h2> - -<p> -<h2><a name='sect60' href='#toc60'>Output Directory Root</a></h2> - -<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 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) -<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 implications for the organisation -of document collections as it could make sense to place documents of a -particular subject, or type within a directory identifying them. This grouping -as suggested could be by subject (sales_law, english_literature); or just -as conveniently by some other classification (X University). The mapping -means it is also possible to place in the same output directory documents -that are for organisational purposes kept separately, for example documents -on a given subject of two different institutions may be kept in two different -directories of the same name, under a directory named after each institution, -and these would be output to the same output directory. Skins could be associated -with each institution on a directory basis and resulting documents will -take on the appropriate different appearance. -<p> -<h2><a name='sect61' href='#toc61'>Alternative Output Structures</a></h2> - -<p> - There are 3 possibile output structures described as being, by language, -by filetype or by filename, the selection is made in sisurc.yml -<p> <br> -<pre>#% output_dir_structure_by: language; filetype; or filename -output_dir_structure_by: language #(language & filetype, preferred?) -#output_dir_structure_by: filetype -#output_dir_structure_by: filename #(default, closest to original v1 & -v2) -</pre> -<p> -<h2><a name='sect62' href='#toc62'>by Language</a></h2> - -<p> The by language directory structure places output files -<p> - The by language directory structure separates output files by language -code (all files of a given language), and within the language directory -by filetype. -<p> Its selection is configured in sisurc.yml -<p> output_dir_structure_by: - -<p>language -<p> <br> -<pre> |-- en - |-- epub - |-- hashes - |-- html - | |-- viral_spiral.david_bollier - | |-- manifest - | |-- qrcode - | |-- odt - | |-- pdf - | |-- sitemaps - | |-- txt - | |-- xhtml - | ‘-- xml - |-- po4a - | ‘-- live-manual - | |-- po - | |-- fr - | ‘-- pot - ‘-- _sisu - |-- css - |-- image - |-- image_sys -> ../../_sisu/image_sys - ‘-- xml - |-- rnc - |-- rng - ‘-- xsd -</pre> -<p> #by: language subject_dir/en/manifest/filename.html -<p> -<h2><a name='sect63' href='#toc63'>by Filetype</a></h2> - -<p> The -by filetype directory structure separates output files by filetype, all -html files in one directory pdfs in another and so on. Filenames are given -a language extension. -<p> Its selection is configured in sisurc.yml -<p> output_dir_structure_by: - -<p>filetype -<p> <br> -<pre> |-- epub - |-- hashes - |-- html - |-- viral_spiral.david_bollier - |-- manifest - |-- qrcode - |-- odt - |-- pdf - |-- po4a - |-- live-manual - | |-- po - | |-- fr - | ‘-- pot - |-- _sisu - | |-- css - | |-- image - | |-- image_sys -> ../../_sisu/image_sys - | ‘-- xml - | |-- rnc - | |-- rng - | ‘-- xsd - |-- sitemaps - |-- txt - |-- xhtml - ‘-- xml -</pre> -<p> #by: filetype subject_dir/html/filename/manifest.en.html -<p> -<h2><a name='sect64' href='#toc64'>by Filename</a></h2> - -<p> -The by filename directory structure places most output of a particular -file (the different filetypes) in a common directory. -<p> Its selection is - -<p>configured in sisurc.yml -<p> output_dir_structure_by: filename -<p> <br> -<pre> |-- epub - |-- po4a - |-- live-manual - | |-- po - | |-- fr - | ‘-- pot - |-- _sisu - | |-- css - | |-- image - | |-- image_sys -> ../../_sisu/image_sys - | ‘-- xml - | |-- rnc - | |-- rng - | ‘-- xsd - |-- sitemaps - |-- src - |-- pod - ‘-- viral_spiral.david_bollier -</pre> -<p> #by: filename subject_dir/filename/manifest.en.html -<p> -<h2><a name='sect65' href='#toc65'>Remote Directories</a></h2> - -<p> -<br> -<pre> ./subject_name/ -% containing sub_directories named after the generated files from which -they are made - ./subject_name/src -% contains shared source files text and binary e.g. sisu_manual.sst and sisu_manual.sst.zip - ./subject_name/_sisu -% configuration file e.g. sisurc.yml - ./subject_name/_sisu/skin -% skins in various skin directories doc, dir, site, yml - ./subject_name/_sisu/css - ./subject_name/_sisu/image -% images for documents contained in this directory - ./subject_name/_sisu/mm -</pre> -<p> -<h2><a name='sect66' href='#toc66'>Sisupod</a></h2> - -<p> <br> -<pre> ./sisupod/ -% files stored at this level e.g. sisu_manual.sst - ./sisupod/_sisu -% configuration file e.g. sisurc.yml - ./sisupod/_sisu/skin -% skins in various skin directories doc, dir, site, yml - ./sisupod/_sisu/css - ./sisupod/_sisu/image -% images for documents contained in this directory - ./sisupod/_sisu/mm -</pre> -<p> -<h2><a name='sect67' href='#toc67'>Organising Content</a></h2> - -<p> -<h2><a name='sect68' href='#toc68'>Homepages</a></h2> - -<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> More accurately, <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: -<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> 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. -<p> -<h2><a name='sect69' href='#toc69'>Home -Page and Other Custom Built Pages in a Sub-directory</a></h2> - -<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: -<p> - sisu -CC -<h2><a name='sect70' href='#toc70'>Markup and Output Examples</a></h2> - -<p> -<h2><a name='sect71' href='#toc71'>Markup Examples</a></h2> - -<p> Current markup examples -and document output samples are provided off <<a href='http://sisudoc.org'>http://sisudoc.org</a> -> or <<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a> -> -and in the sisu -markup-sample package available off <<a href='http://sources.sisudoc.org'>http://sources.sisudoc.org</a> -> - -<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. -<p> -<h2><a name='sect72' href='#toc72'>Sisu Markup Samples</a></h2> - -<p> A few -additional sample books prepared as sisu markup samples, output formats -to be generated using <b>SiSU</b> are contained in a separate package sisu -markup-samples. -sisu -markup-samples contains books (prepared using sisu markup), that were -released by their authors various licenses mostly different Creative Commons -licences that do not permit inclusion in the <b>Debian</b> Project as they have -requirements that do not meet the <b>Debian</b> Free Software Guidelines for various -reasons, most commonly that they require that the original substantive -text remain unchanged, and sometimes that the works be used only non-commercially. - -<p> <i>Accelerando,</i> Charles Stross (2005) accelerando.charles_stross.sst -<p> <i>Alice’s</i> -Adventures in Wonderland, Lewis Carroll (1865) alices_adventures_in_wonderland.lewis_carroll.sst - -<p> <i>CONTENT,</i> Cory Doctorow (2008) content.cory_doctorow.sst -<p> <i>Democratizing</i> -Innovation, Eric von Hippel (2005) democratizing_innovation.eric_von_hippel.sst - -<p> <i>Down</i> and Out in the Magic Kingdom, Cory Doctorow (2003) down_and_out_in_the_magic_kingdom.cory_doctorow.sst - -<p> <i>For</i> the Win, Cory Doctorow (2010) for_the_win.cory_doctorow.sst -<p> <i>Free</i> -as in Freedom - Richard Stallman’s Crusade for Free Software, Sam Williams -(2002) free_as_in_freedom.richard_stallman_crusade_for_free_software.sam_williams.sst - -<p> <i>Free</i> as in Freedom 2.0 - Richard Stallman and the Free Software Revolution, -Sam Williams (2002), Richard M. Stallman (2010) free_as_in_freedom_2.richard_stallman_and_the_free_software_revolution.sam_williams.richard_stallman.sst - -<p> <i>Free</i> Culture - How Big Media Uses Technology and the Law to Lock Down -Culture and Control Creativity, Lawrence Lessig (2004) free_culture.lawrence_lessig.sst - -<p> <i>Free</i> For All - How Linux and the Free Software Movement Undercut the High -Tech Titans, Peter Wayner (2002) free_for_all.peter_wayner.sst -<p> <i>GNU</i> GENERAL -PUBLIC LICENSE v2, Free Software Foundation (1991) gpl2.fsf.sst -<p> <i>GNU</i> GENERAL -PUBLIC LICENSE v3, Free Software Foundation (2007) gpl3.fsf.sst -<p> <i>Gulliver’s</i> -Travels, Jonathan Swift (1726 / 1735) gullivers_travels.jonathan_swift.sst - -<p> <i>Little</i> Brother, Cory Doctorow (2008) little_brother.cory_doctorow.sst -<p> - <i>The</i> Cathederal and the Bazaar, Eric Raymond (2000) the_cathedral_and_the_bazaar.eric_s_raymond.sst - -<p> <i>The</i> Public Domain - Enclosing the Commons of the Mind, James Boyle (2008) - -<p>the_public_domain.james_boyle.sst -<p> <i>The</i> Wealth of Networks - How Social Production -Transforms Markets and Freedom, Yochai Benkler (2006) the_wealth_of_networks.yochai_benkler.sst - -<p> <i>Through</i> the Looking Glass, Lewis Carroll (1871) through_the_looking_glass.lewis_carroll.sst - -<p> <i>Two</i> Bits - The Cultural Significance of Free Software, Christopher Kelty -(2008) two_bits.christopher_kelty.sst -<p> <i>UN</i> Contracts for International Sale -of Goods, UN (1980) un_contracts_international_sale_of_goods_convention_1980.sst - -<p> <i>Viral</i> Spiral, David Bollier (2008) viral_spiral.david_bollier.sst -<p> -<h2><a name='sect73' href='#toc73'>Sisu -Search - Introduction</a></h2> - -<p> <b>SiSU</b> output can easily and conveniently be indexed -by a number of standalone indexing tools, such as Lucene, Hyperestraier. - -<p> Because the document structure of sites created is clearly defined, and -the text <i>object</i> 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. -<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> -<h2><a name='sect74' href='#toc74'>Sql</a></h2> - -<p> -<h2><a name='sect75' href='#toc75'>Populating Sql Type Databases</a></h2> - -<p> <b>SiSU</b> feeds -sisu markupd documents into sql type databases <i>PostgreSQL</i> [^20] and/or <i>SQLite</i> -[^21] database together with information related to document 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: -<p> * one containing semantic (and other) headers, -including, title, author, subject, (the<br> - .I Dublin Core.<br> - ..);<br> - -<p> * another the substantive texts by individual "paragraph" (or object) -- along with structural information, each paragraph being identifiable -by its<br> - paragraph number (if it has one which almost all of them do), and the<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 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 - full text versions of output, eg. pdf, html, xml, and<br> - .I ascii.<br> - -<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. -<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> As individual text objects of -a document stored (and indexed) together with object numbers, and all versions -of the document have the same numbering, complex searches can be tailored -to return just the locations of the search results relevant for all available -output formats, with live links to the precise locations in the database -or in html/xml documents; or, the structural information provided makes -it possible to search the full contents of the database and have headings -in which search content appears, or to search only headings etc. (as the -<i>Dublin</i> Core is incorporated it is easy to make use of that as well). -<p> -<h2><a name='sect76' href='#toc76'>Postgresql</a></h2> - -<p> - -<h2><a name='sect77' href='#toc77'>Name</a></h2> - -<p> <b>SiSU</b> - Structured information, Serialized Units - a document publishing -system, postgresql dependency package -<p> -<h2><a name='sect78' href='#toc78'>Description</a></h2> - -<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> -<h2><a name='sect79' href='#toc79'>Synopsis</a></h2> - -<p> sisu -D [instruction] [filename/wildcard if required] -<p> sisu --D --pg --[instruction] [filename/wildcard if required] -<p> -<h2><a name='sect80' href='#toc80'>Commands</a></h2> - -<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 - -<p>- -<p>- -<p>sqlite or --pgsql may be used -<p> <b>-D or --pgsql</b> may be used interchangeably. -<p> -<h2><a name='sect81' href='#toc81'>Create -and Destroy Database</a></h2> - -<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) -<p> </dd> - -<dt><b>sisu -D --createdb</b> </dt> -<dd>creates database where no database existed before - -<p> </dd> - -<dt><b>sisu -D --create</b> </dt> -<dd>creates database tables where no database tables existed - -<p>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). -<p> </dd> - -<dt><b>sisu -D --recreate</b> </dt> -<dd>destroys existing database - -<p>and builds a new empty database structure -<p> </dd> -</dl> - -<h2><a name='sect82' href='#toc82'>Import and Remove Documents</a></h2> - -<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). -<p> </dd> - -<dt><b>sisu -D --update -v [filename/wildcard]</b> </dt> -<dd>updates file contents - -<p>in database -<p> </dd> - -<dt><b>sisu -D --remove -v [filename/wildcard]</b> </dt> -<dd>removes specified document -from postgresql database. -<p> </dd> -</dl> - -<h2><a name='sect83' href='#toc83'>Sqlite</a></h2> - -<p> -<h2><a name='sect84' href='#toc84'>Name</a></h2> - -<p> <b>SiSU</b> - Structured information, Serialized -Units - a document publishing system. -<p> -<h2><a name='sect85' href='#toc85'>Description</a></h2> - -<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) . -<p> -<h2><a name='sect86' href='#toc86'>Synopsis</a></h2> - -<p> sisu --d [instruction] [filename/wildcard if required] -<p> sisu -d --(sqlite|pg) --[instruction] -[filename/wildcard if required] -<p> -<h2><a name='sect87' href='#toc87'>Commands</a></h2> - -<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 - -<p>may be used -<p> <b>-d or --sqlite</b> may be used interchangeably. -<p> -<h2><a name='sect88' href='#toc88'>Create and Destroy -Database</a></h2> - -<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) -<p> </dd> - -<dt><b>sisu --d --createdb</b> </dt> -<dd>creates database where no database existed before -<p> </dd> - -<dt><b>sisu -d --create</b> -</dt> -<dd> -<p>creates 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). -<p> </dd> - -<dt><b>sisu -d --recreate</b> </dt> -<dd>destroys existing database and builds - -<p>a new empty database structure -<p> </dd> -</dl> - -<h2><a name='sect89' href='#toc89'>Import and Remove Documents</a></h2> - -<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). - -<p> </dd> - -<dt><b>sisu -d --update -v [filename/wildcard]</b> </dt> -<dd>updates file contents in database - -<p> </dd> - -<dt><b>sisu -d --remove -v [filename/wildcard]</b> </dt> -<dd>removes specified document from sqlite -database. -<p> </dd> -</dl> - -<h2><a name='sect90' href='#toc90'>Introduction</a></h2> - -<p> -<h2><a name='sect91' href='#toc91'>Search - Database Frontend Sample, Utilising Database -and Sisu Features,</a></h2> -INCLUDING OBJECT CITATION NUMBERING (BACKEND CURRENTLY -POSTGRESQL) -<p> Sample search frontend <<a href='http://search.sisudoc.org'>http://search.sisudoc.org</a> -> [^22] A small -database and sample query front-end (search from) that makes use of the -citation system, .I object citation numbering to demonstrates functionality.[^23] - -<p> <b>SiSU</b> can provide information on which documents are matched and at what -locations within each document the matches are found. These results are -relevant across all outputs using <i>object</i> citation numbering, which includes -html, <i>XML,</i> <i>EPUB,</i> <i>LaTeX,</i> <i>PDF</i> and indeed the <i>SQL</i> database. You can then refer -to one of the other outputs or in the <i>SQL</i> database expand the text within -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.[^24] -<p> -<dl> - -<dt><b>sisu -F --webserv-webrick</b> </dt> -<dd>builds a cgi web search - -<p>frontend for the database created -<p> The following is feedback on the setup -on a machine provided by the help command: -<p> sisu --help sql <br> -<pre>Postgresql - user: ralph - current db set: SiSU_sisu - port: 5432 - dbi connect: DBI:Pg:database=SiSU_sisu;port=5432 -sqlite - current db set: /home/ralph/sisu_www/sisu/sisu_sqlite.db - dbi connect DBI:SQLite:/home/ralph/sisu_www/sisu/sisu_sqlite.db -</pre> -<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 necessary] </dd> -</dl> - -<h2><a name='sect92' href='#toc92'>Search Form</a></h2> - -<p> -<dl> - -<dt><b>sisu -F</b> </dt> -<dd>generates a sample search form, which - -<p>must 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> </dd> - -<dt><b>sisu -W</b> </dt> -<dd>starts the webrick server which - -<p>should be available wherever sisu is properly installed -<p> The generated - -<p>search form must be copied manually to the webserver directory as instructed - -<p> </dd> -</dl> - -<h2><a name='sect93' href='#toc93'>Sisu_webrick</a></h2> - -<p> -<h2><a name='sect94' href='#toc94'>Name</a></h2> - -<p> <b>SiSU</b> - Structured information, Serialized Units - a document - -<p>publishing system -<p> -<h2><a name='sect95' href='#toc95'>Synopsis</a></h2> - -<p> sisu_webrick [port] -<p> or -<p> sisu -W [port] -<p> - -<h2><a name='sect96' href='#toc96'>Description</a></h2> - -<p> sisu_webrick is part of <b>SiSU</b> (man sisu) sisu_webrick starts -<b>Ruby</b> <b>SiSU</b> output is written, providing a list of these directories (assuming -<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> -<h2><a name='sect97' href='#toc97'>Summary of Man Page</a></h2> - -<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] -<p> where no port is given and settings are unchanged - -<p>the default port is 8081 -<p> -<h2><a name='sect98' href='#toc98'>Document Processing Command Flags</a></h2> - -<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 been - -<p>changed in ~/.sisu/sisurc.yaml then on port 8081 -<p> -<h2><a name='sect99' href='#toc99'>Summary of Features</a></h2> - -<p> * -sparse/minimal markup (clean utf-8 source texts). Documents are prepared -in a single <i>UTF-8</i> file using a minimalistic mnemonic syntax. Typical literature, -documents like "War and Peace" require almost no markup, and most of the -headers are optional. -<p> * markup is easily readable/parsable by the human -eye, (basic markup is simpler and more sparse than the most basic <i>HTML</i> -) , [this may also be converted to <i>XML</i> representations of the same input/source -document]. -<p> * markup defines document structure (this may be done once -in a header pattern-match description, or for heading levels individually); -basic text attributes (bold, italics, underscore, strike-through etc.) as -required; and semantic information related to the document (header information, -extended beyond the Dublin core and easily further extended as required); -the headers may also contain processing instructions. <b>SiSU</b> markup is primarily -an abstraction of document structure and document metadata to permit taking -advantage of the basic strengths of existing alternative practical standard -ways of representing documents [be that browser viewing, paper publication, -sql search etc.] (html, epub, xml, odf, latex, pdf, sql) -<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: -<p> * <i>HTML</i> - both as a single scrollable - -<p>text and a segmented document -<p> * <i>XHTML</i> -<p> * <i>EPUB</i> -<p> * <i>XML</i> - both in sax and - -<p>dom style xml structures for further development as required -<p> * <i>ODT</i> - Open -Document Format text, the iso standard for document storage -<p> * <i>LaTeX</i> - - -<p>used to generate pdf -<p> * <i>PDF</i> (via <i>LaTeX</i> ) -<p> * <i>SQL</i> - population of an sql -database ( <i>PostgreSQL</i> or <i>SQLite</i> ) , (at the same object level that is used -to cite text within a document) -<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 <i>LaTeX,</i> databases populated with documents at an individual -object/paragraph level, making possible <i>granular</i> 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) -lacks a useful way of citing text internally within documents (important -to academics generally and to lawyers) as page numbers are meaningless -across browsers and formats. sisu seeks to provide a common way of pinpoint -the text within a document, (which can be utilized for citation and by -search engines). The outputs share a common numbering system that is meaningful -(to man and machine) across all digital outputs whether paper, screen, -or database oriented, (pdf, <i>HTML,</i> <i>EPUB,</i> xml, sqlite, postgresql) , this -numbering system can be used to reference content. -<p> * Granular search within -documents. <i>SQL</i> 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]. -<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", and -new document formats may be added. e.g. addition of odf (open document text) -module in 2006, epub in 2009 and in future html5 output sometime in future, - -<p>without modification of existing prepared texts -<p> * <i>SQL</i> search aside, documents -are generated as 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 output formats, updated technology document presentations/representations) - -<p> * document source ( <i>plaintext</i> utf-8) if shared on the net may be used - -<p>as 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) -and images and sent as a zip file called a sisupod, if shared on the net - -<p>these too may be processed locally to produce the desired document outputs - -<p> * generated document outputs may automatically be posted to remote sites. - -<p> * for basic document generation, the only software dependency is <b>Ruby,</b> -and a few standard Unix tools (this covers <i>plaintext,</i> <i>HTML,</i> <i>EPUB,</i> <i>XML,</i> -<i>ODF,</i> <i>LaTeX</i> ) . To use a database you of course need that, and to convert -the <i>LaTeX</i> generated to pdf, a latex processor like tetex or texlive. -<p> * - -<p>as a developers tool it is flexible and extensible -<p> Syntax highlighting -for <b>SiSU</b> markup 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 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) ... -<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. -<p> -<ol> -<b>.</b><li>objects include: headings, paragraphs, -verse, tables, images, but not footnotes/endnotes which are numbered separately -and tied to the object from which they are referenced. -<p> </li><b>.</b><li>i.e. the HTML, PDF, -EPUB, ODT outputs are each built individually and optimised for that form -of presentation, rather than for example the html being a saved version -of the odf, or the pdf being a saved version of the html. -<p> </li><b>.</b><li>the different - -<p>heading levels -<p> </li><b>.</b><li>units of text, primarily paragraphs and headings, also -any tables, poems, code-blocks -<p> </li><b>.</b><li>An open standard format for e-books -<p> </li><b>.</b><li>Open -Document Format ( ODF ) text -<p> </li><b>.</b><li>Specification submitted by Adobe to ISO -to become a full open ISO specification <<a href='http://www.linux-watch.com/news/NS7542722606.html'>http://www.linux-watch.com/news/NS7542722606.html</a> -> - -<p> </li><b>.</b><li>ISO standard ISO/IEC 26300:2006 -<p> </dd> - -<dt><b>*1.</b> </dt> -<dd>square brackets -<p> </dd> - -<dt><b>*2.</b> </dt> -<dd>square brackets - -<p> </dd> - -<dt><b>+1.</b> </dt> -<dd>square brackets -<p> </li><b>.</b><li><<a href='http://www.jus.uio.no/sisu/man/'>http://www.jus.uio.no/sisu/man/</a> -> -<p> </li><b>.</b><li><<a href='http://www.jus.uio.no/sisu/man/sisu.1.html'>http://www.jus.uio.no/sisu/man/sisu.1.html</a> -> - -<p> </li><b>.</b><li>From sometime after SiSU 0.58 it should be possible to describe SiSU markup -using SiSU, which though not an original design goal is useful. -<p> </li><b>.</b><li>files - -<p>should be prepared using UTF-8 character encoding -<p> </li><b>.</b><li>a footnote or endnote - -<p> </li><b>.</b><li>self contained endnote marker & endnote in one -<p> </dd> - -<dt><b>*.</b> </dt> -<dd>unnumbered asterisk -footnote/endnote, insert multiple asterisks if required -<p> </dd> - -<dt><b>**.</b> </dt> -<dd>another unnumbered - -<p>asterisk footnote/endnote -<p> </dd> - -<dt><b>*3.</b> </dt> -<dd>editors notes, numbered asterisk footnote/endnote - -<p>series -<p> </dd> - -<dt><b>+2.</b> </dt> -<dd>editors notes, numbered asterisk footnote/endnote series -<p> -</li><b>.</b><li><<a href='http://www.sisudoc.org/'>http://www.sisudoc.org/</a> -> -<p> </li><b>.</b><li><<a href='http://www.ruby-lang.org/en/'>http://www.ruby-lang.org/en/</a> -> -<p> </li><b>.</b><li>Table from the Wealth -of Networks by Yochai Benkler <<a href='http://www.jus.uio.no/sisu/the_wealth_of_networks.yochai_benkler'>http://www.jus.uio.no/sisu/the_wealth_of_networks.yochai_benkler</a> -> - -<p> </li><b>.</b><li>.ssc (for composite) is under consideration but ._sst makes clear that -this is not a regular file to be worked on, and thus less likely that people -will have "accidents", working on a .ssc file that is overwritten by subsequent -processing. It may be however that when the resulting file is shared .ssc -is an appropriate suffix to use. -<p> </li><b>.</b><li>SiSU has worked this way in the past, -though this was dropped as it was thought the complexity outweighed the -flexibility, however, the balance was rather fine and this behaviour could -be reinstated. -<p> </li><b>.</b><li><<a href='http://www.postgresql.org/'>http://www.postgresql.org/</a> -> <<a href='http://advocacy.postgresql.org/'>http://advocacy.postgresql.org/</a> -> -<<a href='http://en.wikipedia.org/wiki/Postgresql'>http://en.wikipedia.org/wiki/Postgresql</a> -> -<p> </li><b>.</b><li><<a href='http://www.hwaci.com/sw/sqlite/'>http://www.hwaci.com/sw/sqlite/</a> -> <<a href='http://en.wikipedia.org/wiki/Sqlite'>http://en.wikipedia.org/wiki/Sqlite</a> -> - -<p> </li><b>.</b><li><<a href='http://search.sisudoc.org'>http://search.sisudoc.org</a> -> -<p> </li><b>.</b><li>(which could be extended further with current -back-end). As regards scaling of the database, it is as scalable as the database -(here Postgresql) and hardware allow. -<p> </li><b>.</b><li>of this feature when demonstrated -to an IBM software innovations evaluator in 2004 he said to paraphrase: -this could be of interest to us. We have large document management systems, -you can search hundreds of thousands of documents and we can tell you which -documents meet your search criteria, but there is no way we can tell you -without opening each document where within each your matches are found. - -<p> -<p> </li> -</ol> - -<h2><a name='sect100' href='#toc100'>See Also</a></h2> - <a href='http:~/bin/man2html?sisu:1'>sisu(1)</a> -,<br> - <a href='http:~/bin/man2html?sisu-epub:1'>sisu-epub(1)</a> -,<br> - <a href='http:~/bin/man2html?sisu-harvest:1'>sisu-harvest(1)</a> -,<br> - <a href='http:~/bin/man2html?sisu-html:1'>sisu-html(1)</a> -,<br> - <a href='http:~/bin/man2html?sisu-odf:1'>sisu-odf(1)</a> -,<br> - <a href='http:~/bin/man2html?sisu-pdf:1'>sisu-pdf(1)</a> -,<br> - <a href='http:~/bin/man2html?sisu-pg:1'>sisu-pg(1)</a> -,<br> - <a href='http:~/bin/man2html?sisu-sqlite:1'>sisu-sqlite(1)</a> -,<br> - <a href='http:~/bin/man2html?sisu-txt:1'>sisu-txt(1)</a> -.<br> - <a href='http:~/bin/man2html?sisu_vim:7'>sisu_vim(7)</a> -<br> - -<h2><a name='sect101' href='#toc101'>Homepage</a></h2> - More information about SiSU can be found at <<a href='http://www.sisudoc.org/'>http://www.sisudoc.org/</a> -> -or <<a href='http://www.jus.uio.no/sisu/'>http://www.jus.uio.no/sisu/</a> -><br> - -<h2><a name='sect102' href='#toc102'>Source</a></h2> - <<a href='http://sources.sisudoc.org/'>http://sources.sisudoc.org/</a> -><br> - -<h2><a name='sect103' href='#toc103'>Author</a></h2> - SiSU is written by Ralph Amissah <ralph@amissah.com><br> - <p> - -<hr><p> -<a name='toc'><b>Table of Contents</b></a><p> -<ul> -<li><a name='toc0' href='#sect0'>Name</a></li> -<li><a name='toc1' href='#sect1'>Synopsis</a></li> -<li><a name='toc2' href='#sect2'>Sisu - Manual,</a></li> -<li><a name='toc3' href='#sect3'>What is Sisu?</a></li> -<li><a name='toc4' href='#sect4'>Introduction - What is Sisu?</a></li> -<li><a name='toc5' href='#sect5'>Commands Summary</a></li> -<li><a name='toc6' href='#sect6'>Description</a></li> -<li><a name='toc7' href='#sect7'>Document Processing Command Flags</a></li> -<li><a name='toc8' href='#sect8'>Command Line Modifiers</a></li> -<li><a name='toc9' href='#sect9'>Database Commands</a></li> -<li><a name='toc10' href='#sect10'>Shortcuts, Shorthand for Multiple Flags</a></li> -<li><a name='toc11' href='#sect11'>Command Line with Flags - Batch Processing</a></li> -<li><a name='toc12' href='#sect12'>Help</a></li> -<li><a name='toc13' href='#sect13'>Sisu Manual</a></li> -<li><a name='toc14' href='#sect14'>Sisu Man Pages</a></li> -<li><a name='toc15' href='#sect15'>Sisu Built-in Interactive Help</a></li> -<li><a name='toc16' href='#sect16'>Introduction to Sisu Markup[^11]</a></li> -<li><a name='toc17' href='#sect17'>Summary</a></li> -<li><a name='toc18' href='#sect18'>Markup Examples</a></li> -<li><a name='toc19' href='#sect19'>Online</a></li> -<li><a name='toc20' href='#sect20'>Installed</a></li> -<li><a name='toc21' href='#sect21'>Markup of Headers</a></li> -<li><a name='toc22' href='#sect22'>Sample Header</a></li> -<li><a name='toc23' href='#sect23'>Available Headers</a></li> -<li><a name='toc24' href='#sect24'>Markup of Substantive Text</a></li> -<li><a name='toc25' href='#sect25'>Heading Levels</a></li> -<li><a name='toc26' href='#sect26'>Font Attributes</a></li> -<li><a name='toc27' href='#sect27'>Indentation and Bullets</a></li> -<li><a name='toc28' href='#sect28'>Hanging Indents</a></li> -<li><a name='toc29' href='#sect29'>Footnotes / Endnotes</a></li> -<li><a name='toc30' href='#sect30'>Links</a></li> -<li><a name='toc31' href='#sect31'>Naked Urls Within Text, Dealing with Urls</a></li> -<li><a name='toc32' href='#sect32'>Linking Text</a></li> -<li><a name='toc33' href='#sect33'>Linking Images</a></li> -<li><a name='toc34' href='#sect34'>Link Shortcut for Multiple Versions of a Sisu Document in the Same Directory</a></li> -<li><a name='toc35' href='#sect35'>Grouped Text</a></li> -<li><a name='toc36' href='#sect36'>Tables</a></li> -<li><a name='toc37' href='#sect37'>Poem</a></li> -<li><a name='toc38' href='#sect38'>Group</a></li> -<li><a name='toc39' href='#sect39'>Code</a></li> -<li><a name='toc40' href='#sect40'>Additional Breaks - Linebreaks Within Objects, Column and Page-breaks</a></li> -<li><a name='toc41' href='#sect41'>Line-breaks</a></li> -<li><a name='toc42' href='#sect42'>Page Breaks</a></li> -<li><a name='toc43' href='#sect43'>Book Index</a></li> -<li><a name='toc44' href='#sect44'>Composite Documents Markup</a></li> -<li><a name='toc45' href='#sect45'>Sisu Filetypes</a></li> -<li><a name='toc46' href='#sect46'>.sst .ssm .ssi Marked Up Plain Text</a></li> -<li><a name='toc47' href='#sect47'>Sisu Text - Regular Files (.sst)</a></li> -<li><a name='toc48' href='#sect48'>Sisu Master Files (.ssm)</a></li> -<li><a name='toc49' href='#sect49'>Sisu Insert Files (.ssi)</a></li> -<li><a name='toc50' href='#sect50'>Sisupod, Zipped Binary Container (sisupod.zip, .ssp)</a></li> -<li><a name='toc51' href='#sect51'>Configuration</a></li> -<li><a name='toc52' href='#sect52'>Configuration Files</a></li> -<li><a name='toc53' href='#sect53'>Config.yml</a></li> -<li><a name='toc54' href='#sect54'>Sisu_document_make</a></li> -<li><a name='toc55' href='#sect55'>Css - Cascading Style Sheets (for Html, Xhtml and Xml)</a></li> -<li><a name='toc56' href='#sect56'>Organising Content - Directory Structure and Mapping</a></li> -<li><a name='toc57' href='#sect57'>Document Source Directory</a></li> -<li><a name='toc58' href='#sect58'>General Directories</a></li> -<li><a name='toc59' href='#sect59'>Document Output Directory Structures</a></li> -<li><a name='toc60' href='#sect60'>Output Directory Root</a></li> -<li><a name='toc61' href='#sect61'>Alternative Output Structures</a></li> -<li><a name='toc62' href='#sect62'>by Language</a></li> -<li><a name='toc63' href='#sect63'>by Filetype</a></li> -<li><a name='toc64' href='#sect64'>by Filename</a></li> -<li><a name='toc65' href='#sect65'>Remote Directories</a></li> -<li><a name='toc66' href='#sect66'>Sisupod</a></li> -<li><a name='toc67' href='#sect67'>Organising Content</a></li> -<li><a name='toc68' href='#sect68'>Homepages</a></li> -<li><a name='toc69' href='#sect69'>Home Page and Other Custom Built Pages in a Sub-directory</a></li> -<li><a name='toc70' href='#sect70'>Markup and Output Examples</a></li> -<li><a name='toc71' href='#sect71'>Markup Examples</a></li> -<li><a name='toc72' href='#sect72'>Sisu Markup Samples</a></li> -<li><a name='toc73' href='#sect73'>Sisu Search - Introduction</a></li> -<li><a name='toc74' href='#sect74'>Sql</a></li> -<li><a name='toc75' href='#sect75'>Populating Sql Type Databases</a></li> -<li><a name='toc76' href='#sect76'>Postgresql</a></li> -<li><a name='toc77' href='#sect77'>Name</a></li> -<li><a name='toc78' href='#sect78'>Description</a></li> -<li><a name='toc79' href='#sect79'>Synopsis</a></li> -<li><a name='toc80' href='#sect80'>Commands</a></li> -<li><a name='toc81' href='#sect81'>Create and Destroy Database</a></li> -<li><a name='toc82' href='#sect82'>Import and Remove Documents</a></li> -<li><a name='toc83' href='#sect83'>Sqlite</a></li> -<li><a name='toc84' href='#sect84'>Name</a></li> -<li><a name='toc85' href='#sect85'>Description</a></li> -<li><a name='toc86' href='#sect86'>Synopsis</a></li> -<li><a name='toc87' href='#sect87'>Commands</a></li> -<li><a name='toc88' href='#sect88'>Create and Destroy Database</a></li> -<li><a name='toc89' href='#sect89'>Import and Remove Documents</a></li> -<li><a name='toc90' href='#sect90'>Introduction</a></li> -<li><a name='toc91' href='#sect91'>Search - Database Frontend Sample, Utilising Database and Sisu Features,</a></li> -<li><a name='toc92' href='#sect92'>Search Form</a></li> -<li><a name='toc93' href='#sect93'>Sisu_webrick</a></li> -<li><a name='toc94' href='#sect94'>Name</a></li> -<li><a name='toc95' href='#sect95'>Synopsis</a></li> -<li><a name='toc96' href='#sect96'>Description</a></li> -<li><a name='toc97' href='#sect97'>Summary of Man Page</a></li> -<li><a name='toc98' href='#sect98'>Document Processing Command Flags</a></li> -<li><a name='toc99' href='#sect99'>Summary of Features</a></li> -<li><a name='toc100' href='#sect100'>See Also</a></li> -<li><a name='toc101' href='#sect101'>Homepage</a></li> -<li><a name='toc102' href='#sect102'>Source</a></li> -<li><a name='toc103' href='#sect103'>Author</a></li> -</ul> -</body> -</html> diff --git a/data/doc/sisu/markup-samples/sisu_manual/sisu_commands.sst b/data/doc/sisu/markup-samples/sisu_manual/sisu_commands.sst index 1c5c1cec..491c03fd 100644 --- a/data/doc/sisu/markup-samples/sisu_manual/sisu_commands.sst +++ b/data/doc/sisu/markup-samples/sisu_manual/sisu_commands.sst @@ -278,8 +278,8 @@ see --sisupod !_ -s [filename/wildcard] \\ see --source -!_ --sample-search-form [--webserv=webrick] \\ -generate examples of (naive) cgi search form for SQLite and PgSQL depends on your already having used sisu to populate an SQLite and/or PgSQL database, (the SQLite version scans the output directories for existing sisu_sqlite databases, so it is first necessary to create them, before generating the search form) see -d -D and the database section below. If the optional parameter --webserv=webrick is passed, the cgi examples created will be set up to use the default port set for use by the webrick server, (otherwise the port is left blank and the system setting used, usually 80). The samples are dumped in the present work directory which must be writable, (with screen instructions given that they be copied to the cgi-bin directory). Alias -F +!_ --sample-search-form [--db=(pgsql|sqlite)] [--webserv=webrick] \\ +generate examples of (naive) cgi search form for SQLite or PgSQL depends on your already having used sisu to populate an SQLite or PgSQL database, (the SQLite version scans the output directories for existing sisu_sqlite databases, so it is first necessary to create them, before generating the search form) see --sqlite & --pg and the database section below. Optional additional parameters include: url location of webserver search form and db: --webserv-search='[url]'; location of webserver output: --webserv-output='[url]'; cgi search form link name: --cgi-search-form-name='[name.cgi]'; for pgsql, database user: --db-user='[username]'. If the optional parameter --webserv=webrick is passed, the cgi examples created will be set up to use the default port set for use by the webrick server, (otherwise the port is left blank and the system setting used, usually 80). The samples are dumped in the present work directory which must be writable, (with screen instructions given that they be copied to the cgi-bin directory). Alias -F !_ --scp [filename/wildcard] \\ copies sisu output files to remote host using scp. This requires that sisurc.yml has been provided with information on hostname and username, and that you have your "keys" and ssh agent in place. Also see --rsync. Alias -r diff --git a/data/doc/sisu/markup-samples/sisu_manual/sisu_help.sst b/data/doc/sisu/markup-samples/sisu_manual/sisu_help.sst index ce6627b7..69535085 100644 --- a/data/doc/sisu/markup-samples/sisu_manual/sisu_help.sst +++ b/data/doc/sisu/markup-samples/sisu_manual/sisu_help.sst @@ -72,24 +72,6 @@ _* {~^ various sisu man pages }http://www.jus.uio.no/sisu/man/ _* {~^ sisu.1 }http://www.jus.uio.no/sisu/man/sisu.1.html -2~ SiSU built-in interactive help +2~ SiSU built-in interactive help, [discontinued] -This is particularly useful for getting the current sisu setup/environment information: - -_1 sisu --help - -_1 sisu --help [subject] - -_2 sisu --help commands - -_2 sisu --help markup - -_2 sisu --help env [for feedback on the way your system is setup with regard to sisu] - -_1 sisu -V [environment information, same as above command] - -_1 sisu (on its own provides version and some help information) - -Apart from real-time information on your current configuration the SiSU manual and man pages are likely to contain more up-to-date information than the sisu interactive help (for example on commands and markup). - -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. +This fell out of date and has been discontinued. diff --git a/data/sisu/v4/v/version.yml b/data/sisu/v4/v/version.yml index aef5aa91..6bf1fee5 100644 --- a/data/sisu/v4/v/version.yml +++ b/data/sisu/v4/v/version.yml @@ -1,5 +1,5 @@ --- -:version: 4.1.1 -:date_stamp: 2013w19/7 -:date: "2013-05-19" +:version: 4.1.2 +:date_stamp: 2013w21/3 +:date: "2013-05-29" :project: SiSU diff --git a/data/sisu/v5/v/version.yml b/data/sisu/v5/v/version.yml index f80d0228..87d04e76 100644 --- a/data/sisu/v5/v/version.yml +++ b/data/sisu/v5/v/version.yml @@ -1,5 +1,5 @@ --- -:version: 5.0.1 -:date_stamp: 2013w19/7 -:date: "2013-05-19" +:version: 5.0.2 +:date_stamp: 2013w21/3 +:date: "2013-05-29" :project: SiSU diff --git a/lib/sisu/v4/cgi.rb b/lib/sisu/v4/cgi.rb index 600d7146..acaa5396 100644 --- a/lib/sisu/v4/cgi.rb +++ b/lib/sisu/v4/cgi.rb @@ -70,8 +70,20 @@ module SiSU_CGI @webserv=@opt.files[0].to_s.strip end def read - SiSU_CGI_SQLite::SearchSQLite.new(@opt,@webserv).sqlite - SiSU_CGI_PgSQL::SearchPgSQL.new(@opt,@webserv).pgsql + if @opt.mod.inspect =~/--db[=-]["']?(?:pg|pg?sql|postgres(?:ql)?)["']+/ + SiSU_CGI_PgSQL::SearchPgSQL.new(@opt,@webserv).pgsql + elsif @opt.mod.inspect =~/--db[=-](?:sqlite)/ + SiSU_CGI_SQLite::SearchSQLite.new(@opt,@webserv).sqlite + else + puts <<-WOK + please select database type for which sample search form should be built (pgsql or sqlite) + sisu --sample-search-form --db=sqlite + sisu --sample-search-form --db=pg + other options include + --webserv-cgi='[cgi-server-name]' + --webserv-output='[sisu-output-server-with-base-path]' + WOK + end end end end diff --git a/lib/sisu/v4/cgi_pgsql.rb b/lib/sisu/v4/cgi_pgsql.rb index 70a60d81..61c20965 100644 --- a/lib/sisu/v4/cgi_pgsql.rb +++ b/lib/sisu/v4/cgi_pgsql.rb @@ -56,7 +56,7 @@ <ralph@amissah.com> <ralph.amissah@gmail.com> - ** Description: generates naive cgi search form for search of sisu database (pgsql sqlite) + ** Description: generates naive cgi search form for search of sisu database (pgsql) =end module SiSU_CGI_PgSQL #% database building documents @@ -66,6 +66,7 @@ module SiSU_CGI_PgSQL class SearchPgSQL < CGI_Common def initialize(opt,webserv) @opt,@webserv=opt,webserv + @cX=SiSU_Screen::Ansi.new(opt.cmd).cX @env=SiSU_Env::InfoEnv.new('',opt) @sys=SiSU_Env::SystemCall.new @db=SiSU_Env::InfoDb.new @@ -90,18 +91,19 @@ module SiSU_CGI_PgSQL and @rc['search']['sisu']['db'] =~/\S+/ @name_of[:db]=@rc['search']['sisu']['db'] #@name_of[:cgi_script]=/https?:\/\/\S+?([^\/]+?)\.cgi$/.match(@rc['search']['sisu']['action'])[1] - @name_of[:host_url_cgi],@name_of[:cgi_script]=/(https?:\/\/\S+?)\/([^\/]+?)\.cgi$/.match(@rc['search']['sisu']['action'])[1,2] + @name_of[:host_url_cgi]=/(https?:\/\/\S+?)\/(?:[^\/]+?)\.cgi$/.match(@rc['search']['sisu']['action'])[1] else - @name_of[:host_url_docs]=@env.url.webserv_files_from_db - @name_of[:db]='sisu' #breaks if not present - @name_of[:host_url_cgi]=@env.url.webserv_base_cgi - @name_of[:cgi_script]='sisu_pgsql' + @name_of[:host_url_docs]=@env.url.webserv_files_from_db(@opt) + @name_of[:db]=@env.path.stub_pwd #'sisu' #breaks if not present + @name_of[:host_url_cgi]=@env.url.webserv_base_cgi(@opt) false end + @name_of[:cgi_script]=@env.url.cgi_sample_search_form_name(@opt) @cgi_file_name="#{Db[:name_prefix_db]}by_#{opt.dir_structure_by.to_s}_pgsql.cgi" - @cgi_link_name="#{@name_of[:db]}.cgi" #sisu_pgsql.cgi, - @image_src="#{@name_of[:host_url_docs]}/_sisu/image_sys" + @cgi_link_name=@name_of[:cgi_script] #sisu_pgsql.cgi, + @image_src="#{@env.url.webserv_base_cgi(@opt)}/_sisu/image_sys" @common=SiSU_CGI_SQL::CGI_Common.new(@webserv,@opt,@image_src,@env) + @user=@db.psql.user(@opt) end def pgsql serve=[] @@ -125,25 +127,69 @@ module SiSU_CGI_PgSQL if FileTest.writable?('.') output=File.open(@cgi_file_name,'w') output << header0 << header1 << header_desc << header2 << f1 << buttons1 << buttons1_pgsql << buttons2 << search_request << search_statement << search_statement_common << search_query1 << @common.pages << search_query2 << @common.tail << @common.main1 << f2 << dbi_connect << @common.main2 << @common.dir_structure << @common.main3 - a=%{ generated #{@cgi_file_name}, - BASED ON ALREADY EXISTING directories that could potentially be used to populate postgresql db, (-D) - } - SiSU_Screen::Ansi.new(@opt.cmd,a).print_grey - c=case @webserv + puts <<-WOK + generated sample search form: #{@cX.green}#{@cgi_file_name}#{@cX.off} + default database name: #{@cX.green}#{Db[:name_prefix]}#{@name_of[:db]}#{@cX.off} (#{@name_of[:db]}) + db user: #{@cX.green}#{@db.psql.user(@opt)}#{@cX.off} + to modify use: #{@cX.brown}sisu --db-pg --db-user='#{@db.psql.user(@opt)}'#{@cX.off} + cgi & db host on: #{@cX.blue}#{@env.url.webserv_base_cgi(@opt)}#{@cX.off} + to modify use: #{@cX.brown}sisu --db-pg --webserv-search='#{@env.url.webserv_base_cgi(@opt)}'#{@cX.off} + sisu output on: #{@cX.blue}#{@env.url.webserv_files_from_db(@opt)}#{@cX.off} + to modify use: #{@cX.brown}sisu --db-pg --webserv-output='#{@env.url.webserv_files_from_db(@opt)}'#{@cX.off} + cgi search form link name: #{@cX.green}#{@env.url.cgi_sample_search_form_name(@opt)}#{@cX.off} + to modify use: #{@cX.brown}sisu --db-pg --cgi-search-form-name='#{@env.url.cgi_sample_search_form_name(@opt)}'#{@cX.off} + #{@cX.fuschia}(settings priority: command line; sisurc.yml; else defaults)#{@cX.off} + + #{@cX.fuschia}BASED ON ALREADY EXISTING databases#{@cX.off} (default database name: #{@db.psql.db}) + NOTE it is first necessary to createdb, + use sisu to create the tables & populate the postgresql db + + the database to be used for this directory (#{@db.psql.db}) + will have to be created manually if it does not exist: + using postgresql tools directly (the following may work): + (i) if you are not yet a postgresql user, + #{@cX.brown}sudo su postgres + createuser -d -a #{@env.user} + exit#{@cX.off} + (ii) create the database: + #{@cX.brown}createdb #{@db.psql.db}#{@cX.off} + [for a list of existing databases try 'psql --list']" + + now you can use sisu to create the database tables and populate the database with documents + + sisu --pg --dropall # removes existing postgresql db & tables + sisu --pg --createall -v # creates postgresql db & tables + sisu --pg --update -v *.sst *.ssm # populate the db + sisu --sample-search-form --pg # creates the postgresql search form + # this should be done after creating the db + # to be searched + sisu --webrick & # starts ruby webrick web server + + # if necessary make the directory '/usr/lib/cgi-bin' + # here we copy the postgresql search form to cgi-bin + # (copy #{@cgi_file_name} to your cgi directory) + # set file permissions to 755, & + # make symbolic link to #{@cgi_link_name} + WOK + a=case @webserv when /pwd/; '' - else "if necessary make the directory /usr/lib/cgi-bin : - sudo cp -vi #{Dir.pwd}/#{@cgi_file_name} /usr/lib/cgi-bin/. - sudo chmod -v 755 /usr/lib/cgi-bin/#{@cgi_file_name} - sudo ln -s /usr/lib/cgi-bin/#{@cgi_file_name} /usr/lib/cgi-bin/#{@cgi_link_name} - (copy #{@cgi_file_name} to your cgi directory) set file permissions to 755, and make symbolic link to #{@cgi_link_name}" + else <<-WOK + + sudo cp -vi #{Dir.pwd}/#{@cgi_file_name} /usr/lib/cgi-bin/.; \\ + cd /usr/lib/cgi-bin && \\ + sudo chmod -v 755 #{@cgi_file_name}; \\ + sudo rm -vi #{@cgi_link_name}; \\ + sudo ln -s #{@cgi_file_name} #{@cgi_link_name}; \\ + cd - + WOK end - a=%{#{c} - #{@env.webserv_base_cgi}/cgi-bin/#{@cgi_link_name} - } SiSU_Screen::Ansi.new(@opt.cmd,a).warn - a="postgresql db used for present directory: #{@db.psql.db}" - b="\n\t(to create and populate postgresql database see 'man sisu' and in particular the -D flag)\n\t[the database to be used for this directory (#{@db.psql.db}) will have to be created manually if it does not exist,\n\tsee 'sisu --help sql'\n\tif you have permission to create databases:\n\t'sisu -d --createdb'\n\tor using postgresql tools directly:\n\t'createdb #{@db.psql.db}'\n\tfor a list of existing databases try 'psql --list']" - SiSU_Screen::Ansi.new(@opt.cmd,a,b).txt_cyan + a=<<-WOK + #{@env.webserv_base_cgi(@opt)}/cgi-bin/#{@cgi_link_name} + WOK + SiSU_Screen::Ansi.new(@opt.cmd,a).print_blue + a="\n\t(to create and populate postgresql database see 'man sisu' and in particular the --pg option)\n\t[the database to be used for this directory (#{@db.psql.db}) will have to be created manually if it does not exist,\n\tusing postgresql tools directly: 'createdb #{@db.psql.db}' for a list of existing databases try 'psql --list']" + SiSU_Screen::Ansi.new(@opt.cmd,a).txt_grey else puts 'failed in attempt to write #{@cgi_file_name} to present directory, is directory writable?' end end @@ -159,13 +205,14 @@ module SiSU_CGI_PgSQL require 'fcgi' require 'dbi' @stub_default='#{@name_of[:db]}' - @image_src='#{@name_of[:host_url_docs]}/_sisu/image_sys' - @hosturl_cgi='#{@name_of[:host_url_cgi]}' - @hosturl_files='#{@name_of[:host_url_docs]}' + @image_src='#{@image_src}' + @hosturl_cgi='#{@env.url.webserv_base_cgi(@opt)}/cgi-bin' + @hosturl_files='#{@env.url.webserv_files_from_db(@opt)}' @output_dir_structure_by='#{@name_of[:output_dir_structure]}' @port='#{@db.psql.port}' @db_name_prefix='#{Db[:name_prefix]}' - user='www-data' # check user name for access to pg database: e.g. www-data or '#{@env.user}' + @user='#{@user}' # check user name for access to pg database: e.g. www-data or '#{@env.user}' + @base='#{@name_of[:host_url_cgi]}/cgi-bin/#{@name_of[:cgi_script]}.cgi' #fix sqlite WOK_SQL end def search_statement @@ -250,7 +297,7 @@ module SiSU_CGI_PgSQL def dbi_connect <<-'WOK_SQL' dbi="dbi:Pg:database=#{@db};port=#{@port}" - @conn=DBI.connect(dbi,user) + @conn=DBI.connect(dbi,@user) WOK_SQL end end diff --git a/lib/sisu/v4/cgi_sql_common.rb b/lib/sisu/v4/cgi_sql_common.rb index 6c0550e6..33cb2dc6 100644 --- a/lib/sisu/v4/cgi_sql_common.rb +++ b/lib/sisu/v4/cgi_sql_common.rb @@ -130,7 +130,6 @@ module SiSU_CGI_SQL <<-'WOK_SQL' #Common TOP @@offset=0 - @base="#{@hosturl_cgi}/#{@stub_default}.cgi" #fix sqlite @@canned_search_url=@base @color_heading='#DDFFAA' @color_match='#ffff48' diff --git a/lib/sisu/v4/cgi_sqlite.rb b/lib/sisu/v4/cgi_sqlite.rb index 05c7e6a7..93129b5c 100644 --- a/lib/sisu/v4/cgi_sqlite.rb +++ b/lib/sisu/v4/cgi_sqlite.rb @@ -56,7 +56,7 @@ <ralph@amissah.com> <ralph.amissah@gmail.com> - ** Description: generates naive cgi search form for search of sisu database (pgsql sqlite) + ** Description: generates naive cgi search form for search of sisu database (sqlite) =end module SiSU_CGI_SQLite #% database building documents @@ -66,17 +66,19 @@ module SiSU_CGI_SQLite class SearchSQLite < CGI_Common def initialize(opt,webserv) @opt,@webserv=opt,webserv + @cX=SiSU_Screen::Ansi.new(opt.cmd).cX @env=SiSU_Env::InfoEnv.new('',opt) - @image_src="#{@env.url.webserv_cgi}/_sisu/image_sys" + @image_src="#{@env.url.webserv_cgi(@opt)}/_sisu/image_sys" @common=SiSU_CGI_SQL::CGI_Common.new(@webserv,@opt,@image_src,@env) @cgi_file_name="#{Db[:name_prefix_db]}by_#{opt.dir_structure_by.to_s}_sqlite.cgi" + @name_of_sqlite_db_file='sisu_sqlite.db' end def sqlite serve=[] Dir.foreach(@env.path.webserv) do |x| if x !~/^\./ \ and FileTest.directory?("#{@env.path.webserv}/#{x}") - if FileTest.file?("#{@env.path.webserv}/#{x}/sisu_sqlite.db") + if FileTest.file?("#{@env.path.webserv}/#{x}/#{@name_of_sqlite_db_file}") serve << x unless x =~/^_\S+/ end end @@ -91,32 +93,62 @@ module SiSU_CGI_SQLite f2 << %{ when /#{Db[:name_prefix]}#{x}/; '<option value="#{Db[:name_prefix]}#{x}">#{x}</option>'\n} end f2 << " end\n" - f3 << %{ db_name='sisu_sqlite.db'\n} + f3 << %{ db_name='#{@name_of_sqlite_db_file}'\n} f3 << %{ db_sqlite=case cgi['db']\n} serve.each do |x| - f3 << %{ when /#{Db[:name_prefix]}#{x}/; "#{@env.path.webserv}/#{x}/sisu_sqlite.db"\n} + f3 << %{ when /#{Db[:name_prefix]}#{x}/; "#{@env.path.webserv}/#{x}/\#{db_name}"\n} end - f3 << %{ else '#{@env.path.webserv}/#{serve[0]}/sisu_sqlite.db'\n end\n} + f3 << %{ else '#{@env.path.webserv}/#{serve[0]}/\#{db_name}'\n end\n} if FileTest.writable?('.') output=File.open(@cgi_file_name,'w') output << header0 << header1 << header_desc << header2 << f1 << buttons1 << buttons2 << search_request << search_statement << search_statement_common << search_query1 << @common.pages << search_query2 << @common.tail << @common.main1 << f2 << f3 << dbi_connect << @common.main2 << @common.dir_structure << @common.main3 - a=%{ generated sisu_sqlite.cgi, - BASED ON ALREADY CREATED sisu_sqlite.db OUTPUT, (-d) - } - SiSU_Screen::Ansi.new(@opt.cmd,a).print_grey - c=case @webserv + puts <<-WOK + generated sample search form: #{@cX.green}#{@cgi_file_name}#{@cX.off} + default database name: #{@cX.green}#{Db[:name_prefix]}#{@env.path.stub_pwd}#{@cX.off} (#{@env.path.stub_pwd}) + cgi & db host on: #{@cX.blue}#{@env.url.webserv_base_cgi(@opt)}#{@cX.off} + to modify use: #{@cX.brown}sisu --db-sqlite --webserv-search='#{@env.url.webserv_base_cgi(@opt)}'#{@cX.off} + sisu output on: #{@cX.blue}#{@env.url.webserv_files_from_db(@opt)}#{@cX.off} + to modify use: #{@cX.brown}sisu --db-sqlite --webserv-output='#{@env.url.webserv_files_from_db(@opt)}'#{@cX.off} + cgi search form link name: #{@cX.green}#{@env.url.cgi_sample_search_form_name(@opt)}#{@cX.off} + to modify use: #{@cX.brown}sisu --db-sqlite --cgi-search-form-name='#{@env.url.cgi_sample_search_form_name(@opt)}'#{@cX.off} + #{@cX.fuschia}(settings priority: command line; sisurc.yml; else defaults)#{@cX.off} + + #{@cX.fuschia}NOTE it is first necessary to create the database and tables and populate it#{@cX.off} + + sisu --sqlite --dropall # removes existing postgresql db & tables + sisu --sqlite --createall -v # creates postgresql db & tables + sisu --sqlite --update -v *.sst *.ssm # populate the db + sisu --sample-search-form --sqlite # creates the postgresql search form + # this should be done after creating the db + # to be searched + sisu --webrick & # starts ruby webrick web server + + # if necessary make the directory '/usr/lib/cgi-bin' + # here we copy the postgresql search form to cgi-bin + # (copy #{@cgi_file_name} to your cgi directory) + # set file permissions to 755, & + # make symbolic link to #{@cgi_link_name} + WOK + a=case @webserv when /pwd/; '' - else "if necessary make the directory /usr/lib/cgi-bin : - sudo cp -vi #{Dir.pwd}/#{@cgi_file_name} /usr/lib/cgi-bin/. - sudo chmod -v 755 /usr/lib/cgi-bin/#{@cgi_file_name} - sudo ln -s /usr/lib/cgi-bin/#{@cgi_file_name} /usr/lib/cgi-bin/sisu_sqlite.cgi - (copy #{@cgi_file_name} to your cgi directory) set file permissions to 755, and make symbolic link to sisu_sqlite.cgi" + else <<-WOK + + sudo cp -vi #{Dir.pwd}/#{@cgi_file_name} /usr/lib/cgi-bin/.; \\ + cd /usr/lib/cgi-bin && \\ + sudo chmod -v 755 #{@cgi_file_name}; \\ + sudo rm -vi #{@env.url.cgi_sample_search_form_name(@opt)}; \\ + sudo ln -sf #{@cgi_file_name} #{@env.url.cgi_sample_search_form_name(@opt)}; \\ + cd - + WOK end - a=%{#{c} - #{@env.webserv_base_cgi}/cgi-bin/sisu_sqlite.cgi - } b='(to create and populate sisu sqlite database see "man sisu" and in particular the -d flag)' SiSU_Screen::Ansi.new(@opt.cmd,a,b).warn + a=<<-WOK + + #{@env.webserv_base_cgi(@opt)}/cgi-bin/#{@cgi_link_name} + + WOK + SiSU_Screen::Ansi.new(@opt.cmd,a).print_blue else puts "failed in attempt to write #{@cgi_file_name} to present directory, is directory writable?" end end @@ -132,10 +164,11 @@ module SiSU_CGI_SQLite require 'fcgi' require 'dbi' @stub_default='sisu_sqlite' - @image_src='#{@env.url.webserv_cgi}/_sisu/image_sys' - @hosturl_cgi='#{@env.url.webserv_base_cgi}/cgi-bin' - @hosturl_files='#{@env.url.webserv_files_from_db}' + @image_src='#{@image_src}' + @hosturl_cgi='#{@env.url.webserv_base_cgi(@opt)}/cgi-bin' + @hosturl_files='#{@env.url.webserv_files_from_db(@opt)}' @db_name_prefix='#{Db[:name_prefix]}' + @base='#{@env.url.webserv_base_cgi(@opt)}/cgi-bin/#{@env.url.cgi_sample_search_form_name(@opt)}' #fix sqlite WOK_SQL end def search_statement diff --git a/lib/sisu/v4/dal_doc_str.rb b/lib/sisu/v4/dal_doc_str.rb index dfea4ad4..25c6f854 100644 --- a/lib/sisu/v4/dal_doc_str.rb +++ b/lib/sisu/v4/dal_doc_str.rb @@ -556,7 +556,6 @@ module SiSU_DAL_DocumentStructureExtract @md,@dob=md,dob end def structure - structure_markup_normalize structure_markup @dob end @@ -590,53 +589,6 @@ module SiSU_DAL_DocumentStructureExtract end @dob end - def structure_markup_normalize #needs a bit of thinking - dob=if @md.markup_version.determined < 0.38 #%convert internal representation, consider making 0.38 structure default ([A-C1-6] instead of [1-9]), requires downstream changes - @dob=@dob.gsub(/^[456]~/,'!_'). - gsub(/^3~(\S+)/,"#{Mx[:lv_o]}6:\\1#{Mx[:lv_c]}"). - gsub(/^3~\s+/,"#{Mx[:lv_o]}6:#{Mx[:lv_c]}"). - gsub(/^2~(\S+)/,"#{Mx[:lv_o]}5:\\1#{Mx[:lv_c]}"). - gsub(/^2~\s+/,"#{Mx[:lv_o]}5:#{Mx[:lv_c]}"). - gsub(/^1~(\S+)/,"#{Mx[:lv_o]}4:\\1#{Mx[:lv_c]}"). - gsub(/^1~\s+/,"#{Mx[:lv_o]}4:#{Mx[:lv_c]}"). - gsub(/^:?C~(\S+)/,"#{Mx[:lv_o]}3:\\1#{Mx[:lv_c]}"). - gsub(/^:?C~\s+/,"#{Mx[:lv_o]}3:#{Mx[:lv_c]}"). - gsub(/^:?B~(\S+)/,"#{Mx[:lv_o]}2:\\1#{Mx[:lv_c]}"). - gsub(/^:?B~\s+/,"#{Mx[:lv_o]}2:#{Mx[:lv_c]}"). - gsub(/^:?A~(\S+)/,"#{Mx[:lv_o]}1:\\1#{Mx[:lv_c]}"). - gsub(/^:?A~\s+/,"#{Mx[:lv_o]}1:#{Mx[:lv_c]}") - @dob=if @dob =~/^@(?:level|markup):\s/ - @dob=@dob.gsub(/3/,'6'). - gsub(/2/,'5'). - gsub(/1/,'4'). - gsub(/:?C/,'3'). - gsub(/:?B/,'2'). - gsub(/:?A/,'1') - @dob - else @dob - end - else @dob - end - end - def structure_marks - t_o=if @md.markup_version.determined < 0.38 - @t_o=@t_o.gsub(/^1~(\S+)/,"#{Mx[:lv_o]}1:\\1#{Mx[:lv_c]}"). - gsub(/^1~\s+/,"#{Mx[:lv_o]}1:#{Mx[:lv_c]}"). - gsub(/^2~(\S+)/,"#{Mx[:lv_o]}2:\\1#{Mx[:lv_c]}"). - gsub(/^2~\s+/,"#{Mx[:lv_o]}2:#{Mx[:lv_c]}"). - gsub(/^3~(\S+)/,"#{Mx[:lv_o]}3:\\1#{Mx[:lv_c]}"). - gsub(/^3~\s+/,"#{Mx[:lv_o]}3:#{Mx[:lv_c]}"). - gsub(/^4~(\S+)/,"#{Mx[:lv_o]}4:\\1#{Mx[:lv_c]}"). - gsub(/^4~\s+/,"#{Mx[:lv_o]}4:#{Mx[:lv_c]}"). - gsub(/^5~(\S+)/,"#{Mx[:lv_o]}5:\\1#{Mx[:lv_c]}"). - gsub(/^5~\s+/,"#{Mx[:lv_o]}5:#{Mx[:lv_c]}"). - gsub(/^6~(\S+)/,"#{Mx[:lv_o]}6:\\1#{Mx[:lv_c]}"). - gsub(/^6~\s+/,"#{Mx[:lv_o]}6:#{Mx[:lv_c]}"). - gsub(/^[789]~/,'!_') - @t_o - else @t_o - end - end end class OCN def initialize(md,data) diff --git a/lib/sisu/v4/dal_substitutions_and_insertions.rb b/lib/sisu/v4/dal_substitutions_and_insertions.rb index ad510488..08a63c89 100644 --- a/lib/sisu/v4/dal_substitutions_and_insertions.rb +++ b/lib/sisu/v4/dal_substitutions_and_insertions.rb @@ -130,11 +130,6 @@ module SiSU_DAL_SubstituteAndInsert end data_new=[] data_expand.each do |para| - para=if @md.markup_version.determined >= 0.38 - SiSU_DAL_DocumentStructureExtract::Structure.new(@md,para).structure_markup_normalize - else - SiSU_DAL_DocumentStructureExtract::Structure.new(@md,para).structure_marks - end para=para.gsub(/^(:?A~)\s*$/,'\1~ @title @author'). #conditional header gsub(/^((?:[1-9]|:?[A-C])~\S*)\s*$/,'\1~ [Note: heading marker::required title missing]~#') #conditional header for incorporated document 2004w12 if para =~/^@\S+?:/ diff --git a/lib/sisu/v4/db_select.rb b/lib/sisu/v4/db_select.rb index 7409db16..34fe6485 100644 --- a/lib/sisu/v4/db_select.rb +++ b/lib/sisu/v4/db_select.rb @@ -205,9 +205,6 @@ module SiSU_DbSelect when /^--(?:db=)?(?:(?:sq)?lite|pg(?:sql)?|my(?:sql)?)$/ when /^--(?:v\d+|dev)$/ else - #help=SiSU_Help::Help.new - #help.summary - #help.commands end if @opt.cmd =~/M/ \ and @opt.cmd =~/d/ diff --git a/lib/sisu/v4/dbi.rb b/lib/sisu/v4/dbi.rb index f109f852..867585dd 100644 --- a/lib/sisu/v4/dbi.rb +++ b/lib/sisu/v4/dbi.rb @@ -60,7 +60,6 @@ =end module SiSU_DBI #% database building - require_relative 'help' # help.rb require_relative 'sysenv' # sysenv.rb include SiSU_Env; include SiSU_Screen require_relative 'param' # param.rb @@ -108,7 +107,11 @@ module SiSU_DBI @conn=@db.psql.conn_dbi rescue if @opt.mod.inspect=~/--(createall|create)/ - puts %{manually create the database: "#{@db.db}" if it does not yet exist} + cX=SiSU_Screen::Ansi.new(@opt.cmd).cX + puts <<-WOK +manually create the database: "#{cX.green}#{@db.db}#{cX.off}" if it does not yet exist + #{cX.yellow}createdb #{@db.db}#{cX.off} + WOK #sudo su -p postgres; createdb #{@db.db}; #[createuser?] end ensure diff --git a/lib/sisu/v4/dbi_discrete.rb b/lib/sisu/v4/dbi_discrete.rb index 8b78f185..3499bc9c 100644 --- a/lib/sisu/v4/dbi_discrete.rb +++ b/lib/sisu/v4/dbi_discrete.rb @@ -60,7 +60,6 @@ =end module SiSU_DBI_Discrete #% database building - require_relative 'help' # help.rb require_relative 'sysenv' # sysenv.rb include SiSU_Env; include SiSU_Screen require_relative 'param' # param.rb diff --git a/lib/sisu/v4/help.rb b/lib/sisu/v4/help.rb deleted file mode 100644 index 35a908e9..00000000 --- a/lib/sisu/v4/help.rb +++ /dev/null @@ -1,1881 +0,0 @@ -# encoding: utf-8 -=begin - - * Name: SiSU - - * Description: a framework for document structuring, publishing and search - - * Author: Ralph Amissah - - * Copyright: (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, - 2007, 2008, 2009, 2010, 2011, 2012, 2013 Ralph Amissah, All Rights Reserved. - - * License: GPL 3 or later: - - SiSU, a framework for document structuring, publishing and search - - Copyright (C) Ralph Amissah - - This program is free software: you can redistribute it and/or modify it - under the terms of the GNU General Public License as published by the Free - Software Foundation, either version 3 of the License, or (at your option) - any later version. - - This program is distributed in the hope that it will be useful, but WITHOUT - ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or - FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for - more details. - - You should have received a copy of the GNU General Public License along with - this program. If not, see <http://www.gnu.org/licenses/>. - - If you have Internet connection, the latest version of the GPL should be - available at these locations: - <http://www.fsf.org/licensing/licenses/gpl.html> - <http://www.gnu.org/licenses/gpl.html> - - <http://www.sisudoc.org/sisu/en/manifest/gpl.fsf.html> - - * SiSU uses: - * Standard SiSU markup syntax, - * Standard SiSU meta-markup syntax, and the - * Standard SiSU object citation numbering and system - - * Hompages: - <http://www.jus.uio.no/sisu> - <http://www.sisudoc.org> - - * Download: - <http://www.sisudoc.org/sisu/en/SiSU/download.html> - - * Git - <http://sources.sisudoc.org/gitweb/?p=code/sisu.git;a=summary> - <http://sources.sisudoc.org/?p=code/sisu.git;a=blob;f=lib/sisu/v4/help.rb;hb=HEAD> - - * Ralph Amissah - <ralph@amissah.com> - <ralph.amissah@gmail.com> - - ** Description: interactive infomation/help - -=end -module SiSU_Help - require_relative 'sysenv' # sysenv.rb - include SiSU_Screen - require_relative 'param' # param.rb - class Help - require_relative 'i18n' # i18n.rb - def initialize(request='',color='') - @request,@color=request,color - @cX=((color =~/color_off/) \ - || (defined? color.act && color.act[:color_state][:set]==:off)) \ - ? (SiSU_Screen::Ansi.new('k').cX) - : (SiSU_Screen::Ansi.new('yes').cX) - fns='help_example_dummy_file_name.sst' - @env=SiSU_Env::InfoEnv.new(fns) - @db=SiSU_Env::InfoDb.new - m=/.+\/(?:src\/)?(\S+)/im # m=/.+?\/(?:src\/)?([^\/]+)$/im # m=/.+\/(\S+)/m - @output_stub=Dir.pwd[m,1] - end - def help_request - begin - gotten=nil - regx=/^(list|com(?:mands)?|mod(?:ifiers)|markup|syntax|example(?:_v1|_v2)?|head(?:ers?)?|(?:heading|title|level|structure)s?|endnotes|footnotes|tables?|customise|skin|dir(?:ectories)?|paths?|lang(?:uage)?|modules|setup|conf(?:ig(?:ure)?)?|standards?|li[cs]en[sc]e|scratch|install|termsheet|dublin(?:core)?|dc|customise|styles?|appearance|theme|env(ironment)?|dir(?:ector(?:y|ies))?|metaverse|abstract|features|summary|(?:short)?cuts?|sisu|about|ext(?:ernal)?(?:_?prog(?:rams)?)?)|utf-?8|plaintext|html|xml|xhtml|epub|odf|odt|opendocument|css|pdf|latex|tex|(?:tex)?info|search|(?:hyper)?est(?:raier)?|searchform|cgi|sql|db|pg|postgresql|pg?sql|sqlite|convert|php|webrick|sitemaps?|ya?ml|ansi|colors|-[AabcDdEeFHhIMmNnopqrRSstUuVvwXxyZz0-9]|-[Ddcv]|-[CcFLSVvW]/ - help_info=%{#{@cX.blue_hi}SiSU help#{@cX.off} #{@cX.ruby}~#{@cX.off} #{@request}} - help_list=%{#{@cX.blue}sisu --help#{@cX.off} #{@cX.cyan}type keyword else "enter" to exit help:\n\tkeywords include:#{@cX.off} #{@cX.brown}list, (com)mands, short(cuts), (mod)ifiers, (env)ironment, markup, syntax, headers, headings, endnotes, tables, example, customise, skin, (dir)ectories, path, (lang)uage, db, install, setup, (conf)igure, convert, termsheet, search, sql, features, license#{@cX.off} \n} - help_prompt=%{#{@cX.fuschia}exit, [or carriage return to exit help] #{@cX.off}\n#{@cX.blue_hi}SiSU help#{@cX.off} #{@cX.ruby}~#{@cX.off} } - until gotten =~/exit|quit|bye|q|^\s*$/ \ - and ( @request.nil? or @request.empty? ) - @help=Help.new(@request,@color) - if @request - puts help_info - gotten=@request - @request=nil - end - case gotten - when /h((?:elp)| )|~/i - @help.summary - help_@request - when /list/; @help.summary - when /com(mands)?/; @help.commands - when /mod(ifiers)?/; @help.modifiers - when /markup|syntax/; @help.markup - when /example\b/; @help.example_v2 - when /example_v1/; @help.example_v1 - when /example(_v2)?/; @help.example_v2 - when /(?:heading|title|level)s?|structure/; @help.headings - when /head(ers?)?/; @help.headers - when /dublin(core)?|dc/; @help.dublin_core - when /(?:foot|end)notes/; @help.endnotes - when /tables?/; @help.tables - when /customise|skin/; @help.customise - when /modules/; @help.modules - when /env(ironment)?/; @help.environment - when /dir(ector(y|ies))?/; @help.directories - when /paths?/; @help.path - when /setup/; @help.setup - when /conf(?:ig(?:ure)?)?/; @help.configure - when /standards?/; @help.standards - when /lang(?:uage)?/; @help.languages - when /li[cs]en[sc]e/; @help.license - when /scratch/; @help.scratch - when /install/; @help.install - when /(?:--)?termsheet/; @help.termsheet - when /customise|styles?|appearance|theme/; @help.customise - when /metaverse/; @help.dal - when /(?:--)?plaintext|(?:--)?te?xt|-[aAeE]/; @help.plaintext - when /utf-?8/i; @help.utf8 - when /(?:--)?html|-[hH]/; @help.html - when /css/; @help.css - when /(?:--)?xhtml|-b/; @help.xhtml - when /(?:--)?xml|-[xX]/; @help.xml - when /(?:--)?odf|(?:--)?odt|opendocument|-o/; @help.odf - when /(?:--)?epub|-e/; @help.epub - when /php/; @help.php - when /(?:--)?pdf|-p/; @help.pdf - when /latex|tex/; @help.latex - when /(tex)?info/; @help.texinfo - when /lout/; @help.lout - when /concordance|index|-w/; @help.concordance - when /search\b/; @help.help_search - when /(?:hyper)?est(?:raier)?/; @help.hyperestraier - when /db|database|sql|postgresql|(?:--)?sqlite|(?:--)?pg|pg?sql|-[dD]/; @help.sql - when /searchform|cgi/; @help.cgi - when /convert/; @help.convert - when /(?:--)?webrick|-W/; @help.webrick - when /abstract|features|summary|about|sisu/; @help.abstract - when /ext(?:ernal)?(?:_?prog(?:rams)?)?/; @help.external_programs - when /ya?ml/; @help.yaml - when /sitemaps?/; @help.sitemap - when /(?:short)?cuts?/; @help.shortcuts - when /ansi|colors?/; SiSU_Screen::Ansi.new('c').colors - else @help.summary - end - print help_list - print help_prompt - gotten=nil - gotten=gets - end - rescue - #STDERR.puts Ansi.new($!, $@).rescue - # dies silently... for now, silence of use in connection with "sisu ~ commands" etc. - ensure - end - end - def summary - print <<-WOK - SiSU, Copyright (C) 1997 - 2013 Ralph Amissah - License GPL version 3 or Later. This program comes with ABSOLUTELY NO WARRANTY; - This is free software, and you are welcome to redistribute it under the conditions of the GPL3 or later. - For more license detail type/enter: "sisu --help license" - -for help type 'sisu --help', 'sisu --help [help request]', 'man sisu', (or see the system or online documentation) - -typing "sisu" on its own or "sisu --help", should give you this sisu help summary and the sisu (interactive help mode) help prompt, from which help on each keyword can be obtained. - -alternatively typing #{@cX.orange}sisu --help#{@cX.off} #{@cX.green}[keyword]#{@cX.off} at the command prompt will provide the sisu help page requested and return to the command prompt (if nothing is found it will print this page and return to the command prompt) - - Keywords (related to using SiSU) - #{@cX.green}help#{@cX.off} or #{@cX.green}list#{@cX.off} this sisu help summary - #{@cX.green}commands#{@cX.off} sisu --help commands - #{@cX.green}environment#{@cX.off} sisu --help env - ------------------------------------------ - Preparing Documents for SiSU - #{@cX.green}markup#{@cX.off} sisu --help markup (an incomplete overview) - #{@cX.green}headers#{@cX.off} sisu --help headers (document-wide instructions, meta-data) - #{@cX.green}structure#{@cX.off} sisu --help structure (document structure, headings, tables of contents) - #{@cX.green}endnotes#{@cX.off} sisu --help endnotes - #{@cX.green}tables#{@cX.off} sisu --help tables - #{@cX.green}example 1.0#{@cX.off} sisu --help example_v1 - #{@cX.green}example 2.0#{@cX.off} sisu --help example - ------------------------------------------ - #{@cX.green}search#{@cX.off} sisu --help search - ------------------------------------------ - #{@cX.green}customise#{@cX.off} sisu --help customise - ------------------------------------------ - SiSU's License - #{@cX.green}license#{@cX.off} sisu --help license - -for help type 'sisu --help', 'sisu --help [help request]', 'man sisu', (or see the system or online documentation) - WOK - end - def abstract - print <<-WOK -Features: -#{@cX.cyan}(i)#{@cX.off} minimal markup requirement -#{@cX.cyan}(ii)#{@cX.off} single file marked up for multiple outputs -#{@cX.cyan}(iii)#{@cX.off} markup is simpler than html -#{@cX.cyan}(iv)#{@cX.off} the simple syntax is mnemonic, influenced by mail/messaging/wiki markup practices -#{@cX.cyan}(v)#{@cX.off} human readable, and easily writable -#{@cX.cyan}(vi)#{@cX.off} multiple outputs include amongst others: html; pdf via LaTeX; (structured) XML; sql - currently PostgreSQL and sqlite; plaintext, (also texinfo) -#{@cX.cyan}(vii)#{@cX.off} all text objects (headings and paragraphs) are numbered identically, for citation purposes, in all outputs (html, pdf, sql etc.) -#{@cX.cyan}(viii)#{@cX.off} creates organised directory/file structure for output -#{@cX.cyan}(ix)#{@cX.off} easily mapped with its clearly defined structure, with all text objects numbered, you know in advance where in each document output type, a bit of text will be found (eg. from an sql search, you know where to go to find the prepared html output or pdf etc.)... there is more -#{@cX.cyan}(x)#{@cX.off} use of Dublin Core and other meta-tags to permit the addition of some semantic information on documents, and making easy integration of rdf/rss feeds etc. -#{@cX.cyan}(xi)#{@cX.off} very easily skinnable, document appearance on a project/site wide, or document instance level easily controlled/changed -#{@cX.cyan}(xii)#{@cX.off} in many cases a regular expression may be used (once in the document header) to define all or part of a documents structure obviating or reducing the need to provide structural markup within the document -#{@cX.cyan}(xiii)#{@cX.off} is a batch processor for handling large document sets, ... though once generated they need not be re-generated, unless changes are made to the desired presentation of a particular output type -#{@cX.cyan}(xiv)#{@cX.off} possible to pre-process, which permits the easy creation of standard form documents, and templates/term-sheets -#{@cX.cyan}(xv)#{@cX.off} extremely modular, (thanks in no small part to Ruby) another output format required, write another module.... -#{@cX.cyan}(xvi)#{@cX.off} easy to update output formats (eg html, xhtml, latex/pdf produced can be updated in program and run against whole document set) -#{@cX.cyan}(xvii)#{@cX.off} easy to add, modify, or have alternative syntax rules for input, should you need to -#{@cX.cyan}(xviii)#{@cX.off} "Concordance" wordmap, consisting of all the words in a document and their (text object) locations within the text -#{@cX.cyan}(xix)#{@cX.off} tied to revision control system, only code and marked up file need be backed up, to be sure of the much larger document set -#{@cX.cyan}(xx)#{@cX.off} syntax highlighting files for markup, primarily (g)vim so far. - -SiSU was developed in relation to legal documents, and so is strong across a wide variety of texts (law, literature...), though weak on formulae/statistics, it does handle images. An assumption has been document sets that are to be preserved and maintained over time (also a result of the legal text origin). SiSU has been developed and used over a number of years, and the requirements to cover a wide range of documents have been thoroughly explored. - -There is more detailed information available on it from: - #{@cX.blue}http://www.jus.uio.no/sisu#{@cX.off} - * plaintext - * HTML - * ODT (Open Document Format text) - * EPUB - * XML (structured) - * LaTeX - * PDF (via LaTeX) - * TeXinfo - * SQL (at postgreSQL & SQLite) - WOK - end - def commands - print <<-WOK - - #{@cX.ruby}-a#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces plaintext with Unix linefeeds. Without markup, (object numbers are omitted), has footnotes at end of each para‐ graph that contains them. Modifier options available: --footnotes (default) or --endnotes and for linefeeds --unix (default) or --msdos - - #{@cX.ruby}-b#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces xhtml/XML output for browser viewing (sax parsing) - - #{@cX.ruby}-C#{@cX.off} initialise shared output directory (config files such as css and dtd files are not updated if they already exist unless modifier is used) #{@cX.ruby}-C --init=site#{@cX.off} 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. in a new markup document working directory should initialise the corresponding output directory, though SiSU will automatically do this, the first time it is run (for processing) in a given directory. - - #{@cX.ruby}-c#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} 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) - - #{@cX.ruby}-D#{@cX.off} #{@cX.green}[instruction]#{@cX.off} #{@cX.green}[filename]#{@cX.off} database instruction, see database section below - - #{@cX.ruby}-d#{@cX.off} #{@cX.green}[instruction]#{@cX.off} #{@cX.green}[filename]#{@cX.off} database instruction, see database section below [only -D currently available] - - #{@cX.ruby}-F#{@cX.off} generate examples of (naive) cgi search form for sqlite and pgsql depends on your already having used sisu to populate an sqlite and/or pgsql database, (the sqlite version scans the output directories for existing sisu_sqlite databases, so it is first necessary to create them, before generating the search form) see -d -D and the database section below. If the optional parameter webrick is passed, the cgi examples created will be set up to use the default port set for use by the webrick server, (otherwise the port is left blank and the system setting used, usually 80). The samples are dumped in the present work directory which must be writable, (with screen instructions given that they be copied to the cgi-bin directory). - - #{@cX.ruby}-H#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces html (css version) (creates html (using css)), with url link suffixes (.html .pdf etc.) omitted ("Hide"). For web servers that are confireud so as not to require file extensions to locate and serve files. [behaviour switched see -h] - - #{@cX.ruby}-h#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces html (hardlinks i.e. with name suffixes in links/local urls). html, with internal document links that include the document suffix, ie whether it is .html or .pdf (required for browsing directly off a file system, and works with most web servers). [behaviour switched see -H] - - #{@cX.ruby}-I#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces texinfo file with its myriad of possibilities - - #{@cX.ruby}-L#{@cX.off} prints license information - - #{@cX.ruby}-M#{@cX.off} #{@cX.green}[filename/wildcard/url]#{@cX.off} maintenance mode, files created for processing are not deleted, and their locations are indicated (also see -V) - - #{@cX.ruby}-m#{@cX.off} #{@cX.green}[filename/wildcard/url]#{@cX.off} create (new)metaVerse (used in all subsequent processing). Produce a meta file, the first step in processing, and the file all subsequent processing utilize. (Should usually be run together with other commands to ensure that the lated version of markup source document is used, i.e. add -m flag to other flags required). - - #{@cX.ruby}-N#{@cX.off} #{@cX.green}[filename/wildcard/url]#{@cX.off} document content certificate as md5 digest tree of document produced (as digest.txt), the digest for the document, and digests for each object contained within the document (together with information on software versions that produced it). Try -mNV for verbose digest output to screen - - #{@cX.ruby}-n#{@cX.off} #{@cX.green}[filename/wildcard/url]#{@cX.off} skip meta-markup (building of "metaverse"), this skips the equivalent of -m - - #{@cX.ruby}-p#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces LaTeX pdf (portrait & landscape). 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). - - #{@cX.ruby}-q#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} quiet, less output to screen - - #{@cX.ruby}-r#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} copies sisu output files to remote host using scp (default). This requires that sisurc.yml has been provided with information on hostname and user name, and that you have your "keys" and ssh agent in place. - - #{@cX.ruby}-S#{@cX.off} #produces a sisupod, a zipped sisu directory of markup files including sisu markup source files and the directories local configuration file, images and skins. Note: this only includes the configuration files or skins contained in ./_sisu not those in ~/.sisu The resulting tar gzip file has a .zip suffix added to the markup source directory name. To tar and gzip individual files see the -Z [filename/wildcard] option. Note: (this option is tested only with zsh) - - #{@cX.ruby}-S#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces a sisupod a zipped sisu of the content assocated with the specified sisu markup documnt, i.e. including sisu markup source file, (and associated documents if a master file, or available in multilingual versions), together with related images and skin. The resulting zipped file has a .zip suffix added to the markup source file name by default, though a .ssp suffix is also recognised. The directory structure of the unzipped file is understood by sisu, and sisu commands can be run within it. SiSU commands can be run against a sisupod contained in a local directory, or provided as a url on a remote site. As there is a security issue with skins provided by other users, they are not applied unless the flag --trust or --trusted is added to the command instruction, it is recommended that file that are not your own are treated as untrusted. This provides a convenient way of packing documents files for sending Note: if you wish to send multiple files, it quickly becomes more space efficient to tar and gzip the sisu markup directory, (without the _sisu_processing subdirectory) rather than the individual files for sending). See the -S option without [filename/wildcard] - - #{@cX.ruby}-T#{@cX.off} #{@cX.green}[filename/wildcard (*.termsheet.rb)]#{@cX.off} standard form document builder, preprocessing feature - - #{@cX.ruby}-t#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces plaintext with Unix linefeeds. Without markup, (object numbers are omitted), has footnotes at end of each para‐ graph that contains them. Modifier options available: --footnotes (default) or --endnotes and for linefeeds --unix (default) or --msdos - - #{@cX.ruby}-U#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} prints url list/map for the available processing flags options and resulting files that could be requested, (can be used to get a list of processing options in relation to a file, together with information on the output that would be produced), -u provides url mapping for those flags requested for processing. The default assumes sisu_webrick is running and provides webrick url mappings where appropriate, but these can be switched to file system paths in sisurc.yml - - #{@cX.ruby}-u#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} provides url mapping of output files for the flags requested for processing, also see -U - - #{@cX.ruby}-V#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} on its own provides SiSU version and environment information (sisu --help env) - - #{@cX.ruby}-V#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} even more verbose than -v the -V flag provides some additional information, also see -M - - #{@cX.ruby}-v#{@cX.off} on its own, provides SiSU version information. - - #{@cX.ruby}-v#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} provides more 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 - - #{@cX.ruby}-X#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces XML output with deep document structure, in the nature of dom - - #{@cX.ruby}-x#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces XML output (sax parsing) - - #{@cX.ruby}-W#{@cX.off} #{@cX.green}[port]#{@cX.off} starts ruby´s webrick webserver, points at sisu output directories (default port is set) - - #{@cX.ruby}-w#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces concordance, a rudimentary index of all the words in a document - - #{@cX.ruby}-Z#{@cX.off} Zap, if used with other processing flags #{@cX.green}deletes output files#{@cX.off} of the type about to be processed, prior to processing. If -Z is used as the lone processing related flag (or in conjunction with a combination of -[mMvVq]), will remove the related document output directory. - - #{@cX.ruby}-z#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces php (zend) [feature disabled, depreciated] - - #{@cX.ruby}--harvest#{@cX.off} #{@cX.green}*.ss[tm]#{@cX.off} makes two lists of sisu output based on the sisu markup documents in a directory: list of author and authors works (year and titles), and; list by topic with titles and author. Makes use of header metadata fields (author, title, date, topic_register). Can be used with -M and -R flags. - - #{@cX.ruby}databases#{@cX.off} - - #{@cX.ruby}dbi - database interface -D or --pgsql set for postgresql -d or --sqlite set for sqlite#{@cX.off} - - #{@cX.ruby}-D#{@cX.off} #{@cX.ruby}--create#{@cX.off} creates empty postgresql db and required tables & indexes (rb.dbi) [#{@cX.ruby}-d --create#{@cX.off} sqlite equivalent] it may be necessary to first run sisu #{@cX.ruby}-D#{@cX.off} #{@cX.ruby}--createdb#{@cX.off} - - #{@cX.ruby}-Di#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} or #{@cX.ruby}-D#{@cX.off} #{@cX.ruby}--import#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} imports data specified to postgresql db (rb.dbi) [#{@cX.ruby}-d --import#{@cX.off} sqlite equivalent] - - #{@cX.ruby}-Du#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} or #{@cX.ruby}-D#{@cX.off} #{@cX.ruby}--update#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} updates/imports specified data to postgresql db (rb.dbi) [#{@cX.ruby}-d --update#{@cX.off} sqlite equivalent] - - #{@cX.ruby}-D#{@cX.off} #{@cX.ruby}--remove#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} removes specified data to postgresql db (rb.dbi) [#{@cX.ruby}-d --remove#{@cX.off} sqlite equivalent] - - #{@cX.ruby}-D#{@cX.off} #{@cX.ruby}--dropall#{@cX.off} kills data" and drops (postgresql) db, tables & indexes [#{@cX.ruby}-d --dropall#{@cX.off} sqlite equivalent] - - #{@cX.ruby}-D#{@cX.off} #{@cX.ruby}--recreate#{@cX.off} kills data" and drops (postgresql or sqlite) db, tables & indexes, then creates an empty db with tables and indexes [#{@cX.ruby}-d --recreate#{@cX.off} sqlite equivalent] - - also see command #{@cX.green}shortcuts#{@cX.off}, and shorthand mappings for multiple flags - WOK - end - def shortcuts - cf_defaults=SiSU_Env::InfoProcessingFlag.new - print <<-WOK - - #{@cX.ruby}Shorthand for multiple flags#{@cX.off} - - #{@cX.ruby}--update#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} Checks existing file output and runs the flags required to update this output. This means that if only html and pdf output was requested on previous runs, only the -hp files will be applied, and only these will be generated this time, together with the summary. This can be very convenient, if you offer different outputs of different files, and just want to do the same again. - - #{@cX.ruby}-0#{@cX.off} to #{@cX.ruby}-5#{@cX.off} #{@cX.green}[filename or wildcard]#{@cX.off} - #{@cX.green}Default shorthand mappings#{@cX.off} (note that the defaults can be changed in the #{@cX.green}sisurc.yml#{@cX.off} file): - - (these can be turned off if unavailable in sisurc.yml under program_set:) - #{@cX.green}processing shortcut defaults set to:#{@cX.off} - color defaut set (on==true) #{@cX.blue}#{cf_defaults.color}#{@cX.off} - sisu -0 (also just "sisu") #{@cX.blue}#{cf_defaults.cf_0}#{@cX.off} - sisu -1 #{@cX.blue}#{cf_defaults.cf_1}#{@cX.off} - sisu -2 #{@cX.blue}#{cf_defaults.cf_2}#{@cX.off} - sisu -3 #{@cX.blue}#{cf_defaults.cf_3}#{@cX.off} - sisu -4 #{@cX.blue}#{cf_defaults.cf_4}#{@cX.off} - sisu -5 #{@cX.blue}#{cf_defaults.cf_5}#{@cX.off} - defaults may be changed in active sisurc.yml file under 'flag:' - - add -v for verbose mode and -c (color toggle), e.g. - WOK - end - def modifiers - print <<-WOK - - #{@cX.ruby}Command flag modifiers#{@cX.off} - - #{@cX.ruby}--no-ocn#{@cX.off} [with -h -H or -p] switches off object citation numbering. Produce output without identifying numbers in margins of html or LaTeX/pdf output. - - #{@cX.ruby}--no-annotate#{@cX.off} strips output text of editor endnotes~[* square brackets ]~ denoted by asterisk or dagger/plus sign - - #{@cX.ruby}--no-asterisk#{@cX.off} strips output text of editor endnotes~[* square brackets ]~ denoted by asterisk - - #{@cX.ruby}--no-dagger#{@cX.off} strips output text of editor endnotes~[+ square brackets ]~ denoted by dagger/plus sign - - WOK - end - def misc - <<-WOK - #{@cX.cyan}misc#{@cX.off} - #{@cX.green}-s#{@cX.off} [filename or wildcard] #{@cX.green}spellcheck#{@cX.off} (aspell previously ispell - \t#{@cX.green}mailer examples#{@cX.off} - from vim mail.er10 (not gvim) issue command - \t:! ruby -S mailer.rb instruction/landscape|a4l|portrait|a4p/ email@address/alias subject line - \t:! ruby -S mailer.rb a4l ralph@amissah.com testing continues - from vim mail.er10 use your vim alias \\mail or \\mutt (modify command line as required) - #{@cX.green}feeds rss/rdf#{@cX.off} - #{@cX.blue}-R #{@cX.off} (yaml|rss) extraction of semantic data into yaml file for auto build of xml feeds (rss, rdf) #{@cX.fuschia}[work area]#{@cX.off} - #{@cX.green}-R #{@cX.off} yaml extraction of semantic data into yaml file for auto build of xml feeds (rss, rdf) - #{@cX.green}-R #{@cX.off} rss creates rss2.0 feed - WOK - end - def markup - print <<-WOK -sisu - Note: files for SiSU should be in UTF-8 character encoding. - - #{@cX.cyan}Data text markup#{@cX.off} (alternative to available html subset) - #{@cX.green}% SiSU 4.00#{@cX.off} [statement on first line of document, declared file-type identifier, SiSU markup document - - #{@cX.green}A~#{@cX.off} heading/title [levels A to C available (and beneath that 1 to 6)] - - #{@cX.green}1~#{@cX.off}filename heading [segmentation level, levels 1 to 6 available] - - #{@cX.green}!{#{@cX.off}emphasis#{@cX.green}}!#{@cX.off} - #{@cX.green}*{#{@cX.off}bold text#{@cX.green}}*#{@cX.off} - #{@cX.green}_{#{@cX.off}underscore#{@cX.green}}_#{@cX.off} - #{@cX.green}/{#{@cX.off}italics#{@cX.green}}/#{@cX.off} - #{@cX.green}"{#{@cX.off}citation#{@cX.green}}"#{@cX.off} - #{@cX.green}^{#{@cX.off}superscript#{@cX.green}}^#{@cX.off} - #{@cX.green},{#{@cX.off}subscript#{@cX.green}},#{@cX.off} - #{@cX.green}+{#{@cX.off}inserted text#{@cX.green}}+#{@cX.off} - #{@cX.green}-{#{@cX.off}strikethrough#{@cX.green}}-#{@cX.off} - - ------------------------------------------ - #{@cX.cyan}Indentation and bullets#{@cX.off} - - #{@cX.green}_1#{@cX.off} indent paragraph one level - - #{@cX.green}_2#{@cX.off} indent paragraph two steps - - #{@cX.green}_*#{@cX.off} bullet text - - #{@cX.green}_1*#{@cX.off} bullet text, first indent - - ------------------------------------------ - #{@cX.cyan}Numbered List#{@cX.off} (not to be confused with headings/titles, (document structure)) - - #{@cX.green}##{@cX.off} numbered list numbered list 1., 2., 3, etc. - - #{@cX.green}_##{@cX.off} numbered list numbered list indented second level a., b., c., d., etc. - - ------------------------------------------ - #{@cX.cyan}Endnotes#{@cX.off} - - #{@cX.green}~{#{@cX.off}footnote/endnote#{@cX.green}}~#{@cX.off} endnote#{@cX.green}~{#{@cX.off}self contained endnote marker & endnote in one#{@cX.green}}~#{@cX.off} - #{@cX.green}~{*#{@cX.off}asterisk footnote/endnote#{@cX.green}}~#{@cX.off} - editor's annotations, square bracket notes - #{@cX.green}~[*#{@cX.off}numbered asterisk footnote/endnote series#{@cX.green}]~#{@cX.off} - #{@cX.green}~[+#{@cX.off}numbered dagger/plus sign footnote/endnote series#{@cX.green}]~#{@cX.off} - --- - alternative endnote pair notation - #{@cX.green}~^#{@cX.off} endnote marker - #{@cX.green}^~#{@cX.off} endnote text following the paragraph in which the marker occurs - - ------------------------------------------ - #{@cX.cyan}Links#{@cX.off} - - http://url.org on its own would be automatically marked up and hyperlinked to itself - #{@cX.green}{#{@cX.off} [text to link] #{@cX.green}}#{@cX.off}http://url.org - #{@cX.green}{#{@cX.off}image.png#{@cX.green}}#{@cX.off}http://url.org - #{@cX.green}{#{@cX.off}image.png#{@cX.green}}#{@cX.off}image #{@cX.green}{#{@cX.off}tux.png 64#{@cX.green}x#{@cX.off}80#{@cX.green}}#{@cX.off}image - Linked image example - #{@cX.green}{#{@cX.off} SiSU Geek Writer #{@cX.green}}#{@cX.off}http://www.jus.uio.no/sisu/ url example - #{@cX.green}{#{@cX.off}tux.png 64#{@cX.green}x#{@cX.off}80 "a better way" #{@cX.green}}#{@cX.off}http://www.jus.uio.no/sisu/ image example with all options (width x height) - Note: png and jpg support only (no gif support) - - shortcut - hyper-linked text with endnote providing the url information - #{@cX.green}{~^#{@cX.off} [text to link] #{@cX.green}}#{@cX.off}http://url.org maps to #{@cX.green}{#{@cX.off} [text to link] #{@cX.green}}#{@cX.off}http://url.org #{@cX.green}~{#{@cX.off} http://url.org #{@cX.green}}~#{@cX.off} - produces hyper-linked text within a document/paragraph, with an endnote providing the url for the text location used in the hyperlink - - shortcut: - #{@cX.green}{#{@cX.off} [text to link] #{@cX.green}[3sS]}#{@cX.off}markup_source_filename.sst - if a server host name has been provided/configured, will provide a list of available output types that would be generated using the shortcut command and the markup file provided, i.e. output generated using the command (as configured): - "sisu -3sS markup_source_filename.sst" - using server host, directory stub, filename to compose the link. - - ------------------------------------------ - adding fixed names in html, manual location marker/tagging - #{@cX.green}*~[name]#{@cX.off} <a name="[name]"> - - ------------------------------------------ - #{@cX.green}~##{@cX.off} unnumbered paragraph (place marker at end of paragraph) - #{@cX.green}-##{@cX.off} unnumbered paragraph, delete when not required (place marker at end of paragraph) [used in dummy headings, eg. for segmented html] - - ------------------------------------------ - manual page breaks (LaTeX/pdf) - #{@cX.green}<:pb>#{@cX.off} page break, which breaks a page, starting a new page in single column text and a new column in double column text - #{@cX.green}<:pn>#{@cX.off} page new, which starts a new page, in both single and double column text (leaving an empty column in double column text if necessary). - Note: page breaks are usually introduced to pdfs either as header instructions, indicating that pages should break at given levels - - ------------------------------------------ - #{@cX.cyan}Composite documents#{@cX.off} - - It is possible to build a document by creating a master document that requires other documents. The documents required may 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 mainly from other documents), it should be named with the suffix #{@cX.blue}.ssm#{@cX.off} 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 #{@cX.blue}.sst#{@cX.off} regular markup file, or #{@cX.blue}.ssi#{@cX.off} (insert/information) A secondary file of the composite document is built prior to processing with the same prefix and the suffix #{@cX.blue}.ssm.sst#{@cX.off} - - #{@cX.cyan}#basic sisu markup alternatives#{@cX.off} - #{@cX.green}{#{@cX.off}filename.ssi#{@cX.green}}require#{@cX.off} - #{@cX.green}<< {#{@cX.off}filename.ssi#{@cX.green}}#{@cX.off} - - #{@cX.cyan}#using textlink alternatives#{@cX.off} - #{@cX.green}|#{@cX.off}filename.ssi#{@cX.green}|@|^|require#{@cX.off} - #{@cX.green}<< |#{@cX.off}filename.ssi#{@cX.green}|@|^|#{@cX.off} - - #{@cX.cyan}#using thlnk alternatives#{@cX.off} - #{@cX.green}<url:#{@cX.off}filename.ssi#{@cX.green}>require#{@cX.off} - #{@cX.green}<< <url:#{@cX.off}filename.ssi#{@cX.green}>#{@cX.off} - - #{@cX.cyan}Composite documents - remote parts#{@cX.off} - Composite documents may be built from remote parts, by using the composite document syntax with a url. This makes sense using either sisu regular syntax (which is just a convenient way of marking up), or thlnk syntax, which also recognises remote urls, and permits hyperlinking ascii to the url location. - - #{@cX.cyan}Remote documents#{@cX.off} - SiSU will download and process remote locations if a url is provided instead of a filename. [this at present works only for sisu markup files without images] - - ------------------------------------------ - #{@cX.green}%#{@cX.off}#{@cX.off} add a comment to text, that will be removed prior to processing (place marker at beginning of line) - #{@cX.green}\\#{@cX.off}#{@cX.off} escape a sepcial character, whether general: { } < > or contextual special characters, (in combination with other characters) ~ - _ / % ^ and occasionally ! # + , - #{@cX.green}%%#{@cX.off}#{@cX.off} same as above but recognised by vim folds for placing fold in document text, in addition to headers and headings - ------------------------------------------ - - #{@cX.ruby}More HELP on Markup#{@cX.off} markup help is available on: - document wide instructions: headers (document structure) - general text markup: headings; endnotes; tables (which also includes a note on preformatted text) - configuration and customisation - document or site wide customisation: customise; skin - WOK - help_markup - end - def example - help_markup - end - def example_v1 - print <<-WOK -% SiSU 1.0 - -@title: Working Sample Document - -@subtitle: Demonstrating markup - -@creator: Ralph Amissah - -@date: - -@markup: num_top=4 - -@bold: [regular expression of words/phrases to be made bold] - -@italics: [regular expression of words/phrases to italicise] - -@links: { SiSU }http://www.jus.uio.no/sisu { FSF }http://www.fsf.org - -A~ A Sample Document - -B~ just for fun - -1~ This is Chapter One or Article One - -Ordinary Text follows here. The Title would be a Chapter or Article depending on the type of document you were working to produce. - -1~ This would be Chapter Two or Article Two - -And so on. - -Assuming sisu is configured properly so it has been instructed where to put the work files and ouput files, you would generate this text once saved, with the suffix .sst if saved as example.sst, by typing sisu -mhwxp example.sst while in the directory in which the file is saved. - -_1 -m initial processing, -h html (css based), -w concordance for html, -x xml, -p pdf output, generated via latex, there are of course additional options - -_1 for a listing type: sisu ~ commands - -_1 for an outline of sisu markup type: sisu ~ markup - -The example ends here. - WOK - help_markup - end - def example_v2 - print <<-WOK -% SiSU 2.0 - -@title: Working Sample Document - :subtitle: Demonstrating markup - -@creator: - :author: Amissah, Ralph - -@date: - :published: 2010-09-18 - -@rights: - :copyright: Ralph Amissah - -@make: - :num_top: 1 - :bold: [regular expression of words/phrases to be made bold] - :italics: [regular expression of words/phrases to italicise] - -@links: - { SiSU }http://www.jus.uio.no/sisu { FSF }http://www.fsf.org - -A~ @title @author - -B~ just for fun - -1~ This is Chapter One or Article One - -Ordinary Text follows here. The Title would be a Chapter or Article depending on the type of document you were working to produce. - -1~ This would be Chapter Two or Article Two - -And so on. - -Assuming sisu is configured properly so it has been instructed where to put the work files and ouput files, you would generate this text once saved, with the suffix .sst if saved as example.sst, by typing sisu -mhwxp example.sst while in the directory in which the file is saved. - -_1 --dal initial processing, --html (css based), --concordance (html), --epub, --odt, --pdf output, generated via LaTeX, there are of course additional options - -_1 for a listing type: sisu ~ commands - -_1 for an outline of sisu markup type: sisu ~ markup - -The example ends here. - WOK - help_markup - end - def headers - print <<-WOK -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 #{@cX.green}@headername:#{@cX.off} followed on the next line by an indented sub-category header if any #{@cX.green}:sub-headername:#{@cX.off}. -#{@cX.green}@indentifier:#{@cX.off} information or instructions -where the #{@cX.green}"identifier"#{@cX.off} is a tag recognised by the program, and the #{@cX.green}"information"#{@cX.off} or #{@cX.green}"instructions"#{@cX.off} belong to the tag/indentifier specified - Note: a header where used should only be used once; all headers apart from #{@cX.ruby}@title:#{@cX.off} are optional. - -#{@cX.ruby}@title:#{@cX.off} My Title - This is now the Title of the Document and used as such - #{@cX.cyan}:subtitle:#{@cX.off} The Subtitle if any - -#{@cX.ruby}@creator:#{@cX.off} - #{@cX.cyan}:author:#{@cX.off} Surname, Other names (if more than one author separate author names with a semi colon, if name is of an institution just write name or the name contains a comma enclose in quotation marks) - #{@cX.cyan}:contributor:#{@cX.off} - #{@cX.cyan}:translator:#{@cX.off} [or :translated_by:] - #{@cX.cyan}:illustrator:#{@cX.off} [or :illustrated_by:] - #{@cX.cyan}:prepared_by:#{@cX.off} [or :digitized_by:] - -#{@cX.ruby}@date:#{@cX.off} - #{@cX.cyan}:published:#{@cX.off} - #{@cX.cyan}:created:#{@cX.off} - #{@cX.cyan}:issued:#{@cX.off} - #{@cX.cyan}:available:#{@cX.off} - #{@cX.cyan}:valid:#{@cX.off} - #{@cX.cyan}:modified:#{@cX.off} - -#{@cX.ruby}@rights:#{@cX.off} - #{@cX.cyan}:copyright:#{@cX.off} Author's name, all rights reserved - #{@cX.cyan}:license:#{@cX.off} public domain, copyleft, creative commons variant, etc. - -#{@cX.ruby}@classify:#{@cX.off} - #{@cX.cyan}:topic_register:#{@cX.off} [e.g.:] text markup language; application:text processing;output:html|xml|latex|pdf|sql - #{@cX.cyan}:subject:#{@cX.off} (whatever your subject) - #{@cX.cyan}:keywords:#{@cX.off} - #{@cX.cyan}:loc:#{@cX.off} [Library of Congress classification] - #{@cX.cyan}:dewey:#{@cX.off} [Dewey classification] - -#{@cX.ruby}@identifier:#{@cX.off} - #{@cX.cyan}:isbn:#{@cX.off} - #{@cX.cyan}:oclc:#{@cX.off} - -#{@cX.ruby}@notes:#{@cX.off} - #{@cX.cyan}:description:#{@cX.off} - #{@cX.cyan}:abstract:#{@cX.off} - #{@cX.cyan}:comment:#{@cX.off} - #{@cX.cyan}:coverage:#{@cX.off} - #{@cX.cyan}:relation:#{@cX.off} - #{@cX.cyan}:source:#{@cX.off} - #{@cX.cyan}:history:#{@cX.off} - #{@cX.cyan}:type:#{@cX.off} - #{@cX.cyan}:format:#{@cX.off} - #{@cX.cyan}:prefix:#{@cX.off} - #{@cX.cyan}:suffix:#{@cX.off} - -#{@cX.ruby}@publisher:#{@cX.off} - -#{@cX.ruby}@language:#{@cX.off} [or @language.document:] [country code for language if available, or language, English, en is the default setting] (en - English, fr - French, de - German, it - Italian, es - Spanish, pt - Portuguese, sv - Swedish, da - Danish, fi - Finnish, no - Norwegian, is - Icelandic, nl - Dutch, et - Estonian, hu - Hungarian, pl - Polish, ro - Romanian, ru - Russian, el - Greek, uk - Ukranian, tr - Turkish, sk - Slovak, sl - Slovenian, hr - Croatian, cs - Czech, bg - Bulgarian ) [however, encodings are not available for all of the languages listed.] - -#{@cX.ruby}@language.original:#{@cX.off} -original language in which the work was published - -#{@cX.ruby}@links:#{@cX.off} - { SiSU }http://www.jus.uio.no/sisu/ - { FSF }http://www.fsf.org - -#{@cX.ruby}@make:#{@cX.off} - #{@cX.cyan}:breaks:#{@cX.off} new=:B; break=1 - #{@cX.cyan}:bold:#{@cX.off} [regular expression of words/phrases to be made bold] - #{@cX.cyan}:italics:#{@cX.off} [regular expression of words/phrases to italize] - #{@cX.cyan}:home_button_image:#{@cX.off} {free_as_in_freedom.png }http://stallman.org/ - #{@cX.cyan}:home_button_text:#{@cX.off} {Free Culture}http://www.free-culture.cc; {Lawrence Lessig}http://www.lessig.org - #{@cX.cyan}:footer:#{@cX.off} {Free Culture}http://www.free-culture.cc; {Lawrence Lessig}http://www.lessig.org - #{@cX.cyan}:headings:#{@cX.off} PART; CHAPTER; Section; Article; - #{@cX.grey}% 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#{@cX.off} - #{@cX.cyan}:papersize:#{@cX.off} (A4|US_letter|book_B5|book_A5|US_legal) - #{@cX.cyan}:markup:#{@cX.off} num_top=4 [various markup instructions, eg: num_top=4 headings tobe numbered, starting at heading level 4... the default is to provide 3 levels, as in 1 level 4, 1.1 level 5, 1.1.1 level 6, markup to be merged within level] - #{@cX.cyan}:promo:#{@cX.off} sisu, ruby, search_libre_docs, open_society [places content in right pane in html, makes use of list.yml and promo.yml, commented out sample in document sample: free_as_in_freedom.richard_stallman_crusade_for_free_software.sam_williams.sst] - -#{@cX.grey}% header ends here, NB only @title: is mandatory [this would be a comment]#{@cX.off} - -#{@cX.blue}A~#{@cX.off} Top level heading [this is usually the same as the title @title: ] - -#{@cX.blue}B~#{@cX.off} Second level heading [this is a heading level divider] - -#{@cX.blue}C~#{@cX.off} Third level heading [this is a heading level divider] - -#{@cX.blue}1~#{@cX.off} Top level heading preceding substantive text of document or sub-heading 5, the heading level that would normally be marked 1. or 2. or 3. etc. in a document - -#{@cX.blue}2~#{@cX.off} Second level heading preceding substantive text of document or sub-heading 6, the heading level that would normally be marked 1.1 or 1.2 or 1.3 or 2.1 etc in a document - -#{@cX.blue}3~#{@cX.off} 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 - - WOK - help_markup - end - def customise - print <<-WOK - There are a number of files that control the appearance of a site or a document i.e. - - #{@cX.blue}(i)#{@cX.off} files that control #{@cX.green}site-wide appearance#{@cX.off}: - - #{@cX.green}defaults.rb#{@cX.off} initial values used by program, not necessary to change - - skins are placed in a configuration directory beneath the markup directory ./_sisu/skin/doc or in ~/.sisu/skin/doc - if a skin is also to be used for a directory or site wide presentations, rather than being called for a single document then a softlink is placed from ~/.sisu/skin/dir or ~/.sisu/skin/site respectively to the relevant skin within ~/.sisu/skin/doc - - rules for skin loading are in #{@cX.green}sysenv.rb#{@cX.off} - the skin loading heuristics / hierarchy is currently as follows: - - a. if there is a skin requested within a document, thent that skin is used - 0~skin skin_lm (would load skin ~/.sisu/skin/doc/skin_lm.rb) - - b. use it if there is a "dir" skin with the same name as the source directory "stub" i.e. - if working in a directory called /home/myhome/workdir/lm - then if ~/.sisu/skin/dir/skin_lm.rb were found it would be used and skin_lm.rb would be a softlink to the relevant skin in the document skin directory (where all the actual skins are kept) - - x. [additionally though discouraged a special rule can be set up in sysenv AddSkin.select (which could override b if desired)] - - #{@cX.green}skin_site_#{@cX.off}#{@cX.cyan}[name of site skin in use]#{@cX.off}#{@cX.green}.rb#{@cX.off} this file is called by skin.rb - if there are several such files, site appearance may be changed by - requesting the skin_site desired from skin.rb - and - - #{@cX.blue}(ii)#{@cX.off} presentation maintenance: - if you have a body of documents the easiest way to give them a particular appearance/skin, is to associate that directory with a skin, all files in that directory take on the specified appearance, changing appearance of documents once directories are set up is as simple as copying the files from one directory to another (or renaming the directory); or associating the directory with a different skin. - - see also directories - WOK - end - def configure - print <<-WOK - see the following topics - install - setup - and note for initial configuration it is necessary to run: - sisu -C - (this places the default CSS files and DTDs in place) - WOK - end - def path - help_env - puts <<-WOK - -If you have problems check permissions (and if in home directory ownership). - -#{@cX.green}directory paths as currently set#{@cX.off}: - output docs: #{@cX.blue}#{@env.path.webserv}#{@cX.off} - cgi scripts: #{@cX.blue}#{@env.path.cgi}#{@cX.off} - processing: #{@cX.blue}#{@env.processing_path.processing}#{@cX.off} - sisu meta markup: #{@cX.blue}#{@env.processing_path.dal}#{@cX.off} - html tuning: #{@cX.blue}#{@env.processing_path.tune}#{@cX.off} - latex: #{@cX.blue}#{@env.processing_path.tex}#{@cX.off} - texinfo: #{@cX.blue}#{@env.processing_path.texi}#{@cX.off} - images: - source: #{@cX.blue}#{@env.path.image_source}#{@cX.off} - latex source: #{@cX.blue}#{@env.path.image_source_include}#{@cX.off} - note images are also sourced from within your pwd - #{@cX.blue}#{Dir.pwd}/_sisu/image#{@cX.off} if it exists - #{@cX.grey}[ texinfo: #{@env.processing_path.texinfo} - check duplication ]#{@cX.off} - - #{@cX.green}resource configuraton files#{@cX.off} to change the paths specified above, are searched for in the following order: - under the current SiSU markup data directory: #{@cX.blue}#{Dir.pwd}/_sisu/sisurc.yml#{@cX.off} - under the home directory ~/.sisu: #{@cX.blue}#{@env.path.home}/.sisu/sisurc.yml#{@cX.off} - in the "/etc" directory: #{@cX.blue}#{@env.path.etc}/sisurc.yml#{@cX.off} - default file paths are set by the program SiSU - - #{@cX.green}skins#{@cX.off} for document appearances on a site, directory or per document basis are located in subdirectories #{@cX.blue}doc/#{@cX.off} #{@cX.blue}dir/#{@cX.off} and #{@cX.blue}site/#{@cX.off} within: - #{@cX.blue}#{Dir.pwd}/_sisu/skin#{@cX.off} - #{@cX.blue}#{@env.path.home}/.sisu/skin#{@cX.off} - #{@cX.blue}#{@env.path.etc}/skin#{@cX.off} - default appearances are set by the program SiSU in the absence of skins - - #{@cX.green}Note on subdirectories for output documents#{@cX.off} - The last part of the name of the directory you choose to work from is used as the major sub-directory in which output files are placed, - i.e. if you are working in a directory called #{@cX.blue}#{@env.path.home}/ebook#{@cX.off} - the output files will be placed in a sub-directory named after the processed text within #{@cX.blue}#{@env.path.webserv}/ebook#{@cX.off} - ( Within this major sub-directory, a sub-directory is made with the name of each document processed, into which output files - html, pdf, xml, plaintext etc. are placed (texinfo being an exception at present) ) - - #{@cX.green}sisu -C#{@cX.off} [#{@cX.green}--init=site#{@cX.off}] configure/initialise shared output directory files initialize shared output directory (config files such as css and dtd files are not updated if they already exist unless modifier is used). -C --init=site configure/initialise site more extensive than -C on its own, shared output directory files/force update, existing shared output config files such as css and dtd files are updated if this modifier is used. in a new markup document working directory should initialise the corresponding output directory, though SiSU will automatically do this, the first time it is run (for processing) in a given directory. - - There are additional details, ... this should get you started. - - See also - sisu --help directory - WOK - help_env - end - def directories - help_env - print <<-WOK - - the directory structure used by sisu is controlled by the configuration files #{@cX.blue}sisurc.yml#{@cX.off} - - there are separate directories for the following: - - (a) #{@cX.green}data directories#{@cX.off} - the directories in which you place the SiSU marked-up data files that are to be processed - there may be as many directories and files as you choose to have, - you are currently in: #{@cX.blue}#{Dir.pwd}#{@cX.off} - - (b) #{@cX.green}output directory#{@cX.off} - by default files in the data directory are output to - a sub-directory within the output directory (usually the web document directory), or to an sql database - of the same name as the stub or last portion of the data directory name - by way of example - you are currently in: #{@cX.blue}#{Dir.pwd}#{@cX.off} - the document output directory is set to: #{@cX.blue}#{@env.path.webserv}#{@cX.off} - documents from your current directory will be placed in: #{@cX.blue}#{@env.path.output}#{@cX.off} - - the final output is placed in subdirectories either as configured by default in the program or as modified by SiSU configuration files - subdirectories are created within the main output directory, based on the name of the data directory - subsubdirectories are created the sub-directory contained in the main output directory based on the name of the file - (subdirectories are created in this (output) sub-directory named after the data file) - for this reason it is a convention to give descriptive names to the data file. - The default output directory is #{@cX.green}~/sisu_www#{@cX.off} - The output directory is currently set to: - #{@cX.blue}#{@env.path.webserv}#{@cX.off} - Output files, are currently set to be produced in: - processed document output: #{@cX.blue}#{@env.path.output}#{@cX.off} - a document in the current directory #{@cX.blue}#{Dir.pwd}#{@cX.off} - will have its output placed in: #{@cX.blue}#{@env.path.output}/#{@output_stub}#{@cX.off} - - NB: the verbose flag v included in the generate command string, should - result in a list of output filenames together with their paths. - The flag U on its own (e.g. sisu -U gpl3.fsf.sst) should provide a list - of output files that could be generated together with their paths. - - (c) #{@cX.green}configuration files#{@cX.off} - SiSU program defaults are set within the program, and may be adjusted in the yml file #{@cX.blue}sisurc.yml#{@cX.off} which is searched for in the following paths, which are prioritized as listed (the first one found is loaded): -### - under the current SiSU markup data directory: #{@cX.blue}#{@env.path.pwd}/_sisu/sisurc.yml#{@cX.off} - under the home directory ~/.sisu: #{@cX.blue}#{@env.path.home}/.sisu/sisurc.yml#{@cX.off} - in the "/etc" directory: #{@cX.blue}#{@env.path.etc}/sisurc.yml#{@cX.off} - - (d) #{@cX.green}processing directories#{@cX.off} sisu creates a number of processing directories, - where these should be located can be modified in #{@cX.green}~/.sisu/sisurc.yml#{@cX.off} - work directories include the following: - root working directory #{@cX.blue}#{@env.processing_path.processing}#{@cX.off} - metaverse intermediate markup #{@cX.blue}#{@env.processing_path.dal}#{@cX.off} - tune html (for special html/navigation pages) #{@cX.blue}#{@env.processing_path.tune}#{@cX.off} - tex for latex and pdf #{@cX.blue}#{@env.processing_path.tex}#{@cX.off} - texinfo for texinfo and info files #{@cX.blue}#{@env.processing_path.texi}#{@cX.off} - - These files are usually used only for processing and removed. There is a maintenance flag to keep them. - - (e) #{@cX.green}images#{@cX.off} - there are a number of categories of images, - NB the document markup directory is initialised by issuing the command - sisu -C --init=site - this creates the output sub-directory, and makes necessary image links, and - copies images specific to the markup directory if there are any. - - general images for the sisu program that come with the package, - that are the defaults used by sisu, these are installed with the program - - images that the author wishes to include within documents, - these should be placed in a sub-directory - within the current document markup directory called #{@cX.green}_sisu/image#{@cX.off} - - if an instruction is given to process a remote document which contains - downloadable images, they are included in a sub-directory of the current - markup directory #{@cX.green}_sisu/sisu/image_external#{@cX.off} that is created - if necessary for the purpose. - - finally skins may specify/indicate other image directories. see sisu --help skin - any site images required by the skin instruction must be copied in to the - site image directory (it may be necessary to do manual configuration depending - on what you are trying to achieve). - - (f) #{@cX.green}program directories#{@cX.off} - sisu --help install - sisu ~ install - - See also - sisu --help path - WOK - help_env - end - def program_found?(program) - if program - rc=if SiSU_Env::InfoSettings.new.program?(program) - SiSU_Env::InfoSettings.new.program?(program) - else '' - end - if program =='rmagick' then program='identify' #rmagick is ruby lib uses imagemagick's identify - end - bin=if SiSU_Env::SystemCall.new.program_found?(program) - SiSU_Env::SystemCall.new.program_found?(program) - else 'false' - end - else bin,rc='false','false' - end - (program) \ - ? ("#{@cX.blue}#{program}#{@cX.off} bin: #{@cX.brown}#{bin}#{@cX.off} rc: #{@cX.brown}#{rc}#{@cX.off}") - : ("bin: #{@cX.brown}#{bin}#{@cX.off} rc: #{@cX.brown}#{rc}#{@cX.off}") - end - def sisu_version - version=SiSU_Env::InfoVersion.instance.get_version - rb_ver=SiSU_Env::InfoVersion.instance.rbversion - if version[:version] - opt_cmd=if defined? @color.cmd \ - and @color.cmd =~/[ck]/ - @color.cmd - else '-v' - end - SiSU_Screen::Ansi.new(opt_cmd,version[:project],version[:version],version[:date_stamp],version[:date],rb_ver).version - else puts 'SiSU version information not available' - end - end - def rhost - @ls=leading_spaces=' '*49 - @rhost=SiSU_Env::InfoRemoteHost.new.rhost - def r1 - (@rhost.r1) \ - ? @rhost.r1 + "\n" - : '' - end - def r2 - (@rhost.r2) \ - ? @ls + @rhost.r2 + "\n" - : '' - end - def r3 - (@rhost.r3) \ - ? @ls + @rhost.r3 + "\n" - : '' - end - def r4 - (@rhost.r4) \ - ? @ls + @rhost.r4 + "\n" - : '' - end - def r5 - (@rhost.r5) \ - ? @ls + @rhost.r5 + "\n" - : '' - end - def r6 - (@rhost.r6) \ - ? @ls + @rhost.r6 + "\n" - : '' - end - def note - msg='(remote settings user and host set in sisurc.yml under remote:)' - (@rhost.r1) \ - ? @ls + msg - : msg - end - self - end - def environment - cf_defaults=SiSU_Env::InfoProcessingFlag.new - sisu_version - x =<<-WOK - #{@cX.green}current and output directories#{@cX.off} - user: #{@cX.blue}#{@env.user}#{@cX.off} - home: #{@cX.blue}#{@env.path.home}#{@cX.off} - remote set [remote user]@[remote host]: #{@cX.blue}#{rhost.r1}#{rhost.r2}#{rhost.r3}#{rhost.r4}#{rhost.r5}#{rhost.r6}#{@cX.off}#{rhost.note} - locale (encoding, UTF-8 desired): #{@cX.blue}#{@env.locale}#{@cX.off} - current directory: #{@cX.blue}#{@env.path.pwd}#{@cX.off} - document output root directory set to: #{@cX.blue}#{@env.path.webserv}#{@cX.off} - documents from current directory placed in: #{@cX.blue}#{@env.path.output}#{@cX.off} - webrick url: #{@cX.blue}#{@env.url.webserv_base_cgi}#{@cX.off} - (to start webrick server 'sisu -W') - sqlite db for present directory: #{@cX.blue}sqlite #{@env.path.output}/sisu_sqlite.db#{@cX.off} - postgresql port set to: #{@cX.blue}#{@db.psql.port}#{@cX.off} - postgresql db for present directory: #{@cX.blue}#{@db.psql.db}#{@cX.off} - [first create manually if necessary: 'createdb #{@db.psql.db}'] - - [generated sqlite cgi search form]: #{@cX.blue}#{@env.url.webserv_base_cgi}/cgi-bin/sisu_sqlite.cgi#{@cX.off} - [generated postgresql cgi search form]: #{@cX.blue}#{@env.url.webserv_base_cgi}/cgi-bin/sisu_pgsql.cgi#{@cX.off} - (to generate 'sisu -F' or 'sisu -F webrick') - #{@cX.green}configuration files#{@cX.off} - sisurc.yml used: #{@cX.blue}#{@env.path.yamlrc}#{@cX.off} - configuration information search path: #{@cX.blue}#{@env.path.rc.join(', ')}#{@cX.off} - (directory also relevant for skins and images) - digest (md5 or sha256): #{@cX.blue}#{@env.digest.type}#{@cX.off} - papersize set (LaTeX/pdf): #{@cX.blue}#{@env.papersize}#{@cX.off} - (digest and papersize can be changed in sisurc.yml under default:) - #{@cX.green}intermediate processing#{@cX.off} - processing directory: #{@cX.blue}#{@env.processing_path.processing}#{@cX.off} - (to keep processing output, use -M flag) - #{@cX.green}programs selected for viewing output#{@cX.off} - text editor: #{@cX.blue}#{@env.program.text_editor}#{@cX.off} - web browser: #{@cX.blue}#{@env.program.web_browser}#{@cX.off} - console web browser: #{@cX.blue}#{@env.program.console_web_browser}#{@cX.off} - pdf viewer: #{@cX.blue}#{@env.program.pdf_viewer}#{@cX.off} - xml viewer: #{@cX.blue}#{@env.program.xml_editor}#{@cX.off} - odf viewer: #{@cX.blue}#{@env.program.odf_viewer}#{@cX.off} - epub viewer: #{@cX.blue}#{@env.program.epub_viewer}#{@cX.off} - (default selections can be changed in sisurc.yml under program_select:) - #{@cX.green}programs used if available#{@cX.off} - word count: #{program_found?(@env.program.wc)} - imagemagick/rmagick: #{program_found?(@env.program.rmagick)} - tidy: #{program_found?(@env.program.tidy)} - rexml: #{program_found?(@env.program.rexml)} - latex to pdf: #{program_found?(@env.program.pdflatex)} - postgresql: #{program_found?(@env.program.postgresql)} - sqlite: #{program_found?(@env.program.sqlite)} - (these can be turned off if unavailable in sisurc.yml under program_set:) - #{@cX.green}processing shortcut defaults set to:#{@cX.off} - color defaut set (on==true) #{@cX.blue}#{cf_defaults.color}#{@cX.off} - sisu -0 #{@cX.blue}#{cf_defaults.cf_0}#{@cX.off} [set as default] - sisu -1 #{@cX.blue}#{cf_defaults.cf_1}#{@cX.off} - sisu -2 #{@cX.blue}#{cf_defaults.cf_2}#{@cX.off} - sisu -3 #{@cX.blue}#{cf_defaults.cf_3}#{@cX.off} - sisu -4 #{@cX.blue}#{cf_defaults.cf_4}#{@cX.off} - sisu -5 #{@cX.blue}#{cf_defaults.cf_5}#{@cX.off} - (defaults may be changed in active sisurc.yml file under flag:) - #{@cX.green}special powers, risky operations set:#{@cX.off} - zap (delete output directories) #{@cX.blue}#{SiSU_Env::InfoSettings.new.permission?('zap')}#{@cX.off} - css copy (copy over css files) #{@cX.blue}#{SiSU_Env::InfoSettings.new.permission?('css_modify')}#{@cX.off} - (true/false defaults may be changed in active sisurc.yml file under permissions_set:) - -NOTE: for HELP type 'sisu --help', 'sisu --help [help request]', 'man sisu', (or see the system or online documentation) - WOK - print x - end - def dublin_core - print <<-WOK -@title: - -@subtitle: [is added to title for purposes of Dublin Core description] - -@creator: - -@type: - -@subject: - -@date: [ccyy-mm-dd] - -@date.created: - -@date.issued: - -@date.available: - -@date.valid: - -@date.modified: - -@source: - -@language: en - -@papersize: A4 - -@relation: - -@coverage: - -@rights: - - WOK - end - def headings - print <<-WOK -These are not required, a header is quicker to prepare if a documents structure can be defined by matching words or a regular expression, see headers). - -@structure: PART; CHAPTER; SECTION; ARTICLE; none; none; - -structure can be defined by a match words or regular expression (the regular expression is assumed to start at the beginning of a line of text i.e. ^) - -The following heading or level (structuring) defaults are available (for use instead of or together with @structure: header): - - A~ B~ C~ 1~ 2~ 3~ - -Heading tags take either of the forms above, ranging from 1-6 - -They appear at the beginning of the line on which a heading appears, -the number indicates the level of the heading with level 1 being a title, - -segments (in html output) are by default created on level 4 -(segmented text is split/segmented on level 4, and -assigned a file name automatically according to the title number, -unless you explicitly specify otherwise) - -A~ Document Title - -B~ Document Subtitle whatever it is - -C~ Part - -1~ Chapter - -2~ Heading - -3~ sub-heading - -Normal text would follow each heading level as appropriate, though it is most usual to start with ordinary writing beneath level 4 as it is at this level that segments are created. - -Automatic numbering of paragraphs is usually set to start at level 4 trough level 6 and takes the form 1. then 1.1 then 1.1.1 this being given as a Header tag 0~ There may be up to 6 levels in a document, - -If auto-numbering is on, then for html output the segments created (on level 4 headings) are automatically assigned the name of the title number. -However, you may indicate an alternative set of key/title words, with one of the following instructions: -4~filename This is a Section or Subject Heading - -If there is a strictly discernable word appearing at the beginning of the line in a document that identifies the level, -the words can be used to identify the levels in a header tag: -0~toc Part; Chapter; Section; Article; none; none -instead of providing individual heading tags - -sisu structure, notation, A,B,C,1,2,3 - - SiSU has in effect two sets of levels to be considered - - A-C pre-ordinary paragraphs /pre-substantive text, and - - 1-3 levels which are followed by ordinary text. - - This may be conceptualised as levels A,B,C, 1,2,3, and using such letter number notation, in effect: - - A must exist, optional B and C follow in the sequence - - 1 must exist, optional 2 and 3 follow in the sequence - - i.e. there are two independent heading level sequences A,B,C and 1,2,3 or using the standard notation 1,2,3 and 4,5,6 - -on the positive side: (a) the A,B,C,1,2,3 alternative makes explicit an aspect of structuring documents in SiSU that is not otherwise obvious to the newcomer (though it appears more complicated, is more in your face and likely to be understood fairly quickly); (b) the substantive text follows levels 1,2,3 and it is 'nice' to do most work in those levels - - WOK - end - def languages - lang=SiSU_i18n::Languages.new.language.table - lang.each_value do |lng| - if lng[:t] == lng[:n] - puts "#{lng[:c]}: #{lng[:t]}" - else - puts "#{lng[:c]}: #{lng[:t]} (#{lng[:n]})" - end - end - puts <<-WOK - - Multi-language Document File Naming and Directory Mapping - - A list of language codes and languages that may be available for most output formats. These are for the most part ISO 639/1 and where there is a departure it follows those made by po4a, and the languages supported will be limited (at this time) to those supported by polyglossia. (SiSU markup text is stored in Unicode so some output formats are served by this, for example, html and sql had no problem with Chinese, pdfs would be a problem as this is not (yet?) suported by xetex and polyglossia. SiSU parses left to right and would have problems with right to left languages.) - - If the same document exists in different language versions, a directory structure, or a filenaming convention may be followed. Using Spannish as the sample language code (es) [filename]~[language code].sst - - The simplest now is to place each document in a sub-directory which has the language code as a name, if this convention is used it is preferable that all files are placed by language in the appropriate language sub-directory ... e.g. - ./en/filename.sst - ./es/filename.sst - - Alternatively files may all be placed in the same directory with the language and named using a tilde and the language code as shown: - filename~es.sst - - within sisurc.yml under the heading - default: - language file: [at 1, 2 or 3] - - determines the output filenaming convention used, as follows: - - (1) [output directory path]/filename/es.index.html - - (2) [output directory path]/filename/index.es.html - - (3) [output directory path]/filename/index.html.es (which Apache for example can be configured to use to automatically serve each users preference) - - filename~fr.sst - filename~de.sst - - etc. would be placed in the same directory using the same convention as indeed would: - filename.sst - using the default convention mapping convention. - - Selecting this form of filename will overide other language settings including the language header within a document. - - WOK - end - def endnotes - print <<-WOK - -(1) Footnote/endnotes tags take a number of possible forms, the simplest being to embed an endnote within your text~{ this would appear as an endnote, and would have an automatically assigned number }~ Embedded endnotes~{this is an endnote}~ and at the end of the paragraph~{* an asterisk marked note }~ writing the endnote:~{another endnote}~ - - ------------------------------------------ -#{@cX.ruby}All you need to know about endnotes appears above this line...#{@cX.off} apart from the fact that you cannot mix endnote markup styles - -(2) The other ways of inserting an endnote involve placing a tag within the text as to where the endnote reference number should appear like so~^ and at the end of the paragraph writing the endnote:~^ - -^~ like so, this is an endnote - -^~ another endnote - - WOK - end - def tables - print <<-WOK - -#{@cX.green}table{ [number of columns] [column width %];[column width %]#{@cX.off} - -[table content, line breaks are important see example below] - -#{@cX.green}}table#{@cX.off} -#{@cX.grey}----#{@cX.off} -This is a sample table: ------------------------ - -#{@cX.green}table{ c3; 40; 30; 30;#{@cX.off} - -This is a table -this would become column two of row one -column three of row one is here - -And here begins another row -column two of row two -column three of row two, and so on - -#{@cX.green}}table#{@cX.off} - -there is an alternative way to markup tables, a sample document is provided in the file -#{@cX.green}sisu_output_overview.sst#{@cX.off} located in -#{@cX.green}/usr/share/doc/sisu#{@cX.off} or equivalent directory - -preformatted text ------------------ - -#{@cX.green}poem{#{@cX.off} - - [Text here] - -#{@cX.green}}poem#{@cX.off} -#{@cX.grey}----#{@cX.off} - -#{@cX.green}block{#{@cX.off} - - [Text here] - -#{@cX.green}}block#{@cX.off} -#{@cX.grey}----#{@cX.off} - -#{@cX.green}group{#{@cX.off} - - [Text here] - -#{@cX.green}}group#{@cX.off} -#{@cX.grey}----#{@cX.off} - -#{@cX.green}code{#{@cX.off} - - [Text here] - -#{@cX.green}}code#{@cX.off} - - WOK - end - def modules - print <<-WOK - - #{@cX.ruby}IGNORE#{@cX.off} - - WOK - end - def install #% system configuration - print <<-WOK - #{@cX.green}Install SiSU#{@cX.off} - - Presumably if you are reading this interactively you have a copy of SiSU already installed, nevertheless here are a few notes. - - SiSU does require setup, the executable file #{@cX.blue}sisu#{@cX.off} is placed in #{@cX.blue}#{Config::CONFIG['bindir']}#{@cX.off} or #{@cX.blue}#{Config::CONFIG['sitelibdir']}#{@cX.off} and the library files, in #{@cX.blue}#{Config::CONFIG['rubylibdir']}/#{SiSU_lib}#{@cX.off} - or in #{@cX.blue}#{Config::CONFIG['sitelibdir']}/#{SiSU_lib}#{@cX.off} - - SiSU comes with a number of installers, including #{@cX.blue}setup.rb#{@cX.off}, #{@cX.blue}install#{@cX.off} and a #{@cX.blue}Rantfile#{@cX.off} if rant is installed on your system, you may need to be root to install sisu on your system. After unpacking the tarball, in the top directory of the tarball which contains the named files type, one of: - sudo ./sisu-install base - sudo ./sisu-install setup - if that does not work try - sudo ruby ./sisu-install setup - if rant is installed on your system you may instead run: - sudo rant base - - for further options: - ./sisu-install -T - - SiSU is pre-packaged for some GNU/Linux distributions such as Debian. - - For information on download and installation, see #{@cX.blue}http://www.jus.uio.no/sisu/SiSU/download#{@cX.off} - - For post installation help it is best you refer to '#{@cX.blue}man 8 sisu#{@cX.off}' - - Host - host: #{@cX.blue}#{@env.hostname}#{@cX.off} - arch: #{@cX.blue}#{@env.arch}#{@cX.off} - - Directories for installation - bin: #{@cX.blue}#{Config::CONFIG['bindir']}#{@cX.off} or #{@cX.blue}#{Config::CONFIG['sitelibdir']}#{@cX.off} - lib (site-ruby): #{@cX.blue}#{Config::CONFIG['rubylibdir']}/#{SiSU_lib}#{@cX.off} or #{@cX.blue}#{Config::CONFIG['sitelibdir']}/#{SiSU_lib}#{@cX.off} - conf [etc]: #{@cX.blue}#{@env.path.etc}/sisu#{@cX.off} - data (document samples, images, README): #{@cX.blue}#{@env.path.sample_data}#{@cX.off} - processing: #{@cX.blue}#{@env.processing_path.processing}#{@cX.off} - output www: #{@cX.blue}#{@env.path.output}#{@cX.off} - - Output files, are currently set to be produced in: - processed document output: #{@cX.blue}#{@env.path.output}#{@cX.off} - a document in the current directory #{@cX.blue}#{Dir.pwd}#{@cX.off} - will have its output placed in: #{@cX.blue}#{@env.path.output}/#{@output_stub}#{@cX.off} - - Install any additional programs of interest (that SiSU makes use of, that are not already on your system) - - Programs SiSU makes use of include: - LaTeX - texinfo - pdfetex aka. pdflatex - sqlite - postgresql - - Again, refer to '#{@cX.blue}man 8 sisu#{@cX.off}' - - For additional help on using SiSU once installed type: - - sisu --help - - WOK - end - def setup - print <<-WOK - - #{@cX.green}configuration files#{@cX.off} - sisurc.yml used: - #{@cX.blue}#{@env.path.yamlrc}#{@cX.off} - configuration information search path: - #{@cX.blue}#{@env.path.rc.join(', ')}#{@cX.off} - (directory also relevant for skins and images) - - to initialise the mapped output directory, from within the markup document directory type: - #{@cX.blue}sisu -CC#{@cX.off} - - for information on your current sisu configuration settings, type: - #{@cX.blue}sisu --help env#{@cX.off} - or - #{@cX.blue}sisu -V#{@cX.off} - - see also - #{@cX.blue}man 8 sisu#{@cX.off} - and - #{@cX.blue}http://www.jus.uio.no/sisu/SiSU#{@cX.off} - WOK - end - def termsheet - print <<-WOK - - #{@cX.green}sisu --termsheet [termsheetname].termsheet.rb#{@cX.off} - will produce the collection of documents associated with [termsheetname.termsheet.rb] - - #{@cX.green}sisu -t [termsheetname].termsheet.rb#{@cX.off} - will produce the collection of documents associated with [termsheetname.termsheet.rb] - - #{@cX.green}termsheet.rb#{@cX.off} files: - (i) are named after the facility - (ii) contain instructions as to which standard forms to use for the agreement (standard_form.rb) - there may be several, eg. the termsheet, and the resulting: - main agreement; collection account charge; and deed of assignment - (iii) contain the variable terms of the agreement, borrower, interest etc. - - for a new loan agreement fill out a new termsheet specifying - what standard forms are to be used, - and the terms of the agreement. - - #{@cX.green}standard_form.rb#{@cX.off} files: - contain the standard terms of the agreement - there is a standard form for each variation of agreement - (so eg. there are as many facility agreements as there are variations in standard facility) - these may be prepared for any agreement that is to be reused. - (preparation takes the form of formating and - placing variable holders for the variables that are to be provided by the termsheet.rb file) - - it is necessary to purge the directory ~facilityData when old files are removed - - WOK - end - def help_commands - print <<-WOK - - also see: - sisu --help commands - man sisu - WOK - end - def help_env - print <<-WOK - - for sisu environment information see: - sisu --help env - WOK - end - def help_general - help_env - help_commands - end - def help_markup - print <<-WOK - - for help with sisu markup see: - sisu --help markup - sisu --help header - sisu --help structure [sisu --help heading] - - to check markup version in file: - sisu --identify [filename].sst - - for brief descriptive summary of markup history - sisu --query-history - - for markup: - sisu --help example - - sample marked up documents are provided in directory: - #{@cX.green}/usr/share/doc/sisu/markup-samples#{@cX.off} - and online - #{@cX.green}www.jus.uio.no/sisu#{@cX.off} - WOK - end - def convert - print <<-WOK - - for information on the markup version used within a sisu markup file: - sisu --inspect [filename] - - convert an sst file with footnotes following text to (preferred) inline footnotes - sisu --convert-footnotes [filename/wildcard] - - to convert from sst to simple xml representations (sax, dom and node): - sisu --to-sax [filename/wildcard] - sisu --to-sxs [filename/wildcard] - - sisu --to-dom [filename/wildcard] - sisu --to-sxd [filename/wildcard] - - sisu --to-node [filename/wildcard] - sisu --to-sxn [filename/wildcard] - - to convert to sst from simple xml representations (sax, dom and node): - sisu --from-xml2sst [filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]] - sisu --from-sxml [filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]] - - to attempt to convert a kdissert (.kdi) file to sisu markup: - sisu --from-kdi [kdissert filename] - (very basic and experimental) - WOK - end - def dal - print <<-WOK - - sisu --dal [filename/wildcard] creates the metaverse, used by all other modules for downstream processing - sisu -m [filename/wildcard] creates the metaverse, used by all other modules for downstream processing - WOK - help_commands - end - def utf8 - print <<-WOK - - documents prepared for sisu processing should be stored in utf8 - WOK - end - def plaintext - print <<-WOK - - sisu --txt [filename/wildcard] plaintext with Unix linefeeds (footnotes follow paragraphs) - sisu -t [filename/wildcard] plaintext with Unix linefeeds (footnotes follow paragraphs) - - WOK - help_commands - end - def html - print <<-WOK - - sisu --html [filename/wildcard] html document type suffixes included - sisu -h [filename/wildcard] html document type suffixes included - - WOK - help_commands - end - def xhtml - print <<-WOK - - sisu --xhtml [filename/wildcard] xhtml document - sisu -b [filename/wildcard] xhtml document - WOK - help_commands - end - def xml - print <<-WOK - - sisu --xml-sax [filename/wildcard] xml document (sax type parsing) - sisu -x [filename/wildcard] xml document (sax type parsing) - - sisu --xml-dom [filename/wildcard] xml document (dom type parsing) - sisu -X [filename/wildcard] xml document (dom type parsing) - - sisu --odt [filename/wildcard] odt document, (odf open document format) - sisu -o [filename/wildcard] odt document, (odf open document format) - - sisu --epub [filename/wildcard] odt document, (epub document) - sisu -e [filename/wildcard] odt document, (epub document) - WOK - help_commands - end - def odf - print <<-WOK - - sisu --odt [filename/wildcard] odt document, (odf open document format) - - sisu -o [filename/wildcard] odt document, (odf open document format) - WOK - help_commands - end - def epub - print <<-WOK - - sisu --epub [filename/wildcard] epub document, (open format for e-books) - sisu -e [filename/wildcard] epub document, (open format for e-books) - WOK - help_commands - end - def php - print <<-WOK - - not supported - [php output has been removed] - WOK - help_commands - end - def pdf - print <<-WOK - - sisu --pdf [filename/wildcard] produces pdf files from LaTeX output - sisu -p [filename/wildcard] produces pdf files from LaTeX output - WOK - help_commands - end - def latex - print <<-WOK - - sisu --pdf [filename/wildcard] produces pdf files from LaTeX output - sisu -p [filename/wildcard] produces pdf files from LaTeX output - WOK - help_commands - end - def texinfo - print <<-WOK - - sisu --texinfo [filename] produces texinfo and info files - sisu -I [filename] produces texinfo and info files - - info and texinfo files are currently left in a separate work/output directory... have not decided what to do with them - - on my system info works fine point at file with info command - - pinfo, requires you to be within the work/output directory - cd [work/output directory] - - and then to point at the file using - pinfo ./[filename] - WOK - help_commands - end - def lout - print <<-WOK - - sisu -l [filename/wildcard] - - not currently supported, revisit someday? - WOK - help_commands - end - def concordance - print <<-WOK - - sisu --concordance starts the sisu webrick server, default port 8081 - sisu --wordmap starts the sisu webrick server, default port 8081 - sisu -W starts the sisu webrick server, default port 8081 - WOK - help_commands - end - def help_search - print <<-WOK - - SiSU searches, - depending on how you wish to implement search, - the following may bre of interest: - sisu --help sql - sisu --help searchform (or 'sisu --help cgi') - sisu --help hyperestraier (or 'sisu --help est') - sisu --help webrick - WOK - end - def cgi - print <<-WOK - - sisu --sample-search-form generates a sample search form - sisu -F generates a sample search form - - sisu -F --webserv=webrick generates a sample search form for use with the webrick server - sisu -Fv as above, and provides some information on setting up hyperestraier - sisu -W starts the webrick server - - the generated search form must be copied to the webserver directory as instructed - WOK - help_search - help_general - end - def sql - print <<-WOK - - Mappings to two databases are provided by default, - postgresql (--pg or -D) and sqlite (--sqlite or -d), - the same modifier commands are used within sisu to construct and populate - databases the examples here will use --sqlite - - sisu --sqlite --createdb creates database where no database existed before - sisu --sqlite --create creates database tables where no database tables existed before - sisu --sqlite --dropall destroys database (including all its content)!! - sisu --sqlite --recreate destroys existing database and builds a new empty database structure - - sisu --sqlite --import [filename/wildcard] populates database with the contents of the file - sisu --sqlite --update [filename/wildcard] updates file contents in database - - sisu --sample-search-form --webserv=webrick builds a cgi web search frontend for the database created - - Postgresql - user: #{@cX.blue}#{@db.psql.user}#{@cX.off} - current db set: #{@cX.blue}#{@db.psql.db}#{@cX.off} - port: #{@cX.blue}#{@db.psql.port}#{@cX.off} - dbi connect: #{@cX.blue}#{@db.psql.dbi}#{@cX.off} - - sqlite - current db set: #{@cX.blue}#{@db.sqlite.db}#{@cX.off} - dbi connect #{@cX.blue}#{@db.sqlite.dbi} #{@cX.off} - - Note on databases built - 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 #{@cX.blue}#{@env.path.home}/ebook#{@cX.off} the database #{@cX.blue}#{Db[:name_prefix]}ebook#{@cX.off} is used. [otherwise a manual mapping for the collection is necessary] - WOK - help_search - help_general - end - def webrick - print <<-WOK - - sisu --webrick starts the sisu webrick server, default port 8081 - sisu -W starts the sisu webrick server, default port 8081 - WOK - help_commands - end - def hyperestraier - out_dir='(' + `ls #{@env.path.webserv}`.split("\n").join('|') + ')' - print <<-WOK - Not tested recently, not up-to-date - - NOTE: The examples that follow assume that sisu output is placed in the directory - /home/ralph/sisu_www - - (A) to generate the index - within the webserver directory to be indexed: - #{@cX.orange}estcmd gather -sd [index name] [directory path to index]#{@cX.off} - the following are examples that will need to be tailored according to your needs: - #{@cX.green} - cd #{@env.path.webserv} - estcmd gather -sd casket #{@env.path.webserv} - #{@cX.off} - you may use the 'find' command together with 'egrep' to limit - indexing to particular document collection directories within - the web server directory:#{@cX.green} - - find /home/ralph/sisu_www -type f | egrep '#{@env.path.output}/.+?\.html$' |estcmd gather -sd casket - #{@cX.off} - - check which directories in the webserver/output directory #{@cX.green}#{@env.path.webserv}#{@cX.off} - you wish to include in the search index, these appear to be: - - #{@env.path.webserv}/#{@cX.green}#{out_dir}#{@cX.off} - - 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 'doc.html' and 'concordance.html', as these - duplicate information held in other html output e.g. #{@cX.green} - - find /home/ralph/sisu_www -type f | egrep '/sisu_www/(sisu|bookmarks)/.+?\.html$' | egrep -v '(doc|concordance)\.html$' |estcmd gather -sd casket - #{@cX.off} - - from your current document preparation/markup directory, you would construct a rune along the following lines: #{@cX.green} - - find /home/ralph/sisu_www -type f | egrep '#{@env.path.webserv}/([specify first directory for inclusion]|[specify second directory for inclusion]|[another directory for inclusion? ...])/.+?\.html$' | egrep -v '(doc|concordance)\.html$' |estcmd gather -sd #{@env.path.webserv}/casket - #{@cX.off} - - (B) to set up the search form - (i) copy #{@cX.green}estseek.cgi#{@cX.off} to your cgi directory and set file permissions to 755: #{@cX.green} - - sudo cp -vi /usr/lib/estraier/estseek.cgi /usr/lib/cgi-bin - sudo chmod -v 755 /usr/lib/cgi-bin/estseek.cgi - sudo cp -v /usr/share/hyperestraier/estseek.* /usr/lib/cgi-bin #{@cX.off} - [see estraier documentation for paths] - - (ii) edit #{@cX.green}estseek.conf#{@cX.off}, with attention to the lines starting 'indexname:' and 'replace:': #{@cX.green} - - indexname: #{@env.path.webserv}/casket - replace: ^file://#{@env.path.webserv}{{!}}#{@env.url.webserv_host_base} - replace: /index\.html?${{!}}/ #{@cX.off} - - (C) to test using webrick, start webrick: #{@cX.green} - sisu -W #{@cX.off} - - and try open the url: #{@cX.blue} - #{@env.url.webserv_host_base}/cgi-bin/estseek.cgi #{@cX.off} - - WOK - end - def yaml - print <<-WOK - Yaml sisurc files may be used to configure sisu, these are searched for in the following locations: - - under the current SiSU markup data directory: #{@cX.blue}#{Dir.pwd}/_sisu/sisurc.yml#{@cX.off} - under the home directory ~/.sisu: #{@cX.blue}#{@env.path.home}/.sisu/sisurc.yml#{@cX.off} - in the "/etc" directory: #{@cX.blue}#{@env.path.etc}/sisurc.yml#{@cX.off} - - The Yaml files #{@cX.blue}promo.yml#{@cX.off} and #{@cX.blue}list.yml#{@cX.off} may be used to build a minor right pane in html, they may be placed in the following locations: - - under the current SiSU markup data directory: #{@cX.blue}#{Dir.pwd}/_sisu/skin/yml/#{@cX.off} - under the home directory ~/.sisu: #{@cX.blue}#{@env.path.home}/.sisu/skin/yml/#{@cX.off} - in the "/etc" directory: #{@cX.blue}#{@env.path.etc}/skin/yml/#{@cX.off} - - these may be called by the sisurc.yml, skins for document, directory or site, or from individual document headers in the header @@promo: [a commented out example header may be found in document sample: free_as_in_freedom.richard_stallman_cru‐ sade_for_free_software.sam_williams.sst, it calls for the specified lists in list.yml, which in turn calls the widgets named in promo.yml which are used to build content in the right pane of html output] - - WOK - end - def sitemap - print <<-WOK - - SiSU sitemaps, - an experimental feature (following g,y,m announcement to use them this week) - sisu -Y [filename/wildcard] - it may be necessary run -m first (generate the the metaverse) - sisu -mY [filename/wildcard] - - to generate/update the index of sitemaps - sisu --sitemaps - WOK - end - def license - - print <<-WOK - - * License: GPL 3 or later: - - SiSU, a framework for document structuring, publishing and search - - Copyright (C) 1997 - 2013 Ralph Amissah - - This program is free software: you can redistribute it and/or modify it - under the terms of the GNU General Public License as published by the Free - Software Foundation, either version 3 of the License, or (at your option) - any later version. - - This program is distributed in the hope that it will be useful, but WITHOUT - ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or - FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for - more details. - - You should have received a copy of the GNU General Public License along with - this program. If not, see <#{@cX.blue}http://www.gnu.org/licenses/#{@cX.off}>. - - If you have Internet connection, the latest version of the GPL should be - available at these locations: - <#{@cX.blue}http://www.fsf.org/licenses/gpl.html#{@cX.off}> - <#{@cX.blue}http://www.gnu.org/licenses/gpl.html#{@cX.off}> - - * SiSU uses: - * Standard SiSU markup syntax, - * Standard SiSU meta-markup syntax, and the - * Standard SiSU object citation numbering and system - - * Hompages: - <#{@cX.blue}http://www.sisudoc.org#{@cX.off}> - <#{@cX.blue}http://www.jus.uio.no/sisu#{@cX.off}> - - * Download: - <#{@cX.blue}http://sources.sisudoc.org#{@cX.off}> - <#{@cX.blue}http://www.jus.uio.no/sisu/en/html/SiSU/download.html#{@cX.off}> - - Ralph Amissah - <#{@cX.blue}ralph@amissah.com#{@cX.off}> - <#{@cX.blue}ralph.amissah@gmail.com#{@cX.off}> - - WOK - end - def standards - print <<-WOK - - * SiSU uses: - * Standard SiSU markup syntax, - * Standard SiSU meta-markup syntax, and the - * Standard SiSU object citation numbering and system - -Copyright (C) Ralph Amissah 1997, current 2013. -All Rights Reserved. - -Information on these may be obtained from: - <#{@cX.blue}http://sisudoc.org#{@cX.off}> - -More information to be provided later. - -* however note also the License section - -* Ralph Amissah ralph@amissah.com - Ralph Amissah ralph.amissah@gmail.com - - WOK - end - def conversion - print <<-WOK -sisu_convert does the initial conversion from a couple of file formats to SiSU file format, currently only html and word97 - #{@cX.cyan}sisu_convert#{@cX.off} [keyword] - sisu [keyword] - #{@cX.green}--html#{@cX.off} convert from html - ------------------------------------------ - Preparing Documents for SiSU - #{@cX.green}--word97#{@cX.off} sisu --help markup (an incomplete overview) - WOK - end - def external_programs - puts <<-WOK - - external ruby programs - - external programs - #{@cX.cyan}pdf output - tex/latex#{@cX.off} - #{@cX.orange}required#{@cX.off} - tex-base/latex - pdfetex aka. pdflatex - #{@cX.brown}suggested/recommended#{@cX.off} - #{@cX.cyan}db/sql output#{@cX.off} - #{@cX.orange}required#{@cX.off} - postgresql - #{@cX.brown}suggested/recommended#{@cX.off} - sqlite - #{@cX.cyan}xml/xhtml/html output#{@cX.off} - #{@cX.orange}required#{@cX.off} - #{@cX.brown}suggested/recommended#{@cX.off} - tidy (xml, xhtml well formed check) - trang (relaxng, rnc to dtd conversion) - WOK - end - def scratch - print <<-WOK -Types of tag, - -then there are various tags which occur within the document. -Structural tags, which consist of: - heading tags that identify headings within text, and; - footnote/endnote tags ... - -Markup instructions: giving information as to what is to be done to the presentation of the text - -Markup tags - -These have been kept to a minimum. A number of text html markup tags can be used <b>to bold</b> <i>to indent</i> <sup>for superscript</sup> <sub>for subscript text</sub> - -_1 at the beginning of a line indents the paragraph - -_2 at the beginning of a line double indents the paragraph - -Others include - -Other things to note: - -By default paragraphs are automatically numbered... and is the same across all output formats -This makes citation a lot easier... regardless of the form of output that is being looked at -It also permits the building of various addons, like the concordance feature which identifies each word and the paragraphs in which the word appears with links to the paragraph... - -Urls are automatically turned to live links in the html and pdf files created... - WOK - end - end -end -__END__ - diff --git a/lib/sisu/v4/hub.rb b/lib/sisu/v4/hub.rb index 0691ff37..2873c2cf 100644 --- a/lib/sisu/v4/hub.rb +++ b/lib/sisu/v4/hub.rb @@ -70,8 +70,6 @@ module SiSU include SiSU_Param require_relative 'defaults' # defaults.rb include SiSU_Viz - require_relative 'help' # help.rb - include SiSU_Help require_relative 'utils' # utils.rb require 'uri' class HubMaster @@ -208,8 +206,8 @@ module SiSU require_relative 'remote' # remote.rb SiSU_Remote::Put.new(@opt).scp_base_all end - def cgi # -F - require_relative 'cgi' # cgi.rb + def cgi # -F + require_relative 'cgi' # cgi.rb SiSU_CGI::SearchSQL.new(@opt).read end def termsheet # -t @@ -372,10 +370,10 @@ module SiSU end def do_loop_files_on_given_option_pre begin - if @opt.act[:zap][:set]==:on #% --zap, -Z + if @opt.act[:zap][:set]==:on #% --zap, -Z OptionLoopFiles.new(@opt).loop_files_on_given_option do require_relative 'zap' - SiSU_Zap::Source.new(@opt).read # -Z zap.rb + SiSU_Zap::Source.new(@opt).read # -Z zap.rb end end ensure @@ -423,8 +421,8 @@ module SiSU end if (@opt.act[:sisupod][:set]==:on \ || @opt.act[:share_source][:set]==:on) \ - and @opt.act[:manifest][:set]==:on #% --manifest, -y - require_relative 'manifest' # -y manifest.rb + and @opt.act[:manifest][:set]==:on #% --manifest, -y + require_relative 'manifest' # -y manifest.rb begin ensure OptionLoopFiles.new(@opt).loop_files_on_given_option_bundle do @@ -455,7 +453,6 @@ module SiSU end end if @opt.cmd =~/T/ #% -T termsheet/standard form - SiSU_Help::Help.new('termsheet').help_request @opt.files.each do |fns| if FileTest.file?(fns) @opt.fns=fns @@ -519,10 +516,7 @@ module SiSU @cX=SiSU_Screen::Ansi.new(@opt.cmd).cX flag=SiSU_Env::InfoProcessingFlag.new if @opt.act[:version_info][:set]==:on #% version information - SiSU_Help::Help.new('env',@opt).sisu_version - end - if @opt.act[:license][:set]==:on #% license information - SiSU_Help::Help.new('license',@opt).help_request + SiSU_Env::InfoAbout.new(@opt).sisu_version end if @opt.act[:dal][:set]==:on \ or @opt.act[:maintenance][:set]==:on #% --maintenance, -m for -C @@ -698,7 +692,7 @@ module SiSU end elsif action_on_file_ == :true \ and @opt.files.length == 0 - STDERR.puts %{requested action requires valid sisu markup file filename (.sst .ssm) or wildcard (that includes a valid filame)} + STDERR.puts %{requested action requires valid sisu markup file [filename (.sst .ssm)] or wildcard (that includes a valid filename)} puts SiSU_Utils::CodeMarker.new(__LINE__,__FILE__).set(:fuchsia) if @opt.cmd =~/[MV]/ end elsif @opt.mod.inspect =~/--query/ @@ -707,13 +701,6 @@ module SiSU elsif @opt.mod.inspect =~/--identify/ require_relative 'sst_identify_markup' # sst_identify_markup.rb markup_version=SiSU_Markup::MarkupIdentify.new(@opt).markup_version? - elsif @opt.mod.inspect =~/--about/ #% help instructions - if @opt.mod.inspect =~/--about/ \ - and not @opt.what.empty? - SiSU_Help::Help.new(@opt.what,'color_off').help_request - else - SiSU_Help::Help.new('list','color_off').help_request - end elsif @opt.mod.inspect =~/--sitemaps/ #% sitemaps require_relative 'sitemaps' # sitemaps.rb SiSU_Sitemaps::Source.new(@opt).read @@ -721,19 +708,9 @@ module SiSU require_relative 'remote' # remote.rb SiSU_Remote::Put.new(@opt).rsync_sitemaps end - else #% help instructions - unless @opt.mod.inspect =~/--convert|--to|--from|--harvest/ - if @opt.mod.inspect =~/--help/ \ - and not @opt.what.empty? - SiSU_Help::Help.new(@opt.what).help_request - elsif @opt.mod.inspect =~/--help/ - SiSU_Help::Help.new('list').help_request - else - SiSU_Help::Help.new('env',@opt).sisu_version - tell=SiSU_Screen::Ansi.new(''," for HELP type:\n\tsisu --help [help request]\n\tman sisu\n or see the system or online documentation on SiSU:\n #{Config::CONFIG['datadir']}/doc/sisu/\n <http://www.jus.uio.no/sisu/>\n <http://sisudoc.org/>") - tell.puts_grey - end - end + else #% sisu help refer to man pages + SiSU_Env::InfoAbout.new(@opt).sisu_version + SiSU_Env::InfoAbout.new(@opt).sisu_about end @opt.files.each do |fns| if FileTest.file?(fns) diff --git a/lib/sisu/v4/param.rb b/lib/sisu/v4/param.rb index b8e582eb..cc9f7018 100644 --- a/lib/sisu/v4/param.rb +++ b/lib/sisu/v4/param.rb @@ -66,8 +66,6 @@ module SiSU_Param include SiSU_Env require_relative 'param_make' # param_make.rb require_relative 'param_identify_markup' # param_identify_markup.rb - require_relative 'help' # help.rb - include SiSU_Help @@date=SiSU_Env::InfoDate.new @@proc=@@filename_txt=@@filename_texinfo=@@filename_lout_portrait=@@filename_lout_landscape=@@filename_html_scroll=@@filename_html_index=@@filename_html_segtoc=@@filename_semantic=@@filename_rss=@@newfile=@@drr=nil @doc={ initialise: nil, markup: '', lnks: '', stmp: '', req: {} } @@ -830,14 +828,14 @@ module SiSU_Param @doc={ lv: [] } @doc[:fns],@doc[:fnb],@doc[:scr_suffix]='','','' @@publisher='SiSU scribe' - attr_accessor :make,:env,:path,:file,:fn,:fns,:fno,:fnb,:fnn,:fnt,:fnl,:flv,:fnz,:fnstex,:ocn,:sfx_src,:pdf,:file_type,:dir_out,:dir_tex,:dir_lout,:txt_path,:sisu,:sisu_version,:ruby_version,:title,:subtitle,:full_title,:html_title,:subtitle_tex,:creator,:classify,:author_home,:author,:author_title,:author_nationality,:authors,:authorship,:translator,:illustrator,:prepared_by,:digitized_by,:subject,:description,:publisher,:current_publisher,:contributor,:date,:date_created,:date_issued,:date_available,:date_valid,:date_modified,:date_translated,:date_added_to_site,:date_scheme,:date_created_scheme,:date_issued_scheme,:date_available_scheme,:date_valid_scheme,:date_modified_scheme,:type,:format,:identifier,:source,:language,:language_original,:relation,:coverage,:rights,:keywords,:comments,:abstract,:cls_loc,:cls_dewey,:cls_pg,:cls_isbn,:papersize,:papersize_array,:toc,:lv1,:lv2,:lv3,:lv4,:lv5,:lv6,:lvs,:pagenew,:pagebreak,:pageline,:num_top,:bold_match_list,:italics_match_list,:substitution_match_list,:emphasis_set_to,:toc_lev_limit,:flag_endnotes,:flag_auto_endnotes,:flag_separate_endnotes,:flag_separate_endnotes_make,:markup,:markup_instruction,:markup_version,:markup_declared,:flag_tables,:vocabulary,:doc_css,:yaml,:lnk,:links,:prefix_a,:prefix_b,:suffix,:information,:contact,:icon,:image,:ad_url,:ad_png,:ad_alt,:ad_began,:flag_promo,:promo,:ad_home,:stmp,:stmpd,:sc_filename,:sc_number,:sc_date,:sc_time,:sc_info,:yamladdr,:locale,:wc_lines,:wc_words,:wc_bytes,:file_encoding,:filesize,:user,:home,:hostname,:pwd,:firstseg,:programs,:author_copymark,:i18n,:lang,:lang_code_insert,:en,:notes,:dgst,:generated,:tags,:tag_array,:concord_make,:seg_names,:seg_autoname_safe,:set_header_title,:set_heading_top,:set_heading_seg,:heading_seg_first,:heading_seg_first_flag,:base_program,:ec,:opt,:sem_tag,:book_idx,:topic_register,:topic_register_array,:original,:writing_focus,:audio,:daisy,:home_button_image,:home_button_links,:footer_links,:cover_image,:man_section + attr_accessor :make,:env,:path,:file,:fn,:fns,:fno,:fnb,:fnn,:fnt,:fnl,:flv,:fnz,:fnstex,:ocn,:sfx_src,:pdf,:file_type,:dir_out,:dir_tex,:dir_lout,:txt_path,:sisu,:sisu_version,:ruby_version,:title,:subtitle,:full_title,:html_title,:subtitle_tex,:creator,:classify,:author_home,:author,:author_title,:author_nationality,:authors,:authorship,:translator,:illustrator,:prepared_by,:digitized_by,:subject,:description,:publisher,:current_publisher,:contributor,:date,:date_created,:date_issued,:date_available,:date_valid,:date_modified,:date_translated,:date_added_to_site,:date_scheme,:date_created_scheme,:date_issued_scheme,:date_available_scheme,:date_valid_scheme,:date_modified_scheme,:type,:format,:identifier,:source,:language,:language_original,:relation,:coverage,:rights,:keywords,:comments,:abstract,:cls_loc,:cls_dewey,:cls_pg,:cls_isbn,:papersize,:papersize_array,:toc,:lv1,:lv2,:lv3,:lv4,:lv5,:lv6,:lvs,:pagenew,:pagebreak,:pageline,:num_top,:bold_match_list,:italics_match_list,:substitution_match_list,:emphasis_set_to,:toc_lev_limit,:flag_endnotes,:flag_auto_endnotes,:flag_separate_endnotes,:flag_separate_endnotes_make,:markup,:markup_instruction,:flag_tables,:vocabulary,:doc_css,:yaml,:lnk,:links,:prefix_a,:prefix_b,:suffix,:information,:contact,:icon,:image,:ad_url,:ad_png,:ad_alt,:ad_began,:flag_promo,:promo,:ad_home,:stmp,:stmpd,:sc_filename,:sc_number,:sc_date,:sc_time,:sc_info,:yamladdr,:locale,:wc_lines,:wc_words,:wc_bytes,:file_encoding,:filesize,:user,:home,:hostname,:pwd,:firstseg,:programs,:author_copymark,:i18n,:lang,:lang_code_insert,:en,:notes,:dgst,:generated,:tags,:tag_array,:concord_make,:seg_names,:seg_autoname_safe,:set_header_title,:set_heading_top,:set_heading_seg,:heading_seg_first,:heading_seg_first_flag,:base_program,:ec,:opt,:sem_tag,:book_idx,:topic_register,:topic_register_array,:original,:writing_focus,:audio,:daisy,:home_button_image,:home_button_links,:footer_links,:cover_image,:man_section def initialize(fns_array,opt) @env=@path,@file=@fn=@fns=@fno=@fnb=@fnn=@fnt=@fnl=@flv=@fnz=@fnstex=@ocn=@sfx_src=@pdf=@file_type=@dir_out=@dir_tex=@dir_lout=@txt_path=@make=@flag_endnotes=@flag_auto_endnotes=@flag_separate_endnotes=@flag_separate_endnotes_make=@sisu=@sisu_version=@ruby_version=@title=@subtitle=@full_title=@html_title=@subtitle_tex=@creator=@classify=@author_home=@author=@author_title=@author_nationality=@translator=@illustrator=@prepared_by=@digitized_by=@subject=@description=@publisher=@current_publisher=@contributor=@date=@date_created=@date_issued=@date_available=@date_valid=@date_modified=@date_translated=@date_added_to_site=@date_scheme=@date_created_scheme=@date_issued_scheme=@date_available_scheme=@date_valid_scheme=@date_modified_scheme=@type=@format=@identifier=@source=@language=@language_original=@relation=@coverage=@rights=@keywords=@comments=@abstract=@cls_loc=@cls_dewey=@cls_pg=@cls_isbn=@papersize=@toc=@lv1=@lv2=@lv3=@lv4=@lv5=@lv6=@pagenew=@pagebreak=@pageline=@num_top=@bold_match_list=@italics_match_list=@substitution_match_list=@emphasis_set_to=@toc_lev_limit=@flag_tables=@vocabulary=@doc_css=@yaml=@lnk=@links=@prefix_a=@prefix_b=@suffix=@information=@contact=@icon=@ad_url=@ad_png=@ad_alt=@ad_began=@promo=@ad_home=@stmp=@stmpd=@sc_filename=@sc_number=@sc_date=@sc_time=@sc_info=@yamladdr=@locale=@wc_lines=@wc_words=@wc_bytes=@file_encoding=@filesize=@firstseg=@programs=@author_copymark=@i18n=@lang=@lang_code_insert=@en=@notes=@dgst=@generated=@heading_seg_first=@base_program=@topic_register=@original=@writing_focus=@audio=@home_button_image=@home_button_links=@cover_image=@man_section=nil @data,@path,@fns,@fno,@opt=fns_array,opt.pth,opt.fns,opt.fno,opt #@data used as data @flag_tables,@set_header_title,@set_heading_top,@set_heading_seg,@heading_seg_first_flag,@flag_promo,@book_idx=false,false,false,false,false,false,false @seg_autoname_safe=true @daisy,@sem_tag=false,false - @authorship,@markup_instruction,@markup_declared,@image='','','','' #check which other values should be set to empty rather than nil + @authorship,@markup_instruction,@image='','','','' #check which other values should be set to empty rather than nil @markup=@markup_instruction #use @markup_instruction @doc,@fn,@make_italic,@tag_hash,@ec={},{},{},{},{},{} @flv,@lang,@seg_names,@tags,@tag_array,@tag_a,@ec[:image],@ec[:audio],@ec[:multimedia]=Array.new(9){[]} @@ -956,44 +954,6 @@ module SiSU_Param @generated=Time.now fns_array=@data.dup skip unless fns_array # consider - @markup_version=SiSU_MarkupType::MarkupIdentify.new(fns_array,@opt).markup_version? #% determine markup version - if fns_array[0] =~ /^(?:%\s+)?(?:SiSU\s+(?:master\s+)?[\d.]*|sisu-[\d.]+)$/ #check markup and markup version - if fns_array[0] =~ /^(?:%\s+)?(?:SiSU\s+(?:master\s+)?|sisu-)(?:(?:[0-9]+?)(?:\.[0-9]+?)(?:\.[0-9]+))?$/ #check markup and markup version - @markup_version_declared=fns_array[0].match(/^(?:%\s+)?(?:SiSU\s+(?:master\s+)?|sisu-)([\d.]+)$/)[1] - sm_a,sm_b,sm_c=fns_array[0].match(/^(?:%\s+)?(?:SiSU\s+(?:master\s+)?|sisu-)([0-9]+)?(?:\.([0-9]+))?(?:\.([0-9]+))?$/)[1..3] - sm_c ||=0 - sv=(@opt.cmd =~/[VMv]/) ? ("SiSU version (#{@sisu_version[:version]})") : '' - s_a,s_b,s_c=@sisu_version[:version].match(/^([0-9]+)?(?:\.([0-9]+))?(?:\.([0-9]+))?(?:[~-]\S+)?$/)[1..3] - tell=(@markup_version_declared.to_f==@markup_version.determined) \ - ? SiSU_Screen::Ansi.new(@opt.cmd,"Markup version (#{@markup_version.series} version #{@markup_version.determined})",sv) - : SiSU_Screen::Ansi.new(@opt.cmd,"Markup version declared (#{@markup_version_declared}), determined (#{@markup_version.series} version #{@markup_version.determined})",sv) - ok=if s_a.to_i > sm_a.to_i - true - elsif s_a.to_i == sm_a.to_i \ - and s_b.to_i >= sm_b.to_i - true - elsif s_a.to_i == sm_a.to_i \ - and s_b.to_i == sm_b.to_i \ - and s_c.to_i >= sm_c.to_i - true - else false - end - if ok - tell.txt_green if @opt.cmd =~/[vVM]/ - else - SiSU_Screen::Ansi.new(@opt.cmd,"WARNING: markup version determined (#{@markup_version.determined}) or markup version declared (#{@markup_version_declared}) is newer than SiSU version (#{@sisu_version[:version]})").warn unless @opt.cmd =~/q/ - end - else - SiSU_Screen::Ansi.new(@opt.cmd,'No SiSU markup version provided').warn if @opt.cmd =~/[VM]/ - end - else - mv=if @markup_version.determined.is_a?(Float) - x=@markup_version.determined - "markup version determined #{x}" - else '' - end - SiSU_Screen::Ansi.new(@opt.cmd,'SiSU filetype indicator not provided',mv).warn unless @opt.cmd =~/q/ - end @code_flag=false fns_array.each do |para| #% scan document if para !~/^%+\s/ \ @@ -1144,11 +1104,6 @@ module SiSU_Param @lvs[6]=1 end if para =~ /^:A~/ #% processing - if @markup.nil? \ - or @markup.empty? - @markup=@markup_version.determined.to_s - elsif @markup !~/0\.38/ then @markup=@markup.strip + "; #{@markup_version.determined}" - end if not defined? @title.full.nil? tf=para[/^:A~\S*(.+)$/m,1] tf="@title: #{tf}" @@ -1275,38 +1230,36 @@ module SiSU_Param else @i18n=[ 'en' ] end - if @markup_version.determined >= 0.38 #convert values in headers to internal representation - translated=[] - translate_list=[@pagenew,@pagebreak,@pageline,@num_top,@toc_lev_limit] - translate_list.each do |t| - translate=t.to_s if t - translated << if translate - translate.gsub!(/3/,'6') - translate.gsub!(/2/,'5') - translate.gsub!(/1/,'4') - translate.gsub!(/:?C/,'3') - translate.gsub!(/:?B/,'2') - translate.gsub!(/:?A/,'1') - # looks like an ok substituion for the above but is not, causes problems, check why - #translate=translate.gsub(/3/,'6'). - # gsub(/2/,'5'). - # gsub(/1/,'4'). - # gsub(/:?C/,'3'). - # gsub(/:?B/,'2'). - # gsub(/:?A/,'1') - translate=(translate =~/^\d+$/) \ - ? translate.to_i - : translate - else nil - end + translated=[] + translate_list=[@pagenew,@pagebreak,@pageline,@num_top,@toc_lev_limit] + translate_list.each do |t| + translate=t.to_s if t + translated << if translate + translate.gsub!(/3/,'6') + translate.gsub!(/2/,'5') + translate.gsub!(/1/,'4') + translate.gsub!(/:?C/,'3') + translate.gsub!(/:?B/,'2') + translate.gsub!(/:?A/,'1') + # looks like an ok substituion for the above but is not, causes problems, check why + #translate=translate.gsub(/3/,'6'). + # gsub(/2/,'5'). + # gsub(/1/,'4'). + # gsub(/:?C/,'3'). + # gsub(/:?B/,'2'). + # gsub(/:?A/,'1') + translate=(translate =~/^\d+$/) \ + ? translate.to_i + : translate + else nil end - @pagenew,@pagebreak,@pageline,@num_top,@toc_lev_limit=translated - @markup=@markup.gsub(/page_new\s*=\s*([\dA-C])/,"page_new=#{@pagenew}"). - gsub(/page_break\s*=\s*([\dA-C])/,"page_break=#{@pagebreak}"). - gsub(/page_line\s*=\s*([\dA-C])/,"page_line=#{@pageline}"). - gsub(/num_top\s*=\s*([\dA-C])/,"num_top=#{@num_top}"). - gsub(/toc_lev_limit\s*=\s*([\dA-C])/,"toc_lev_limit=#{@toc_lev_limit}") end + @pagenew,@pagebreak,@pageline,@num_top,@toc_lev_limit=translated + @markup=@markup.gsub(/page_new\s*=\s*([\dA-C])/,"page_new=#{@pagenew}"). + gsub(/page_break\s*=\s*([\dA-C])/,"page_break=#{@pagebreak}"). + gsub(/page_line\s*=\s*([\dA-C])/,"page_line=#{@pageline}"). + gsub(/num_top\s*=\s*([\dA-C])/,"num_top=#{@num_top}"). + gsub(/toc_lev_limit\s*=\s*([\dA-C])/,"toc_lev_limit=#{@toc_lev_limit}") papersize_array_rc=@papersize.downcase.scan(/(?:a4|letter|legal|book|a5|b5)/) papersize_array_opt=[ ((@opt.act[:pdf_a4][:set]==:on) ? 'a4' : ''), diff --git a/lib/sisu/v4/sysenv.rb b/lib/sisu/v4/sysenv.rb index 9f57e099..6bc97396 100644 --- a/lib/sisu/v4/sysenv.rb +++ b/lib/sisu/v4/sysenv.rb @@ -2383,7 +2383,7 @@ WOK def po "#{root}/po4a/po" end - def webserv_host_base + def webserv_host_base(opt=nil) if defined? @rc['webserv']['host'] case @rc['webserv']['host'] when /https?:\/\//; @rc['webserv']['host'] @@ -2393,7 +2393,7 @@ WOK else defaults[:webserv_host_cgi] end end - def webserv_cgi #web url for local webserv (localhost, or hostname) + def webserv_cgi(opt=nil) #web url for local webserv (localhost, or hostname) http=if defined? @rc['webserv_cgi']['host'] \ and @rc['webserv_cgi']['host'].is_a?(String) http=((@rc['webserv_cgi']['host'] =~ /https?:\/\//) ? '' : 'http://') #check https? missing @@ -2403,25 +2403,28 @@ WOK end else http=((webserv_host_base=~/https?:\/\//) ? '' : 'http://') - if port.webserv_port_cgi - "#{http}#{webserv_host_base}:#{port.webserv_port_cgi}/#{@stub_pwd}" + if port.webserv_port_cgi(opt) + "#{http}#{webserv_host_base}:#{port.webserv_port_cgi(opt)}/#{@stub_pwd}" else "#{http}#{webserv_host_base}/#{@stub_pwd}" end end http=http.strip end - def webserv_base_cgi #web url for local webserv (localhost, or hostname) - http=if defined? @rc['webserv_cgi']['host'] \ + def webserv_base_cgi(opt=nil) #web url for local webserv (localhost, or hostname) + http=if opt.mod.inspect =~/--webserv-(?:cgi|db|search)[=-]["']?(\S+)["']+/ + m=$1 + (m=~/http\/\/:/) ? m : %{http://#{m}} + elsif defined? @rc['webserv_cgi']['host'] \ and @rc['webserv_cgi']['host'].is_a?(String) http=((@rc['webserv_cgi']['host'] =~ /https?:\/\//) ? '' : 'http://') - if port.webserv_port_cgi - "#{http}#{@rc['webserv_cgi']['host']}:#{port.webserv_port_cgi}" + if port.webserv_port_cgi(opt) + "#{http}#{@rc['webserv_cgi']['host']}:#{port.webserv_port_cgi(opt)}" else "#{http}#{@rc['webserv_cgi']['host']}" end else http=((webserv_host_base=~/https?:\/\//) ? '' : 'http://') - if port.webserv_port_cgi - "#{http}#{webserv_host_base}:#{port.webserv_port_cgi}" + if port.webserv_port_cgi(opt) + "#{http}#{webserv_host_base}:#{port.webserv_port_cgi(opt)}" else "#{http}#{webserv_host_base}" end end @@ -2469,16 +2472,39 @@ WOK else "#{url.webrick_base}" end end - def webserv_files_from_db #sort this out, messy - if defined? @rc['webserv_cgi']['file_links'] - case @rc['webserv_cgi']['file_links'] - when /webserv_cgi/; url.webserv_base_cgi + def webserv_files_from_db(opt=nil) #sort this out, messy + if opt.mod.inspect =~/--webserv-output[=-]["']?(\S+)["']+/ + m=$1 + (m=~/(?:http|file\/)\/\/:/) ? m : %{http://#{m}} + else + show_output_on=if defined? @rc['webserv_cgi']['show_output_on'] + @rc['webserv_cgi']['show_output_on'] + elsif defined? @rc['webserv_cgi']['file_links'] + @rc['webserv_cgi']['file_links'] + else '' + end + m=case show_output_on + when /webserv_cgi/; url.webserv_base_cgi(opt) when /webserv/; @rc['webserv']['url_root'] when /https?:\/\//; @rc['webserv_cgi']['file_links'] when /\S+/; "http://#{@rc['webserv_cgi']['file_links']}" - else webserv_base_cgi + else webserv_base_cgi(opt) end - else webserv_base_cgi + end + end + def cgi_sample_search_form_name(opt=nil) + if opt.mod.inspect =~/--(?:cgi-)?search-form-name[=-]["']?(\S+?\.cgi)/ + m=$1 + elsif not (opt.mod.inspect =~/--db[=-]["']?sqlite/) \ + and defined? @rc['search'] \ + and defined? @rc['search']['sisu'] \ + and defined? @rc['search']['sisu']['action'] \ + and @rc['search']['sisu']['action'] =~/https?:\/\/\S+?\.cgi/ + x=/(?:https?:\/\/\S+?)\/([^\/]+?\.cgi)$/.match(@rc['search']['sisu']['action'])[1] + else + (opt.mod.inspect =~/--db[=-]["']?sqlite/) \ + ? 'sisu_sqlite.cgi' \ + : 'sisu_pgsql.cgi' end end def sample_search_form_title(organised_by=:language) @@ -2569,24 +2595,29 @@ WOK end end end - def webserv_port_cgi - if @md \ - and defined? @md.opt \ - and @md.opt.cmd.inspect=~/-F/ \ - and @md.opt.mod.inspect=~/port=(\d+)/ + def webserv_port_cgi(opt=nil) + port=if opt \ + and opt.cmd.inspect=~/-F/ \ + and opt.mod.inspect=~/port=(\d+)/ $1 else - if defined? @rc['webserv_cgi']['port'] + port=if defined? @rc['webserv_cgi']['port'] if @rc['webserv_cgi']['port'].nil? \ - and (defined? @md.opt.mod \ - and not @md.opt.mod.nil? \ - and @md.opt.mod.inspect=~/webrick/) + and (defined? opt.mod \ + and not opt.mod.nil? \ + and opt.mod.inspect=~/webrick/) defaults[:webserv_port_cgi] elsif not @rc['webserv_cgi']['port'].nil? @rc['webserv_cgi']['port'] else nil end - else nil + else + if (defined? opt.mod \ + and not opt.mod.nil? \ + and opt.mod.inspect=~/webrick/) + defaults[:webserv_port_cgi] + else nil + end end end end @@ -3548,6 +3579,38 @@ WOK %x{ruby -v}.strip end end + class InfoAbout + def initialize(color='') + @color=color + end + def sisu_version + version=SiSU_Env::InfoVersion.instance.get_version + rb_ver=SiSU_Env::InfoVersion.instance.rbversion + if version[:version] + opt_cmd=if defined? @color.cmd \ + and @color.cmd =~/[ck]/ + @color.cmd + else '-v' + end + SiSU_Screen::Ansi.new(opt_cmd,version[:project],version[:version],version[:date_stamp],version[:date],rb_ver).version + else puts 'SiSU version information not available' + end + end + def sisu_about + puts <<-WOK + sisu: documents; markup, structuring, publishing in multiple standard formats, & search + most (not all) useful commands (are made in a directory containing a sisu markup file &) take the form: + sisu [action(s)] [filename(s)] + where filename refers to a valid sisu marked up file, e.g.: + cd /usr/share/doc/sisu/markup-samples/sisu_manual + sisu --html --verbose sisu_commands.sst + sisu --txt --html --epub --odt --pdf --sqlite --manpage --texinfo --concordance --qrcode --verbose sisu.ssm + cd - + See output produced, or see man pages: man sisu + <http://www.sisudoc.org/> <http://www.jus.uio.no/sisu/> + WOK + end + end class InfoFile <InfoEnv #todo unify with FileOp def initialize(fns) begin @@ -4004,11 +4067,17 @@ WOK self end def psql - def user - ((defined? @rc['db']['postgresql']['user']) \ - && @rc['db']['postgresql']['user']=~/\S+/) \ - ? @rc['db']['postgresql']['user'] - : @env.user + def user(opt) + if opt.mod.inspect =~/--db-user[=-]["']?(\S+)["']+/ + m=$1 + elsif opt.mod =~/--webserv[=-]webrick/ + @env.user + else + ((defined? @rc['db']['postgresql']['user']) \ + && @rc['db']['postgresql']['user']=~/\S+/) \ + ? @rc['db']['postgresql']['user'] + : @env.user + end end def db #db_name "#{Db[:name_prefix]}#{@pwd_stub}" diff --git a/lib/sisu/v5/cgi.rb b/lib/sisu/v5/cgi.rb index dd9cdf22..1c0e023a 100644 --- a/lib/sisu/v5/cgi.rb +++ b/lib/sisu/v5/cgi.rb @@ -70,8 +70,20 @@ module SiSU_CGI @webserv=@opt.files[0].to_s.strip end def read - SiSU_CGI_SQLite::SearchSQLite.new(@opt,@webserv).sqlite - SiSU_CGI_PgSQL::SearchPgSQL.new(@opt,@webserv).pgsql + if @opt.mod.inspect =~/--db[=-]["']?(?:pg|pg?sql|postgres(?:ql)?)["']+/ + SiSU_CGI_PgSQL::SearchPgSQL.new(@opt,@webserv).pgsql + elsif @opt.mod.inspect =~/--db[=-](?:sqlite)/ + SiSU_CGI_SQLite::SearchSQLite.new(@opt,@webserv).sqlite + else + puts <<-WOK + please select database type for which sample search form should be built (pgsql or sqlite) + sisu --sample-search-form --db=sqlite + sisu --sample-search-form --db=pg + other options include + --webserv-cgi='[cgi-server-name]' + --webserv-output='[sisu-output-server-with-base-path]' + WOK + end end end end diff --git a/lib/sisu/v5/cgi_pgsql.rb b/lib/sisu/v5/cgi_pgsql.rb index 1fa19e0d..45a4aae9 100644 --- a/lib/sisu/v5/cgi_pgsql.rb +++ b/lib/sisu/v5/cgi_pgsql.rb @@ -56,7 +56,7 @@ <ralph@amissah.com> <ralph.amissah@gmail.com> - ** Description: generates naive cgi search form for search of sisu database (pgsql sqlite) + ** Description: generates naive cgi search form for search of sisu database (pgsql) =end module SiSU_CGI_PgSQL #% database building documents @@ -66,6 +66,7 @@ module SiSU_CGI_PgSQL class SearchPgSQL < CGI_Common def initialize(opt,webserv) @opt,@webserv=opt,webserv + @cX=SiSU_Screen::Ansi.new(opt.cmd).cX @env=SiSU_Env::InfoEnv.new('',opt) @sys=SiSU_Env::SystemCall.new @db=SiSU_Env::InfoDb.new @@ -90,18 +91,19 @@ module SiSU_CGI_PgSQL and @rc['search']['sisu']['db'] =~/\S+/ @name_of[:db]=@rc['search']['sisu']['db'] #@name_of[:cgi_script]=/https?:\/\/\S+?([^\/]+?)\.cgi$/.match(@rc['search']['sisu']['action'])[1] - @name_of[:host_url_cgi],@name_of[:cgi_script]=/(https?:\/\/\S+?)\/([^\/]+?)\.cgi$/.match(@rc['search']['sisu']['action'])[1,2] + @name_of[:host_url_cgi]=/(https?:\/\/\S+?)\/(?:[^\/]+?)\.cgi$/.match(@rc['search']['sisu']['action'])[1] else - @name_of[:host_url_docs]=@env.url.webserv_files_from_db - @name_of[:db]='sisu' #breaks if not present - @name_of[:host_url_cgi]=@env.url.webserv_base_cgi - @name_of[:cgi_script]='sisu_pgsql' + @name_of[:host_url_docs]=@env.url.webserv_files_from_db(@opt) + @name_of[:db]=@env.path.stub_pwd #'sisu' #breaks if not present + @name_of[:host_url_cgi]=@env.url.webserv_base_cgi(@opt) false end + @name_of[:cgi_script]=@env.url.cgi_sample_search_form_name(@opt) @cgi_file_name="#{Db[:name_prefix_db]}by_#{opt.dir_structure_by.to_s}_pgsql.cgi" - @cgi_link_name="#{@name_of[:db]}.cgi" #sisu_pgsql.cgi, - @image_src="#{@name_of[:host_url_docs]}/_sisu/image_sys" + @cgi_link_name=@name_of[:cgi_script] #sisu_pgsql.cgi, + @image_src="#{@env.url.webserv_base_cgi(@opt)}/_sisu/image_sys" @common=SiSU_CGI_SQL::CGI_Common.new(@webserv,@opt,@image_src,@env) + @user=@db.psql.user(@opt) end def pgsql serve=[] @@ -125,25 +127,69 @@ module SiSU_CGI_PgSQL if FileTest.writable?('.') output=File.open(@cgi_file_name,'w') output << header0 << header1 << header_desc << header2 << f1 << buttons1 << buttons1_pgsql << buttons2 << search_request << search_statement << search_statement_common << search_query1 << @common.pages << search_query2 << @common.tail << @common.main1 << f2 << dbi_connect << @common.main2 << @common.dir_structure << @common.main3 - a=%{ generated #{@cgi_file_name}, - BASED ON ALREADY EXISTING directories that could potentially be used to populate postgresql db, (-D) - } - SiSU_Screen::Ansi.new(@opt.cmd,a).print_grey - c=case @webserv + puts <<-WOK + generated sample search form: #{@cX.green}#{@cgi_file_name}#{@cX.off} + default database name: #{@cX.green}#{Db[:name_prefix]}#{@name_of[:db]}#{@cX.off} (#{@name_of[:db]}) + db user: #{@cX.green}#{@db.psql.user(@opt)}#{@cX.off} + to modify use: #{@cX.brown}sisu --db-pg --db-user='#{@db.psql.user(@opt)}'#{@cX.off} + cgi & db host on: #{@cX.blue}#{@env.url.webserv_base_cgi(@opt)}#{@cX.off} + to modify use: #{@cX.brown}sisu --db-pg --webserv-search='#{@env.url.webserv_base_cgi(@opt)}'#{@cX.off} + sisu output on: #{@cX.blue}#{@env.url.webserv_files_from_db(@opt)}#{@cX.off} + to modify use: #{@cX.brown}sisu --db-pg --webserv-output='#{@env.url.webserv_files_from_db(@opt)}'#{@cX.off} + cgi search form link name: #{@cX.green}#{@env.url.cgi_sample_search_form_name(@opt)}#{@cX.off} + to modify use: #{@cX.brown}sisu --db-pg --cgi-search-form-name='#{@env.url.cgi_sample_search_form_name(@opt)}'#{@cX.off} + #{@cX.fuschia}(settings priority: command line; sisurc.yml; else defaults)#{@cX.off} + + #{@cX.fuschia}BASED ON ALREADY EXISTING databases#{@cX.off} (default database name: #{@db.psql.db}) + NOTE it is first necessary to createdb, + use sisu to create the tables & populate the postgresql db + + the database to be used for this directory (#{@db.psql.db}) + will have to be created manually if it does not exist: + using postgresql tools directly (the following may work): + (i) if you are not yet a postgresql user, + #{@cX.brown}sudo su postgres + createuser -d -a #{@env.user} + exit#{@cX.off} + (ii) create the database: + #{@cX.brown}createdb #{@db.psql.db}#{@cX.off} + [for a list of existing databases try 'psql --list']" + + now you can use sisu to create the database tables and populate the database with documents + + sisu --pg --dropall # removes existing postgresql db & tables + sisu --pg --createall -v # creates postgresql db & tables + sisu --pg --update -v *.sst *.ssm # populate the db + sisu --sample-search-form --pg # creates the postgresql search form + # this should be done after creating the db + # to be searched + sisu --webrick & # starts ruby webrick web server + + # if necessary make the directory '/usr/lib/cgi-bin' + # here we copy the postgresql search form to cgi-bin + # (copy #{@cgi_file_name} to your cgi directory) + # set file permissions to 755, & + # make symbolic link to #{@cgi_link_name} + WOK + a=case @webserv when /pwd/; '' - else "if necessary make the directory /usr/lib/cgi-bin : - sudo cp -vi #{Dir.pwd}/#{@cgi_file_name} /usr/lib/cgi-bin/. - sudo chmod -v 755 /usr/lib/cgi-bin/#{@cgi_file_name} - sudo ln -s /usr/lib/cgi-bin/#{@cgi_file_name} /usr/lib/cgi-bin/#{@cgi_link_name} - (copy #{@cgi_file_name} to your cgi directory) set file permissions to 755, and make symbolic link to #{@cgi_link_name}" + else <<-WOK + + sudo cp -vi #{Dir.pwd}/#{@cgi_file_name} /usr/lib/cgi-bin/.; \\ + cd /usr/lib/cgi-bin && \\ + sudo chmod -v 755 #{@cgi_file_name}; \\ + sudo rm -vi #{@cgi_link_name}; \\ + sudo ln -s #{@cgi_file_name} #{@cgi_link_name}; \\ + cd - + WOK end - a=%{#{c} - #{@env.webserv_base_cgi}/cgi-bin/#{@cgi_link_name} - } SiSU_Screen::Ansi.new(@opt.cmd,a).warn - a="postgresql db used for present directory: #{@db.psql.db}" - b="\n\t(to create and populate postgresql database see 'man sisu' and in particular the -D flag)\n\t[the database to be used for this directory (#{@db.psql.db}) will have to be created manually if it does not exist,\n\tsee 'sisu --help sql'\n\tif you have permission to create databases:\n\t'sisu -d --createdb'\n\tor using postgresql tools directly:\n\t'createdb #{@db.psql.db}'\n\tfor a list of existing databases try 'psql --list']" - SiSU_Screen::Ansi.new(@opt.cmd,a,b).txt_cyan + a=<<-WOK + #{@env.webserv_base_cgi(@opt)}/cgi-bin/#{@cgi_link_name} + WOK + SiSU_Screen::Ansi.new(@opt.cmd,a).print_blue + a="\n\t(to create and populate postgresql database see 'man sisu' and in particular the --pg option)\n\t[the database to be used for this directory (#{@db.psql.db}) will have to be created manually if it does not exist,\n\tusing postgresql tools directly: 'createdb #{@db.psql.db}' for a list of existing databases try 'psql --list']" + SiSU_Screen::Ansi.new(@opt.cmd,a).txt_grey else puts 'failed in attempt to write #{@cgi_file_name} to present directory, is directory writable?' end end @@ -159,13 +205,14 @@ module SiSU_CGI_PgSQL require 'fcgi' require 'dbi' @stub_default='#{@name_of[:db]}' - @image_src='#{@name_of[:host_url_docs]}/_sisu/image_sys' - @hosturl_cgi='#{@name_of[:host_url_cgi]}' - @hosturl_files='#{@name_of[:host_url_docs]}' + @image_src='#{@image_src}' + @hosturl_cgi='#{@env.url.webserv_base_cgi(@opt)}/cgi-bin' + @hosturl_files='#{@env.url.webserv_files_from_db(@opt)}' @output_dir_structure_by='#{@name_of[:output_dir_structure]}' @port='#{@db.psql.port}' @db_name_prefix='#{Db[:name_prefix]}' - user='www-data' # check user name for access to pg database: e.g. www-data or '#{@env.user}' + @user='#{@user}' # check user name for access to pg database: e.g. www-data or '#{@env.user}' + @base='#{@name_of[:host_url_cgi]}/cgi-bin/#{@name_of[:cgi_script]}.cgi' #fix sqlite WOK_SQL end def search_statement @@ -250,7 +297,7 @@ module SiSU_CGI_PgSQL def dbi_connect <<-'WOK_SQL' dbi="dbi:Pg:database=#{@db};port=#{@port}" - @conn=DBI.connect(dbi,user) + @conn=DBI.connect(dbi,@user) WOK_SQL end end diff --git a/lib/sisu/v5/cgi_sql_common.rb b/lib/sisu/v5/cgi_sql_common.rb index 5604d6cb..9e872139 100644 --- a/lib/sisu/v5/cgi_sql_common.rb +++ b/lib/sisu/v5/cgi_sql_common.rb @@ -130,7 +130,6 @@ module SiSU_CGI_SQL <<-'WOK_SQL' #Common TOP @@offset=0 - @base="#{@hosturl_cgi}/#{@stub_default}.cgi" #fix sqlite @@canned_search_url=@base @color_heading='#DDFFAA' @color_match='#ffff48' diff --git a/lib/sisu/v5/cgi_sqlite.rb b/lib/sisu/v5/cgi_sqlite.rb index cf891c5a..e53497e1 100644 --- a/lib/sisu/v5/cgi_sqlite.rb +++ b/lib/sisu/v5/cgi_sqlite.rb @@ -56,7 +56,7 @@ <ralph@amissah.com> <ralph.amissah@gmail.com> - ** Description: generates naive cgi search form for search of sisu database (pgsql sqlite) + ** Description: generates naive cgi search form for search of sisu database (sqlite) =end module SiSU_CGI_SQLite #% database building documents @@ -66,17 +66,19 @@ module SiSU_CGI_SQLite class SearchSQLite < CGI_Common def initialize(opt,webserv) @opt,@webserv=opt,webserv + @cX=SiSU_Screen::Ansi.new(opt.cmd).cX @env=SiSU_Env::InfoEnv.new('',opt) - @image_src="#{@env.url.webserv_cgi}/_sisu/image_sys" + @image_src="#{@env.url.webserv_cgi(@opt)}/_sisu/image_sys" @common=SiSU_CGI_SQL::CGI_Common.new(@webserv,@opt,@image_src,@env) @cgi_file_name="#{Db[:name_prefix_db]}by_#{opt.dir_structure_by.to_s}_sqlite.cgi" + @name_of_sqlite_db_file='sisu_sqlite.db' end def sqlite serve=[] Dir.foreach(@env.path.webserv) do |x| if x !~/^\./ \ and FileTest.directory?("#{@env.path.webserv}/#{x}") - if FileTest.file?("#{@env.path.webserv}/#{x}/sisu_sqlite.db") + if FileTest.file?("#{@env.path.webserv}/#{x}/#{@name_of_sqlite_db_file}") serve << x unless x =~/^_\S+/ end end @@ -91,32 +93,62 @@ module SiSU_CGI_SQLite f2 << %{ when /#{Db[:name_prefix]}#{x}/; '<option value="#{Db[:name_prefix]}#{x}">#{x}</option>'\n} end f2 << " end\n" - f3 << %{ db_name='sisu_sqlite.db'\n} + f3 << %{ db_name='#{@name_of_sqlite_db_file}'\n} f3 << %{ db_sqlite=case cgi['db']\n} serve.each do |x| - f3 << %{ when /#{Db[:name_prefix]}#{x}/; "#{@env.path.webserv}/#{x}/sisu_sqlite.db"\n} + f3 << %{ when /#{Db[:name_prefix]}#{x}/; "#{@env.path.webserv}/#{x}/\#{db_name}"\n} end - f3 << %{ else '#{@env.path.webserv}/#{serve[0]}/sisu_sqlite.db'\n end\n} + f3 << %{ else '#{@env.path.webserv}/#{serve[0]}/\#{db_name}'\n end\n} if FileTest.writable?('.') output=File.open(@cgi_file_name,'w') output << header0 << header1 << header_desc << header2 << f1 << buttons1 << buttons2 << search_request << search_statement << search_statement_common << search_query1 << @common.pages << search_query2 << @common.tail << @common.main1 << f2 << f3 << dbi_connect << @common.main2 << @common.dir_structure << @common.main3 - a=%{ generated sisu_sqlite.cgi, - BASED ON ALREADY CREATED sisu_sqlite.db OUTPUT, (-d) - } - SiSU_Screen::Ansi.new(@opt.cmd,a).print_grey - c=case @webserv + puts <<-WOK + generated sample search form: #{@cX.green}#{@cgi_file_name}#{@cX.off} + default database name: #{@cX.green}#{Db[:name_prefix]}#{@env.path.stub_pwd}#{@cX.off} (#{@env.path.stub_pwd}) + cgi & db host on: #{@cX.blue}#{@env.url.webserv_base_cgi(@opt)}#{@cX.off} + to modify use: #{@cX.brown}sisu --db-sqlite --webserv-search='#{@env.url.webserv_base_cgi(@opt)}'#{@cX.off} + sisu output on: #{@cX.blue}#{@env.url.webserv_files_from_db(@opt)}#{@cX.off} + to modify use: #{@cX.brown}sisu --db-sqlite --webserv-output='#{@env.url.webserv_files_from_db(@opt)}'#{@cX.off} + cgi search form link name: #{@cX.green}#{@env.url.cgi_sample_search_form_name(@opt)}#{@cX.off} + to modify use: #{@cX.brown}sisu --db-sqlite --cgi-search-form-name='#{@env.url.cgi_sample_search_form_name(@opt)}'#{@cX.off} + #{@cX.fuschia}(settings priority: command line; sisurc.yml; else defaults)#{@cX.off} + + #{@cX.fuschia}NOTE it is first necessary to create the database and tables and populate it#{@cX.off} + + sisu --sqlite --dropall # removes existing postgresql db & tables + sisu --sqlite --createall -v # creates postgresql db & tables + sisu --sqlite --update -v *.sst *.ssm # populate the db + sisu --sample-search-form --sqlite # creates the postgresql search form + # this should be done after creating the db + # to be searched + sisu --webrick & # starts ruby webrick web server + + # if necessary make the directory '/usr/lib/cgi-bin' + # here we copy the postgresql search form to cgi-bin + # (copy #{@cgi_file_name} to your cgi directory) + # set file permissions to 755, & + # make symbolic link to #{@cgi_link_name} + WOK + a=case @webserv when /pwd/; '' - else "if necessary make the directory /usr/lib/cgi-bin : - sudo cp -vi #{Dir.pwd}/#{@cgi_file_name} /usr/lib/cgi-bin/. - sudo chmod -v 755 /usr/lib/cgi-bin/#{@cgi_file_name} - sudo ln -s /usr/lib/cgi-bin/#{@cgi_file_name} /usr/lib/cgi-bin/sisu_sqlite.cgi - (copy #{@cgi_file_name} to your cgi directory) set file permissions to 755, and make symbolic link to sisu_sqlite.cgi" + else <<-WOK + + sudo cp -vi #{Dir.pwd}/#{@cgi_file_name} /usr/lib/cgi-bin/.; \\ + cd /usr/lib/cgi-bin && \\ + sudo chmod -v 755 #{@cgi_file_name}; \\ + sudo rm -vi #{@env.url.cgi_sample_search_form_name(@opt)}; \\ + sudo ln -sf #{@cgi_file_name} #{@env.url.cgi_sample_search_form_name(@opt)}; \\ + cd - + WOK end - a=%{#{c} - #{@env.webserv_base_cgi}/cgi-bin/sisu_sqlite.cgi - } b='(to create and populate sisu sqlite database see "man sisu" and in particular the -d flag)' SiSU_Screen::Ansi.new(@opt.cmd,a,b).warn + a=<<-WOK + + #{@env.webserv_base_cgi(@opt)}/cgi-bin/#{@cgi_link_name} + + WOK + SiSU_Screen::Ansi.new(@opt.cmd,a).print_blue else puts "failed in attempt to write #{@cgi_file_name} to present directory, is directory writable?" end end @@ -132,10 +164,11 @@ module SiSU_CGI_SQLite require 'fcgi' require 'dbi' @stub_default='sisu_sqlite' - @image_src='#{@env.url.webserv_cgi}/_sisu/image_sys' - @hosturl_cgi='#{@env.url.webserv_base_cgi}/cgi-bin' - @hosturl_files='#{@env.url.webserv_files_from_db}' + @image_src='#{@image_src}' + @hosturl_cgi='#{@env.url.webserv_base_cgi(@opt)}/cgi-bin' + @hosturl_files='#{@env.url.webserv_files_from_db(@opt)}' @db_name_prefix='#{Db[:name_prefix]}' + @base='#{@env.url.webserv_base_cgi(@opt)}/cgi-bin/#{@env.url.cgi_sample_search_form_name(@opt)}' #fix sqlite WOK_SQL end def search_statement diff --git a/lib/sisu/v5/dal_doc_str.rb b/lib/sisu/v5/dal_doc_str.rb index da417bd6..2979412b 100644 --- a/lib/sisu/v5/dal_doc_str.rb +++ b/lib/sisu/v5/dal_doc_str.rb @@ -556,7 +556,6 @@ module SiSU_DAL_DocumentStructureExtract @md,@dob=md,dob end def structure - structure_markup_normalize structure_markup @dob end @@ -590,53 +589,6 @@ module SiSU_DAL_DocumentStructureExtract end @dob end - def structure_markup_normalize #needs a bit of thinking - dob=if @md.markup_version.determined < 0.38 #%convert internal representation, consider making 0.38 structure default ([A-C1-6] instead of [1-9]), requires downstream changes - @dob=@dob.gsub(/^[456]~/,'!_'). - gsub(/^3~(\S+)/,"#{Mx[:lv_o]}6:\\1#{Mx[:lv_c]}"). - gsub(/^3~\s+/,"#{Mx[:lv_o]}6:#{Mx[:lv_c]}"). - gsub(/^2~(\S+)/,"#{Mx[:lv_o]}5:\\1#{Mx[:lv_c]}"). - gsub(/^2~\s+/,"#{Mx[:lv_o]}5:#{Mx[:lv_c]}"). - gsub(/^1~(\S+)/,"#{Mx[:lv_o]}4:\\1#{Mx[:lv_c]}"). - gsub(/^1~\s+/,"#{Mx[:lv_o]}4:#{Mx[:lv_c]}"). - gsub(/^:?C~(\S+)/,"#{Mx[:lv_o]}3:\\1#{Mx[:lv_c]}"). - gsub(/^:?C~\s+/,"#{Mx[:lv_o]}3:#{Mx[:lv_c]}"). - gsub(/^:?B~(\S+)/,"#{Mx[:lv_o]}2:\\1#{Mx[:lv_c]}"). - gsub(/^:?B~\s+/,"#{Mx[:lv_o]}2:#{Mx[:lv_c]}"). - gsub(/^:?A~(\S+)/,"#{Mx[:lv_o]}1:\\1#{Mx[:lv_c]}"). - gsub(/^:?A~\s+/,"#{Mx[:lv_o]}1:#{Mx[:lv_c]}") - @dob=if @dob =~/^@(?:level|markup):\s/ - @dob=@dob.gsub(/3/,'6'). - gsub(/2/,'5'). - gsub(/1/,'4'). - gsub(/:?C/,'3'). - gsub(/:?B/,'2'). - gsub(/:?A/,'1') - @dob - else @dob - end - else @dob - end - end - def structure_marks - t_o=if @md.markup_version.determined < 0.38 - @t_o=@t_o.gsub(/^1~(\S+)/,"#{Mx[:lv_o]}1:\\1#{Mx[:lv_c]}"). - gsub(/^1~\s+/,"#{Mx[:lv_o]}1:#{Mx[:lv_c]}"). - gsub(/^2~(\S+)/,"#{Mx[:lv_o]}2:\\1#{Mx[:lv_c]}"). - gsub(/^2~\s+/,"#{Mx[:lv_o]}2:#{Mx[:lv_c]}"). - gsub(/^3~(\S+)/,"#{Mx[:lv_o]}3:\\1#{Mx[:lv_c]}"). - gsub(/^3~\s+/,"#{Mx[:lv_o]}3:#{Mx[:lv_c]}"). - gsub(/^4~(\S+)/,"#{Mx[:lv_o]}4:\\1#{Mx[:lv_c]}"). - gsub(/^4~\s+/,"#{Mx[:lv_o]}4:#{Mx[:lv_c]}"). - gsub(/^5~(\S+)/,"#{Mx[:lv_o]}5:\\1#{Mx[:lv_c]}"). - gsub(/^5~\s+/,"#{Mx[:lv_o]}5:#{Mx[:lv_c]}"). - gsub(/^6~(\S+)/,"#{Mx[:lv_o]}6:\\1#{Mx[:lv_c]}"). - gsub(/^6~\s+/,"#{Mx[:lv_o]}6:#{Mx[:lv_c]}"). - gsub(/^[789]~/,'!_') - @t_o - else @t_o - end - end end class OCN def initialize(md,data) diff --git a/lib/sisu/v5/dal_substitutions_and_insertions.rb b/lib/sisu/v5/dal_substitutions_and_insertions.rb index 051d2bfd..eeabc1a5 100644 --- a/lib/sisu/v5/dal_substitutions_and_insertions.rb +++ b/lib/sisu/v5/dal_substitutions_and_insertions.rb @@ -130,11 +130,6 @@ module SiSU_DAL_SubstituteAndInsert end data_new=[] data_expand.each do |para| - para=if @md.markup_version.determined >= 0.38 - SiSU_DAL_DocumentStructureExtract::Structure.new(@md,para).structure_markup_normalize - else - SiSU_DAL_DocumentStructureExtract::Structure.new(@md,para).structure_marks - end para=para.gsub(/^(:?A~)\s*$/,'\1~ @title @author'). #conditional header gsub(/^((?:[1-9]|:?[A-C])~\S*)\s*$/,'\1~ [Note: heading marker::required title missing]~#') #conditional header for incorporated document 2004w12 if para =~/^@\S+?:/ diff --git a/lib/sisu/v5/db_select.rb b/lib/sisu/v5/db_select.rb index f6930fa4..67009f0c 100644 --- a/lib/sisu/v5/db_select.rb +++ b/lib/sisu/v5/db_select.rb @@ -205,9 +205,6 @@ module SiSU_DbSelect when /^--(?:db=)?(?:(?:sq)?lite|pg(?:sql)?|my(?:sql)?)$/ when /^--(?:v\d+|dev)$/ else - #help=SiSU_Help::Help.new - #help.summary - #help.commands end if @opt.cmd =~/M/ \ and @opt.cmd =~/d/ diff --git a/lib/sisu/v5/dbi.rb b/lib/sisu/v5/dbi.rb index 33592727..eae39ae8 100644 --- a/lib/sisu/v5/dbi.rb +++ b/lib/sisu/v5/dbi.rb @@ -60,7 +60,6 @@ =end module SiSU_DBI #% database building - require_relative 'help' # help.rb require_relative 'sysenv' # sysenv.rb include SiSU_Env; include SiSU_Screen require_relative 'param' # param.rb @@ -108,7 +107,11 @@ module SiSU_DBI @conn=@db.psql.conn_dbi rescue if @opt.mod.inspect=~/--(createall|create)/ - puts %{manually create the database: "#{@db.db}" if it does not yet exist} + cX=SiSU_Screen::Ansi.new(@opt.cmd).cX + puts <<-WOK +manually create the database: "#{cX.green}#{@db.db}#{cX.off}" if it does not yet exist + #{cX.yellow}createdb #{@db.db}#{cX.off} + WOK #sudo su -p postgres; createdb #{@db.db}; #[createuser?] end ensure diff --git a/lib/sisu/v5/dbi_discrete.rb b/lib/sisu/v5/dbi_discrete.rb index 89fd3898..cddc03f3 100644 --- a/lib/sisu/v5/dbi_discrete.rb +++ b/lib/sisu/v5/dbi_discrete.rb @@ -60,7 +60,6 @@ =end module SiSU_DBI_Discrete #% database building - require_relative 'help' # help.rb require_relative 'sysenv' # sysenv.rb include SiSU_Env; include SiSU_Screen require_relative 'param' # param.rb diff --git a/lib/sisu/v5/help.rb b/lib/sisu/v5/help.rb deleted file mode 100644 index b73cd138..00000000 --- a/lib/sisu/v5/help.rb +++ /dev/null @@ -1,1881 +0,0 @@ -# encoding: utf-8 -=begin - - * Name: SiSU - - * Description: a framework for document structuring, publishing and search - - * Author: Ralph Amissah - - * Copyright: (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, - 2007, 2008, 2009, 2010, 2011, 2012, 2013 Ralph Amissah, All Rights Reserved. - - * License: GPL 3 or later: - - SiSU, a framework for document structuring, publishing and search - - Copyright (C) Ralph Amissah - - This program is free software: you can redistribute it and/or modify it - under the terms of the GNU General Public License as published by the Free - Software Foundation, either version 3 of the License, or (at your option) - any later version. - - This program is distributed in the hope that it will be useful, but WITHOUT - ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or - FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for - more details. - - You should have received a copy of the GNU General Public License along with - this program. If not, see <http://www.gnu.org/licenses/>. - - If you have Internet connection, the latest version of the GPL should be - available at these locations: - <http://www.fsf.org/licensing/licenses/gpl.html> - <http://www.gnu.org/licenses/gpl.html> - - <http://www.sisudoc.org/sisu/en/manifest/gpl.fsf.html> - - * SiSU uses: - * Standard SiSU markup syntax, - * Standard SiSU meta-markup syntax, and the - * Standard SiSU object citation numbering and system - - * Hompages: - <http://www.jus.uio.no/sisu> - <http://www.sisudoc.org> - - * Download: - <http://www.sisudoc.org/sisu/en/SiSU/download.html> - - * Git - <http://sources.sisudoc.org/gitweb/?p=code/sisu.git;a=summary> - <http://sources.sisudoc.org/?p=code/sisu.git;a=blob;f=lib/sisu/v5/help.rb;hb=HEAD> - - * Ralph Amissah - <ralph@amissah.com> - <ralph.amissah@gmail.com> - - ** Description: interactive infomation/help - -=end -module SiSU_Help - require_relative 'sysenv' # sysenv.rb - include SiSU_Screen - require_relative 'param' # param.rb - class Help - require_relative 'i18n' # i18n.rb - def initialize(request='',color='') - @request,@color=request,color - @cX=((color =~/color_off/) \ - || (defined? color.act && color.act[:color_state][:set]==:off)) \ - ? (SiSU_Screen::Ansi.new('k').cX) - : (SiSU_Screen::Ansi.new('yes').cX) - fns='help_example_dummy_file_name.sst' - @env=SiSU_Env::InfoEnv.new(fns) - @db=SiSU_Env::InfoDb.new - m=/.+\/(?:src\/)?(\S+)/im # m=/.+?\/(?:src\/)?([^\/]+)$/im # m=/.+\/(\S+)/m - @output_stub=Dir.pwd[m,1] - end - def help_request - begin - gotten=nil - regx=/^(list|com(?:mands)?|mod(?:ifiers)|markup|syntax|example(?:_v1|_v2)?|head(?:ers?)?|(?:heading|title|level|structure)s?|endnotes|footnotes|tables?|customise|skin|dir(?:ectories)?|paths?|lang(?:uage)?|modules|setup|conf(?:ig(?:ure)?)?|standards?|li[cs]en[sc]e|scratch|install|termsheet|dublin(?:core)?|dc|customise|styles?|appearance|theme|env(ironment)?|dir(?:ector(?:y|ies))?|metaverse|abstract|features|summary|(?:short)?cuts?|sisu|about|ext(?:ernal)?(?:_?prog(?:rams)?)?)|utf-?8|plaintext|html|xml|xhtml|epub|odf|odt|opendocument|css|pdf|latex|tex|(?:tex)?info|search|(?:hyper)?est(?:raier)?|searchform|cgi|sql|db|pg|postgresql|pg?sql|sqlite|convert|php|webrick|sitemaps?|ya?ml|ansi|colors|-[AabcDdEeFHhIMmNnopqrRSstUuVvwXxyZz0-9]|-[Ddcv]|-[CcFLSVvW]/ - help_info=%{#{@cX.blue_hi}SiSU help#{@cX.off} #{@cX.ruby}~#{@cX.off} #{@request}} - help_list=%{#{@cX.blue}sisu --help#{@cX.off} #{@cX.cyan}type keyword else "enter" to exit help:\n\tkeywords include:#{@cX.off} #{@cX.brown}list, (com)mands, short(cuts), (mod)ifiers, (env)ironment, markup, syntax, headers, headings, endnotes, tables, example, customise, skin, (dir)ectories, path, (lang)uage, db, install, setup, (conf)igure, convert, termsheet, search, sql, features, license#{@cX.off} \n} - help_prompt=%{#{@cX.fuschia}exit, [or carriage return to exit help] #{@cX.off}\n#{@cX.blue_hi}SiSU help#{@cX.off} #{@cX.ruby}~#{@cX.off} } - until gotten =~/exit|quit|bye|q|^\s*$/ \ - and ( @request.nil? or @request.empty? ) - @help=Help.new(@request,@color) - if @request - puts help_info - gotten=@request - @request=nil - end - case gotten - when /h((?:elp)| )|~/i - @help.summary - help_@request - when /list/; @help.summary - when /com(mands)?/; @help.commands - when /mod(ifiers)?/; @help.modifiers - when /markup|syntax/; @help.markup - when /example\b/; @help.example_v2 - when /example_v1/; @help.example_v1 - when /example(_v2)?/; @help.example_v2 - when /(?:heading|title|level)s?|structure/; @help.headings - when /head(ers?)?/; @help.headers - when /dublin(core)?|dc/; @help.dublin_core - when /(?:foot|end)notes/; @help.endnotes - when /tables?/; @help.tables - when /customise|skin/; @help.customise - when /modules/; @help.modules - when /env(ironment)?/; @help.environment - when /dir(ector(y|ies))?/; @help.directories - when /paths?/; @help.path - when /setup/; @help.setup - when /conf(?:ig(?:ure)?)?/; @help.configure - when /standards?/; @help.standards - when /lang(?:uage)?/; @help.languages - when /li[cs]en[sc]e/; @help.license - when /scratch/; @help.scratch - when /install/; @help.install - when /(?:--)?termsheet/; @help.termsheet - when /customise|styles?|appearance|theme/; @help.customise - when /metaverse/; @help.dal - when /(?:--)?plaintext|(?:--)?te?xt|-[aAeE]/; @help.plaintext - when /utf-?8/i; @help.utf8 - when /(?:--)?html|-[hH]/; @help.html - when /css/; @help.css - when /(?:--)?xhtml|-b/; @help.xhtml - when /(?:--)?xml|-[xX]/; @help.xml - when /(?:--)?odf|(?:--)?odt|opendocument|-o/; @help.odf - when /(?:--)?epub|-e/; @help.epub - when /php/; @help.php - when /(?:--)?pdf|-p/; @help.pdf - when /latex|tex/; @help.latex - when /(tex)?info/; @help.texinfo - when /lout/; @help.lout - when /concordance|index|-w/; @help.concordance - when /search\b/; @help.help_search - when /(?:hyper)?est(?:raier)?/; @help.hyperestraier - when /db|database|sql|postgresql|(?:--)?sqlite|(?:--)?pg|pg?sql|-[dD]/; @help.sql - when /searchform|cgi/; @help.cgi - when /convert/; @help.convert - when /(?:--)?webrick|-W/; @help.webrick - when /abstract|features|summary|about|sisu/; @help.abstract - when /ext(?:ernal)?(?:_?prog(?:rams)?)?/; @help.external_programs - when /ya?ml/; @help.yaml - when /sitemaps?/; @help.sitemap - when /(?:short)?cuts?/; @help.shortcuts - when /ansi|colors?/; SiSU_Screen::Ansi.new('c').colors - else @help.summary - end - print help_list - print help_prompt - gotten=nil - gotten=gets - end - rescue - #STDERR.puts Ansi.new($!, $@).rescue - # dies silently... for now, silence of use in connection with "sisu ~ commands" etc. - ensure - end - end - def summary - print <<-WOK - SiSU, Copyright (C) 1997 - 2013 Ralph Amissah - License GPL version 3 or Later. This program comes with ABSOLUTELY NO WARRANTY; - This is free software, and you are welcome to redistribute it under the conditions of the GPL3 or later. - For more license detail type/enter: "sisu --help license" - -for help type 'sisu --help', 'sisu --help [help request]', 'man sisu', (or see the system or online documentation) - -typing "sisu" on its own or "sisu --help", should give you this sisu help summary and the sisu (interactive help mode) help prompt, from which help on each keyword can be obtained. - -alternatively typing #{@cX.orange}sisu --help#{@cX.off} #{@cX.green}[keyword]#{@cX.off} at the command prompt will provide the sisu help page requested and return to the command prompt (if nothing is found it will print this page and return to the command prompt) - - Keywords (related to using SiSU) - #{@cX.green}help#{@cX.off} or #{@cX.green}list#{@cX.off} this sisu help summary - #{@cX.green}commands#{@cX.off} sisu --help commands - #{@cX.green}environment#{@cX.off} sisu --help env - ------------------------------------------ - Preparing Documents for SiSU - #{@cX.green}markup#{@cX.off} sisu --help markup (an incomplete overview) - #{@cX.green}headers#{@cX.off} sisu --help headers (document-wide instructions, meta-data) - #{@cX.green}structure#{@cX.off} sisu --help structure (document structure, headings, tables of contents) - #{@cX.green}endnotes#{@cX.off} sisu --help endnotes - #{@cX.green}tables#{@cX.off} sisu --help tables - #{@cX.green}example 1.0#{@cX.off} sisu --help example_v1 - #{@cX.green}example 2.0#{@cX.off} sisu --help example - ------------------------------------------ - #{@cX.green}search#{@cX.off} sisu --help search - ------------------------------------------ - #{@cX.green}customise#{@cX.off} sisu --help customise - ------------------------------------------ - SiSU's License - #{@cX.green}license#{@cX.off} sisu --help license - -for help type 'sisu --help', 'sisu --help [help request]', 'man sisu', (or see the system or online documentation) - WOK - end - def abstract - print <<-WOK -Features: -#{@cX.cyan}(i)#{@cX.off} minimal markup requirement -#{@cX.cyan}(ii)#{@cX.off} single file marked up for multiple outputs -#{@cX.cyan}(iii)#{@cX.off} markup is simpler than html -#{@cX.cyan}(iv)#{@cX.off} the simple syntax is mnemonic, influenced by mail/messaging/wiki markup practices -#{@cX.cyan}(v)#{@cX.off} human readable, and easily writable -#{@cX.cyan}(vi)#{@cX.off} multiple outputs include amongst others: html; pdf via LaTeX; (structured) XML; sql - currently PostgreSQL and sqlite; plaintext, (also texinfo) -#{@cX.cyan}(vii)#{@cX.off} all text objects (headings and paragraphs) are numbered identically, for citation purposes, in all outputs (html, pdf, sql etc.) -#{@cX.cyan}(viii)#{@cX.off} creates organised directory/file structure for output -#{@cX.cyan}(ix)#{@cX.off} easily mapped with its clearly defined structure, with all text objects numbered, you know in advance where in each document output type, a bit of text will be found (eg. from an sql search, you know where to go to find the prepared html output or pdf etc.)... there is more -#{@cX.cyan}(x)#{@cX.off} use of Dublin Core and other meta-tags to permit the addition of some semantic information on documents, and making easy integration of rdf/rss feeds etc. -#{@cX.cyan}(xi)#{@cX.off} very easily skinnable, document appearance on a project/site wide, or document instance level easily controlled/changed -#{@cX.cyan}(xii)#{@cX.off} in many cases a regular expression may be used (once in the document header) to define all or part of a documents structure obviating or reducing the need to provide structural markup within the document -#{@cX.cyan}(xiii)#{@cX.off} is a batch processor for handling large document sets, ... though once generated they need not be re-generated, unless changes are made to the desired presentation of a particular output type -#{@cX.cyan}(xiv)#{@cX.off} possible to pre-process, which permits the easy creation of standard form documents, and templates/term-sheets -#{@cX.cyan}(xv)#{@cX.off} extremely modular, (thanks in no small part to Ruby) another output format required, write another module.... -#{@cX.cyan}(xvi)#{@cX.off} easy to update output formats (eg html, xhtml, latex/pdf produced can be updated in program and run against whole document set) -#{@cX.cyan}(xvii)#{@cX.off} easy to add, modify, or have alternative syntax rules for input, should you need to -#{@cX.cyan}(xviii)#{@cX.off} "Concordance" wordmap, consisting of all the words in a document and their (text object) locations within the text -#{@cX.cyan}(xix)#{@cX.off} tied to revision control system, only code and marked up file need be backed up, to be sure of the much larger document set -#{@cX.cyan}(xx)#{@cX.off} syntax highlighting files for markup, primarily (g)vim so far. - -SiSU was developed in relation to legal documents, and so is strong across a wide variety of texts (law, literature...), though weak on formulae/statistics, it does handle images. An assumption has been document sets that are to be preserved and maintained over time (also a result of the legal text origin). SiSU has been developed and used over a number of years, and the requirements to cover a wide range of documents have been thoroughly explored. - -There is more detailed information available on it from: - #{@cX.blue}http://www.jus.uio.no/sisu#{@cX.off} - * plaintext - * HTML - * ODT (Open Document Format text) - * EPUB - * XML (structured) - * LaTeX - * PDF (via LaTeX) - * TeXinfo - * SQL (at postgreSQL & SQLite) - WOK - end - def commands - print <<-WOK - - #{@cX.ruby}-a#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces plaintext with Unix linefeeds. Without markup, (object numbers are omitted), has footnotes at end of each para‐ graph that contains them. Modifier options available: --footnotes (default) or --endnotes and for linefeeds --unix (default) or --msdos - - #{@cX.ruby}-b#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces xhtml/XML output for browser viewing (sax parsing) - - #{@cX.ruby}-C#{@cX.off} initialise shared output directory (config files such as css and dtd files are not updated if they already exist unless modifier is used) #{@cX.ruby}-C --init=site#{@cX.off} 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. in a new markup document working directory should initialise the corresponding output directory, though SiSU will automatically do this, the first time it is run (for processing) in a given directory. - - #{@cX.ruby}-c#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} 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) - - #{@cX.ruby}-D#{@cX.off} #{@cX.green}[instruction]#{@cX.off} #{@cX.green}[filename]#{@cX.off} database instruction, see database section below - - #{@cX.ruby}-d#{@cX.off} #{@cX.green}[instruction]#{@cX.off} #{@cX.green}[filename]#{@cX.off} database instruction, see database section below [only -D currently available] - - #{@cX.ruby}-F#{@cX.off} generate examples of (naive) cgi search form for sqlite and pgsql depends on your already having used sisu to populate an sqlite and/or pgsql database, (the sqlite version scans the output directories for existing sisu_sqlite databases, so it is first necessary to create them, before generating the search form) see -d -D and the database section below. If the optional parameter webrick is passed, the cgi examples created will be set up to use the default port set for use by the webrick server, (otherwise the port is left blank and the system setting used, usually 80). The samples are dumped in the present work directory which must be writable, (with screen instructions given that they be copied to the cgi-bin directory). - - #{@cX.ruby}-H#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces html (css version) (creates html (using css)), with url link suffixes (.html .pdf etc.) omitted ("Hide"). For web servers that are confireud so as not to require file extensions to locate and serve files. [behaviour switched see -h] - - #{@cX.ruby}-h#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces html (hardlinks i.e. with name suffixes in links/local urls). html, with internal document links that include the document suffix, ie whether it is .html or .pdf (required for browsing directly off a file system, and works with most web servers). [behaviour switched see -H] - - #{@cX.ruby}-I#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces texinfo file with its myriad of possibilities - - #{@cX.ruby}-L#{@cX.off} prints license information - - #{@cX.ruby}-M#{@cX.off} #{@cX.green}[filename/wildcard/url]#{@cX.off} maintenance mode, files created for processing are not deleted, and their locations are indicated (also see -V) - - #{@cX.ruby}-m#{@cX.off} #{@cX.green}[filename/wildcard/url]#{@cX.off} create (new)metaVerse (used in all subsequent processing). Produce a meta file, the first step in processing, and the file all subsequent processing utilize. (Should usually be run together with other commands to ensure that the lated version of markup source document is used, i.e. add -m flag to other flags required). - - #{@cX.ruby}-N#{@cX.off} #{@cX.green}[filename/wildcard/url]#{@cX.off} document content certificate as md5 digest tree of document produced (as digest.txt), the digest for the document, and digests for each object contained within the document (together with information on software versions that produced it). Try -mNV for verbose digest output to screen - - #{@cX.ruby}-n#{@cX.off} #{@cX.green}[filename/wildcard/url]#{@cX.off} skip meta-markup (building of "metaverse"), this skips the equivalent of -m - - #{@cX.ruby}-p#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces LaTeX pdf (portrait & landscape). 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). - - #{@cX.ruby}-q#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} quiet, less output to screen - - #{@cX.ruby}-r#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} copies sisu output files to remote host using scp (default). This requires that sisurc.yml has been provided with information on hostname and user name, and that you have your "keys" and ssh agent in place. - - #{@cX.ruby}-S#{@cX.off} #produces a sisupod, a zipped sisu directory of markup files including sisu markup source files and the directories local configuration file, images and skins. Note: this only includes the configuration files or skins contained in ./_sisu not those in ~/.sisu The resulting tar gzip file has a .zip suffix added to the markup source directory name. To tar and gzip individual files see the -Z [filename/wildcard] option. Note: (this option is tested only with zsh) - - #{@cX.ruby}-S#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces a sisupod a zipped sisu of the content assocated with the specified sisu markup documnt, i.e. including sisu markup source file, (and associated documents if a master file, or available in multilingual versions), together with related images and skin. The resulting zipped file has a .zip suffix added to the markup source file name by default, though a .ssp suffix is also recognised. The directory structure of the unzipped file is understood by sisu, and sisu commands can be run within it. SiSU commands can be run against a sisupod contained in a local directory, or provided as a url on a remote site. As there is a security issue with skins provided by other users, they are not applied unless the flag --trust or --trusted is added to the command instruction, it is recommended that file that are not your own are treated as untrusted. This provides a convenient way of packing documents files for sending Note: if you wish to send multiple files, it quickly becomes more space efficient to tar and gzip the sisu markup directory, (without the _sisu_processing subdirectory) rather than the individual files for sending). See the -S option without [filename/wildcard] - - #{@cX.ruby}-T#{@cX.off} #{@cX.green}[filename/wildcard (*.termsheet.rb)]#{@cX.off} standard form document builder, preprocessing feature - - #{@cX.ruby}-t#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces plaintext with Unix linefeeds. Without markup, (object numbers are omitted), has footnotes at end of each para‐ graph that contains them. Modifier options available: --footnotes (default) or --endnotes and for linefeeds --unix (default) or --msdos - - #{@cX.ruby}-U#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} prints url list/map for the available processing flags options and resulting files that could be requested, (can be used to get a list of processing options in relation to a file, together with information on the output that would be produced), -u provides url mapping for those flags requested for processing. The default assumes sisu_webrick is running and provides webrick url mappings where appropriate, but these can be switched to file system paths in sisurc.yml - - #{@cX.ruby}-u#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} provides url mapping of output files for the flags requested for processing, also see -U - - #{@cX.ruby}-V#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} on its own provides SiSU version and environment information (sisu --help env) - - #{@cX.ruby}-V#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} even more verbose than -v the -V flag provides some additional information, also see -M - - #{@cX.ruby}-v#{@cX.off} on its own, provides SiSU version information. - - #{@cX.ruby}-v#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} provides more 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 - - #{@cX.ruby}-X#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces XML output with deep document structure, in the nature of dom - - #{@cX.ruby}-x#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces XML output (sax parsing) - - #{@cX.ruby}-W#{@cX.off} #{@cX.green}[port]#{@cX.off} starts ruby´s webrick webserver, points at sisu output directories (default port is set) - - #{@cX.ruby}-w#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces concordance, a rudimentary index of all the words in a document - - #{@cX.ruby}-Z#{@cX.off} Zap, if used with other processing flags #{@cX.green}deletes output files#{@cX.off} of the type about to be processed, prior to processing. If -Z is used as the lone processing related flag (or in conjunction with a combination of -[mMvVq]), will remove the related document output directory. - - #{@cX.ruby}-z#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} produces php (zend) [feature disabled, depreciated] - - #{@cX.ruby}--harvest#{@cX.off} #{@cX.green}*.ss[tm]#{@cX.off} makes two lists of sisu output based on the sisu markup documents in a directory: list of author and authors works (year and titles), and; list by topic with titles and author. Makes use of header metadata fields (author, title, date, topic_register). Can be used with -M and -R flags. - - #{@cX.ruby}databases#{@cX.off} - - #{@cX.ruby}dbi - database interface -D or --pgsql set for postgresql -d or --sqlite set for sqlite#{@cX.off} - - #{@cX.ruby}-D#{@cX.off} #{@cX.ruby}--create#{@cX.off} creates empty postgresql db and required tables & indexes (rb.dbi) [#{@cX.ruby}-d --create#{@cX.off} sqlite equivalent] it may be necessary to first run sisu #{@cX.ruby}-D#{@cX.off} #{@cX.ruby}--createdb#{@cX.off} - - #{@cX.ruby}-Di#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} or #{@cX.ruby}-D#{@cX.off} #{@cX.ruby}--import#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} imports data specified to postgresql db (rb.dbi) [#{@cX.ruby}-d --import#{@cX.off} sqlite equivalent] - - #{@cX.ruby}-Du#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} or #{@cX.ruby}-D#{@cX.off} #{@cX.ruby}--update#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} updates/imports specified data to postgresql db (rb.dbi) [#{@cX.ruby}-d --update#{@cX.off} sqlite equivalent] - - #{@cX.ruby}-D#{@cX.off} #{@cX.ruby}--remove#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} removes specified data to postgresql db (rb.dbi) [#{@cX.ruby}-d --remove#{@cX.off} sqlite equivalent] - - #{@cX.ruby}-D#{@cX.off} #{@cX.ruby}--dropall#{@cX.off} kills data" and drops (postgresql) db, tables & indexes [#{@cX.ruby}-d --dropall#{@cX.off} sqlite equivalent] - - #{@cX.ruby}-D#{@cX.off} #{@cX.ruby}--recreate#{@cX.off} kills data" and drops (postgresql or sqlite) db, tables & indexes, then creates an empty db with tables and indexes [#{@cX.ruby}-d --recreate#{@cX.off} sqlite equivalent] - - also see command #{@cX.green}shortcuts#{@cX.off}, and shorthand mappings for multiple flags - WOK - end - def shortcuts - cf_defaults=SiSU_Env::InfoProcessingFlag.new - print <<-WOK - - #{@cX.ruby}Shorthand for multiple flags#{@cX.off} - - #{@cX.ruby}--update#{@cX.off} #{@cX.green}[filename/wildcard]#{@cX.off} Checks existing file output and runs the flags required to update this output. This means that if only html and pdf output was requested on previous runs, only the -hp files will be applied, and only these will be generated this time, together with the summary. This can be very convenient, if you offer different outputs of different files, and just want to do the same again. - - #{@cX.ruby}-0#{@cX.off} to #{@cX.ruby}-5#{@cX.off} #{@cX.green}[filename or wildcard]#{@cX.off} - #{@cX.green}Default shorthand mappings#{@cX.off} (note that the defaults can be changed in the #{@cX.green}sisurc.yml#{@cX.off} file): - - (these can be turned off if unavailable in sisurc.yml under program_set:) - #{@cX.green}processing shortcut defaults set to:#{@cX.off} - color defaut set (on==true) #{@cX.blue}#{cf_defaults.color}#{@cX.off} - sisu -0 (also just "sisu") #{@cX.blue}#{cf_defaults.cf_0}#{@cX.off} - sisu -1 #{@cX.blue}#{cf_defaults.cf_1}#{@cX.off} - sisu -2 #{@cX.blue}#{cf_defaults.cf_2}#{@cX.off} - sisu -3 #{@cX.blue}#{cf_defaults.cf_3}#{@cX.off} - sisu -4 #{@cX.blue}#{cf_defaults.cf_4}#{@cX.off} - sisu -5 #{@cX.blue}#{cf_defaults.cf_5}#{@cX.off} - defaults may be changed in active sisurc.yml file under 'flag:' - - add -v for verbose mode and -c (color toggle), e.g. - WOK - end - def modifiers - print <<-WOK - - #{@cX.ruby}Command flag modifiers#{@cX.off} - - #{@cX.ruby}--no-ocn#{@cX.off} [with -h -H or -p] switches off object citation numbering. Produce output without identifying numbers in margins of html or LaTeX/pdf output. - - #{@cX.ruby}--no-annotate#{@cX.off} strips output text of editor endnotes~[* square brackets ]~ denoted by asterisk or dagger/plus sign - - #{@cX.ruby}--no-asterisk#{@cX.off} strips output text of editor endnotes~[* square brackets ]~ denoted by asterisk - - #{@cX.ruby}--no-dagger#{@cX.off} strips output text of editor endnotes~[+ square brackets ]~ denoted by dagger/plus sign - - WOK - end - def misc - <<-WOK - #{@cX.cyan}misc#{@cX.off} - #{@cX.green}-s#{@cX.off} [filename or wildcard] #{@cX.green}spellcheck#{@cX.off} (aspell previously ispell - \t#{@cX.green}mailer examples#{@cX.off} - from vim mail.er10 (not gvim) issue command - \t:! ruby -S mailer.rb instruction/landscape|a4l|portrait|a4p/ email@address/alias subject line - \t:! ruby -S mailer.rb a4l ralph@amissah.com testing continues - from vim mail.er10 use your vim alias \\mail or \\mutt (modify command line as required) - #{@cX.green}feeds rss/rdf#{@cX.off} - #{@cX.blue}-R #{@cX.off} (yaml|rss) extraction of semantic data into yaml file for auto build of xml feeds (rss, rdf) #{@cX.fuschia}[work area]#{@cX.off} - #{@cX.green}-R #{@cX.off} yaml extraction of semantic data into yaml file for auto build of xml feeds (rss, rdf) - #{@cX.green}-R #{@cX.off} rss creates rss2.0 feed - WOK - end - def markup - print <<-WOK -sisu - Note: files for SiSU should be in UTF-8 character encoding. - - #{@cX.cyan}Data text markup#{@cX.off} (alternative to available html subset) - #{@cX.green}% SiSU 4.00#{@cX.off} [statement on first line of document, declared file-type identifier, SiSU markup document - - #{@cX.green}A~#{@cX.off} heading/title [levels A to C available (and beneath that 1 to 6)] - - #{@cX.green}1~#{@cX.off}filename heading [segmentation level, levels 1 to 6 available] - - #{@cX.green}!{#{@cX.off}emphasis#{@cX.green}}!#{@cX.off} - #{@cX.green}*{#{@cX.off}bold text#{@cX.green}}*#{@cX.off} - #{@cX.green}_{#{@cX.off}underscore#{@cX.green}}_#{@cX.off} - #{@cX.green}/{#{@cX.off}italics#{@cX.green}}/#{@cX.off} - #{@cX.green}"{#{@cX.off}citation#{@cX.green}}"#{@cX.off} - #{@cX.green}^{#{@cX.off}superscript#{@cX.green}}^#{@cX.off} - #{@cX.green},{#{@cX.off}subscript#{@cX.green}},#{@cX.off} - #{@cX.green}+{#{@cX.off}inserted text#{@cX.green}}+#{@cX.off} - #{@cX.green}-{#{@cX.off}strikethrough#{@cX.green}}-#{@cX.off} - - ------------------------------------------ - #{@cX.cyan}Indentation and bullets#{@cX.off} - - #{@cX.green}_1#{@cX.off} indent paragraph one level - - #{@cX.green}_2#{@cX.off} indent paragraph two steps - - #{@cX.green}_*#{@cX.off} bullet text - - #{@cX.green}_1*#{@cX.off} bullet text, first indent - - ------------------------------------------ - #{@cX.cyan}Numbered List#{@cX.off} (not to be confused with headings/titles, (document structure)) - - #{@cX.green}##{@cX.off} numbered list numbered list 1., 2., 3, etc. - - #{@cX.green}_##{@cX.off} numbered list numbered list indented second level a., b., c., d., etc. - - ------------------------------------------ - #{@cX.cyan}Endnotes#{@cX.off} - - #{@cX.green}~{#{@cX.off}footnote/endnote#{@cX.green}}~#{@cX.off} endnote#{@cX.green}~{#{@cX.off}self contained endnote marker & endnote in one#{@cX.green}}~#{@cX.off} - #{@cX.green}~{*#{@cX.off}asterisk footnote/endnote#{@cX.green}}~#{@cX.off} - editor's annotations, square bracket notes - #{@cX.green}~[*#{@cX.off}numbered asterisk footnote/endnote series#{@cX.green}]~#{@cX.off} - #{@cX.green}~[+#{@cX.off}numbered dagger/plus sign footnote/endnote series#{@cX.green}]~#{@cX.off} - --- - alternative endnote pair notation - #{@cX.green}~^#{@cX.off} endnote marker - #{@cX.green}^~#{@cX.off} endnote text following the paragraph in which the marker occurs - - ------------------------------------------ - #{@cX.cyan}Links#{@cX.off} - - http://url.org on its own would be automatically marked up and hyperlinked to itself - #{@cX.green}{#{@cX.off} [text to link] #{@cX.green}}#{@cX.off}http://url.org - #{@cX.green}{#{@cX.off}image.png#{@cX.green}}#{@cX.off}http://url.org - #{@cX.green}{#{@cX.off}image.png#{@cX.green}}#{@cX.off}image #{@cX.green}{#{@cX.off}tux.png 64#{@cX.green}x#{@cX.off}80#{@cX.green}}#{@cX.off}image - Linked image example - #{@cX.green}{#{@cX.off} SiSU Geek Writer #{@cX.green}}#{@cX.off}http://www.jus.uio.no/sisu/ url example - #{@cX.green}{#{@cX.off}tux.png 64#{@cX.green}x#{@cX.off}80 "a better way" #{@cX.green}}#{@cX.off}http://www.jus.uio.no/sisu/ image example with all options (width x height) - Note: png and jpg support only (no gif support) - - shortcut - hyper-linked text with endnote providing the url information - #{@cX.green}{~^#{@cX.off} [text to link] #{@cX.green}}#{@cX.off}http://url.org maps to #{@cX.green}{#{@cX.off} [text to link] #{@cX.green}}#{@cX.off}http://url.org #{@cX.green}~{#{@cX.off} http://url.org #{@cX.green}}~#{@cX.off} - produces hyper-linked text within a document/paragraph, with an endnote providing the url for the text location used in the hyperlink - - shortcut: - #{@cX.green}{#{@cX.off} [text to link] #{@cX.green}[3sS]}#{@cX.off}markup_source_filename.sst - if a server host name has been provided/configured, will provide a list of available output types that would be generated using the shortcut command and the markup file provided, i.e. output generated using the command (as configured): - "sisu -3sS markup_source_filename.sst" - using server host, directory stub, filename to compose the link. - - ------------------------------------------ - adding fixed names in html, manual location marker/tagging - #{@cX.green}*~[name]#{@cX.off} <a name="[name]"> - - ------------------------------------------ - #{@cX.green}~##{@cX.off} unnumbered paragraph (place marker at end of paragraph) - #{@cX.green}-##{@cX.off} unnumbered paragraph, delete when not required (place marker at end of paragraph) [used in dummy headings, eg. for segmented html] - - ------------------------------------------ - manual page breaks (LaTeX/pdf) - #{@cX.green}<:pb>#{@cX.off} page break, which breaks a page, starting a new page in single column text and a new column in double column text - #{@cX.green}<:pn>#{@cX.off} page new, which starts a new page, in both single and double column text (leaving an empty column in double column text if necessary). - Note: page breaks are usually introduced to pdfs either as header instructions, indicating that pages should break at given levels - - ------------------------------------------ - #{@cX.cyan}Composite documents#{@cX.off} - - It is possible to build a document by creating a master document that requires other documents. The documents required may 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 mainly from other documents), it should be named with the suffix #{@cX.blue}.ssm#{@cX.off} 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 #{@cX.blue}.sst#{@cX.off} regular markup file, or #{@cX.blue}.ssi#{@cX.off} (insert/information) A secondary file of the composite document is built prior to processing with the same prefix and the suffix #{@cX.blue}.ssm.sst#{@cX.off} - - #{@cX.cyan}#basic sisu markup alternatives#{@cX.off} - #{@cX.green}{#{@cX.off}filename.ssi#{@cX.green}}require#{@cX.off} - #{@cX.green}<< {#{@cX.off}filename.ssi#{@cX.green}}#{@cX.off} - - #{@cX.cyan}#using textlink alternatives#{@cX.off} - #{@cX.green}|#{@cX.off}filename.ssi#{@cX.green}|@|^|require#{@cX.off} - #{@cX.green}<< |#{@cX.off}filename.ssi#{@cX.green}|@|^|#{@cX.off} - - #{@cX.cyan}#using thlnk alternatives#{@cX.off} - #{@cX.green}<url:#{@cX.off}filename.ssi#{@cX.green}>require#{@cX.off} - #{@cX.green}<< <url:#{@cX.off}filename.ssi#{@cX.green}>#{@cX.off} - - #{@cX.cyan}Composite documents - remote parts#{@cX.off} - Composite documents may be built from remote parts, by using the composite document syntax with a url. This makes sense using either sisu regular syntax (which is just a convenient way of marking up), or thlnk syntax, which also recognises remote urls, and permits hyperlinking ascii to the url location. - - #{@cX.cyan}Remote documents#{@cX.off} - SiSU will download and process remote locations if a url is provided instead of a filename. [this at present works only for sisu markup files without images] - - ------------------------------------------ - #{@cX.green}%#{@cX.off}#{@cX.off} add a comment to text, that will be removed prior to processing (place marker at beginning of line) - #{@cX.green}\\#{@cX.off}#{@cX.off} escape a sepcial character, whether general: { } < > or contextual special characters, (in combination with other characters) ~ - _ / % ^ and occasionally ! # + , - #{@cX.green}%%#{@cX.off}#{@cX.off} same as above but recognised by vim folds for placing fold in document text, in addition to headers and headings - ------------------------------------------ - - #{@cX.ruby}More HELP on Markup#{@cX.off} markup help is available on: - document wide instructions: headers (document structure) - general text markup: headings; endnotes; tables (which also includes a note on preformatted text) - configuration and customisation - document or site wide customisation: customise; skin - WOK - help_markup - end - def example - help_markup - end - def example_v1 - print <<-WOK -% SiSU 1.0 - -@title: Working Sample Document - -@subtitle: Demonstrating markup - -@creator: Ralph Amissah - -@date: - -@markup: num_top=4 - -@bold: [regular expression of words/phrases to be made bold] - -@italics: [regular expression of words/phrases to italicise] - -@links: { SiSU }http://www.jus.uio.no/sisu { FSF }http://www.fsf.org - -A~ A Sample Document - -B~ just for fun - -1~ This is Chapter One or Article One - -Ordinary Text follows here. The Title would be a Chapter or Article depending on the type of document you were working to produce. - -1~ This would be Chapter Two or Article Two - -And so on. - -Assuming sisu is configured properly so it has been instructed where to put the work files and ouput files, you would generate this text once saved, with the suffix .sst if saved as example.sst, by typing sisu -mhwxp example.sst while in the directory in which the file is saved. - -_1 -m initial processing, -h html (css based), -w concordance for html, -x xml, -p pdf output, generated via latex, there are of course additional options - -_1 for a listing type: sisu ~ commands - -_1 for an outline of sisu markup type: sisu ~ markup - -The example ends here. - WOK - help_markup - end - def example_v2 - print <<-WOK -% SiSU 2.0 - -@title: Working Sample Document - :subtitle: Demonstrating markup - -@creator: - :author: Amissah, Ralph - -@date: - :published: 2010-09-18 - -@rights: - :copyright: Ralph Amissah - -@make: - :num_top: 1 - :bold: [regular expression of words/phrases to be made bold] - :italics: [regular expression of words/phrases to italicise] - -@links: - { SiSU }http://www.jus.uio.no/sisu { FSF }http://www.fsf.org - -A~ @title @author - -B~ just for fun - -1~ This is Chapter One or Article One - -Ordinary Text follows here. The Title would be a Chapter or Article depending on the type of document you were working to produce. - -1~ This would be Chapter Two or Article Two - -And so on. - -Assuming sisu is configured properly so it has been instructed where to put the work files and ouput files, you would generate this text once saved, with the suffix .sst if saved as example.sst, by typing sisu -mhwxp example.sst while in the directory in which the file is saved. - -_1 --dal initial processing, --html (css based), --concordance (html), --epub, --odt, --pdf output, generated via LaTeX, there are of course additional options - -_1 for a listing type: sisu ~ commands - -_1 for an outline of sisu markup type: sisu ~ markup - -The example ends here. - WOK - help_markup - end - def headers - print <<-WOK -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 #{@cX.green}@headername:#{@cX.off} followed on the next line by an indented sub-category header if any #{@cX.green}:sub-headername:#{@cX.off}. -#{@cX.green}@indentifier:#{@cX.off} information or instructions -where the #{@cX.green}"identifier"#{@cX.off} is a tag recognised by the program, and the #{@cX.green}"information"#{@cX.off} or #{@cX.green}"instructions"#{@cX.off} belong to the tag/indentifier specified - Note: a header where used should only be used once; all headers apart from #{@cX.ruby}@title:#{@cX.off} are optional. - -#{@cX.ruby}@title:#{@cX.off} My Title - This is now the Title of the Document and used as such - #{@cX.cyan}:subtitle:#{@cX.off} The Subtitle if any - -#{@cX.ruby}@creator:#{@cX.off} - #{@cX.cyan}:author:#{@cX.off} Surname, Other names (if more than one author separate author names with a semi colon, if name is of an institution just write name or the name contains a comma enclose in quotation marks) - #{@cX.cyan}:contributor:#{@cX.off} - #{@cX.cyan}:translator:#{@cX.off} [or :translated_by:] - #{@cX.cyan}:illustrator:#{@cX.off} [or :illustrated_by:] - #{@cX.cyan}:prepared_by:#{@cX.off} [or :digitized_by:] - -#{@cX.ruby}@date:#{@cX.off} - #{@cX.cyan}:published:#{@cX.off} - #{@cX.cyan}:created:#{@cX.off} - #{@cX.cyan}:issued:#{@cX.off} - #{@cX.cyan}:available:#{@cX.off} - #{@cX.cyan}:valid:#{@cX.off} - #{@cX.cyan}:modified:#{@cX.off} - -#{@cX.ruby}@rights:#{@cX.off} - #{@cX.cyan}:copyright:#{@cX.off} Author's name, all rights reserved - #{@cX.cyan}:license:#{@cX.off} public domain, copyleft, creative commons variant, etc. - -#{@cX.ruby}@classify:#{@cX.off} - #{@cX.cyan}:topic_register:#{@cX.off} [e.g.:] text markup language; application:text processing;output:html|xml|latex|pdf|sql - #{@cX.cyan}:subject:#{@cX.off} (whatever your subject) - #{@cX.cyan}:keywords:#{@cX.off} - #{@cX.cyan}:loc:#{@cX.off} [Library of Congress classification] - #{@cX.cyan}:dewey:#{@cX.off} [Dewey classification] - -#{@cX.ruby}@identifier:#{@cX.off} - #{@cX.cyan}:isbn:#{@cX.off} - #{@cX.cyan}:oclc:#{@cX.off} - -#{@cX.ruby}@notes:#{@cX.off} - #{@cX.cyan}:description:#{@cX.off} - #{@cX.cyan}:abstract:#{@cX.off} - #{@cX.cyan}:comment:#{@cX.off} - #{@cX.cyan}:coverage:#{@cX.off} - #{@cX.cyan}:relation:#{@cX.off} - #{@cX.cyan}:source:#{@cX.off} - #{@cX.cyan}:history:#{@cX.off} - #{@cX.cyan}:type:#{@cX.off} - #{@cX.cyan}:format:#{@cX.off} - #{@cX.cyan}:prefix:#{@cX.off} - #{@cX.cyan}:suffix:#{@cX.off} - -#{@cX.ruby}@publisher:#{@cX.off} - -#{@cX.ruby}@language:#{@cX.off} [or @language.document:] [country code for language if available, or language, English, en is the default setting] (en - English, fr - French, de - German, it - Italian, es - Spanish, pt - Portuguese, sv - Swedish, da - Danish, fi - Finnish, no - Norwegian, is - Icelandic, nl - Dutch, et - Estonian, hu - Hungarian, pl - Polish, ro - Romanian, ru - Russian, el - Greek, uk - Ukranian, tr - Turkish, sk - Slovak, sl - Slovenian, hr - Croatian, cs - Czech, bg - Bulgarian ) [however, encodings are not available for all of the languages listed.] - -#{@cX.ruby}@language.original:#{@cX.off} -original language in which the work was published - -#{@cX.ruby}@links:#{@cX.off} - { SiSU }http://www.jus.uio.no/sisu/ - { FSF }http://www.fsf.org - -#{@cX.ruby}@make:#{@cX.off} - #{@cX.cyan}:breaks:#{@cX.off} new=:B; break=1 - #{@cX.cyan}:bold:#{@cX.off} [regular expression of words/phrases to be made bold] - #{@cX.cyan}:italics:#{@cX.off} [regular expression of words/phrases to italize] - #{@cX.cyan}:home_button_image:#{@cX.off} {free_as_in_freedom.png }http://stallman.org/ - #{@cX.cyan}:home_button_text:#{@cX.off} {Free Culture}http://www.free-culture.cc; {Lawrence Lessig}http://www.lessig.org - #{@cX.cyan}:footer:#{@cX.off} {Free Culture}http://www.free-culture.cc; {Lawrence Lessig}http://www.lessig.org - #{@cX.cyan}:headings:#{@cX.off} PART; CHAPTER; Section; Article; - #{@cX.grey}% 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#{@cX.off} - #{@cX.cyan}:papersize:#{@cX.off} (A4|US_letter|book_B5|book_A5|US_legal) - #{@cX.cyan}:markup:#{@cX.off} num_top=4 [various markup instructions, eg: num_top=4 headings tobe numbered, starting at heading level 4... the default is to provide 3 levels, as in 1 level 4, 1.1 level 5, 1.1.1 level 6, markup to be merged within level] - #{@cX.cyan}:promo:#{@cX.off} sisu, ruby, search_libre_docs, open_society [places content in right pane in html, makes use of list.yml and promo.yml, commented out sample in document sample: free_as_in_freedom.richard_stallman_crusade_for_free_software.sam_williams.sst] - -#{@cX.grey}% header ends here, NB only @title: is mandatory [this would be a comment]#{@cX.off} - -#{@cX.blue}A~#{@cX.off} Top level heading [this is usually the same as the title @title: ] - -#{@cX.blue}B~#{@cX.off} Second level heading [this is a heading level divider] - -#{@cX.blue}C~#{@cX.off} Third level heading [this is a heading level divider] - -#{@cX.blue}1~#{@cX.off} Top level heading preceding substantive text of document or sub-heading 5, the heading level that would normally be marked 1. or 2. or 3. etc. in a document - -#{@cX.blue}2~#{@cX.off} Second level heading preceding substantive text of document or sub-heading 6, the heading level that would normally be marked 1.1 or 1.2 or 1.3 or 2.1 etc in a document - -#{@cX.blue}3~#{@cX.off} 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 - - WOK - help_markup - end - def customise - print <<-WOK - There are a number of files that control the appearance of a site or a document i.e. - - #{@cX.blue}(i)#{@cX.off} files that control #{@cX.green}site-wide appearance#{@cX.off}: - - #{@cX.green}defaults.rb#{@cX.off} initial values used by program, not necessary to change - - skins are placed in a configuration directory beneath the markup directory ./_sisu/skin/doc or in ~/.sisu/skin/doc - if a skin is also to be used for a directory or site wide presentations, rather than being called for a single document then a softlink is placed from ~/.sisu/skin/dir or ~/.sisu/skin/site respectively to the relevant skin within ~/.sisu/skin/doc - - rules for skin loading are in #{@cX.green}sysenv.rb#{@cX.off} - the skin loading heuristics / hierarchy is currently as follows: - - a. if there is a skin requested within a document, thent that skin is used - 0~skin skin_lm (would load skin ~/.sisu/skin/doc/skin_lm.rb) - - b. use it if there is a "dir" skin with the same name as the source directory "stub" i.e. - if working in a directory called /home/myhome/workdir/lm - then if ~/.sisu/skin/dir/skin_lm.rb were found it would be used and skin_lm.rb would be a softlink to the relevant skin in the document skin directory (where all the actual skins are kept) - - x. [additionally though discouraged a special rule can be set up in sysenv AddSkin.select (which could override b if desired)] - - #{@cX.green}skin_site_#{@cX.off}#{@cX.cyan}[name of site skin in use]#{@cX.off}#{@cX.green}.rb#{@cX.off} this file is called by skin.rb - if there are several such files, site appearance may be changed by - requesting the skin_site desired from skin.rb - and - - #{@cX.blue}(ii)#{@cX.off} presentation maintenance: - if you have a body of documents the easiest way to give them a particular appearance/skin, is to associate that directory with a skin, all files in that directory take on the specified appearance, changing appearance of documents once directories are set up is as simple as copying the files from one directory to another (or renaming the directory); or associating the directory with a different skin. - - see also directories - WOK - end - def configure - print <<-WOK - see the following topics - install - setup - and note for initial configuration it is necessary to run: - sisu -C - (this places the default CSS files and DTDs in place) - WOK - end - def path - help_env - puts <<-WOK - -If you have problems check permissions (and if in home directory ownership). - -#{@cX.green}directory paths as currently set#{@cX.off}: - output docs: #{@cX.blue}#{@env.path.webserv}#{@cX.off} - cgi scripts: #{@cX.blue}#{@env.path.cgi}#{@cX.off} - processing: #{@cX.blue}#{@env.processing_path.processing}#{@cX.off} - sisu meta markup: #{@cX.blue}#{@env.processing_path.dal}#{@cX.off} - html tuning: #{@cX.blue}#{@env.processing_path.tune}#{@cX.off} - latex: #{@cX.blue}#{@env.processing_path.tex}#{@cX.off} - texinfo: #{@cX.blue}#{@env.processing_path.texi}#{@cX.off} - images: - source: #{@cX.blue}#{@env.path.image_source}#{@cX.off} - latex source: #{@cX.blue}#{@env.path.image_source_include}#{@cX.off} - note images are also sourced from within your pwd - #{@cX.blue}#{Dir.pwd}/_sisu/image#{@cX.off} if it exists - #{@cX.grey}[ texinfo: #{@env.processing_path.texinfo} - check duplication ]#{@cX.off} - - #{@cX.green}resource configuraton files#{@cX.off} to change the paths specified above, are searched for in the following order: - under the current SiSU markup data directory: #{@cX.blue}#{Dir.pwd}/_sisu/sisurc.yml#{@cX.off} - under the home directory ~/.sisu: #{@cX.blue}#{@env.path.home}/.sisu/sisurc.yml#{@cX.off} - in the "/etc" directory: #{@cX.blue}#{@env.path.etc}/sisurc.yml#{@cX.off} - default file paths are set by the program SiSU - - #{@cX.green}skins#{@cX.off} for document appearances on a site, directory or per document basis are located in subdirectories #{@cX.blue}doc/#{@cX.off} #{@cX.blue}dir/#{@cX.off} and #{@cX.blue}site/#{@cX.off} within: - #{@cX.blue}#{Dir.pwd}/_sisu/skin#{@cX.off} - #{@cX.blue}#{@env.path.home}/.sisu/skin#{@cX.off} - #{@cX.blue}#{@env.path.etc}/skin#{@cX.off} - default appearances are set by the program SiSU in the absence of skins - - #{@cX.green}Note on subdirectories for output documents#{@cX.off} - The last part of the name of the directory you choose to work from is used as the major sub-directory in which output files are placed, - i.e. if you are working in a directory called #{@cX.blue}#{@env.path.home}/ebook#{@cX.off} - the output files will be placed in a sub-directory named after the processed text within #{@cX.blue}#{@env.path.webserv}/ebook#{@cX.off} - ( Within this major sub-directory, a sub-directory is made with the name of each document processed, into which output files - html, pdf, xml, plaintext etc. are placed (texinfo being an exception at present) ) - - #{@cX.green}sisu -C#{@cX.off} [#{@cX.green}--init=site#{@cX.off}] configure/initialise shared output directory files initialize shared output directory (config files such as css and dtd files are not updated if they already exist unless modifier is used). -C --init=site configure/initialise site more extensive than -C on its own, shared output directory files/force update, existing shared output config files such as css and dtd files are updated if this modifier is used. in a new markup document working directory should initialise the corresponding output directory, though SiSU will automatically do this, the first time it is run (for processing) in a given directory. - - There are additional details, ... this should get you started. - - See also - sisu --help directory - WOK - help_env - end - def directories - help_env - print <<-WOK - - the directory structure used by sisu is controlled by the configuration files #{@cX.blue}sisurc.yml#{@cX.off} - - there are separate directories for the following: - - (a) #{@cX.green}data directories#{@cX.off} - the directories in which you place the SiSU marked-up data files that are to be processed - there may be as many directories and files as you choose to have, - you are currently in: #{@cX.blue}#{Dir.pwd}#{@cX.off} - - (b) #{@cX.green}output directory#{@cX.off} - by default files in the data directory are output to - a sub-directory within the output directory (usually the web document directory), or to an sql database - of the same name as the stub or last portion of the data directory name - by way of example - you are currently in: #{@cX.blue}#{Dir.pwd}#{@cX.off} - the document output directory is set to: #{@cX.blue}#{@env.path.webserv}#{@cX.off} - documents from your current directory will be placed in: #{@cX.blue}#{@env.path.output}#{@cX.off} - - the final output is placed in subdirectories either as configured by default in the program or as modified by SiSU configuration files - subdirectories are created within the main output directory, based on the name of the data directory - subsubdirectories are created the sub-directory contained in the main output directory based on the name of the file - (subdirectories are created in this (output) sub-directory named after the data file) - for this reason it is a convention to give descriptive names to the data file. - The default output directory is #{@cX.green}~/sisu_www#{@cX.off} - The output directory is currently set to: - #{@cX.blue}#{@env.path.webserv}#{@cX.off} - Output files, are currently set to be produced in: - processed document output: #{@cX.blue}#{@env.path.output}#{@cX.off} - a document in the current directory #{@cX.blue}#{Dir.pwd}#{@cX.off} - will have its output placed in: #{@cX.blue}#{@env.path.output}/#{@output_stub}#{@cX.off} - - NB: the verbose flag v included in the generate command string, should - result in a list of output filenames together with their paths. - The flag U on its own (e.g. sisu -U gpl3.fsf.sst) should provide a list - of output files that could be generated together with their paths. - - (c) #{@cX.green}configuration files#{@cX.off} - SiSU program defaults are set within the program, and may be adjusted in the yml file #{@cX.blue}sisurc.yml#{@cX.off} which is searched for in the following paths, which are prioritized as listed (the first one found is loaded): -### - under the current SiSU markup data directory: #{@cX.blue}#{@env.path.pwd}/_sisu/sisurc.yml#{@cX.off} - under the home directory ~/.sisu: #{@cX.blue}#{@env.path.home}/.sisu/sisurc.yml#{@cX.off} - in the "/etc" directory: #{@cX.blue}#{@env.path.etc}/sisurc.yml#{@cX.off} - - (d) #{@cX.green}processing directories#{@cX.off} sisu creates a number of processing directories, - where these should be located can be modified in #{@cX.green}~/.sisu/sisurc.yml#{@cX.off} - work directories include the following: - root working directory #{@cX.blue}#{@env.processing_path.processing}#{@cX.off} - metaverse intermediate markup #{@cX.blue}#{@env.processing_path.dal}#{@cX.off} - tune html (for special html/navigation pages) #{@cX.blue}#{@env.processing_path.tune}#{@cX.off} - tex for latex and pdf #{@cX.blue}#{@env.processing_path.tex}#{@cX.off} - texinfo for texinfo and info files #{@cX.blue}#{@env.processing_path.texi}#{@cX.off} - - These files are usually used only for processing and removed. There is a maintenance flag to keep them. - - (e) #{@cX.green}images#{@cX.off} - there are a number of categories of images, - NB the document markup directory is initialised by issuing the command - sisu -C --init=site - this creates the output sub-directory, and makes necessary image links, and - copies images specific to the markup directory if there are any. - - general images for the sisu program that come with the package, - that are the defaults used by sisu, these are installed with the program - - images that the author wishes to include within documents, - these should be placed in a sub-directory - within the current document markup directory called #{@cX.green}_sisu/image#{@cX.off} - - if an instruction is given to process a remote document which contains - downloadable images, they are included in a sub-directory of the current - markup directory #{@cX.green}_sisu/sisu/image_external#{@cX.off} that is created - if necessary for the purpose. - - finally skins may specify/indicate other image directories. see sisu --help skin - any site images required by the skin instruction must be copied in to the - site image directory (it may be necessary to do manual configuration depending - on what you are trying to achieve). - - (f) #{@cX.green}program directories#{@cX.off} - sisu --help install - sisu ~ install - - See also - sisu --help path - WOK - help_env - end - def program_found?(program) - if program - rc=if SiSU_Env::InfoSettings.new.program?(program) - SiSU_Env::InfoSettings.new.program?(program) - else '' - end - if program =='rmagick' then program='identify' #rmagick is ruby lib uses imagemagick's identify - end - bin=if SiSU_Env::SystemCall.new.program_found?(program) - SiSU_Env::SystemCall.new.program_found?(program) - else 'false' - end - else bin,rc='false','false' - end - (program) \ - ? ("#{@cX.blue}#{program}#{@cX.off} bin: #{@cX.brown}#{bin}#{@cX.off} rc: #{@cX.brown}#{rc}#{@cX.off}") - : ("bin: #{@cX.brown}#{bin}#{@cX.off} rc: #{@cX.brown}#{rc}#{@cX.off}") - end - def sisu_version - version=SiSU_Env::InfoVersion.instance.get_version - rb_ver=SiSU_Env::InfoVersion.instance.rbversion - if version[:version] - opt_cmd=if defined? @color.cmd \ - and @color.cmd =~/[ck]/ - @color.cmd - else '-v' - end - SiSU_Screen::Ansi.new(opt_cmd,version[:project],version[:version],version[:date_stamp],version[:date],rb_ver).version - else puts 'SiSU version information not available' - end - end - def rhost - @ls=leading_spaces=' '*49 - @rhost=SiSU_Env::InfoRemoteHost.new.rhost - def r1 - (@rhost.r1) \ - ? @rhost.r1 + "\n" - : '' - end - def r2 - (@rhost.r2) \ - ? @ls + @rhost.r2 + "\n" - : '' - end - def r3 - (@rhost.r3) \ - ? @ls + @rhost.r3 + "\n" - : '' - end - def r4 - (@rhost.r4) \ - ? @ls + @rhost.r4 + "\n" - : '' - end - def r5 - (@rhost.r5) \ - ? @ls + @rhost.r5 + "\n" - : '' - end - def r6 - (@rhost.r6) \ - ? @ls + @rhost.r6 + "\n" - : '' - end - def note - msg='(remote settings user and host set in sisurc.yml under remote:)' - (@rhost.r1) \ - ? @ls + msg - : msg - end - self - end - def environment - cf_defaults=SiSU_Env::InfoProcessingFlag.new - sisu_version - x =<<-WOK - #{@cX.green}current and output directories#{@cX.off} - user: #{@cX.blue}#{@env.user}#{@cX.off} - home: #{@cX.blue}#{@env.path.home}#{@cX.off} - remote set [remote user]@[remote host]: #{@cX.blue}#{rhost.r1}#{rhost.r2}#{rhost.r3}#{rhost.r4}#{rhost.r5}#{rhost.r6}#{@cX.off}#{rhost.note} - locale (encoding, UTF-8 desired): #{@cX.blue}#{@env.locale}#{@cX.off} - current directory: #{@cX.blue}#{@env.path.pwd}#{@cX.off} - document output root directory set to: #{@cX.blue}#{@env.path.webserv}#{@cX.off} - documents from current directory placed in: #{@cX.blue}#{@env.path.output}#{@cX.off} - webrick url: #{@cX.blue}#{@env.url.webserv_base_cgi}#{@cX.off} - (to start webrick server 'sisu -W') - sqlite db for present directory: #{@cX.blue}sqlite #{@env.path.output}/sisu_sqlite.db#{@cX.off} - postgresql port set to: #{@cX.blue}#{@db.psql.port}#{@cX.off} - postgresql db for present directory: #{@cX.blue}#{@db.psql.db}#{@cX.off} - [first create manually if necessary: 'createdb #{@db.psql.db}'] - - [generated sqlite cgi search form]: #{@cX.blue}#{@env.url.webserv_base_cgi}/cgi-bin/sisu_sqlite.cgi#{@cX.off} - [generated postgresql cgi search form]: #{@cX.blue}#{@env.url.webserv_base_cgi}/cgi-bin/sisu_pgsql.cgi#{@cX.off} - (to generate 'sisu -F' or 'sisu -F webrick') - #{@cX.green}configuration files#{@cX.off} - sisurc.yml used: #{@cX.blue}#{@env.path.yamlrc}#{@cX.off} - configuration information search path: #{@cX.blue}#{@env.path.rc.join(', ')}#{@cX.off} - (directory also relevant for skins and images) - digest (md5 or sha256): #{@cX.blue}#{@env.digest.type}#{@cX.off} - papersize set (LaTeX/pdf): #{@cX.blue}#{@env.papersize}#{@cX.off} - (digest and papersize can be changed in sisurc.yml under default:) - #{@cX.green}intermediate processing#{@cX.off} - processing directory: #{@cX.blue}#{@env.processing_path.processing}#{@cX.off} - (to keep processing output, use -M flag) - #{@cX.green}programs selected for viewing output#{@cX.off} - text editor: #{@cX.blue}#{@env.program.text_editor}#{@cX.off} - web browser: #{@cX.blue}#{@env.program.web_browser}#{@cX.off} - console web browser: #{@cX.blue}#{@env.program.console_web_browser}#{@cX.off} - pdf viewer: #{@cX.blue}#{@env.program.pdf_viewer}#{@cX.off} - xml viewer: #{@cX.blue}#{@env.program.xml_editor}#{@cX.off} - odf viewer: #{@cX.blue}#{@env.program.odf_viewer}#{@cX.off} - epub viewer: #{@cX.blue}#{@env.program.epub_viewer}#{@cX.off} - (default selections can be changed in sisurc.yml under program_select:) - #{@cX.green}programs used if available#{@cX.off} - word count: #{program_found?(@env.program.wc)} - imagemagick/rmagick: #{program_found?(@env.program.rmagick)} - tidy: #{program_found?(@env.program.tidy)} - rexml: #{program_found?(@env.program.rexml)} - latex to pdf: #{program_found?(@env.program.pdflatex)} - postgresql: #{program_found?(@env.program.postgresql)} - sqlite: #{program_found?(@env.program.sqlite)} - (these can be turned off if unavailable in sisurc.yml under program_set:) - #{@cX.green}processing shortcut defaults set to:#{@cX.off} - color defaut set (on==true) #{@cX.blue}#{cf_defaults.color}#{@cX.off} - sisu -0 #{@cX.blue}#{cf_defaults.cf_0}#{@cX.off} [set as default] - sisu -1 #{@cX.blue}#{cf_defaults.cf_1}#{@cX.off} - sisu -2 #{@cX.blue}#{cf_defaults.cf_2}#{@cX.off} - sisu -3 #{@cX.blue}#{cf_defaults.cf_3}#{@cX.off} - sisu -4 #{@cX.blue}#{cf_defaults.cf_4}#{@cX.off} - sisu -5 #{@cX.blue}#{cf_defaults.cf_5}#{@cX.off} - (defaults may be changed in active sisurc.yml file under flag:) - #{@cX.green}special powers, risky operations set:#{@cX.off} - zap (delete output directories) #{@cX.blue}#{SiSU_Env::InfoSettings.new.permission?('zap')}#{@cX.off} - css copy (copy over css files) #{@cX.blue}#{SiSU_Env::InfoSettings.new.permission?('css_modify')}#{@cX.off} - (true/false defaults may be changed in active sisurc.yml file under permissions_set:) - -NOTE: for HELP type 'sisu --help', 'sisu --help [help request]', 'man sisu', (or see the system or online documentation) - WOK - print x - end - def dublin_core - print <<-WOK -@title: - -@subtitle: [is added to title for purposes of Dublin Core description] - -@creator: - -@type: - -@subject: - -@date: [ccyy-mm-dd] - -@date.created: - -@date.issued: - -@date.available: - -@date.valid: - -@date.modified: - -@source: - -@language: en - -@papersize: A4 - -@relation: - -@coverage: - -@rights: - - WOK - end - def headings - print <<-WOK -These are not required, a header is quicker to prepare if a documents structure can be defined by matching words or a regular expression, see headers). - -@structure: PART; CHAPTER; SECTION; ARTICLE; none; none; - -structure can be defined by a match words or regular expression (the regular expression is assumed to start at the beginning of a line of text i.e. ^) - -The following heading or level (structuring) defaults are available (for use instead of or together with @structure: header): - - A~ B~ C~ 1~ 2~ 3~ - -Heading tags take either of the forms above, ranging from 1-6 - -They appear at the beginning of the line on which a heading appears, -the number indicates the level of the heading with level 1 being a title, - -segments (in html output) are by default created on level 4 -(segmented text is split/segmented on level 4, and -assigned a file name automatically according to the title number, -unless you explicitly specify otherwise) - -A~ Document Title - -B~ Document Subtitle whatever it is - -C~ Part - -1~ Chapter - -2~ Heading - -3~ sub-heading - -Normal text would follow each heading level as appropriate, though it is most usual to start with ordinary writing beneath level 4 as it is at this level that segments are created. - -Automatic numbering of paragraphs is usually set to start at level 4 trough level 6 and takes the form 1. then 1.1 then 1.1.1 this being given as a Header tag 0~ There may be up to 6 levels in a document, - -If auto-numbering is on, then for html output the segments created (on level 4 headings) are automatically assigned the name of the title number. -However, you may indicate an alternative set of key/title words, with one of the following instructions: -4~filename This is a Section or Subject Heading - -If there is a strictly discernable word appearing at the beginning of the line in a document that identifies the level, -the words can be used to identify the levels in a header tag: -0~toc Part; Chapter; Section; Article; none; none -instead of providing individual heading tags - -sisu structure, notation, A,B,C,1,2,3 - - SiSU has in effect two sets of levels to be considered - - A-C pre-ordinary paragraphs /pre-substantive text, and - - 1-3 levels which are followed by ordinary text. - - This may be conceptualised as levels A,B,C, 1,2,3, and using such letter number notation, in effect: - - A must exist, optional B and C follow in the sequence - - 1 must exist, optional 2 and 3 follow in the sequence - - i.e. there are two independent heading level sequences A,B,C and 1,2,3 or using the standard notation 1,2,3 and 4,5,6 - -on the positive side: (a) the A,B,C,1,2,3 alternative makes explicit an aspect of structuring documents in SiSU that is not otherwise obvious to the newcomer (though it appears more complicated, is more in your face and likely to be understood fairly quickly); (b) the substantive text follows levels 1,2,3 and it is 'nice' to do most work in those levels - - WOK - end - def languages - lang=SiSU_i18n::Languages.new.language.table - lang.each_value do |lng| - if lng[:t] == lng[:n] - puts "#{lng[:c]}: #{lng[:t]}" - else - puts "#{lng[:c]}: #{lng[:t]} (#{lng[:n]})" - end - end - puts <<-WOK - - Multi-language Document File Naming and Directory Mapping - - A list of language codes and languages that may be available for most output formats. These are for the most part ISO 639/1 and where there is a departure it follows those made by po4a, and the languages supported will be limited (at this time) to those supported by polyglossia. (SiSU markup text is stored in Unicode so some output formats are served by this, for example, html and sql had no problem with Chinese, pdfs would be a problem as this is not (yet?) suported by xetex and polyglossia. SiSU parses left to right and would have problems with right to left languages.) - - If the same document exists in different language versions, a directory structure, or a filenaming convention may be followed. Using Spannish as the sample language code (es) [filename]~[language code].sst - - The simplest now is to place each document in a sub-directory which has the language code as a name, if this convention is used it is preferable that all files are placed by language in the appropriate language sub-directory ... e.g. - ./en/filename.sst - ./es/filename.sst - - Alternatively files may all be placed in the same directory with the language and named using a tilde and the language code as shown: - filename~es.sst - - within sisurc.yml under the heading - default: - language file: [at 1, 2 or 3] - - determines the output filenaming convention used, as follows: - - (1) [output directory path]/filename/es.index.html - - (2) [output directory path]/filename/index.es.html - - (3) [output directory path]/filename/index.html.es (which Apache for example can be configured to use to automatically serve each users preference) - - filename~fr.sst - filename~de.sst - - etc. would be placed in the same directory using the same convention as indeed would: - filename.sst - using the default convention mapping convention. - - Selecting this form of filename will overide other language settings including the language header within a document. - - WOK - end - def endnotes - print <<-WOK - -(1) Footnote/endnotes tags take a number of possible forms, the simplest being to embed an endnote within your text~{ this would appear as an endnote, and would have an automatically assigned number }~ Embedded endnotes~{this is an endnote}~ and at the end of the paragraph~{* an asterisk marked note }~ writing the endnote:~{another endnote}~ - - ------------------------------------------ -#{@cX.ruby}All you need to know about endnotes appears above this line...#{@cX.off} apart from the fact that you cannot mix endnote markup styles - -(2) The other ways of inserting an endnote involve placing a tag within the text as to where the endnote reference number should appear like so~^ and at the end of the paragraph writing the endnote:~^ - -^~ like so, this is an endnote - -^~ another endnote - - WOK - end - def tables - print <<-WOK - -#{@cX.green}table{ [number of columns] [column width %];[column width %]#{@cX.off} - -[table content, line breaks are important see example below] - -#{@cX.green}}table#{@cX.off} -#{@cX.grey}----#{@cX.off} -This is a sample table: ------------------------ - -#{@cX.green}table{ c3; 40; 30; 30;#{@cX.off} - -This is a table -this would become column two of row one -column three of row one is here - -And here begins another row -column two of row two -column three of row two, and so on - -#{@cX.green}}table#{@cX.off} - -there is an alternative way to markup tables, a sample document is provided in the file -#{@cX.green}sisu_output_overview.sst#{@cX.off} located in -#{@cX.green}/usr/share/doc/sisu#{@cX.off} or equivalent directory - -preformatted text ------------------ - -#{@cX.green}poem{#{@cX.off} - - [Text here] - -#{@cX.green}}poem#{@cX.off} -#{@cX.grey}----#{@cX.off} - -#{@cX.green}block{#{@cX.off} - - [Text here] - -#{@cX.green}}block#{@cX.off} -#{@cX.grey}----#{@cX.off} - -#{@cX.green}group{#{@cX.off} - - [Text here] - -#{@cX.green}}group#{@cX.off} -#{@cX.grey}----#{@cX.off} - -#{@cX.green}code{#{@cX.off} - - [Text here] - -#{@cX.green}}code#{@cX.off} - - WOK - end - def modules - print <<-WOK - - #{@cX.ruby}IGNORE#{@cX.off} - - WOK - end - def install #% system configuration - print <<-WOK - #{@cX.green}Install SiSU#{@cX.off} - - Presumably if you are reading this interactively you have a copy of SiSU already installed, nevertheless here are a few notes. - - SiSU does require setup, the executable file #{@cX.blue}sisu#{@cX.off} is placed in #{@cX.blue}#{Config::CONFIG['bindir']}#{@cX.off} or #{@cX.blue}#{Config::CONFIG['sitelibdir']}#{@cX.off} and the library files, in #{@cX.blue}#{Config::CONFIG['rubylibdir']}/#{SiSU_lib}#{@cX.off} - or in #{@cX.blue}#{Config::CONFIG['sitelibdir']}/#{SiSU_lib}#{@cX.off} - - SiSU comes with a number of installers, including #{@cX.blue}setup.rb#{@cX.off}, #{@cX.blue}install#{@cX.off} and a #{@cX.blue}Rantfile#{@cX.off} if rant is installed on your system, you may need to be root to install sisu on your system. After unpacking the tarball, in the top directory of the tarball which contains the named files type, one of: - sudo ./sisu-install base - sudo ./sisu-install setup - if that does not work try - sudo ruby ./sisu-install setup - if rant is installed on your system you may instead run: - sudo rant base - - for further options: - ./sisu-install -T - - SiSU is pre-packaged for some GNU/Linux distributions such as Debian. - - For information on download and installation, see #{@cX.blue}http://www.jus.uio.no/sisu/SiSU/download#{@cX.off} - - For post installation help it is best you refer to '#{@cX.blue}man 8 sisu#{@cX.off}' - - Host - host: #{@cX.blue}#{@env.hostname}#{@cX.off} - arch: #{@cX.blue}#{@env.arch}#{@cX.off} - - Directories for installation - bin: #{@cX.blue}#{Config::CONFIG['bindir']}#{@cX.off} or #{@cX.blue}#{Config::CONFIG['sitelibdir']}#{@cX.off} - lib (site-ruby): #{@cX.blue}#{Config::CONFIG['rubylibdir']}/#{SiSU_lib}#{@cX.off} or #{@cX.blue}#{Config::CONFIG['sitelibdir']}/#{SiSU_lib}#{@cX.off} - conf [etc]: #{@cX.blue}#{@env.path.etc}/sisu#{@cX.off} - data (document samples, images, README): #{@cX.blue}#{@env.path.sample_data}#{@cX.off} - processing: #{@cX.blue}#{@env.processing_path.processing}#{@cX.off} - output www: #{@cX.blue}#{@env.path.output}#{@cX.off} - - Output files, are currently set to be produced in: - processed document output: #{@cX.blue}#{@env.path.output}#{@cX.off} - a document in the current directory #{@cX.blue}#{Dir.pwd}#{@cX.off} - will have its output placed in: #{@cX.blue}#{@env.path.output}/#{@output_stub}#{@cX.off} - - Install any additional programs of interest (that SiSU makes use of, that are not already on your system) - - Programs SiSU makes use of include: - LaTeX - texinfo - pdfetex aka. pdflatex - sqlite - postgresql - - Again, refer to '#{@cX.blue}man 8 sisu#{@cX.off}' - - For additional help on using SiSU once installed type: - - sisu --help - - WOK - end - def setup - print <<-WOK - - #{@cX.green}configuration files#{@cX.off} - sisurc.yml used: - #{@cX.blue}#{@env.path.yamlrc}#{@cX.off} - configuration information search path: - #{@cX.blue}#{@env.path.rc.join(', ')}#{@cX.off} - (directory also relevant for skins and images) - - to initialise the mapped output directory, from within the markup document directory type: - #{@cX.blue}sisu -CC#{@cX.off} - - for information on your current sisu configuration settings, type: - #{@cX.blue}sisu --help env#{@cX.off} - or - #{@cX.blue}sisu -V#{@cX.off} - - see also - #{@cX.blue}man 8 sisu#{@cX.off} - and - #{@cX.blue}http://www.jus.uio.no/sisu/SiSU#{@cX.off} - WOK - end - def termsheet - print <<-WOK - - #{@cX.green}sisu --termsheet [termsheetname].termsheet.rb#{@cX.off} - will produce the collection of documents associated with [termsheetname.termsheet.rb] - - #{@cX.green}sisu -t [termsheetname].termsheet.rb#{@cX.off} - will produce the collection of documents associated with [termsheetname.termsheet.rb] - - #{@cX.green}termsheet.rb#{@cX.off} files: - (i) are named after the facility - (ii) contain instructions as to which standard forms to use for the agreement (standard_form.rb) - there may be several, eg. the termsheet, and the resulting: - main agreement; collection account charge; and deed of assignment - (iii) contain the variable terms of the agreement, borrower, interest etc. - - for a new loan agreement fill out a new termsheet specifying - what standard forms are to be used, - and the terms of the agreement. - - #{@cX.green}standard_form.rb#{@cX.off} files: - contain the standard terms of the agreement - there is a standard form for each variation of agreement - (so eg. there are as many facility agreements as there are variations in standard facility) - these may be prepared for any agreement that is to be reused. - (preparation takes the form of formating and - placing variable holders for the variables that are to be provided by the termsheet.rb file) - - it is necessary to purge the directory ~facilityData when old files are removed - - WOK - end - def help_commands - print <<-WOK - - also see: - sisu --help commands - man sisu - WOK - end - def help_env - print <<-WOK - - for sisu environment information see: - sisu --help env - WOK - end - def help_general - help_env - help_commands - end - def help_markup - print <<-WOK - - for help with sisu markup see: - sisu --help markup - sisu --help header - sisu --help structure [sisu --help heading] - - to check markup version in file: - sisu --identify [filename].sst - - for brief descriptive summary of markup history - sisu --query-history - - for markup: - sisu --help example - - sample marked up documents are provided in directory: - #{@cX.green}/usr/share/doc/sisu/markup-samples#{@cX.off} - and online - #{@cX.green}www.jus.uio.no/sisu#{@cX.off} - WOK - end - def convert - print <<-WOK - - for information on the markup version used within a sisu markup file: - sisu --inspect [filename] - - convert an sst file with footnotes following text to (preferred) inline footnotes - sisu --convert-footnotes [filename/wildcard] - - to convert from sst to simple xml representations (sax, dom and node): - sisu --to-sax [filename/wildcard] - sisu --to-sxs [filename/wildcard] - - sisu --to-dom [filename/wildcard] - sisu --to-sxd [filename/wildcard] - - sisu --to-node [filename/wildcard] - sisu --to-sxn [filename/wildcard] - - to convert to sst from simple xml representations (sax, dom and node): - sisu --from-xml2sst [filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]] - sisu --from-sxml [filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]] - - to attempt to convert a kdissert (.kdi) file to sisu markup: - sisu --from-kdi [kdissert filename] - (very basic and experimental) - WOK - end - def dal - print <<-WOK - - sisu --dal [filename/wildcard] creates the metaverse, used by all other modules for downstream processing - sisu -m [filename/wildcard] creates the metaverse, used by all other modules for downstream processing - WOK - help_commands - end - def utf8 - print <<-WOK - - documents prepared for sisu processing should be stored in utf8 - WOK - end - def plaintext - print <<-WOK - - sisu --txt [filename/wildcard] plaintext with Unix linefeeds (footnotes follow paragraphs) - sisu -t [filename/wildcard] plaintext with Unix linefeeds (footnotes follow paragraphs) - - WOK - help_commands - end - def html - print <<-WOK - - sisu --html [filename/wildcard] html document type suffixes included - sisu -h [filename/wildcard] html document type suffixes included - - WOK - help_commands - end - def xhtml - print <<-WOK - - sisu --xhtml [filename/wildcard] xhtml document - sisu -b [filename/wildcard] xhtml document - WOK - help_commands - end - def xml - print <<-WOK - - sisu --xml-sax [filename/wildcard] xml document (sax type parsing) - sisu -x [filename/wildcard] xml document (sax type parsing) - - sisu --xml-dom [filename/wildcard] xml document (dom type parsing) - sisu -X [filename/wildcard] xml document (dom type parsing) - - sisu --odt [filename/wildcard] odt document, (odf open document format) - sisu -o [filename/wildcard] odt document, (odf open document format) - - sisu --epub [filename/wildcard] odt document, (epub document) - sisu -e [filename/wildcard] odt document, (epub document) - WOK - help_commands - end - def odf - print <<-WOK - - sisu --odt [filename/wildcard] odt document, (odf open document format) - - sisu -o [filename/wildcard] odt document, (odf open document format) - WOK - help_commands - end - def epub - print <<-WOK - - sisu --epub [filename/wildcard] epub document, (open format for e-books) - sisu -e [filename/wildcard] epub document, (open format for e-books) - WOK - help_commands - end - def php - print <<-WOK - - not supported - [php output has been removed] - WOK - help_commands - end - def pdf - print <<-WOK - - sisu --pdf [filename/wildcard] produces pdf files from LaTeX output - sisu -p [filename/wildcard] produces pdf files from LaTeX output - WOK - help_commands - end - def latex - print <<-WOK - - sisu --pdf [filename/wildcard] produces pdf files from LaTeX output - sisu -p [filename/wildcard] produces pdf files from LaTeX output - WOK - help_commands - end - def texinfo - print <<-WOK - - sisu --texinfo [filename] produces texinfo and info files - sisu -I [filename] produces texinfo and info files - - info and texinfo files are currently left in a separate work/output directory... have not decided what to do with them - - on my system info works fine point at file with info command - - pinfo, requires you to be within the work/output directory - cd [work/output directory] - - and then to point at the file using - pinfo ./[filename] - WOK - help_commands - end - def lout - print <<-WOK - - sisu -l [filename/wildcard] - - not currently supported, revisit someday? - WOK - help_commands - end - def concordance - print <<-WOK - - sisu --concordance starts the sisu webrick server, default port 8081 - sisu --wordmap starts the sisu webrick server, default port 8081 - sisu -W starts the sisu webrick server, default port 8081 - WOK - help_commands - end - def help_search - print <<-WOK - - SiSU searches, - depending on how you wish to implement search, - the following may bre of interest: - sisu --help sql - sisu --help searchform (or 'sisu --help cgi') - sisu --help hyperestraier (or 'sisu --help est') - sisu --help webrick - WOK - end - def cgi - print <<-WOK - - sisu --sample-search-form generates a sample search form - sisu -F generates a sample search form - - sisu -F --webserv=webrick generates a sample search form for use with the webrick server - sisu -Fv as above, and provides some information on setting up hyperestraier - sisu -W starts the webrick server - - the generated search form must be copied to the webserver directory as instructed - WOK - help_search - help_general - end - def sql - print <<-WOK - - Mappings to two databases are provided by default, - postgresql (--pg or -D) and sqlite (--sqlite or -d), - the same modifier commands are used within sisu to construct and populate - databases the examples here will use --sqlite - - sisu --sqlite --createdb creates database where no database existed before - sisu --sqlite --create creates database tables where no database tables existed before - sisu --sqlite --dropall destroys database (including all its content)!! - sisu --sqlite --recreate destroys existing database and builds a new empty database structure - - sisu --sqlite --import [filename/wildcard] populates database with the contents of the file - sisu --sqlite --update [filename/wildcard] updates file contents in database - - sisu --sample-search-form --webserv=webrick builds a cgi web search frontend for the database created - - Postgresql - user: #{@cX.blue}#{@db.psql.user}#{@cX.off} - current db set: #{@cX.blue}#{@db.psql.db}#{@cX.off} - port: #{@cX.blue}#{@db.psql.port}#{@cX.off} - dbi connect: #{@cX.blue}#{@db.psql.dbi}#{@cX.off} - - sqlite - current db set: #{@cX.blue}#{@db.sqlite.db}#{@cX.off} - dbi connect #{@cX.blue}#{@db.sqlite.dbi} #{@cX.off} - - Note on databases built - 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 #{@cX.blue}#{@env.path.home}/ebook#{@cX.off} the database #{@cX.blue}#{Db[:name_prefix]}ebook#{@cX.off} is used. [otherwise a manual mapping for the collection is necessary] - WOK - help_search - help_general - end - def webrick - print <<-WOK - - sisu --webrick starts the sisu webrick server, default port 8081 - sisu -W starts the sisu webrick server, default port 8081 - WOK - help_commands - end - def hyperestraier - out_dir='(' + `ls #{@env.path.webserv}`.split("\n").join('|') + ')' - print <<-WOK - Not tested recently, not up-to-date - - NOTE: The examples that follow assume that sisu output is placed in the directory - /home/ralph/sisu_www - - (A) to generate the index - within the webserver directory to be indexed: - #{@cX.orange}estcmd gather -sd [index name] [directory path to index]#{@cX.off} - the following are examples that will need to be tailored according to your needs: - #{@cX.green} - cd #{@env.path.webserv} - estcmd gather -sd casket #{@env.path.webserv} - #{@cX.off} - you may use the 'find' command together with 'egrep' to limit - indexing to particular document collection directories within - the web server directory:#{@cX.green} - - find /home/ralph/sisu_www -type f | egrep '#{@env.path.output}/.+?\.html$' |estcmd gather -sd casket - #{@cX.off} - - check which directories in the webserver/output directory #{@cX.green}#{@env.path.webserv}#{@cX.off} - you wish to include in the search index, these appear to be: - - #{@env.path.webserv}/#{@cX.green}#{out_dir}#{@cX.off} - - 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 'doc.html' and 'concordance.html', as these - duplicate information held in other html output e.g. #{@cX.green} - - find /home/ralph/sisu_www -type f | egrep '/sisu_www/(sisu|bookmarks)/.+?\.html$' | egrep -v '(doc|concordance)\.html$' |estcmd gather -sd casket - #{@cX.off} - - from your current document preparation/markup directory, you would construct a rune along the following lines: #{@cX.green} - - find /home/ralph/sisu_www -type f | egrep '#{@env.path.webserv}/([specify first directory for inclusion]|[specify second directory for inclusion]|[another directory for inclusion? ...])/.+?\.html$' | egrep -v '(doc|concordance)\.html$' |estcmd gather -sd #{@env.path.webserv}/casket - #{@cX.off} - - (B) to set up the search form - (i) copy #{@cX.green}estseek.cgi#{@cX.off} to your cgi directory and set file permissions to 755: #{@cX.green} - - sudo cp -vi /usr/lib/estraier/estseek.cgi /usr/lib/cgi-bin - sudo chmod -v 755 /usr/lib/cgi-bin/estseek.cgi - sudo cp -v /usr/share/hyperestraier/estseek.* /usr/lib/cgi-bin #{@cX.off} - [see estraier documentation for paths] - - (ii) edit #{@cX.green}estseek.conf#{@cX.off}, with attention to the lines starting 'indexname:' and 'replace:': #{@cX.green} - - indexname: #{@env.path.webserv}/casket - replace: ^file://#{@env.path.webserv}{{!}}#{@env.url.webserv_host_base} - replace: /index\.html?${{!}}/ #{@cX.off} - - (C) to test using webrick, start webrick: #{@cX.green} - sisu -W #{@cX.off} - - and try open the url: #{@cX.blue} - #{@env.url.webserv_host_base}/cgi-bin/estseek.cgi #{@cX.off} - - WOK - end - def yaml - print <<-WOK - Yaml sisurc files may be used to configure sisu, these are searched for in the following locations: - - under the current SiSU markup data directory: #{@cX.blue}#{Dir.pwd}/_sisu/sisurc.yml#{@cX.off} - under the home directory ~/.sisu: #{@cX.blue}#{@env.path.home}/.sisu/sisurc.yml#{@cX.off} - in the "/etc" directory: #{@cX.blue}#{@env.path.etc}/sisurc.yml#{@cX.off} - - The Yaml files #{@cX.blue}promo.yml#{@cX.off} and #{@cX.blue}list.yml#{@cX.off} may be used to build a minor right pane in html, they may be placed in the following locations: - - under the current SiSU markup data directory: #{@cX.blue}#{Dir.pwd}/_sisu/skin/yml/#{@cX.off} - under the home directory ~/.sisu: #{@cX.blue}#{@env.path.home}/.sisu/skin/yml/#{@cX.off} - in the "/etc" directory: #{@cX.blue}#{@env.path.etc}/skin/yml/#{@cX.off} - - these may be called by the sisurc.yml, skins for document, directory or site, or from individual document headers in the header @@promo: [a commented out example header may be found in document sample: free_as_in_freedom.richard_stallman_cru‐ sade_for_free_software.sam_williams.sst, it calls for the specified lists in list.yml, which in turn calls the widgets named in promo.yml which are used to build content in the right pane of html output] - - WOK - end - def sitemap - print <<-WOK - - SiSU sitemaps, - an experimental feature (following g,y,m announcement to use them this week) - sisu -Y [filename/wildcard] - it may be necessary run -m first (generate the the metaverse) - sisu -mY [filename/wildcard] - - to generate/update the index of sitemaps - sisu --sitemaps - WOK - end - def license - - print <<-WOK - - * License: GPL 3 or later: - - SiSU, a framework for document structuring, publishing and search - - Copyright (C) 1997 - 2013 Ralph Amissah - - This program is free software: you can redistribute it and/or modify it - under the terms of the GNU General Public License as published by the Free - Software Foundation, either version 3 of the License, or (at your option) - any later version. - - This program is distributed in the hope that it will be useful, but WITHOUT - ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or - FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for - more details. - - You should have received a copy of the GNU General Public License along with - this program. If not, see <#{@cX.blue}http://www.gnu.org/licenses/#{@cX.off}>. - - If you have Internet connection, the latest version of the GPL should be - available at these locations: - <#{@cX.blue}http://www.fsf.org/licenses/gpl.html#{@cX.off}> - <#{@cX.blue}http://www.gnu.org/licenses/gpl.html#{@cX.off}> - - * SiSU uses: - * Standard SiSU markup syntax, - * Standard SiSU meta-markup syntax, and the - * Standard SiSU object citation numbering and system - - * Hompages: - <#{@cX.blue}http://www.sisudoc.org#{@cX.off}> - <#{@cX.blue}http://www.jus.uio.no/sisu#{@cX.off}> - - * Download: - <#{@cX.blue}http://sources.sisudoc.org#{@cX.off}> - <#{@cX.blue}http://www.jus.uio.no/sisu/en/html/SiSU/download.html#{@cX.off}> - - Ralph Amissah - <#{@cX.blue}ralph@amissah.com#{@cX.off}> - <#{@cX.blue}ralph.amissah@gmail.com#{@cX.off}> - - WOK - end - def standards - print <<-WOK - - * SiSU uses: - * Standard SiSU markup syntax, - * Standard SiSU meta-markup syntax, and the - * Standard SiSU object citation numbering and system - -Copyright (C) Ralph Amissah 1997, current 2013. -All Rights Reserved. - -Information on these may be obtained from: - <#{@cX.blue}http://sisudoc.org#{@cX.off}> - -More information to be provided later. - -* however note also the License section - -* Ralph Amissah ralph@amissah.com - Ralph Amissah ralph.amissah@gmail.com - - WOK - end - def conversion - print <<-WOK -sisu_convert does the initial conversion from a couple of file formats to SiSU file format, currently only html and word97 - #{@cX.cyan}sisu_convert#{@cX.off} [keyword] - sisu [keyword] - #{@cX.green}--html#{@cX.off} convert from html - ------------------------------------------ - Preparing Documents for SiSU - #{@cX.green}--word97#{@cX.off} sisu --help markup (an incomplete overview) - WOK - end - def external_programs - puts <<-WOK - - external ruby programs - - external programs - #{@cX.cyan}pdf output - tex/latex#{@cX.off} - #{@cX.orange}required#{@cX.off} - tex-base/latex - pdfetex aka. pdflatex - #{@cX.brown}suggested/recommended#{@cX.off} - #{@cX.cyan}db/sql output#{@cX.off} - #{@cX.orange}required#{@cX.off} - postgresql - #{@cX.brown}suggested/recommended#{@cX.off} - sqlite - #{@cX.cyan}xml/xhtml/html output#{@cX.off} - #{@cX.orange}required#{@cX.off} - #{@cX.brown}suggested/recommended#{@cX.off} - tidy (xml, xhtml well formed check) - trang (relaxng, rnc to dtd conversion) - WOK - end - def scratch - print <<-WOK -Types of tag, - -then there are various tags which occur within the document. -Structural tags, which consist of: - heading tags that identify headings within text, and; - footnote/endnote tags ... - -Markup instructions: giving information as to what is to be done to the presentation of the text - -Markup tags - -These have been kept to a minimum. A number of text html markup tags can be used <b>to bold</b> <i>to indent</i> <sup>for superscript</sup> <sub>for subscript text</sub> - -_1 at the beginning of a line indents the paragraph - -_2 at the beginning of a line double indents the paragraph - -Others include - -Other things to note: - -By default paragraphs are automatically numbered... and is the same across all output formats -This makes citation a lot easier... regardless of the form of output that is being looked at -It also permits the building of various addons, like the concordance feature which identifies each word and the paragraphs in which the word appears with links to the paragraph... - -Urls are automatically turned to live links in the html and pdf files created... - WOK - end - end -end -__END__ - diff --git a/lib/sisu/v5/hub.rb b/lib/sisu/v5/hub.rb index 6f0d0b63..50ad39c3 100644 --- a/lib/sisu/v5/hub.rb +++ b/lib/sisu/v5/hub.rb @@ -70,8 +70,6 @@ module SiSU include SiSU_Param require_relative 'defaults' # defaults.rb include SiSU_Viz - require_relative 'help' # help.rb - include SiSU_Help require_relative 'utils' # utils.rb require 'uri' class HubMaster @@ -208,8 +206,8 @@ module SiSU require_relative 'remote' # remote.rb SiSU_Remote::Put.new(@opt).scp_base_all end - def cgi # -F - require_relative 'cgi' # cgi.rb + def cgi # -F + require_relative 'cgi' # cgi.rb SiSU_CGI::SearchSQL.new(@opt).read end def termsheet # -t @@ -372,10 +370,10 @@ module SiSU end def do_loop_files_on_given_option_pre begin - if @opt.act[:zap][:set]==:on #% --zap, -Z + if @opt.act[:zap][:set]==:on #% --zap, -Z OptionLoopFiles.new(@opt).loop_files_on_given_option do require_relative 'zap' - SiSU_Zap::Source.new(@opt).read # -Z zap.rb + SiSU_Zap::Source.new(@opt).read # -Z zap.rb end end ensure @@ -423,8 +421,8 @@ module SiSU end if (@opt.act[:sisupod][:set]==:on \ || @opt.act[:share_source][:set]==:on) \ - and @opt.act[:manifest][:set]==:on #% --manifest, -y - require_relative 'manifest' # -y manifest.rb + and @opt.act[:manifest][:set]==:on #% --manifest, -y + require_relative 'manifest' # -y manifest.rb begin ensure OptionLoopFiles.new(@opt).loop_files_on_given_option_bundle do @@ -455,7 +453,6 @@ module SiSU end end if @opt.cmd =~/T/ #% -T termsheet/standard form - SiSU_Help::Help.new('termsheet').help_request @opt.files.each do |fns| if FileTest.file?(fns) @opt.fns=fns @@ -519,10 +516,7 @@ module SiSU @cX=SiSU_Screen::Ansi.new(@opt.cmd).cX flag=SiSU_Env::InfoProcessingFlag.new if @opt.act[:version_info][:set]==:on #% version information - SiSU_Help::Help.new('env',@opt).sisu_version - end - if @opt.act[:license][:set]==:on #% license information - SiSU_Help::Help.new('license',@opt).help_request + SiSU_Env::InfoAbout.new(@opt).sisu_version end if @opt.act[:dal][:set]==:on \ or @opt.act[:maintenance][:set]==:on #% --maintenance, -m for -C @@ -698,7 +692,7 @@ module SiSU end elsif action_on_file_ == :true \ and @opt.files.length == 0 - STDERR.puts %{requested action requires valid sisu markup file filename (.sst .ssm) or wildcard (that includes a valid filame)} + STDERR.puts %{requested action requires valid sisu markup file [filename (.sst .ssm)] or wildcard (that includes a valid filename)} puts SiSU_Utils::CodeMarker.new(__LINE__,__FILE__).set(:fuchsia) if @opt.cmd =~/[MV]/ end elsif @opt.mod.inspect =~/--query/ @@ -707,13 +701,6 @@ module SiSU elsif @opt.mod.inspect =~/--identify/ require_relative 'sst_identify_markup' # sst_identify_markup.rb markup_version=SiSU_Markup::MarkupIdentify.new(@opt).markup_version? - elsif @opt.mod.inspect =~/--about/ #% help instructions - if @opt.mod.inspect =~/--about/ \ - and not @opt.what.empty? - SiSU_Help::Help.new(@opt.what,'color_off').help_request - else - SiSU_Help::Help.new('list','color_off').help_request - end elsif @opt.mod.inspect =~/--sitemaps/ #% sitemaps require_relative 'sitemaps' # sitemaps.rb SiSU_Sitemaps::Source.new(@opt).read @@ -721,19 +708,9 @@ module SiSU require_relative 'remote' # remote.rb SiSU_Remote::Put.new(@opt).rsync_sitemaps end - else #% help instructions - unless @opt.mod.inspect =~/--convert|--to|--from|--harvest/ - if @opt.mod.inspect =~/--help/ \ - and not @opt.what.empty? - SiSU_Help::Help.new(@opt.what).help_request - elsif @opt.mod.inspect =~/--help/ - SiSU_Help::Help.new('list').help_request - else - SiSU_Help::Help.new('env',@opt).sisu_version - tell=SiSU_Screen::Ansi.new(''," for HELP type:\n\tsisu --help [help request]\n\tman sisu\n or see the system or online documentation on SiSU:\n #{Config::CONFIG['datadir']}/doc/sisu/\n <http://www.jus.uio.no/sisu/>\n <http://sisudoc.org/>") - tell.puts_grey - end - end + else #% sisu help refer to man pages + SiSU_Env::InfoAbout.new(@opt).sisu_version + SiSU_Env::InfoAbout.new(@opt).sisu_about end @opt.files.each do |fns| if FileTest.file?(fns) diff --git a/lib/sisu/v5/param.rb b/lib/sisu/v5/param.rb index b2ced415..a78e9fbd 100644 --- a/lib/sisu/v5/param.rb +++ b/lib/sisu/v5/param.rb @@ -66,8 +66,6 @@ module SiSU_Param include SiSU_Env require_relative 'param_make' # param_make.rb require_relative 'param_identify_markup' # param_identify_markup.rb - require_relative 'help' # help.rb - include SiSU_Help @@date=SiSU_Env::InfoDate.new @@proc=@@filename_txt=@@filename_texinfo=@@filename_lout_portrait=@@filename_lout_landscape=@@filename_html_scroll=@@filename_html_index=@@filename_html_segtoc=@@filename_semantic=@@filename_rss=@@newfile=@@drr=nil @doc={ initialise: nil, markup: '', lnks: '', stmp: '', req: {} } @@ -830,14 +828,14 @@ module SiSU_Param @doc={ lv: [] } @doc[:fns],@doc[:fnb],@doc[:scr_suffix]='','','' @@publisher='SiSU scribe' - attr_accessor :make,:env,:path,:file,:fn,:fns,:fno,:fnb,:fnn,:fnt,:fnl,:flv,:fnz,:fnstex,:ocn,:sfx_src,:pdf,:file_type,:dir_out,:dir_tex,:dir_lout,:txt_path,:sisu,:sisu_version,:ruby_version,:title,:subtitle,:full_title,:html_title,:subtitle_tex,:creator,:classify,:author_home,:author,:author_title,:author_nationality,:authors,:authorship,:translator,:illustrator,:prepared_by,:digitized_by,:subject,:description,:publisher,:current_publisher,:contributor,:date,:date_created,:date_issued,:date_available,:date_valid,:date_modified,:date_translated,:date_added_to_site,:date_scheme,:date_created_scheme,:date_issued_scheme,:date_available_scheme,:date_valid_scheme,:date_modified_scheme,:type,:format,:identifier,:source,:language,:language_original,:relation,:coverage,:rights,:keywords,:comments,:abstract,:cls_loc,:cls_dewey,:cls_pg,:cls_isbn,:papersize,:papersize_array,:toc,:lv1,:lv2,:lv3,:lv4,:lv5,:lv6,:lvs,:pagenew,:pagebreak,:pageline,:num_top,:bold_match_list,:italics_match_list,:substitution_match_list,:emphasis_set_to,:toc_lev_limit,:flag_endnotes,:flag_auto_endnotes,:flag_separate_endnotes,:flag_separate_endnotes_make,:markup,:markup_instruction,:markup_version,:markup_declared,:flag_tables,:vocabulary,:doc_css,:yaml,:lnk,:links,:prefix_a,:prefix_b,:suffix,:information,:contact,:icon,:image,:ad_url,:ad_png,:ad_alt,:ad_began,:flag_promo,:promo,:ad_home,:stmp,:stmpd,:sc_filename,:sc_number,:sc_date,:sc_time,:sc_info,:yamladdr,:locale,:wc_lines,:wc_words,:wc_bytes,:file_encoding,:filesize,:user,:home,:hostname,:pwd,:firstseg,:programs,:author_copymark,:i18n,:lang,:lang_code_insert,:en,:notes,:dgst,:generated,:tags,:tag_array,:concord_make,:seg_names,:seg_autoname_safe,:set_header_title,:set_heading_top,:set_heading_seg,:heading_seg_first,:heading_seg_first_flag,:base_program,:ec,:opt,:sem_tag,:book_idx,:topic_register,:topic_register_array,:original,:writing_focus,:audio,:daisy,:home_button_image,:home_button_links,:footer_links,:cover_image,:man_section + attr_accessor :make,:env,:path,:file,:fn,:fns,:fno,:fnb,:fnn,:fnt,:fnl,:flv,:fnz,:fnstex,:ocn,:sfx_src,:pdf,:file_type,:dir_out,:dir_tex,:dir_lout,:txt_path,:sisu,:sisu_version,:ruby_version,:title,:subtitle,:full_title,:html_title,:subtitle_tex,:creator,:classify,:author_home,:author,:author_title,:author_nationality,:authors,:authorship,:translator,:illustrator,:prepared_by,:digitized_by,:subject,:description,:publisher,:current_publisher,:contributor,:date,:date_created,:date_issued,:date_available,:date_valid,:date_modified,:date_translated,:date_added_to_site,:date_scheme,:date_created_scheme,:date_issued_scheme,:date_available_scheme,:date_valid_scheme,:date_modified_scheme,:type,:format,:identifier,:source,:language,:language_original,:relation,:coverage,:rights,:keywords,:comments,:abstract,:cls_loc,:cls_dewey,:cls_pg,:cls_isbn,:papersize,:papersize_array,:toc,:lv1,:lv2,:lv3,:lv4,:lv5,:lv6,:lvs,:pagenew,:pagebreak,:pageline,:num_top,:bold_match_list,:italics_match_list,:substitution_match_list,:emphasis_set_to,:toc_lev_limit,:flag_endnotes,:flag_auto_endnotes,:flag_separate_endnotes,:flag_separate_endnotes_make,:markup,:markup_instruction,:flag_tables,:vocabulary,:doc_css,:yaml,:lnk,:links,:prefix_a,:prefix_b,:suffix,:information,:contact,:icon,:image,:ad_url,:ad_png,:ad_alt,:ad_began,:flag_promo,:promo,:ad_home,:stmp,:stmpd,:sc_filename,:sc_number,:sc_date,:sc_time,:sc_info,:yamladdr,:locale,:wc_lines,:wc_words,:wc_bytes,:file_encoding,:filesize,:user,:home,:hostname,:pwd,:firstseg,:programs,:author_copymark,:i18n,:lang,:lang_code_insert,:en,:notes,:dgst,:generated,:tags,:tag_array,:concord_make,:seg_names,:seg_autoname_safe,:set_header_title,:set_heading_top,:set_heading_seg,:heading_seg_first,:heading_seg_first_flag,:base_program,:ec,:opt,:sem_tag,:book_idx,:topic_register,:topic_register_array,:original,:writing_focus,:audio,:daisy,:home_button_image,:home_button_links,:footer_links,:cover_image,:man_section def initialize(fns_array,opt) @env=@path,@file=@fn=@fns=@fno=@fnb=@fnn=@fnt=@fnl=@flv=@fnz=@fnstex=@ocn=@sfx_src=@pdf=@file_type=@dir_out=@dir_tex=@dir_lout=@txt_path=@make=@flag_endnotes=@flag_auto_endnotes=@flag_separate_endnotes=@flag_separate_endnotes_make=@sisu=@sisu_version=@ruby_version=@title=@subtitle=@full_title=@html_title=@subtitle_tex=@creator=@classify=@author_home=@author=@author_title=@author_nationality=@translator=@illustrator=@prepared_by=@digitized_by=@subject=@description=@publisher=@current_publisher=@contributor=@date=@date_created=@date_issued=@date_available=@date_valid=@date_modified=@date_translated=@date_added_to_site=@date_scheme=@date_created_scheme=@date_issued_scheme=@date_available_scheme=@date_valid_scheme=@date_modified_scheme=@type=@format=@identifier=@source=@language=@language_original=@relation=@coverage=@rights=@keywords=@comments=@abstract=@cls_loc=@cls_dewey=@cls_pg=@cls_isbn=@papersize=@toc=@lv1=@lv2=@lv3=@lv4=@lv5=@lv6=@pagenew=@pagebreak=@pageline=@num_top=@bold_match_list=@italics_match_list=@substitution_match_list=@emphasis_set_to=@toc_lev_limit=@flag_tables=@vocabulary=@doc_css=@yaml=@lnk=@links=@prefix_a=@prefix_b=@suffix=@information=@contact=@icon=@ad_url=@ad_png=@ad_alt=@ad_began=@promo=@ad_home=@stmp=@stmpd=@sc_filename=@sc_number=@sc_date=@sc_time=@sc_info=@yamladdr=@locale=@wc_lines=@wc_words=@wc_bytes=@file_encoding=@filesize=@firstseg=@programs=@author_copymark=@i18n=@lang=@lang_code_insert=@en=@notes=@dgst=@generated=@heading_seg_first=@base_program=@topic_register=@original=@writing_focus=@audio=@home_button_image=@home_button_links=@cover_image=@man_section=nil @data,@path,@fns,@fno,@opt=fns_array,opt.pth,opt.fns,opt.fno,opt #@data used as data @flag_tables,@set_header_title,@set_heading_top,@set_heading_seg,@heading_seg_first_flag,@flag_promo,@book_idx=false,false,false,false,false,false,false @seg_autoname_safe=true @daisy,@sem_tag=false,false - @authorship,@markup_instruction,@markup_declared,@image='','','','' #check which other values should be set to empty rather than nil + @authorship,@markup_instruction,@image='','','','' #check which other values should be set to empty rather than nil @markup=@markup_instruction #use @markup_instruction @doc,@fn,@make_italic,@tag_hash,@ec={},{},{},{},{},{} @flv,@lang,@seg_names,@tags,@tag_array,@tag_a,@ec[:image],@ec[:audio],@ec[:multimedia]=Array.new(9){[]} @@ -956,44 +954,6 @@ module SiSU_Param @generated=Time.now fns_array=@data.dup skip unless fns_array # consider - @markup_version=SiSU_MarkupType::MarkupIdentify.new(fns_array,@opt).markup_version? #% determine markup version - if fns_array[0] =~ /^(?:%\s+)?(?:SiSU\s+(?:master\s+)?[\d.]*|sisu-[\d.]+)$/ #check markup and markup version - if fns_array[0] =~ /^(?:%\s+)?(?:SiSU\s+(?:master\s+)?|sisu-)(?:(?:[0-9]+?)(?:\.[0-9]+?)(?:\.[0-9]+))?$/ #check markup and markup version - @markup_version_declared=fns_array[0].match(/^(?:%\s+)?(?:SiSU\s+(?:master\s+)?|sisu-)([\d.]+)$/)[1] - sm_a,sm_b,sm_c=fns_array[0].match(/^(?:%\s+)?(?:SiSU\s+(?:master\s+)?|sisu-)([0-9]+)?(?:\.([0-9]+))?(?:\.([0-9]+))?$/)[1..3] - sm_c ||=0 - sv=(@opt.cmd =~/[VMv]/) ? ("SiSU version (#{@sisu_version[:version]})") : '' - s_a,s_b,s_c=@sisu_version[:version].match(/^([0-9]+)?(?:\.([0-9]+))?(?:\.([0-9]+))?(?:[~-]\S+)?$/)[1..3] - tell=(@markup_version_declared.to_f==@markup_version.determined) \ - ? SiSU_Screen::Ansi.new(@opt.cmd,"Markup version (#{@markup_version.series} version #{@markup_version.determined})",sv) - : SiSU_Screen::Ansi.new(@opt.cmd,"Markup version declared (#{@markup_version_declared}), determined (#{@markup_version.series} version #{@markup_version.determined})",sv) - ok=if s_a.to_i > sm_a.to_i - true - elsif s_a.to_i == sm_a.to_i \ - and s_b.to_i >= sm_b.to_i - true - elsif s_a.to_i == sm_a.to_i \ - and s_b.to_i == sm_b.to_i \ - and s_c.to_i >= sm_c.to_i - true - else false - end - if ok - tell.txt_green if @opt.cmd =~/[vVM]/ - else - SiSU_Screen::Ansi.new(@opt.cmd,"WARNING: markup version determined (#{@markup_version.determined}) or markup version declared (#{@markup_version_declared}) is newer than SiSU version (#{@sisu_version[:version]})").warn unless @opt.cmd =~/q/ - end - else - SiSU_Screen::Ansi.new(@opt.cmd,'No SiSU markup version provided').warn if @opt.cmd =~/[VM]/ - end - else - mv=if @markup_version.determined.is_a?(Float) - x=@markup_version.determined - "markup version determined #{x}" - else '' - end - SiSU_Screen::Ansi.new(@opt.cmd,'SiSU filetype indicator not provided',mv).warn unless @opt.cmd =~/q/ - end @code_flag=false fns_array.each do |para| #% scan document if para !~/^%+\s/ \ @@ -1144,11 +1104,6 @@ module SiSU_Param @lvs[6]=1 end if para =~ /^:A~/ #% processing - if @markup.nil? \ - or @markup.empty? - @markup=@markup_version.determined.to_s - elsif @markup !~/0\.38/ then @markup=@markup.strip + "; #{@markup_version.determined}" - end if not defined? @title.full.nil? tf=para[/^:A~\S*(.+)$/m,1] tf="@title: #{tf}" @@ -1275,38 +1230,36 @@ module SiSU_Param else @i18n=[ 'en' ] end - if @markup_version.determined >= 0.38 #convert values in headers to internal representation - translated=[] - translate_list=[@pagenew,@pagebreak,@pageline,@num_top,@toc_lev_limit] - translate_list.each do |t| - translate=t.to_s if t - translated << if translate - translate.gsub!(/3/,'6') - translate.gsub!(/2/,'5') - translate.gsub!(/1/,'4') - translate.gsub!(/:?C/,'3') - translate.gsub!(/:?B/,'2') - translate.gsub!(/:?A/,'1') - # looks like an ok substituion for the above but is not, causes problems, check why - #translate=translate.gsub(/3/,'6'). - # gsub(/2/,'5'). - # gsub(/1/,'4'). - # gsub(/:?C/,'3'). - # gsub(/:?B/,'2'). - # gsub(/:?A/,'1') - translate=(translate =~/^\d+$/) \ - ? translate.to_i - : translate - else nil - end + translated=[] + translate_list=[@pagenew,@pagebreak,@pageline,@num_top,@toc_lev_limit] + translate_list.each do |t| + translate=t.to_s if t + translated << if translate + translate.gsub!(/3/,'6') + translate.gsub!(/2/,'5') + translate.gsub!(/1/,'4') + translate.gsub!(/:?C/,'3') + translate.gsub!(/:?B/,'2') + translate.gsub!(/:?A/,'1') + # looks like an ok substituion for the above but is not, causes problems, check why + #translate=translate.gsub(/3/,'6'). + # gsub(/2/,'5'). + # gsub(/1/,'4'). + # gsub(/:?C/,'3'). + # gsub(/:?B/,'2'). + # gsub(/:?A/,'1') + translate=(translate =~/^\d+$/) \ + ? translate.to_i + : translate + else nil end - @pagenew,@pagebreak,@pageline,@num_top,@toc_lev_limit=translated - @markup=@markup.gsub(/page_new\s*=\s*([\dA-C])/,"page_new=#{@pagenew}"). - gsub(/page_break\s*=\s*([\dA-C])/,"page_break=#{@pagebreak}"). - gsub(/page_line\s*=\s*([\dA-C])/,"page_line=#{@pageline}"). - gsub(/num_top\s*=\s*([\dA-C])/,"num_top=#{@num_top}"). - gsub(/toc_lev_limit\s*=\s*([\dA-C])/,"toc_lev_limit=#{@toc_lev_limit}") end + @pagenew,@pagebreak,@pageline,@num_top,@toc_lev_limit=translated + @markup=@markup.gsub(/page_new\s*=\s*([\dA-C])/,"page_new=#{@pagenew}"). + gsub(/page_break\s*=\s*([\dA-C])/,"page_break=#{@pagebreak}"). + gsub(/page_line\s*=\s*([\dA-C])/,"page_line=#{@pageline}"). + gsub(/num_top\s*=\s*([\dA-C])/,"num_top=#{@num_top}"). + gsub(/toc_lev_limit\s*=\s*([\dA-C])/,"toc_lev_limit=#{@toc_lev_limit}") papersize_array_rc=@papersize.downcase.scan(/(?:a4|letter|legal|book|a5|b5)/) papersize_array_opt=[ ((@opt.act[:pdf_a4][:set]==:on) ? 'a4' : ''), diff --git a/lib/sisu/v5/sysenv.rb b/lib/sisu/v5/sysenv.rb index 25984397..edaec7f8 100644 --- a/lib/sisu/v5/sysenv.rb +++ b/lib/sisu/v5/sysenv.rb @@ -2383,7 +2383,7 @@ WOK def po "#{root}/po4a/po" end - def webserv_host_base + def webserv_host_base(opt=nil) if defined? @rc['webserv']['host'] case @rc['webserv']['host'] when /https?:\/\//; @rc['webserv']['host'] @@ -2393,7 +2393,7 @@ WOK else defaults[:webserv_host_cgi] end end - def webserv_cgi #web url for local webserv (localhost, or hostname) + def webserv_cgi(opt=nil) #web url for local webserv (localhost, or hostname) http=if defined? @rc['webserv_cgi']['host'] \ and @rc['webserv_cgi']['host'].is_a?(String) http=((@rc['webserv_cgi']['host'] =~ /https?:\/\//) ? '' : 'http://') #check https? missing @@ -2403,25 +2403,28 @@ WOK end else http=((webserv_host_base=~/https?:\/\//) ? '' : 'http://') - if port.webserv_port_cgi - "#{http}#{webserv_host_base}:#{port.webserv_port_cgi}/#{@stub_pwd}" + if port.webserv_port_cgi(opt) + "#{http}#{webserv_host_base}:#{port.webserv_port_cgi(opt)}/#{@stub_pwd}" else "#{http}#{webserv_host_base}/#{@stub_pwd}" end end http=http.strip end - def webserv_base_cgi #web url for local webserv (localhost, or hostname) - http=if defined? @rc['webserv_cgi']['host'] \ + def webserv_base_cgi(opt=nil) #web url for local webserv (localhost, or hostname) + http=if opt.mod.inspect =~/--webserv-(?:cgi|db|search)[=-]["']?(\S+)["']+/ + m=$1 + (m=~/http\/\/:/) ? m : %{http://#{m}} + elsif defined? @rc['webserv_cgi']['host'] \ and @rc['webserv_cgi']['host'].is_a?(String) http=((@rc['webserv_cgi']['host'] =~ /https?:\/\//) ? '' : 'http://') - if port.webserv_port_cgi - "#{http}#{@rc['webserv_cgi']['host']}:#{port.webserv_port_cgi}" + if port.webserv_port_cgi(opt) + "#{http}#{@rc['webserv_cgi']['host']}:#{port.webserv_port_cgi(opt)}" else "#{http}#{@rc['webserv_cgi']['host']}" end else http=((webserv_host_base=~/https?:\/\//) ? '' : 'http://') - if port.webserv_port_cgi - "#{http}#{webserv_host_base}:#{port.webserv_port_cgi}" + if port.webserv_port_cgi(opt) + "#{http}#{webserv_host_base}:#{port.webserv_port_cgi(opt)}" else "#{http}#{webserv_host_base}" end end @@ -2469,16 +2472,39 @@ WOK else "#{url.webrick_base}" end end - def webserv_files_from_db #sort this out, messy - if defined? @rc['webserv_cgi']['file_links'] - case @rc['webserv_cgi']['file_links'] - when /webserv_cgi/; url.webserv_base_cgi + def webserv_files_from_db(opt=nil) #sort this out, messy + if opt.mod.inspect =~/--webserv-output[=-]["']?(\S+)["']+/ + m=$1 + (m=~/(?:http|file\/)\/\/:/) ? m : %{http://#{m}} + else + show_output_on=if defined? @rc['webserv_cgi']['show_output_on'] + @rc['webserv_cgi']['show_output_on'] + elsif defined? @rc['webserv_cgi']['file_links'] + @rc['webserv_cgi']['file_links'] + else '' + end + m=case show_output_on + when /webserv_cgi/; url.webserv_base_cgi(opt) when /webserv/; @rc['webserv']['url_root'] when /https?:\/\//; @rc['webserv_cgi']['file_links'] when /\S+/; "http://#{@rc['webserv_cgi']['file_links']}" - else webserv_base_cgi + else webserv_base_cgi(opt) end - else webserv_base_cgi + end + end + def cgi_sample_search_form_name(opt=nil) + if opt.mod.inspect =~/--(?:cgi-)?search-form-name[=-]["']?(\S+?\.cgi)/ + m=$1 + elsif not (opt.mod.inspect =~/--db[=-]["']?sqlite/) \ + and defined? @rc['search'] \ + and defined? @rc['search']['sisu'] \ + and defined? @rc['search']['sisu']['action'] \ + and @rc['search']['sisu']['action'] =~/https?:\/\/\S+?\.cgi/ + x=/(?:https?:\/\/\S+?)\/([^\/]+?\.cgi)$/.match(@rc['search']['sisu']['action'])[1] + else + (opt.mod.inspect =~/--db[=-]["']?sqlite/) \ + ? 'sisu_sqlite.cgi' \ + : 'sisu_pgsql.cgi' end end def sample_search_form_title(organised_by=:language) @@ -2569,24 +2595,29 @@ WOK end end end - def webserv_port_cgi - if @md \ - and defined? @md.opt \ - and @md.opt.cmd.inspect=~/-F/ \ - and @md.opt.mod.inspect=~/port=(\d+)/ + def webserv_port_cgi(opt=nil) + port=if opt \ + and opt.cmd.inspect=~/-F/ \ + and opt.mod.inspect=~/port=(\d+)/ $1 else - if defined? @rc['webserv_cgi']['port'] + port=if defined? @rc['webserv_cgi']['port'] if @rc['webserv_cgi']['port'].nil? \ - and (defined? @md.opt.mod \ - and not @md.opt.mod.nil? \ - and @md.opt.mod.inspect=~/webrick/) + and (defined? opt.mod \ + and not opt.mod.nil? \ + and opt.mod.inspect=~/webrick/) defaults[:webserv_port_cgi] elsif not @rc['webserv_cgi']['port'].nil? @rc['webserv_cgi']['port'] else nil end - else nil + else + if (defined? opt.mod \ + and not opt.mod.nil? \ + and opt.mod.inspect=~/webrick/) + defaults[:webserv_port_cgi] + else nil + end end end end @@ -3548,6 +3579,38 @@ WOK %x{ruby -v}.strip end end + class InfoAbout + def initialize(color='') + @color=color + end + def sisu_version + version=SiSU_Env::InfoVersion.instance.get_version + rb_ver=SiSU_Env::InfoVersion.instance.rbversion + if version[:version] + opt_cmd=if defined? @color.cmd \ + and @color.cmd =~/[ck]/ + @color.cmd + else '-v' + end + SiSU_Screen::Ansi.new(opt_cmd,version[:project],version[:version],version[:date_stamp],version[:date],rb_ver).version + else puts 'SiSU version information not available' + end + end + def sisu_about + puts <<-WOK + sisu: documents; markup, structuring, publishing in multiple standard formats, & search + most (not all) useful commands (are made in a directory containing a sisu markup file &) take the form: + sisu [action(s)] [filename(s)] + where filename refers to a valid sisu marked up file, e.g.: + cd /usr/share/doc/sisu/markup-samples/sisu_manual + sisu --html --verbose sisu_commands.sst + sisu --txt --html --epub --odt --pdf --sqlite --manpage --texinfo --concordance --qrcode --verbose sisu.ssm + cd - + See output produced, or see man pages: man sisu + <http://www.sisudoc.org/> <http://www.jus.uio.no/sisu/> + WOK + end + end class InfoFile <InfoEnv #todo unify with FileOp def initialize(fns) begin @@ -4004,11 +4067,17 @@ WOK self end def psql - def user - ((defined? @rc['db']['postgresql']['user']) \ - && @rc['db']['postgresql']['user']=~/\S+/) \ - ? @rc['db']['postgresql']['user'] - : @env.user + def user(opt) + if opt.mod.inspect =~/--db-user[=-]["']?(\S+)["']+/ + m=$1 + elsif opt.mod =~/--webserv[=-]webrick/ + @env.user + else + ((defined? @rc['db']['postgresql']['user']) \ + && @rc['db']['postgresql']['user']=~/\S+/) \ + ? @rc['db']['postgresql']['user'] + : @env.user + end end def db #db_name "#{Db[:name_prefix]}#{@pwd_stub}" diff --git a/man/man1/sisu.1 b/man/man1/sisu.1 index 9fcc524c..2bafb76b 100644 --- a/man/man1/sisu.1 +++ b/man/man1/sisu.1 @@ -601,21 +601,26 @@ see --sisupod .B -s [filename/wildcard] see --source .TP -.B --sample-search-form [--webserv=webrick] +.B --sample-search-form [--db=(pgsql|sqlite)] [--webserv=webrick] generate examples of (naive) cgi search form for .I SQLite -and PgSQL depends on your already having used sisu to populate an +or PgSQL depends on your already having used sisu to populate an .I SQLite -and/or PgSQL database, (the +or PgSQL database, (the .I SQLite version scans the output directories for existing sisu_sqlite databases, so it -is first necessary to create them, before generating the search form) see -d -D -and the database section below. If the optional parameter --webserv=webrick is -passed, the cgi examples created will be set up to use the default port set for -use by the webrick server, (otherwise the port is left blank and the system -setting used, usually 80). The samples are dumped in the present work directory -which must be writable, (with screen instructions given that they be copied to -the cgi-bin directory). Alias -F +is first necessary to create them, before generating the search form) see +--sqlite & --pg and the database section below. Optional additional parameters +include: url location of webserver search form and db: +--webserv-search='[url]'; location of webserver output: +--webserv-output='[url]'; cgi search form link name: +--cgi-search-form-name='[name.cgi]'; for pgsql, database user: +--db-user='[username]'. If the optional parameter --webserv=webrick is passed, +the cgi examples created will be set up to use the default port set for use by +the webrick server, (otherwise the port is left blank and the system setting +used, usually 80). The samples are dumped in the present work directory which +must be writable, (with screen instructions given that they be copied to the +cgi-bin directory). Alias -F .TP .B --scp [filename/wildcard] copies sisu output files to remote host using scp. This requires that @@ -986,45 +991,10 @@ An online version of the sisu man page is available here: .BR * sisu.1 <http://www.jus.uio.no/sisu/man/sisu.1.html> [^10] -.SH SISU BUILT\-IN INTERACTIVE HELP +.SH SISU BUILT-IN INTERACTIVE HELP, [DISCONTINUED] .BR -This is particularly useful for getting the current sisu setup/environment -information: - -.BR - sisu --help - -.BR - sisu --help [subject] - -.BR -sisu --help commands - -.BR -sisu --help markup - -.BR -sisu --help env [for feedback on the way your system is setup with regard - to sisu ] - -.BR - sisu -V [environment information, same as above command] - -.BR - sisu (on its own provides version and some help information) - -.BR -Apart from real-time information on your current configuration the -.B SiSU -manual and man pages are likely to contain more up-to-date information than the -sisu interactive help (for example on commands and markup). - -.BR -NOTE: Running the command sisu (alone without any flags, filenames or -wildcards) brings up the interactive help, as does any sisu command that is not -recognised. Enter to escape. - +This fell out of date and has been discontinued. .SH INTRODUCTION TO SISU MARKUP[^11] .SH SUMMARY @@ -1067,10 +1037,10 @@ primary outline of the document structure. Markup of substantive text includes: * footnotes/endnotes .BR - * linked text and images +* linked text and images .BR - * paragraph actions, such as indent, bulleted, numbered-lists, etc. +* paragraph actions, such as indent, bulleted, numbered-lists, etc. .BR Some interactive help on markup is available, by typing sisu and selecting @@ -1080,19 +1050,19 @@ markup or sisu --help markup To check the markup in a file: .BR - sisu --identify [filename].sst +sisu --identify [filename].sst .BR For brief descriptive summary of markup history .BR - sisu --query-history +sisu --query-history .BR or if for a particular version: .BR - sisu --query-0.38 +sisu --query-0.38 .SH MARKUP EXAMPLES .SH ONLINE @@ -2431,7 +2401,7 @@ locally or on a remote server for which a url is provided. source markup can be shared with the command: .BR - sisu -s [filename] +sisu -s [filename] .SH SISU TEXT - REGULAR FILES (.SST) @@ -2511,13 +2481,13 @@ documents. The command to create a sisupod is: .BR - sisu -S [filename] +sisu -S [filename] .BR Alternatively, make a pod of the contents of a whole directory: .BR - sisu -S +sisu -S .BR .B SiSU @@ -2959,7 +2929,7 @@ for the configuration directory, namely ./_sisu ; ~/_sisu ; /etc/sisu From there they are copied to the root of the output directory with the command: .BR - sisu -CC +sisu -CC .SH MARKUP AND OUTPUT EXAMPLES .SH MARKUP EXAMPLES @@ -3143,25 +3113,25 @@ should they so choose). All site texts/documents are (currently) streamed to four tables: .BR - * one containing semantic (and other) headers, including, title, author, +* one containing semantic (and other) headers, including, title, author, subject, (the .I Dublin Core. ..); .BR - * another the substantive texts by individual "paragraph" (or object) - along +* another the substantive texts by individual "paragraph" (or object) - along with structural information, each paragraph being identifiable by its paragraph number (if it has one which almost all of them do), and the substantive text of each paragraph quite naturally being searchable (both in formatted and clean text versions for searching); and .BR - * a third containing endnotes cross-referenced back to the paragraph from +* a third containing endnotes cross-referenced back to the paragraph from which they are referenced (both in formatted and clean text versions for searching). .BR - * a fourth table with a one to one relation with the headers table contains +* a fourth table with a one to one relation with the headers table contains full text versions of output, eg. pdf, html, xml, and .I ascii. @@ -3217,10 +3187,10 @@ to populate a postgresql database, this being part of .SH SYNOPSIS .BR - sisu -D [instruction] [filename/wildcard if required] +sisu -D [instruction] [filename/wildcard if required] .BR - sisu -D --pg --[instruction] [filename/wildcard if required] +sisu -D --pg --[instruction] [filename/wildcard if required] .SH COMMANDS .BR @@ -3295,10 +3265,10 @@ to populate an sqlite database, this being part of .SH SYNOPSIS .BR - sisu -d [instruction] [filename/wildcard if required] +sisu -d [instruction] [filename/wildcard if required] .BR - sisu -d --(sqlite|pg) --[instruction] [filename/wildcard if required] +sisu -d --(sqlite|pg) --[instruction] [filename/wildcard if required] .SH COMMANDS @@ -3397,7 +3367,7 @@ The following is feedback on the setup on a machine provided by the help command: .BR - sisu --help sql +sisu --help sql .nf Postgresql user: ralph |