diff options
Diffstat (limited to 'data/doc/sisu/markup-samples/manual')
25 files changed, 214 insertions, 59 deletions
diff --git a/data/doc/sisu/markup-samples/manual/_sisu/sisu_document_make b/data/doc/sisu/markup-samples/manual/_sisu/sisu_document_make index 2327875e..211f052c 100644 --- a/data/doc/sisu/markup-samples/manual/_sisu/sisu_document_make +++ b/data/doc/sisu/markup-samples/manual/_sisu/sisu_document_make @@ -3,7 +3,7 @@ :breaks: new=C; break=1 :bold: /Debian|Ruby|SiSU/ :italics: /Linux|GPL|GPLv3|LaTeX|PostgreSQL|SQLite|SQL|Vim|ascii|plaintext|UTF-?8|HTML|XHTML|XML|EPUB|OpenDocument|ODF|ODT|PDF|pgSQL|TeXinfo|YAML|YML|OCN|object citation system|object citation numbering|granular search|Dublin Core/ - :substitute: /${sisu_stable}/,'5.6.0' /${sisu_dev}/,'6.2.1' /${debian_stable}/,'*{Wheezy}*' /${debian_testing}/,'*{Jessie}*' + :substitute: /${sisu_stable}/,'5.6.2' /${sisu_dev}/,'6.2.3' /${debian_stable}/,'*{Wheezy}*' /${debian_testing}/,'*{Jessie}*' :home_button_text: {SiSU}http://sisudoc.org; {git}http://git.sisudoc.org :footer: {SiSU}http://sisudoc.org; {git}http://git.sisudoc.org diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_commands.sst b/data/doc/sisu/markup-samples/manual/en/sisu_commands.sst index 2de5ff43..31f1d7a0 100644 --- a/data/doc/sisu/markup-samples/manual/en/sisu_commands.sst +++ b/data/doc/sisu/markup-samples/manual/en/sisu_commands.sst @@ -42,12 +42,15 @@ see --act !_ --ao [filename/wildcard/url] \\ assumed for most other flags, creates new intermediate files for processing (abstract objects, 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. +={ SiSU command:abstract objects|document abstraction|--ao|--dal|-m (document abstraction) } !_ --act[0-9] [filename/wildcard] \\ --act0 to --act9 configurable shortcuts for multiple flags, -0 to -9 synonyms, configure in sisurc.yml, sisu default action on a specified file where no flag is provided is --act0, current default setting for --act0 is --digest --qrcode --text --html --epub --concordance --pdf --odf --docbook --xhtml --xml-sax --xml-dom --sqlite --manifest --verbose +={ SiSU command:multiple instruction shortcut|--act } -!_ --asciitext [filename/wildcard] \\ -asciitext, smart text (not available) +!_ --asciidoc [filename/wildcard] \\ +asciidoc, smart text (not available) +={ SiSU command:asciidoc output (not available)|--asciidoc (not available) } !_ -b [filename/wildcard] \\ see --xhtml @@ -66,18 +69,23 @@ see --color-on !_ --color-off \\ turn off color in output to terminal +={ SiSU command:terminal output color|--color-on } !_ --color-on \\ turn on color in output to terminal +={ SiSU command:terminal output color|--color-off } !_ --color-toggle [filename/wildcard] \\ 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 +={ SiSU command:terminal output color|--color-toggle|-c (color toggle) } !_ --configure \\ 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. +={ SiSU command:configure|--configure|--init-site|-C (initialize site/configure) } !_ --concordance [filename/wildcard] \\ 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 +={ SiSU command:concordance file output|--concordance|-w (concordance file/ wordlist);output:concordance command;concordance:command } !_ -d [filename/wildcard/url] \\ see --docbook @@ -90,21 +98,29 @@ see --zap !_ --digests [filename/wildcard/url] \\ document digest or document content certificate ( DCC ) as sha 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). --digests -V for verbose digest output to screen. +={ SiSU command:digests output|--digests|-N (hash digests) } !_ --docbook [filename/wildcard/url] \\ docbook xml +={ SiSU command:docbook output|--docbook|-d (docbook output) } !_ --dom [filename/wildcard/url] \\ see --xml-dom !_ --dump[=directory_path] [filename/wildcard] \\ places output in directory specified, if none is specified in the current directory (pwd). Unlike using default settings HTML files have embedded css. Compare --redirect +={ SiSU command:place output in specified directory|--dump } !_ -e [filename/wildcard] \\ see --epub !_ --epub [filename/wildcard] \\ produces an epub document, [sisu version >=2 ] (filename.epub). Alias -e +={ SiSU command:epub output|--epub|-e (epub output);output:epub command;epub:command } + +!_ --errors-as-warnings \\ +override stop processing on error. Alias --no-stop +={ SiSU command:error override|--errors-as-warnings|--no-stop;errors:override|no stop } !_ --exc-* \\ exclude output feature, overrides configuration settings @@ -123,6 +139,7 @@ exclude output feature, overrides configuration settings --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-* +={ SiSU command:exclude object numbering|exclude table of contents|exclude links to manifest|exclude search form|exclude mini table of contents|exclude mini table of contents in manifest|exclude html navigation bar|--exc-numbering|--exc-ocn|--exc-toc|--exc-search-form|--exc-minitoc|--exc-manifest-minitoc } !_ -F [--webserv=webrick] \\ see --sample-search-form @@ -134,10 +151,10 @@ see --find fictionbook xml (not available) !_ --find [optional string part of filename] \\ -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 +see --glob !_ -G [optional string part of filename] \\ -see --find +see --glob !_ -g [filename/wildcard] \\ see --git @@ -146,28 +163,31 @@ see --git produces or updates markup source file structure in a git repo (experimental and subject to change). Alias -g !_ --glob [optional string part of filename] \\ -see --find +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 -G, -f, --find +={ SiSU command:glob|find|--glob|--find } !_ -h [filename/wildcard] \\ see --html !_ --harvest *.ss[tm] \\ 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. - -!_ --help [topic] \\ -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. +={ SiSU command:harvest metadata (docment authors and topics)|--harvest } !_ --html [filename/wildcard] \\ produces html output, in two forms (i) segmented text with table of contents (toc.html and index.html) and (ii) the document in a single file (scroll.html). Alias -h +={ SiSU command:html output|--html|-h (html output);output:html command;html:command } !_ --html-scroll [filename/wildcard] \\ produces html output, the document in a single file (scroll.html) only. Compare --html-seg and --html +={ SiSU command:html output|--html-scroll } !_ --html-seg [filename/wildcard] \\ produces html output, segmented text with table of contents (toc.html and index.html). Compare --html-scroll and --html +={ SiSU command:html output|--html-seg } !_ --html-strict [filename/wildcard] \\ produces html with --strict option. see --strict +={ SiSU command:html output|--html-strict } !_ -I [filename/wildcard] \\ see --texinfo @@ -205,12 +225,15 @@ see --dal (document abstraction level/layer) !_ --maintenance [filename/wildcard/url] \\ maintenance mode, interim processing files are preserved and their locations indicated. (also see -V). Aliases -M and --keep-processing-files. +={ SiSU command:maintenance mode (retain intermediate files)|--maintenance|-M (maintenance mode) } !_ --manifest [filename/wildcard] \\ 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. +={ SiSU command:manifest (of outputs)|--manifest|-y (output manifest) } !_ --manpage [filename/wildcard] \\ produces man page of file, not suitable for all outputs. Alias -i +={ SiSU command:manpage output|--manpage|-i (manpage output);output:manpage command;manpage:command } !_ --markdown [filename/wildcard/url] \\ markdown smart text (not available) @@ -230,6 +253,10 @@ skip the creation of intermediate processing files (document abstraction) if the !_ --no-* \\ see --exc-* +!_ --no-stop \\ +override stop processing on error. Alias --erros-as-warnings +={ SiSU command:error override|--errors-as-warnings|--no-stop;errors:override|no stop } + !_ --numbering \\ turn on "object citation numbers". See --inc-ocn and --exc-ocn @@ -251,6 +278,7 @@ select output directory structure from 3 alternatives: --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-* +={ SiSU command:output structure|--output-by-filename|--output-by-filetype|--output-by-language } !_ -P [language_directory/filename language_directory] \\ see --po4a @@ -260,27 +288,32 @@ see --pdf !_ --papersize-(a4|a5|b5|letter|legal) \\ in conjunction with --pdf set pdf papersize, overriding any configuration settings, to set more than one papersize repeat the option --pdf --papersize-a4 --papersize-letter. See also --papersize=* +={ SiSU command:pdf papersize|--papersize-a4|--papersize-letter|--papersize } !_ --papersize=a4,a5,b5,letter,legal in conjunction with --pdf set pdf papersize, overriding any configuration settings, to set more than one papersize list after the equal sign with a comma separator --papersize=a4,letter. See also --papersize-* !_ --pdf [filename/wildcard] \\ produces LaTeX pdf (portrait.pdf & landscape.pdf). Orientation and papersize may be set on the command-line. 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), and; --landscape or --portrait, so: e.g. "sisu --pdf-a4 --pdf-letter --landscape --verbose [filename/wildcard]" or "sisu --pdf --landscape --a4 --letter --verbose [filename/wildcard]". --pdf defaults to both landscape & portrait output, and a4 if no other papersizes are configured. Related options --pdf-landscape --pdf-portrait --pdf-papersize-* --pdf-papersize=[list]. Alias -p +={ SiSU command:pdf output|--pdf|-p (pdf output);output:pdf command;pdf:command } !_ --pdf-l [filename/wildcard] \\ See --pdf-landscape !_ --pdf-landscape [filename/wildcard] \\ sets orientation, produces LaTeX 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). Related options --pdf --pdf-portrait. See also --papersize-* or --papersize=[list]. Alias --pdf-l or in conjunction with --pdf --landscape +={ SiSU command:pdf landscape output|--pdf-landscape } !_ --pdf-p [filename/wildcard] \\ See --pdf-portrait !_ --pdf-portrait [filename/wildcard] \\ sets orientation, produces LaTeX pdf portrait.pdf.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). Related options --pdf --pdf-landscape. See also --papersize-* or --papersize=[list]. Alias --pdf-p or in conjunction with --pdf --portrait +={ SiSU command:pdf portrait output|--pdf-portrait } !_ --pg-[instruction] [filename] \\ database PostgreSQL ( --pgsql may be used instead) possible instructions, include: --pg-createdb; --pg-create; --pg-dropall; --pg-import [filename]; --pg-update [filename]; --pg-remove [filename]; see database section below. +={ SiSU command:postgresql|--pg|--pg-update|--pg-remove;output:pg command;pg:command } !_ --po [language_directory/filename language_directory] \\ see --po4a @@ -308,12 +341,15 @@ see --scp !_ --redirect[=directory_path] [filename/wildcard] \\ 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). Unlike using default settings HTML files have embedded css. Compare --dump +={ SiSU command:place output under specified directory|--redirect } !_ --rst [filename/wildcard/url] \\ ReST (rST restructured text) smart text (not available) +={ SiSU command:rst output (not available)|--rst (not available) } !_ --rsync [filename/wildcard] \\ 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 +={ SiSU command:remote site|--rsync|-R (rsync to remote site) } !_ -S \\ see --sisupod @@ -326,33 +362,42 @@ see --source !_ --sample-search-form [--db-(pg|sqlite)] \\ 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: --db-user='www-data'. 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 +={ SiSU command:sample search form|--sample-search-form --db-pg|--sample-search-form --db-sqlite|-F (sample search form) } !_ --sax [filename/wildcard/url] \\ see --xml-sax !_ --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 +={ SiSU command:remote site|--scp|-r (scp to remote site) } !_ --sha256 \\ set hash digest where used to sha256 +={ SiSU command:digests output sha256|--digests --sha256 } !_ --sha512 \\ set hash digest where used to sha512 +={ SiSU command:digests output sha512|--digests --sha512 } !_ --sqlite-[instruction] [filename] \\ database type set to SQLite, this produces one of two possible databases, without additional database related instructions it produces a discreet SQLite file for the document processed; with additional instructions it produces a common SQLite 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: --sqlite-createdb; --sqlite-create; --sqlite-dropall; --sqlite-import [filename]; --sqlite-update [filename]; --sqlite-remove [filename]); see database section below. +={ SiSU command:sqlite|--sqlite|--sqlite-update|--sqlite-remove;output:sqlite command;sqlite:command } !_ --sisupod \\ 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 -S [filename/wildcard] option. Note: (this option is tested only with zsh). Alias -S +={ SiSU command:sisupod (bundled sisu document source)|--sisupod } !_ --sisupod [filename/wildcard] \\ 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. 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 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 +={ SiSU command:sisupod (bundled sisu document source)|--sisupod|-S (sisupod, sisu markup source);output:sisupod command;sisupod:command } !_ --source [filename/wildcard] \\ copies sisu markup file to output directory. Alias -s +={ SiSU command:sisu markup source|--source|-s (sisu markup source text);output:source command;source:command } !_ --strict \\ together with --html, produces more w3c compliant html, for example not having purely numeric identifiers for text, the location object url#33 becomes url#o33 +={ SiSU command:html strict|--html --strict } !_ -T [filename/wildcard (*.termsheet.rb)] \\ standard form document builder, preprocessing feature @@ -362,15 +407,18 @@ see --txt !_ --texinfo [filename/wildcard] \\ produces texinfo and info file, (view with pinfo). Alias -I +={ SiSU command:texinfo|--texinfo|-I (texinfo output);output:texinfo command;texinfo:command } !_ --textile [filename/wildcard/url] \\ textile smart text (not available) +={ SiSU command:textile output (not available)|--textile (not available) } !_ --txt [filename/wildcard] \\ produces plaintext 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 +={ SiSU command:plaintext|--txt|-t (plain text output);output:text command;text:command;plaintext:command } -!_ --txt-asciitext [filename/wildcard] \\ -see --asciitext +!_ --txt-asciidoc [filename/wildcard] \\ +see --asciidoc !_ --txt-markdown [filename/wildcard] \\ see --markdown @@ -389,6 +437,7 @@ provides url mapping of output files for the flags requested for processing, als !_ --urls [filename/wildcard] \\ 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 +={ SiSU command:urls to generated output|--urls|-U (urls to generated output) } !_ -V \\ on its own, provides SiSU version and environment information (sisu --help env) @@ -404,12 +453,23 @@ see --verbose !_ --v5 [filename/wildcard] \\ invokes the sisu v5 document parser/generator. You may run sisu5 instead. This is the current default and is normally omitted. +={ SiSU command:sisu5|sisu version 5|--v5 } !_ --v6 [filename/wildcard] \\ invokes the sisu v6 document parser/generator. You may run sisu6 instead. +={ SiSU command:sisu6|sisu version 6|--v6 } !_ --verbose [filename/wildcard] \\ 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 +={ SiSU command:verbose|--verbose|-v (verbose) } + +!_ --very-verbose [filename/wildcard] \\ +provides more verbose output of what is being generated. See --verbose. Alias -V +={ SiSU command:verbose|--very-verbose|-V (very verbose) } + +!_ --version \\ +sisu version +={ SiSU command:version|--version|-v (version) } !_ -W \\ see --webrick @@ -419,18 +479,22 @@ see --concordance !_ --webrick \\ 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 +={ SiSU command:webrick web server|--webrick|-W (webrick web server) } !_ --wordmap [filename/wildcard] \\ see --concordance !_ --xhtml [filename/wildcard] \\ produces xhtml/XML output for browser viewing (sax parsing). Alias -b +={ SiSU command:xhtml output|--xhtml|-b (xhtml output) } !_ --xml-dom [filename/wildcard] \\ produces XML output with deep document structure, in the nature of dom. Alias -X +={ SiSU command:xml output|--xml-dom|--dom|-X (xml dom output) } !_ --xml-sax [filename/wildcard] \\ produces XML output shallow structure (sax parsing). Alias -x +={ SiSU command:xml output|--xml-sax|--sax|-x (xml sax output) } !_ -X [filename/wildcard] \\ see --xml-dom diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_config.ssi b/data/doc/sisu/markup-samples/manual/en/sisu_config.ssi index a53d5cc6..a4e5d3b1 100644 --- a/data/doc/sisu/markup-samples/manual/en/sisu_config.ssi +++ b/data/doc/sisu/markup-samples/manual/en/sisu_config.ssi @@ -24,8 +24,10 @@ 1~config Configuration 2~ Configuration files +={ SiSU:configuration files;configuration files } 3~ config.yml +={ SiSU:configuration files;configuration files:sisurc.yml } SiSU 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. @@ -54,6 +56,7 @@ Configuration determines the output and processing directories and the database If SiSU is installed a sample sisurc.yml may be found in /etc/sisu/sisurc.yml 3~ sisu_document_make +={ SiSU:configuration files;configuration files:sisu_document_make } 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. diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_content_directories.ssi b/data/doc/sisu/markup-samples/manual/en/sisu_content_directories.ssi index 182b176d..4d3980ae 100644 --- a/data/doc/sisu/markup-samples/manual/en/sisu_content_directories.ssi +++ b/data/doc/sisu/markup-samples/manual/en/sisu_content_directories.ssi @@ -22,10 +22,12 @@ :B~? Content Directories 1~organising_content Organising Content - Directory Structure and Mapping +={ SiSU:directories;directories;content directories } SiSU v3 has new options for the source directory tree, and output directory structures of which there are 3 alternatives. 2~ Document Source Directory +={ SiSU:directories document source;directories:document source;content directories:document source } 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. @@ -54,6 +56,7 @@ code{ }code 2~ Document Output Directory Structures +={ SiSU:directories output;directories:output;output directories:document output|structure } 3~ Output Directory Root @@ -62,6 +65,7 @@ The output directory root can be set in the sisurc.yml file. Under the root, sub 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. 3~ Alternative Output Structures +={ output directories:structure } There are 3 possibile output structures described as being, by language, by filetype or by filename, the selection is made in sisurc.yml @@ -75,6 +79,7 @@ output_dir_structure_by: language #(language & filetype, preferred?) }code 3~ By Language +={ output directories:by language } The by language directory structure places output files @@ -121,6 +126,7 @@ code{ subject_dir/en/manifest/filename.html 3~ By Filetype +={ output directories:by filetype } 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. @@ -164,6 +170,7 @@ code{ subject_dir/html/filename/manifest.en.html 3~ By Filename +={ output directories:by filename } The by filename directory structure places most output of a particular file (the different filetypes) in a common directory. @@ -230,6 +237,7 @@ code{ }code 3~ Sisupod +={ output directories:sisupod } code{ @@ -255,9 +263,7 @@ code{ }code -2~ Organising Content - - +% 2~ Organising Content % .SH "SKINS \- document, directory and site skins" diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_css.ssi b/data/doc/sisu/markup-samples/manual/en/sisu_css.ssi index 7ffc654b..9f5e61f3 100644 --- a/data/doc/sisu/markup-samples/manual/en/sisu_css.ssi +++ b/data/doc/sisu/markup-samples/manual/en/sisu_css.ssi @@ -20,6 +20,7 @@ :A~? CSS 1~css CSS - Cascading Style Sheets (for html, XHTML and XML) +={ SiSU:css;css } CSS files to modify the appearance of SiSU html, XHTML or XML may be placed in the configuration directory: ./_sisu/css ; ~/.sisu/css or; /etc/sisu/css and these will be copied to the output directories with the command sisu -CC. diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_download.ssi b/data/doc/sisu/markup-samples/manual/en/sisu_download.ssi index 96c97985..447db43f 100644 --- a/data/doc/sisu/markup-samples/manual/en/sisu_download.ssi +++ b/data/doc/sisu/markup-samples/manual/en/sisu_download.ssi @@ -24,10 +24,12 @@ :C~ Download information 1~download Download SiSU - Linux/Unix +={ SiSU program:source;SiSU:download program } 2~current- SiSU Current Version - Linux/Unix 3~source- Source (tarball tar.gz) +={ SiSU program:tarball;SiSU:tarball } _* {~^ sisu_[version].orig.tar.gz }http://www.jus.uio.no/sisu/pkg/src/ @@ -38,6 +40,7 @@ For more general use see http://sisudoc.org/sisu/sisu_manual For changelogs see http://www.jus.uio.no/sisu/SiSU/changelog.html 3~git- Git (source control management) +={ SiSU program:git source;SiSU:version control source } Git repository currently at: @@ -56,6 +59,7 @@ On using git, see {~^ The Git Community Book }http://book.git-scm.com/index.html, {~^ Git Magic }http://www-cs-students.stanford.edu/~blynn/gitmagic/, {~^ Git From the Bottom Up (pdf) }http://www.newartisans.com/blog_assets/git.from.bottom.up.pdf 3~debian- Debian +={ SiSU program:Debian;SiSU:Debian } This section contains information on the latest SiSU release. For installation notes see http://sisudoc.org/sisu/sisu_manual/installation.html diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_examples.ssi b/data/doc/sisu/markup-samples/manual/en/sisu_examples.ssi index cf9df9d5..a2429bf1 100644 --- a/data/doc/sisu/markup-samples/manual/en/sisu_examples.ssi +++ b/data/doc/sisu/markup-samples/manual/en/sisu_examples.ssi @@ -22,14 +22,17 @@ A~? @title @creator B~? SiSU Markup and Output Examples 1~examples Markup and Output Examples +={ SiSU markup:examples;SiSU output:examples } 2~ Markup examples *~markup +={ SiSU markup:examples } Current markup examples and document output samples are provided off http://sisudoc.org or http://www.jus.uio.no/sisu and in the sisu-markup-sample package available off http://sources.sisudoc.org 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. 2~sisu-markup-samples SiSU Markup Samples +={ SiSU markup:samples } A few additional sample books prepared as sisu markup samples, output formats to be generated using SiSU 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 Debian Project as they have requirements that do not meet the Debian 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. diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_filetypes.sst b/data/doc/sisu/markup-samples/manual/en/sisu_filetypes.sst index 4b5c31e7..0c5fd173 100644 --- a/data/doc/sisu/markup-samples/manual/en/sisu_filetypes.sst +++ b/data/doc/sisu/markup-samples/manual/en/sisu_filetypes.sst @@ -24,6 +24,7 @@ :A~? @title @creator 1~filetypes SiSU filetypes +={ SiSU:file types;file types } SiSU has plaintext and binary filetypes, and can process either type of document. @@ -38,10 +39,12 @@ SiSU source markup can be shared with the command: _1 sisu -s [filename] 3~ sisu text - regular files (.sst) +={ SiSU:file types;file types:sst } The most common form of document in SiSU, see the section on SiSU markup. 3~ sisu master files (.ssm) +={ SiSU:file types;file types:ssm } Composite documents which incorporate other SiSU documents which may be either regular SiSU text .sst which may be generated independently, or inserts prepared solely for the purpose of being incorporated into one or more master documents. @@ -52,10 +55,12 @@ Note: Master documents may be prepared in a similar way to regular documents, an Note: a secondary file of the composite document is built prior to processing with the same prefix and the suffix ._sst ~{ .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. }~ 3~ sisu insert files (.ssi) +={ SiSU:file types;file types:ssi } Inserts are documents prepared solely for the purpose of being incorporated into one or more master documents. They resemble regular SiSU text files (.sst). Since sisu-5.5.0 (6.1.0) .ssi files can like .ssm files include other .sst or .ssm files. .ssi files cannot be called by the sisu processor directly and can only be incorporated in other documents. Making a file a .ssi file is a quick and convenient way of breaking up a document that is to be included in a master document, and flagging that the file to be incorporated .ssi is not intended that the file should be processed on its own. 2~ sisupod, zipped binary container (sisupod.zip, .ssp) +={ SiSU:file types;file types:sisupod } A sisupod is a zipped SiSU text file or set of SiSU text files and any associated images that they contain (this will be extended to include sound and multimedia-files) diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_help.sst b/data/doc/sisu/markup-samples/manual/en/sisu_help.sst index 69535085..ddd3893f 100644 --- a/data/doc/sisu/markup-samples/manual/en/sisu_help.sst +++ b/data/doc/sisu/markup-samples/manual/en/sisu_help.sst @@ -28,6 +28,7 @@ 1~help Help 2~ SiSU Manual +={ SiSU:manual;help:manual } The most up to date information on sisu should be contained in the sisu_manual, available at: @@ -47,6 +48,7 @@ _1 sisu sisu_manual.ssm % The manual pages provided with SiSU are also available online, and there is an interactive help, which is being superseded by the man page, and possibly some document which contains this component. 2~ SiSU man pages *~man +={ SiSU:manpage;help:manpage } If SiSU is installed on your system usual man commands should be available, try: @@ -73,5 +75,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, [discontinued] +={ SiSU:interactive help (discontinued);help:interactive (discontinued) } This fell out of date and has been discontinued. diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_homepages.ssi b/data/doc/sisu/markup-samples/manual/en/sisu_homepages.ssi index 3d8d95d5..f798a7ea 100644 --- a/data/doc/sisu/markup-samples/manual/en/sisu_homepages.ssi +++ b/data/doc/sisu/markup-samples/manual/en/sisu_homepages.ssi @@ -22,6 +22,7 @@ :B~? Setting up of homepages 1~home Homepages +={ homepages } SiSU is about the ability to auto-generate documents. Home pages are regarded as custom built items, and are not created by SiSU. More accurately, SiSU 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: diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_how.ssi b/data/doc/sisu/markup-samples/manual/en/sisu_how.ssi index 3372bcd4..cd3b705f 100644 --- a/data/doc/sisu/markup-samples/manual/en/sisu_how.ssi +++ b/data/doc/sisu/markup-samples/manual/en/sisu_how.ssi @@ -23,4 +23,4 @@ 1~sisu_how How does sisu work? -SiSU markup is fairly minimalistic, it consists of: a (largely optional) document header, made up of information about the document (such as when it was published, who authored it, and granting what rights) and any processing instructions; and markup within the substantive text of the document, which is related to document structure and typeface. SiSU must be able to discern the structure of a document, (text headings and their levels in relation to each other), either from information provided in the document header or from markup within the text (or from a combination of both). Processing is done against an abstraction of the document comprising of information on the document's structure and its objects,[2] which the program serializes (providing the object numbers) and which are assigned hash sum values based on their content. This abstraction of information about document structure, objects, (and hash sums), provides considerable flexibility in representing documents different ways and for different purposes (e.g. search, document layout, publishing, content certification, concordance etc.), and makes it possible to take advantage of some of the strengths of established ways of representing documents, (or indeed to create new ones). +SiSU markup is fairly minimalistic, it consists of: a (largely optional) document header, made up of information about the document (such as when it was published, who authored it, and granting what rights) and any processing instructions; and markup within the substantive text of the document, which is related to document structure and typeface. SiSU must be able to discern the structure of a document, (text headings and their levels in relation to each other), either from information provided in the document header or from markup within the text (or from a combination of both). Processing is done against an abstraction of the document comprising of information on the document's structure and its objects, which the program serializes (providing the object numbers) and which are assigned hash sum values based on their content. This abstraction of information about document structure, objects, (and hash sums), provides considerable flexibility in representing documents different ways and for different purposes (e.g. search, document layout, publishing, content certification, concordance etc.), and makes it possible to take advantage of some of the strengths of established ways of representing documents, (or indeed to create new ones). diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_howto.sst b/data/doc/sisu/markup-samples/manual/en/sisu_howto.sst index 050c91b7..cbbb26aa 100644 --- a/data/doc/sisu/markup-samples/manual/en/sisu_howto.sst +++ b/data/doc/sisu/markup-samples/manual/en/sisu_howto.sst @@ -36,6 +36,7 @@ http://www.jus.uio.no/sisu_manual/ The manual pages provided with SiSU are also available online, and there is an interactive help, which is being superseded by the man page, and possibly some document which contains this component. 2~ SiSU "man" pages *~man +={ SiSU help:manpage } If SiSU is installed on your system usual man commands should be available, try: @@ -53,27 +54,8 @@ _* {~^ sisu.8 }http://www.jus.uio.no/sisu/man/sisu.8.html _* {~^ sisu_webrick.1 }http://www.jus.uio.no/sisu/man/sisu_webrick.1.html -2~ SiSU built-in help - -_1 sisu --help - -_1 sisu --help [subject] - -_2 sisu --help env [for feedback on the way your system is setup with regard to sisu] - -_2 sisu -V [same as above command] - -_2 sisu --help commands - -_2 sisu --help markup - -2~ Command Line with Flags - Batch Processing - -Running sisu (alone without any flags, filenames or wildcards) brings up the interactive help, as does any sisu command that is not recognised. - -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. - 1~howto_setup Setup, initialisation +={ SiSU:initialize } 2~ initialise output directory @@ -81,7 +63,7 @@ Images, css files for a document directory are copied to their respective locati while within your document markup/preparation directory, issue the following command -_1 sisu -CC +_1 sisu --config 3~ Use of search functionality, an example using sqlite diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_install_run.sst b/data/doc/sisu/markup-samples/manual/en/sisu_install_run.sst index b77e216a..08c9ba02 100644 --- a/data/doc/sisu/markup-samples/manual/en/sisu_install_run.sst +++ b/data/doc/sisu/markup-samples/manual/en/sisu_install_run.sst @@ -22,6 +22,7 @@ 1~source_tarball Source tarball 2~ run off source package directory tree (without installing) +={ SiSU program:run off source package directory tree;SiSU:run off source package directory tree } 1. Download the latest source @@ -32,6 +33,7 @@ Provided you have Ruby, SiSU can be run without installation straight from the s Note however, that additional external package dependencies, such as texlive (for pdfs), sqlite3 or postgresql (for search) should you desire to use them are not taken care of for you. 2~ Gem install (with rake) +={ SiSU program:gem;SiSU:ruby gem } Gem install, you need to: @@ -71,6 +73,7 @@ Rake: http://rake.rubyforge.org/ http://rubyforge.org/frs/?group_id=50 Rant: http://make.rubyforge.org/ http://rubyforge.org/frs/?group_id=615 2~ installation with setup.rb +={ SiSU program:setup.rb;SiSU:setup.rb } It should also be possible to install sisu using setup.rb @@ -94,6 +97,7 @@ _1 ruby setup.rb config && ruby setup.rb setup && sudo ruby setup.rb install A distribution install should take care of the dependencies of sisu for producing various outputs. 2~ Debian +={ SiSU program:Debian;SiSU:Debian } SiSU is available off the Debian archives. It should necessary only to run as root, Using apt-get: @@ -140,6 +144,7 @@ _1 *sisu-markup-samples*, sisu markup samples and other miscellany (under Debian SiSU is available off { Debian Unstable and Testing }http://packages.debian.org/cgi-bin/search_packages.pl?searchon=names&subword=1&version=all&release=all&keywords=sisu ~{ http://packages.qa.debian.org/s/sisu.html }~ install it using apt-get, aptitude or alternative Debian install tools. *~apt-get 1~dependencies Dependencies +={ SiSU program:dependencies;SiSU:dependencies } Here is a list of sisu's current dependencies,~{from the Debian control file}~ which depend on such factors as whether you want to generate pdf, whether you will be using SiSU with or without a database, ...). sisu_markup-samples may also be of interest. diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_introduction.sst b/data/doc/sisu/markup-samples/manual/en/sisu_introduction.sst index 1fc14d9a..1e5d1b5b 100644 --- a/data/doc/sisu/markup-samples/manual/en/sisu_introduction.sst +++ b/data/doc/sisu/markup-samples/manual/en/sisu_introduction.sst @@ -25,8 +25,10 @@ :B~? What is SiSU? 1~sisu_intro Introduction - What is SiSU? +={ SiSU: introduction } SiSU is a lightweight markup based document creation and publishing framework that is controlled from the command line. Prepare documents for SiSU using your text editor of choice, then use SiSU to generate various output document formats. +={ SiSU: description } From a single lightly prepared document (plain-text UTF-8) 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. SiSU produces: plain-text, HTML, XHTML, XML, EPUB, ODF:ODT (Opendocument), LaTeX, PDF, and populates an SQL database (PostgreSQL or SQLite) with text objects, roughly, paragraph sized chunks so that document searches are done at this level of granularity. diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_manual.ssm b/data/doc/sisu/markup-samples/manual/en/sisu_manual.ssm index 46d80198..34052d67 100644 --- a/data/doc/sisu/markup-samples/manual/en/sisu_manual.ssm +++ b/data/doc/sisu/markup-samples/manual/en/sisu_manual.ssm @@ -57,7 +57,7 @@ << sisu_examples.ssi -<< sisu_output_overview.sst +% << sisu_output_overview.sst << sisu_search_intro.ssi diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_markup.sst b/data/doc/sisu/markup-samples/manual/en/sisu_markup.sst index 7db8416e..6c201951 100644 --- a/data/doc/sisu/markup-samples/manual/en/sisu_markup.sst +++ b/data/doc/sisu/markup-samples/manual/en/sisu_markup.sst @@ -30,6 +30,7 @@ 2~ Summary SiSU source documents are plaintext (UTF-8)~{ files should be prepared using UTF-8 character encoding }~ files +={ SiSU markup:description } All paragraphs are separated by an empty line. @@ -51,21 +52,8 @@ _1* linked text and images _1* paragraph actions, such as indent, bulleted, numbered-lists, etc. -Some interactive help on markup is available, by typing sisu and selecting markup or sisu --help markup - -To check the markup in a file: - -_1 sisu --identify [filename].sst - -For brief descriptive summary of markup history - -_1 sisu --query-history - -or if for a particular version: - -_1 sisu --query-0.38 - 2~ Markup Rules, document structure and metadata requirements +={ SiSU markup:rules and requirements } minimal content/structure requirement: @@ -79,12 +67,15 @@ minimal content/structure requirement: ``` code A~ (level A [title]) + 1~ (at least one level 1 [segment/(chapter)]) ``` +={ output:code markup example;SiSU markup output:code block (tic syntax);code block:tic syntax } structure rules (document heirarchy, heading levels): there are two sets of heading levels ABCD (title & parts if any) and 123 (segment & subsegments if any) +={ SiSU markup:heading levels } sisu has the fllowing levels: @@ -142,8 +133,10 @@ text * ``` 2~ Markup Examples +={ SiSU markup:locating examples } 3~ Online +={ SiSU markup:examples online } Online markup examples are available together with the respective outputs produced from http://www.jus.uio.no/sisu/SiSU/examples.html or from http://www.jus.uio.no/sisu/sisu_examples/ @@ -152,10 +145,12 @@ There is of course this document, which provides a cursory overview of sisu mark an alternative presentation of markup syntax: /usr/share/doc/sisu/on_markup.txt.gz 3~ Installed +={ SiSU markup:examples installed } With SiSU 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: /usr/share/doc/sisu/markup-samples-non-free 1~headers Markup of Headers +={ SiSU markup:headers} Headers contain either: semantic meta-data about a document, which can be used by any output module of the program, or; processing instructions. @@ -166,8 +161,10 @@ code{ % this would be a comment }code +={ output:code markup example;SiSU markup output:code block (curly brace syntax);code block:curly brace syntax } 2~ Sample Header +={ SiSU markup:sample header} This current document is loaded by a master document that has a header similar to this one: @@ -228,6 +225,7 @@ code{ }code 2~ Available Headers +={ SiSU markup:headers available } 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 the form @headername: or on the next line and indented by once space :subheadername: All Dublin Core meta tags are available @@ -355,8 +353,10 @@ code{ % NOTE: headings/levels below refer to 0.38 expermental markup (a conversion script provided in sisu-examples, modify.rb makes conversion between 0.37 and 0.38 markup simple) 1~ Markup of Substantive Text +={ SiSU markup:substantive text } 2~heading_levels Heading Levels +={ SiSU markup:heading levels } 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) @@ -388,12 +388,13 @@ code{ }code 2~ Font Attributes +={ SiSU markup:font attributes } !_ markup example: code{ -normal text, *{emphasis}*, !{bold text}!, /{italics}/, _{underscore}_, "{citation}", +normal text, *{emphasis}*, !{bold text}!, /{italics}/, _{underscore}_, "{citation}", ^{superscript}^, ,{subscript},, +{inserted text}+, -{strikethrough}-, #{monospace}# normal text @@ -448,8 +449,10 @@ _{underscore}_ #{monospace}# 2~ Indentation and bullets +={ SiSU markup:indentation and bullets } !_ markup example: +={ SiSU markup:indentation } code{ @@ -474,6 +477,7 @@ _2 indent paragraph two steps _9 indent paragraph nine steps !_ markup example: +={ SiSU markup:bullets } code{ @@ -506,6 +510,7 @@ _# numbered list numbered list indented a., b., c., d., etc. }code 2~ Hanging Indents +={ SiSU markup:hanging indents;indented text:hanging } !_ markup example: @@ -537,6 +542,7 @@ _0_1 *{live-build}* \\ A collection of scripts used to build customized Debian Livesystems. /{live-build}/ was formerly known as live-helper, and even earlier known as live-package. 2~ Footnotes / Endnotes +={ SiSU markup:hanging indents;footnotes;endnotes } Footnotes and endnotes are marked up at the location where they would be indicated within a text. They are automatically numbered. The output type determines whether footnotes or endnotes will be produced @@ -611,6 +617,7 @@ normal text~^ continues the standard and pair notation cannot be mixed in the same document 2~ Links +={ SiSU markup:links (text, images);links:images|text } 3~ Naked URLs within text, dealing with urls @@ -658,6 +665,7 @@ deb-src http://www.jus.uio.no/sisu/archive unstable main non-free }code 3~link_text Linking Text +={ SiSU markup:links (text);links:text } To link text or an image to a url the markup is as follows @@ -716,6 +724,7 @@ about { SiSU book markup examples }:SiSU/examples.html about { SiSU book markup examples }:SiSU/examples.html 3~ Linking Images +={ SiSU markup:links (images);links:images } !_ markup example: @@ -780,9 +789,51 @@ code{ { "Viral Spiral", David Bollier [3sS]}viral_spiral.david_bollier.sst -2~ Grouped Text +2~ Grouped Text / blocked text +={ SiSU markup:grouped text;grouped text;blocked text;text blocks } + +There are two markup syntaxes for blocked text, using curly braces or using tics + +3~ blocked text curly brace syntax +={ SiSU markup:grouped text;grouped text:curly brace syntax;blocked text:curly brace syntax;text blocks:curly brace syntax } + +at the start of a line on its own use name of block type with an opening curly brace, follow with the content of the block, and close with a closing curly brace and the name of the block type, e.g. + +``` code +code{ + +this is a code block + +}code +``` + +``` code +poem{ + +this here is a poem + +}poem +``` + +3~ blocked text tic syntax +={ SiSU markup:grouped text;grouped text:tic syntax;blocked text:tic syntax;text blocks:tic syntax } + +code{ + +``` code +this is a code block +``` + +``` poem +this here is a poem +``` + +}code + +start a line with three backtics, a space followed by the name of the name of block type, follow with the content of the block, and close with three back ticks on a line of their own, e.g. 3~ Tables +={ SiSU markup:tables;tables } Tables may be prepared in two either of two forms @@ -818,6 +869,8 @@ column three of row two, and so on }table +% ={ output:table markup example;SiSU markup output:table (curly brace syntax) } + a second form may be easier to work with in cases where there is not much information in each column *{markup example:}*~{ Table from the Wealth of Networks by Yochai Benkler \\ http://www.jus.uio.no/sisu/the_wealth_of_networks.yochai_benkler }~ @@ -870,6 +923,7 @@ No. of articles, all languages | 25| 19,000| 138,000| 490,000| 862,0 % }code 3~ Poem +={ SiSU markup:poem;poems } !_ basic markup: @@ -935,7 +989,6 @@ poem{ you to death."' - }poem }code @@ -988,10 +1041,12 @@ poem{ you to death."' - }poem +% ={ output:poem markup example;SiSU markup output:poem (curly brace syntax) } + 3~ Group +={ SiSU markup:group text;group text } !_ basic markup: @@ -1112,8 +1167,10 @@ group{ death."' }group +={ output:group block markup example;SiSU markup output:group block (curly brace syntax) } 3~ Code +={ SiSU markup:code block;code block } 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 SiSU markup. You cannot however use code tags to escape code tags. They are however used in the same way as group or poem tags. @@ -1220,10 +1277,13 @@ code{# death."' }code +={ output:code markup example;SiSU markup output:code block (curly brace syntax);code block:curly brace syntax } 2~ Additional breaks - linebreaks within objects, column and page-breaks +={ SiSU markup:breaks (page and line);breaks } 3~ line-breaks +={ SiSU markup:line break;line break } To break a line within a "paragraph object", two backslashes \\\\ \\ with a space before and a space or newline after them \\ may be used. @@ -1241,12 +1301,13 @@ The html break br enclosed in angle brackets (though undocumented) is available To draw a dividing line dividing paragraphs, see the section on page breaks. 3~ page breaks +={ SiSU markup:page break;page break } 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: -page new =\\= (or <:pn>) breaks the page, starts a new page. +page new =\\= breaks the page, starts a new page. -page break -\\- (or <:pb>) breaks a column, starts a new column, if using columns, else breaks the page, starts a new page. +page break -\\- breaks a column, starts a new column, if using columns, else breaks the page, starts a new page. page break line across page -..- draws a dividing line, dividing paragraphs @@ -1275,6 +1336,7 @@ code{ }code 2~ Book index +={ SiSU markup:book index;book index } To make an index append to paragraph the book index term relates to it, using an equal sign and curly braces. @@ -1343,8 +1405,9 @@ code{ }code 1~ Composite documents markup +={ SiSU markup:composite documents;composite documents } -It is possible to build a document by creating a master document that requires other documents. The documents required may be complete documents that could be generated independently, or they could be markup snippets, prepared so as to be easily available to be placed within another text. If the calling document is a master document (built from other documents), it should be named with the suffix *{.ssm}* Within this document you would provide information on the other documents that should be included within the text. These may be other documents that would be processed in a regular way, or markup bits prepared only for inclusion within a master document *{.sst}* regular markup file, or *{.ssi}* (insert). A secondary file of the composite document is built prior to processing with the same prefix and the suffix *{._sst}* +It is possible to build a document by creating a master document that requires other documents. The documents required may be complete documents that could be generated independently, or they could be markup snippets, prepared so as to be easily available to be placed within another text. If the calling document is a master document (built from other documents), it should be named with the suffix *{.ssm}* Within this document you would provide information on the other documents that should be included within the text. These may be other documents that would be processed in a regular way, or markup bits prepared only for inclusion within a master document *{.sst}* regular markup file, or *{.ssi}* (insert/information) A secondary file of the composite document is built prior to processing with the same prefix and the suffix *{._sst}* basic markup for importing a document into a master document @@ -1359,6 +1422,7 @@ code{ The form described above should be relied on. Within the Vim editor it results in the text thus linked becoming hyperlinked to the document it is calling in which is convenient for editing. 1~ Substitutions +={ SiSU markup:substitutions;substitutions } !_ markup example: diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_postgresql.sst b/data/doc/sisu/markup-samples/manual/en/sisu_postgresql.sst index e5b0c4cb..4653d73b 100644 --- a/data/doc/sisu/markup-samples/manual/en/sisu_postgresql.sst +++ b/data/doc/sisu/markup-samples/manual/en/sisu_postgresql.sst @@ -29,6 +29,7 @@ % :B~? SiSU Postgresql 1~postgresql Postgresql +={ SiSU sql:postgresql; SiSU search:postgresql } 2~ Name diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_quickstart.sst b/data/doc/sisu/markup-samples/manual/en/sisu_quickstart.sst index ae95f528..44331f32 100644 --- a/data/doc/sisu/markup-samples/manual/en/sisu_quickstart.sst +++ b/data/doc/sisu/markup-samples/manual/en/sisu_quickstart.sst @@ -26,12 +26,14 @@ :B~? Quickstart - SiSU installation and use 1~ Quickstart - Getting Started Howto +={ SiSU quick start } 2~ Installation Installation is currently most straightforward and tested on the Debian platform, as there are packages for the installation of sisu and all requirements for what it does. 3~ Debian Installation +={ SiSU quick start:Debian installation } SiSU is available directly from the Debian Sid and testing archives (and possibly Ubuntu), assuming your /etc/apt/sources.list is set accordingly: @@ -97,6 +99,7 @@ as root type: _1 rpm -i [rpm package name] 3~ Installation from source +={ SiSU quick start:installation from source } To install SiSU from source check information at: diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_remote.sst b/data/doc/sisu/markup-samples/manual/en/sisu_remote.sst index 54ea9a7b..dd866c7c 100644 --- a/data/doc/sisu/markup-samples/manual/en/sisu_remote.sst +++ b/data/doc/sisu/markup-samples/manual/en/sisu_remote.sst @@ -26,6 +26,7 @@ :B~? SiSU Remote Operations 1~remote_source Remote Source Documents +={ remote:source documents } SiSU processing instructions can be run against remote source documents by providing the url of the documents against which the processing instructions are to be carried out. The remote SiSU documents can either be sisu marked up files in plaintext .sst or .ssm or; zipped sisu files, sisupod.zip or filename.ssp @@ -60,6 +61,7 @@ Any of the source documents in the sisu examples page can be used in this way, s :C~ Remote Document Output 1~remote_output Remote Output +={ remote:output } Once properly configured SiSU output can be automatically posted once generated to a designated remote machine using either rsync, or scp. diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_search_cgi.ssi b/data/doc/sisu/markup-samples/manual/en/sisu_search_cgi.ssi index 301cfa72..9641bea6 100644 --- a/data/doc/sisu/markup-samples/manual/en/sisu_search_cgi.ssi +++ b/data/doc/sisu/markup-samples/manual/en/sisu_search_cgi.ssi @@ -23,7 +23,8 @@ :C~? CGI Search Form -1~search_cgi Introduction +1~search_cgi CGI Search Form +={ SiSU sql:cgi search form; SiSU search:cgi search form;search form } 2~ Setup search form diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_search_intro.ssi b/data/doc/sisu/markup-samples/manual/en/sisu_search_intro.ssi index 386b8175..1969c1a4 100644 --- a/data/doc/sisu/markup-samples/manual/en/sisu_search_intro.ssi +++ b/data/doc/sisu/markup-samples/manual/en/sisu_search_intro.ssi @@ -22,6 +22,7 @@ :B~? SiSU Search 1~search_intro SiSU Search - Introduction +={ SiSU search } SiSU output can easily and conveniently be indexed by a number of standalone indexing tools, such as Lucene, Hyperestraier. diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_short_feature_summary.ssi b/data/doc/sisu/markup-samples/manual/en/sisu_short_feature_summary.ssi index 294644af..0c166b49 100644 --- a/data/doc/sisu/markup-samples/manual/en/sisu_short_feature_summary.ssi +++ b/data/doc/sisu/markup-samples/manual/en/sisu_short_feature_summary.ssi @@ -24,6 +24,7 @@ :C~? Description 1~sisu_feature_summary Summary of features +={ SiSU:feature summary } _* sparse/minimal markup (clean utf-8 source texts). Documents are prepared in a single UTF-8 file using a minimalistic mnemonic syntax. Typical literature, documents like "War and Peace" require almost no markup, and most of the headers are optional. diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_sql.ssi b/data/doc/sisu/markup-samples/manual/en/sisu_sql.ssi index f24fe2a9..771d3001 100644 --- a/data/doc/sisu/markup-samples/manual/en/sisu_sql.ssi +++ b/data/doc/sisu/markup-samples/manual/en/sisu_sql.ssi @@ -29,6 +29,7 @@ 1~search_sql SQL 2~ populating SQL type databases +={ SiSU sql; SiSU search } SiSU feeds sisu markupd documents into sql type databases PostgreSQL~{ http://www.postgresql.org/ \\ http://advocacy.postgresql.org/ \\ http://en.wikipedia.org/wiki/Postgresql }~ and/or SQLite~{ http://www.hwaci.com/sw/sqlite/ \\ http://en.wikipedia.org/wiki/Sqlite }~ database together with information related to document structure. diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_sqlite.sst b/data/doc/sisu/markup-samples/manual/en/sisu_sqlite.sst index 2c43aa92..08df5eec 100644 --- a/data/doc/sisu/markup-samples/manual/en/sisu_sqlite.sst +++ b/data/doc/sisu/markup-samples/manual/en/sisu_sqlite.sst @@ -29,6 +29,7 @@ % :B~? SiSU Sqlite 1~sqlite Sqlite +={ SiSU sql:sqlite; SiSU search:sqlite } 2~ Name diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_webrick.sst b/data/doc/sisu/markup-samples/manual/en/sisu_webrick.sst index 6e56e53a..e1868376 100644 --- a/data/doc/sisu/markup-samples/manual/en/sisu_webrick.sst +++ b/data/doc/sisu/markup-samples/manual/en/sisu_webrick.sst @@ -29,6 +29,7 @@ :B~? SiSU Webrick 1~webrick sisu_webrick +={ webrick;web server:webrick } 2~ Name |