diff options
author | Ralph Amissah <ralph@amissah.com> | 2013-05-29 19:50:40 -0400 |
---|---|---|
committer | Ralph Amissah <ralph@amissah.com> | 2013-05-29 19:50:40 -0400 |
commit | 4adb525fb4f143781a05c0e62c3798730f9b0713 (patch) | |
tree | 0ab8a677b71ce286c8a300d076d5e6185bcc2bc4 /data/doc/sisu/html/sisu.1.html | |
parent | v4 v5: cgi helper script, sample search form generator, adjust/improve (diff) |
v4 v5: help, documentation update, concentrate on man pagessisu_4.1.2
* documentation, manpage update
* interactive help, out of date, removed
Diffstat (limited to 'data/doc/sisu/html/sisu.1.html')
-rw-r--r-- | data/doc/sisu/html/sisu.1.html | 220 |
1 files changed, 101 insertions, 119 deletions
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> |