diff options
Diffstat (limited to 'data/doc/sisu/html/sisu.1.html')
| -rw-r--r-- | data/doc/sisu/html/sisu.1.html | 496 |
1 files changed, 249 insertions, 247 deletions
diff --git a/data/doc/sisu/html/sisu.1.html b/data/doc/sisu/html/sisu.1.html index 4922bab1..61d0ab0d 100644 --- a/data/doc/sisu/html/sisu.1.html +++ b/data/doc/sisu/html/sisu.1.html @@ -46,19 +46,19 @@ other information. </dt> <dt><b>-A</b><i> [filename/wildcard]</i> </dt> -<dd>produces <i>plaintext</i> with <i>dos</i> linefeeds and without markup, (object numbers +<dd>produces <i>plaintext</i> with <i>dos</i> linefeeds and without markup, (object numbers are omitted), has footnotes at end of each paragraph that contains them [ <i>-a</i> for equivalent Unix (linefeed) output file] [see <i>-E</i> for endnotes]. </dd> <dt><b>-a</b><i> [filename/wildcard]</i> </dt> -<dd>produces <i>plaintext</i> with <i>Unix</i> linefeeds and without markup, (object numbers +<dd>produces <i>plaintext</i> with <i>Unix</i> linefeeds and without markup, (object numbers are omitted), has footnotes at end of each paragraph that contains them [ <i>-A</i> for equivalent dos (linefeed) output file] [see <i>-e</i> for endnotes]. </dd> <dt><b>-b</b><i> [filename/wildcard]</i> </dt> -<dd>produces <i>xhtml/XML</i> output for browser viewing (sax parsing). </dd> +<dd>produces <i>xhtml/XML</i> output for browser viewing (sax parsing). </dd> <dt><b>-C</b><i> [--init=site]</i> </dt> @@ -67,10 +67,10 @@ directory (config files such as css and dtd files are not updated if they already exist unless modifier is used). <b>-C</b><i> --init=site</i> <i>configure/initialise</i> site more extensive than <i>-C</i> 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> +updated if this modifier is used. </dd> <dt><b>-c</b><i> [filename/wildcard]</i> </dt> -<dd>screen <i>toggle</i> ansi +<dd>screen <i>toggle</i> 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 @@ -78,59 +78,59 @@ output will be without colour). </dd> <dt><b>-D</b><i> [instruction]</i><b> [filename]</b> </dt> <dd>database postgresql -( <i>--pgsql</i> may be used instead) possible instructions, include: <i>--createdb;</i> +( <i>--pgsql</i> may be used instead) possible instructions, include: <i>--createdb;</i> <i>--create;</i> <i>--dropall;</i> <i>--import</i> [filename]; <i>--update</i> [filename]; <i>--remove</i> [filename]; see database section below. </dd> <dt><b>-d</b><i> [--db-[database</i><b> type</b><i> (sqlite|pg)]]</i><b> --[instruction]</b><i> [filename]</i> </dt> -<dd>database type default set to sqlite, (for which <i>--sqlite</i> may be used instead) +<dd>database type default set to sqlite, (for which <i>--sqlite</i> may be used instead) or to specify another database <i>--db-[pgsql,</i> sqlite] (however see -D) possible instructions include: <i>--createdb;</i> <i>--create;</i> <i>--dropall;</i> <i>--import</i> [filename]; <i>--update</i> [filename]; <i>--remove</i> [filename]; see database section below. </dd> <dt><b>-E</b><i> [filename/wildcard]</i> </dt> -<dd>produces <i>plaintext</i> with <i>dos</i> linefeeds, and without markup, endnotes follow -the main text (in <i>-a</i> endnotes follow the paragraphs that contain them). -There are no object numbers [see <i>-e</i> for Unix (linefeed) output file] [see -<i>-A</i> for footnotes]. </dd> +<dd>produces <i>plaintext</i> with <i>dos</i> linefeeds, and without markup, endnotes follow +the main text (in <i>-a</i> endnotes follow the paragraphs that contain them). There +are no object numbers [see <i>-e</i> for Unix (linefeed) output file] [see <i>-A</i> for +footnotes]. </dd> <dt><b>-e</b><i> [filename/wildcard]</i> </dt> -<dd>produces <i>plaintext</i> with <i>Unix</i> linefeeds, +<dd>produces <i>plaintext</i> with <i>Unix</i> linefeeds, and without markup, endnotes follow the main text. Object numbers are omitted. [ <i>-E</i> for equivalent dos (linefeed) output file] [ <i>-a</i> for footnotes]. </dd> <dt><b>-F</b><i> [--webserv=webrick]</i> </dt> -<dd>generate examples of (naive) <i>cgi</i> search form for <i>sqlite</i> and <i>pgsql</i> depends +<dd>generate examples of (naive) <i>cgi</i> search form for <i>sqlite</i> and <i>pgsql</i> 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 <i>-d</i> <i>-D</i> and the <i>database</i> section below. If the optional -parameter <i>--webserv=webrick</i> 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 <i>cgi-bin</i> directory). -<i>-Fv</i> (in addition to the above) provides some information on setting up -<i>hyperestraier</i> for sisu </dd> +search form) see <i>-d</i> <i>-D</i> and the <i>database</i> section below. If the optional parameter +<i>--webserv=webrick</i> 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 <i>cgi-bin</i> directory). <i>-Fv</i> (in +addition to the above) provides some information on setting up <i>hyperestraier</i> +for sisu </dd> <dt> <b>-H</b><i> [filename/wildcard]</i> </dt> -<dd>produces <i>html</i> without -link suffixes (.html .pdf etc.) ("Hide"). Requires an appropriately configured -web server. [behaviour switched after 0.35 see -h]. </dd> +<dd>produces <i>html</i> without link suffixes +(.html .pdf etc.) ("Hide"). Requires an appropriately configured web server. +[behaviour switched after 0.35 see -h]. </dd> <dt><b>-h</b><i> [filename/wildcard]</i> </dt> -<dd>produces - <i>html</i> (with hardlinks i.e. with name suffixes in links/local urls). html, -with internal document links that include the document suffix, i.e. whether -it is .html or .pdf (required for browsing directly off a file system, and -works with most web servers). [behaviour switched after 0.35 see -H]. </dd> +<dd>produces <i>html</i> +(with hardlinks i.e. with name suffixes in links/local urls). html, with internal +document links that include the document suffix, i.e. whether it is .html +or .pdf (required for browsing directly off a file system, and works with +most web servers). [behaviour switched after 0.35 see -H]. </dd> <dt><b>-I</b><i> [filename/wildcard]</i> </dt> -<dd>produces <i>texinfo</i> file. </dd> +<dd>produces <i>texinfo</i> file. </dd> <dt><b>-L</b> </dt> <dd>prints license information. </dd> @@ -155,7 +155,7 @@ for the document, and digests for each object contained within the document <dt><b>-n</b><i> [filename/wildcard/url]</i> </dt> <dd>skip meta-markup -(building of "metaverse"), this skips the equivalent of <i>-m</i> which is otherwise +(building of "metaverse"), this skips the equivalent of <i>-m</i> which is otherwise assumed by most processing flags. </dd> <dt><b>-o</b><i> [filename/wildcard/url]</i> </dt> @@ -164,7 +164,7 @@ document in <i>opendocument</i> file format (opendocument.odt). </dd> <dt><b>-p</b><i> [filename/wildcard]</i> </dt> -<dd>produces <i>LaTeX</i> pdf (portrait.pdf & landscape.pdf). Default paper size is set +<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. <i>--papersize-a4</i> preset sizes include: ’A4’, U.S. ’letter’ and ’legal’ and book sizes ’A5’ and ’B5’ (system defaults to A4). </dd> @@ -175,7 +175,7 @@ line parameter, e.g. <i>--papersize-a4</i> preset sizes include: ’A4&rsquo <dt><b>-R</b><i> [filename/wildcard]</i> </dt> <dd><i>copies</i> sisu output files -to <i>remote</i> host using rsync. This requires that sisurc.yml has been provided +to <i>remote</i> 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 @@ -184,27 +184,27 @@ with other flags, it is not). Also see <i>-r</i> </dd> <dt><b>-r</b><i> [filename/wildcard]</i> </dt> <dd><i>copies</i> sisu -output files to <i>remote</i> host using scp. This requires that sisurc.yml has +output files to <i>remote</i> 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 <i>-R</i> </dd> <dt><b>-S</b> </dt> <dd>produces a <i>sisupod</i> a zipped -sisu directory of markup files including <i>sisu</i> markup source files and -the directories local <i>configuration</i> file, <i>images</i> and <i>skins.</i> <b>Note:</b> this -only includes the configuration files or skins contained in <i>./_sisu</i> not -those in <i>~/.sisu</i> <i>-S</i> [filename/wildcard] option. <b>Note:</b> (this option is tested -only with zsh). </dd> +sisu directory of markup files including <i>sisu</i> markup source files and the +directories local <i>configuration</i> file, <i>images</i> and <i>skins.</i> <b>Note:</b> this only +includes the configuration files or skins contained in <i>./_sisu</i> not those +in <i>~/.sisu</i> <i>-S</i> [filename/wildcard] option. <b>Note:</b> (this option is tested only +with zsh). </dd> <dt><b>-S</b><i> [filename/wildcard]</i> </dt> -<dd>produces a zipped file of the prepared -document specified along with associated images, by default named <i>sisupod.zip</i> -they may alternatively be named with the filename extension <i>.ssp</i> This provides +<dd>produces a zipped file of the prepared document +specified along with associated images, by default named <i>sisupod.zip</i> they +may alternatively be named with the filename extension <i>.ssp</i> This provides a quick way of gathering the relevant parts of a sisu document which can -then for example be emailed. A sisupod includes <i>sisu</i> markup source file, - (along with associated documents if a master file, or available in multilingual -versions), together with related <i>images</i> and <i>skin.</i> SiSU commands can be -run directly against a sisupod contained in a local directory, or provided +then for example be emailed. A sisupod includes <i>sisu</i> markup source file, +(along with associated documents if a master file, or available in multilingual +versions), together with related <i>images</i> and <i>skin.</i> SiSU 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 @@ -212,7 +212,7 @@ 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. <b>Note:</b> 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 <i>-S</i> option without [filename/wildcard]. </dd> +sending). See the <i>-S</i> option without [filename/wildcard]. </dd> <dt><b>-s</b><i> [filename/wildcard]</i> </dt> @@ -224,78 +224,79 @@ sending). See the <i>-S</i> option without [filename/wildcard]. </dd> <dt><b>-U</b><i> [filename/wildcard]</i> </dt> -<dd>prints <i>url</i> 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), <i>-u</i> provides <i>url</i> 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 </dd> - -<dt><b>-u</b><i> [filename/wildcard]</i> -</dt> -<dd>provides <i>url</i> mapping of output files for the flags requested for processing, -also see <i>-U</i> </dd> +<dd>prints <i>url</i> 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), <i>-u</i> provides <i>url</i> 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 </dd> + +<dt><b>-u</b><i> [filename/wildcard]</i> </dt> +<dd>provides <i>url</i> mapping +of output files for the flags requested for processing, also see <i>-U</i> </dd> <dt><b>-V</b> </dt> -<dd>on its own, provides SiSU <i>version</i> and <i>environment</i> information -(sisu --help env) </dd> +<dd>on +its own, provides SiSU <i>version</i> and <i>environment</i> information (sisu --help env) +</dd> <dt><b>-V</b><i> [filename/wildcard]</i> </dt> -<dd>even more <i>verbose</i> than the <i>-v</i> flag. -(also see -M) </dd> +<dd>even more <i>verbose</i> than the <i>-v</i> flag. (also see -M) </dd> <dt><b>-v</b> </dt> -<dd>on its own, provides SiSU <i>version</i> information </dd> +<dd>on +its own, provides SiSU <i>version</i> information </dd> -<dt><b>-v</b><i> [filename/wildcard]</i> -</dt> -<dd>provides <i>verbose</i> output of what is being built, where it is being built -(and error messages if any), as with <i>-u</i> flag provides a url mapping of -files created for each of the processing flag requests. See also <b>-V</b> </dd> +<dt><b>-v</b><i> [filename/wildcard]</i> </dt> +<dd>provides +<i>verbose</i> output of what is being built, where it is being built (and error +messages if any), as with <i>-u</i> flag provides a url mapping of files created +for each of the processing flag requests. See also <b>-V</b> </dd> <dt><b>-W</b> </dt> -<dd>starts -ruby’s <i>webrick</i> 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 <i>-h</i> option rather than <i>-H</i> ; also, note <i>-F</i> webrick -]. </dd> - -<dt><b>-w</b><i> [filename/wildcard]</i> </dt> -<dd>produces <i>concordance</i> (wordmap) a rudimentary -index of all the words in a document. </dd> - -<dt><b>-X</b><i> [filename/wildcard]</i> </dt> -<dd>produces <i>XML</i> -output with deep document structure, in the nature of dom. </dd> - -<dt><b>-x</b><i> [filename/wildcard]</i> -</dt> -<dd>produces <i>XML</i> output shallow structure (sax parsing). </dd> +<dd>starts ruby’s <i>webrick</i> +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 +<i>-h</i> option rather than <i>-H</i> ; also, note <i>-F</i> webrick ]. </dd> -<dt><b>-Y</b><i> [filename/wildcard]</i> +<dt><b>-w</b><i> [filename/wildcard]</i> </dt> -<dd>produces a short sitemap entry for the document, based on html output and -the sisu_manifest. <i>--sitemaps</i> generates/updates the sitemap index of existing -sitemaps. (Experimental, [g,y,m announcement this week]) </dd> +<dd>produces <i>concordance</i> (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) </dd> -<dt><b>-y</b><i> [filename/wildcard]</i> +<dt><b>-X</b><i> [filename/wildcard]</i> </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> +<dd>produces <i>XML</i> output with deep document structure, in the nature of dom. +</dd> + +<dt><b>-x</b><i> [filename/wildcard]</i> </dt> +<dd>produces <i>XML</i> output shallow structure (sax parsing). +</dd> + +<dt><b>-Y</b><i> [filename/wildcard]</i> </dt> +<dd>produces a short sitemap entry for the document, based +on html output and the sisu_manifest. <i>--sitemaps</i> generates/updates the sitemap +index of existing sitemaps. (Experimental, [g,y,m announcement this week]) +</dd> + +<dt><b>-y</b><i> [filename/wildcard]</i> </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</b><i> [filename/wildcard]</i> </dt> -<dd>Zap, if used with other processing -flags <i>deletes</i> 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. </dd> +<dd>Zap, if used +with other processing flags <i>deletes</i> 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. </dd> <dt><b>-z</b><i> [filename/wildcard]</i> </dt> -<dd>produces <i>php</i> (zend) [this feature is disabled -for the time being] </dd> +<dd>produces <i>php</i> (zend) +[this feature is disabled for the time being] </dd> </dl> <h2><a name='sect5' href='#toc5'>modifiers</a></h2> @@ -303,85 +304,85 @@ for the time being] </dd> <dl> <dt><b>--no-ocn</b> </dt> -<dd>[with -h -H or -p] switches off object -citation numbering. Produce output without identifying numbers in margins -of html or LaTeX/pdf output. </dd> +<dd>[with -h -H +or -p] switches off object citation numbering. Produce output without identifying +numbers in margins of html or LaTeX/pdf output. </dd> <dt><b>--no-annotate</b> </dt> -<dd>strips output text of editor endnotes~[* -square brackets ]~ denoted by asterisk or dagger/plus sign </dd> +<dd>strips output +text of editor endnotes~[* square brackets ]~ denoted by asterisk or dagger/plus +sign </dd> <dt><b>--no-asterisk</b> </dt> -<dd>strips -output text of editor endnotes~[* square brackets ]~ denoted by asterisk -sign </dd> +<dd>strips output text of editor endnotes~[* square brackets +]~ denoted by asterisk sign </dd> <dt><b>--no-dagger</b> </dt> -<dd>strips output text of editor endnotes~[+ square brackets -]~ denoted by dagger/plus sign </dd> +<dd>strips output text of editor endnotes~[+ +square brackets ]~ denoted by dagger/plus sign </dd> </dl> <h2><a name='sect6' href='#toc6'>databases</a></h2> <dl> -<dt>dbi - database interface +<dt>dbi - database +interface </dt> +<dd><b>-D</b> or <b>--pgsql</b> set for <i>postgresql</i> <b>-d</b> or <b>--sqlite</b> default set for <i>sqlite</i> +-d is modifiable with --db=[database type (pgsql or sqlite)] </dd> + +<dt><b>-Dv --createall</b> </dt> -<dd><b>-D</b> or <b>--pgsql</b> set for <i>postgresql</i> <b>-d</b> or <b>--sqlite</b> default set for <i>sqlite</i> -d is -modifiable with --db=[database type (pgsql or sqlite)] </dd> - -<dt><b>-Dv --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) [ <i>-dv</i> --createall sqlite equivalent] -it may be necessary to run sisu <i>-Dv</i> --createdb initially </dd> - -<dt>NOTE: at the present -time for postgresql it may be necessary to manually create the database. -The command would be </dt> -<dd><i>’createdb</i> [database name]’ where database name would -be SiSU_[present working directory name (without path)]. Please use only -alphanumerics and underscores. </dd> - -<dt><b>-Dv --import </b> </dt> -<dd><i>[filename/wildcard]</i> imports data -specified to postgresql db (rb.dbi) [ <i>-dv</i> --import sqlite equivalent] </dd> - -<dt><b>-Dv --update -</b> </dt> -<dd><i>[filename/wildcard]</i> updates/imports specified data to postgresql db (rb.dbi) -[ <i>-dv</i> --update sqlite equivalent] </dd> +<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) [ <i>-dv</i> --createall sqlite +equivalent] it may be necessary to run sisu <i>-Dv</i> --createdb initially </dd> + +<dt>NOTE: +at the present time for postgresql it may be necessary to manually create +the database. The command would be </dt> +<dd><i>’createdb</i> [database name]’ where database +name would be SiSU_[present working directory name (without path)]. Please +use only alphanumerics and underscores. </dd> + +<dt><b>-Dv --import</b> </dt> +<dd><i>[filename/wildcard]</i> imports +data specified to postgresql db (rb.dbi) [ <i>-dv</i> --import sqlite equivalent] +</dd> + +<dt><b>-Dv --update</b> </dt> +<dd><i>[filename/wildcard]</i> updates/imports specified data to postgresql +db (rb.dbi) [ <i>-dv</i> --update sqlite equivalent] </dd> <dt><b>-D --remove</b> </dt> -<dd><i>[filename/wildcard]</i> removes specified -data to postgresql db (rb.dbi) [ <i>-d</i> --remove sqlite equivalent] </dd> +<dd><i>[filename/wildcard]</i> +removes specified data to postgresql db (rb.dbi) [ <i>-d</i> --remove sqlite equivalent] +</dd> -<dt><b>-D --dropall</b> -</dt> -<dd>kills data" and drops (postgresql or sqlite) db, tables & indexes [ <i>-d</i> --dropall -sqlite equivalent] </dd> +<dt><b>-D --dropall</b> </dt> +<dd>kills data" and drops (postgresql or sqlite) db, tables & indexes +[ <i>-d</i> --dropall sqlite equivalent] </dd> <dt>The v in e.g. -Dv is for verbose output. </dt> <dd></dd> </dl> </blockquote> -<h2><a name='sect7' href='#toc7'>Shortcuts, Shorthand -for multiple flags</a></h2> +<h2><a name='sect7' href='#toc7'>Shortcuts, +Shorthand for multiple flags</a></h2> <dl> <dt><b>--update</b><i> [filename/wildcard]</i> </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>-0 to -5 [filename or -wildcard] </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>-0 to -5 [filename +or wildcard] </dt> <dd>Default shorthand mappings (note that the defaults can be changed/configured in the sisurc.yml file): </dd> </dl> @@ -395,20 +396,20 @@ default action run when no options are give, i.e. on ’sisu [filename]&rsqu <i>-4</i> -mNhwpAobxXDyY --import <p> <i>-5</i> -mNhwpAobxXDyY --update <p> -add <i>-v</i> for verbose mode and <i>-c</i> for color, e.g. <i>sisu</i> -2vc [filename or wildcard] +add <i>-v</i> for verbose mode and <i>-c</i> for color, e.g. <i>sisu</i> -2vc [filename or wildcard] <p> -consider <i>-u</i> for appended url info or <i>-v</i> for verbose output +consider <i>-u</i> for appended url info or <i>-v</i> for verbose output <h2><a name='sect8' href='#toc8'>Document Markup</a></h2> <b>SiSU -Markup</b> an incomplete summary. <p> -<b>Note:</b> files should be marked up for SiSU -using <i>UTF-8</i> encoding. <p> -Some interactive help on markup is available, by typing - <i>sisu</i> and selecting <i>markup</i> or <i>sisu</i> --help markup +Markup</b> an incomplete summary. <p> +<b>Note:</b> files should be marked up for SiSU using +<i>UTF-8</i> encoding. <p> +Some interactive help on markup is available, by typing <i>sisu</i> +and selecting <i>markup</i> or <i>sisu</i> --help markup <dl> -<dt>Sample markup files can -be used as examples: </dt> +<dt>Sample markup files can be used +as examples: </dt> <dd><i><<a href='http://www.jus.uio.no/sisu/sample'>http://www.jus.uio.no/sisu/sample</a> ></i> </dd> @@ -495,12 +496,12 @@ the shortcut: <p> <i>{~^</i> [text to link] <i>}<a href='http://url.org'>http://url.org</i></a> <p> -is equivalent to: <p> +is equivalent to: <p> <i>{</i> [text to link] <i>}<a href='http://url.org'>http://url.org</i></a> <i>~{</i> <a href='http://url.org'>http://url.org</a> - <i>}~</i> -<p> -(which produces hyper-linked text within a document/paragraph, with an endnote + <i>}~</i> <p> +(which +produces hyper-linked text within a document/paragraph, with an endnote providing the url for the text location used in the hyperlink) <p> url example: <p> @@ -537,7 +538,7 @@ citation numbering</a></h2> <i>-#</i> unnumbered paragraph, delete when not required (place marker at end of paragraph) [used in dummy headings, eg. for segmented html] <p> It is convenient -to mention here that the <i>-0</i> flag generates html and latex/pdf output without +to mention here that the <i>-0</i> flag generates html and latex/pdf output without visible object character numbers. <p> <i>sisu</i> -0 [filename.sst] <h2><a name='sect15' href='#toc15'>Page breaks (LaTeX/pdf)</a></h2> @@ -560,7 +561,7 @@ line <p> for folding by vim folds <h2><a name='sect17' href='#toc17'>Special characters</a></h2> special characters can be escaped -with a backslash <i>{</i> } < > are contextual special characters, (in combination +with a backslash <i>{</i> } < > are contextual special characters, (in combination with other characters). <i>~</i> - _ / % ^ and occasionally <i>!</i> # + , are special characters in particular circumstances, see the syntax chart. [note that SiSU is not optimised for technical writing] @@ -586,8 +587,8 @@ see example below]<br> <p> column one row three<br> and so on<br> here<br> - <br> - <i>}table</i> + +<p> <i>}table</i> <p> whole table gets an object citation number <p> <h2><a name='sect19' href='#toc19'>Other Grouped or @@ -628,7 +629,7 @@ be other documents that would be processed in a regular way, or markup bits prepared only for inclusion within a master document <i>.sst</i> regular markup file, or <i>.ssi</i> (insert/information) <i>.sst</i> A secondary file of the composite document is built prior to processing with the same prefix and the suffix - <i>._sst</i> and <i>._sst</i> There are a number of alternative syntaxes for requiring +<i>._sst</i> and <i>._sst</i> There are a number of alternative syntaxes for requiring external documents in order to permit use of ascii hypertext linking available in the vim editor. They are as follows: <p> @@ -670,29 +671,29 @@ thlnk syntax (or regular sisu syntax), e.g. </dt> <h2><a name='sect21' href='#toc21'>Document Headers</a></h2> 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. -<p> All -header instructions may take either form: <i>@headername:</i> [introduced in 0.38] +information as to how the document as a whole is to be processed. +<p> All header +instructions may take either form: <i>@headername:</i> [introduced in 0.38] or -<p>or <i>0~headername</i> All Dublin Core meta tags are available -<p> <i>@indentifier:</i> -information or instructions [introduced in 0.38] +<p><i>0~headername</i> All Dublin Core meta tags are available +<p> <i>@indentifier:</i> information +or instructions [introduced in 0.38] <p> or -<p> <i>0~indentifier</i> information -or instructions, old equivalent, depreciated -<p> where the "identifier" is -a tag recognised by the program, and the "information" or "instructions" -belong to the tag/indentifier specified. -<p> Note: a header where used should -only be used once; all headers apart from @title: (0~title) are optional; -the @structure: (0~toc) header is used to describe document structure, -and can be useful to know. -<p> @structure: PART; CHAPTER; SECTION; ARTICLE; -none; none; -<p> 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. ^) -<p> For help see one of the following (and markup samples):<br> +<p> <i>0~indentifier</i> information or instructions, +old equivalent, depreciated +<p> where the "identifier" is a tag recognised +by the program, and the "information" or "instructions" belong to the tag/indentifier +specified. +<p> Note: a header where used should only be used once; all headers +apart from @title: (0~title) are optional; the @structure: (0~toc) header +is used to describe document structure, and can be useful to know. +<p> @structure: +PART; CHAPTER; SECTION; ARTICLE; none; none; +<p> 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. ^) +<p> For help see one of +the following (and markup samples):<br> <p> * interactive help - type ’sisu --help headers’<br> @@ -728,16 +729,16 @@ markup version] <p> <i>@format:</i> <p> <i>@identifier:</i> <p> <i>@source:</i> -<p> <i>@language:</i> [or @language.document:] -language in which current version of document is published. Some country -settings result in processing adjustments, e.g. in LaTeX hyphenation, some -country codes are recognized, but the language name in Engish is preferred. -English 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, ee - Estonian, hu - Hungarian, pl -- Polish, ro - Romanian, ru - Russian, gl - Greek, uk - Ukranian, tr - Turkish, -si - Slovene, sk - Slovak, hr - Croatian, cs - Czech, bg - Bulgarian ) [however, -encodings are not available for all of the languages listed.] +<p> <i>@language:</i> [or @language.document:] language +in which current version of document is published. Some country settings +result in processing adjustments, e.g. in LaTeX hyphenation, some country +codes are recognized, but the language name in Engish is preferred. English +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, ee - Estonian, hu - Hungarian, pl - Polish, +ro - Romanian, ru - Russian, gl - Greek, uk - Ukranian, tr - Turkish, si - Slovene, +sk - Slovak, hr - Croatian, cs - Czech, bg - Bulgarian ) [however, encodings +are not available for all of the languages listed.] <p> <i>@language.original:</i> <p>original language in which the work was published @@ -769,7 +770,7 @@ classification]; isbn=[ISBN]; pg=[Project Gutenberg text number] <p> <i>@prefix_b:</i> or @prefix: [prefix is placed just after table of contents] <p> <i>@rcs:</i> $Id$ -[or <i>@cvs:</i> used by rcs or cvs to embed version (revision control) information +[or <i>@cvs:</i> used by rcs or cvs to embed version (revision control) information into document, rcs or cvs can usefully provide a history of updates to a document ] <p> <i>@structure:</i> PART; CHAPTER; SECTION; ARTICLE; none; none; @@ -795,21 +796,23 @@ new=A,B,C; break=1; num_top=1 [or newpage=A,B,C; breakpage=1; num_top=1] see headings] <p> <i>@bold:</i> [regular expression of words/phrases to be made bold] -<p> <i>@italics:</i> [regular expression of words/phrases to italicise] <br> - <i>@vocabulary:</i> name of taxonomy/vocabulary/wordlist to use against document +<p> <i>@italics:</i> [regular expression of words/phrases to italicise] +<p> <i>@vocabulary:</i> -<p> <i>@skin:</i> skin_doc_[name_of_desired_document_skin] -<p> <i>@links:</i> { SiSU }<a href='http://www.jus.uio.no/sisu/'>http://www.jus.uio.no/sisu/</a> +<p>name of taxonomy/vocabulary/wordlist to use against document +<p> <i>@skin:</i> skin_doc_[name_of_desired_document_skin] -{ FSF }<a href='http://www.fsf.org'>http://www.fsf.org</a> +<p> <i>@links:</i> { SiSU }<a href='http://www.jus.uio.no/sisu/'>http://www.jus.uio.no/sisu/</a> + { FSF }<a href='http://www.fsf.org'>http://www.fsf.org</a> -<p> <i>@promo:</i> 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] +<p> <i>@promo:</i> +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] <p> <i>:A~</i> Top level heading [this usually has similar content to the title @title: ] NOTE: the heading levels described here are in 0.38 notation, see heading - + <p> <i>:B~</i> Second level heading [this is a heading level divider] <p> <i>:C~</i> Third level heading [this is a heading level divider] @@ -916,7 +919,7 @@ of their own. </dt> <dl> -<dt>would map to </dt> +<dt>would map to </dt> <dd></dd> </dl> <p> @@ -1015,7 +1018,7 @@ The last part of a directory path is used to create a sub-directory into which generated documents are placed, in a database of the same name, unless overridden. <p> Documents within -the directory <i>~/ebook</i> <p> +the directory <i>~/ebook</i> <p> <blockquote><i>~/ebook/free_culture.sst</i> </blockquote> <p> would be placed in tables @@ -1044,9 +1047,9 @@ all documents within that directory take on a particular appearance. If a skin exists in the skin/dir with the same name as the document directory, it will automatically be used for each of the documents in that directory, (except where a document specifies the use of another skin, in the skin/doc -directory). when end <p> -A personal habit is to place all skins within the -doc directory, and symbolic links as needed from the site, or dir directories +directory). when end <p> +A personal habit is to place all skins within the doc +directory, and symbolic links as needed from the site, or dir directories as required. <p> A site skin, modifies the program default skin. <p> Sample skins @@ -1058,7 +1061,7 @@ directory) <h2><a name='sect31' href='#toc31'>Document Naming Convention</a></h2> <p> SiSU documents are named with the -suffix <i>ss</i> followed by a third distinguishing letter, usually t for ordinary +suffix <i>ss</i> followed by a third distinguishing letter, usually t for ordinary text files. <p> <i>.sst</i> is used by regular documents, and for most purposes is all you need to be aware of <p> @@ -1117,7 +1120,7 @@ are not amongst the options considered. For basic use only a fraction of the information provided here is required. There may be a bit of an information management problem in determining what though. For the markup of a book -see the samples provided in <i><<a href='http://www.jus.uio.no/sisu/sample'>http://www.jus.uio.no/sisu/sample</a> +see the samples provided in <i><<a href='http://www.jus.uio.no/sisu/sample'>http://www.jus.uio.no/sisu/sample</a> ></i> and referred to in the text <i><<a href='http://www.jus.uio.no/sisu/SiSU'>http://www.jus.uio.no/sisu/SiSU</a> ></i> The flags to generate html @@ -1139,31 +1142,31 @@ markup file will not appear in subsequently generated text unless this flag is used: <b>sisu</b> <i>-m</i> [filename or wildcard] <p> to create html and pdf output, with verbose output of samplefile1.sst and samplefile2.sst <b>sisu</b> <i>-mhpv</i> samplefile1.sst -samplefile2.sst <blockquote>Note: <i>-m</i> does initial processing, and <i>-H</i> omits filename -suffixes and requires a properly configured web server. <i>-h</i> is used to include -filename suffixes for file system viewing </blockquote> -<p> -generate html, a word map and -pdf with verbose output for all marked up documents in a directory: <b>sisu</b> -<i>-mhwpv</i> * <p> -generate html, word map, pdf, plaintext, xhtml, xml sax and xml -dom versions with verbose output for all marked up documents in a directory: -<b>sisu</b> <i>-mhwpabxXv</i> * <p> -to create html, pdf, xml, plaintext and a concordance -file (wordmap) as output, with verbose output of all marked up files in -a directory <b>sisu</b> <i>-mhpxXawv</i> *.{r,s}? <p> -generate html, word map and pdf and place -on remote server with verbose output 2 named example files in a directory -(assumes has been set up, and first time must be run without other flags -ie sisu <i>-mrv</i> [filenames/wildcard]): <b>sisu</b> <i>-mhwprv</i> example_file.sst other_example_file.sst +samplefile2.sst <blockquote>Note: <i>-m</i> does initial processing, and <i>-H</i> omits filename suffixes +and requires a properly configured web server. <i>-h</i> is used to include filename +suffixes for file system viewing </blockquote> <p> -to process a remote sisu marked up file (html,pdf,concordance), provide -the url(s) (works for text only files, will be downloaded and processed -locally): <b>sisu</b> <i>-mhwpv</i> <a href='http://www.jus.uio.no/sisu/sample/markup/gpl2.fsf.sst'>http://www.jus.uio.no/sisu/sample/markup/gpl2.fsf.sst</a> - http://www.jus.uio.no/sisu/sample/markup/autonomy_markup0.sst +generate html, a word map and pdf with +verbose output for all marked up documents in a directory: <b>sisu</b> <i>-mhwpv</i> * <p> -one file is local the other remote process (html,pdf,concordance,plaintext -and place on pre-set remote destination): <b>sisu</b> <i>-mhwparv</i> gpl2.fsf.sst <a href='http://www.jus.uio.no/sisu/sample/markup/autonomy_markup0.sst'>http://www.jus.uio.no/sisu/sample/markup/autonomy_markup0.sst</a> +generate html, word map, pdf, plaintext, xhtml, xml sax and xml dom versions +with verbose output for all marked up documents in a directory: <b>sisu</b> <i>-mhwpabxXv</i> +* <p> +to create html, pdf, xml, plaintext and a concordance file (wordmap) +as output, with verbose output of all marked up files in a directory <b>sisu</b> +<i>-mhpxXawv</i> *.{r,s}? <p> +generate html, word map and pdf and place on remote server +with verbose output 2 named example files in a directory (assumes has been +set up, and first time must be run without other flags ie sisu <i>-mrv</i> [filenames/wildcard]): +<b>sisu</b> <i>-mhwprv</i> example_file.sst other_example_file.sst <p> +to process a remote sisu +marked up file (html,pdf,concordance), provide the url(s) (works for text +only files, will be downloaded and processed locally): <b>sisu</b> <i>-mhwpv</i> <a href='http://www.jus.uio.no/sisu/gpl3.fsf/gpl3.fsf.sst'>http://www.jus.uio.no/sisu/gpl3.fsf/gpl3.fsf.sst</a> + +http://www.jus.uio.no/sisu/sample/markup/autonomy_markup0.sst <p> +one file is local +the other remote process (html,pdf,concordance,plaintext and place on pre-set +remote destination): <b>sisu</b> <i>-mhwparv</i> gpl3.fsf.sst <a href='http://www.jus.uio.no/sisu/sample/markup/autonomy_markup0.sst'>http://www.jus.uio.no/sisu/sample/markup/autonomy_markup0.sst</a> <p> initialize database, create relations (first manually create database with @@ -1180,8 +1183,7 @@ has an interactive help, which is accessed by typing just "sisu" at the command line, or as described below: <b>sisu</b> commands, document preparation, customisation, installation etc. <br> <pre>try: -sisu --help - sisu help +sisu --help sisu help help sisu --help commands sisu --help commands environment sisu --help env @@ -1252,7 +1254,7 @@ dom and node): <p> <i>sisu</i> --from-kdi [kdissert filename] attempts to convert a kdissert file (.kdi) <p>to sisu markup -<p> <i>sisu</i> --identify [filename/wildcard] attempts to identify +<p> <i>sisu</i> --identify [filename/wildcard] attempts to identify <p>the markup version of the file <p> <i>sisu</i> --query=[version number] and <i>sisu</i> --query=history |