From 0506d0a1261305a0a631b00d0b401edc2bf790ae Mon Sep 17 00:00:00 2001 From: Ralph Amissah Date: Sun, 3 Feb 2013 23:24:37 -0500 Subject: v4: documentation, include --html-scroll and --html-seg options * sisu_manual/sisu_commands * manpage & html --- data/doc/sisu/html/sisu.1.html | 432 ++++++++++++++++++++--------------------- 1 file changed, 211 insertions(+), 221 deletions(-) (limited to 'data/doc/sisu/html/sisu.1.html') diff --git a/data/doc/sisu/html/sisu.1.html b/data/doc/sisu/html/sisu.1.html index f7268daa..2063c021 100644 --- a/data/doc/sisu/html/sisu.1.html +++ b/data/doc/sisu/html/sisu.1.html @@ -255,47 +255,46 @@ To skip it see -n. Alias -m
--dump[=directory_path] [filename/wildcard]
places output in directory specified, if none is specified -in the current directory (pwd). Compare --redirect
+in the current directory (pwd). Unlike using default settings HTML files +have embedded css. Compare --redirect
-e [filename/wildcard]
-
see ---epub
+
see --epub
-
--epub [filename/wildcard]
-
produces an epub document, [sisu version ->=2 ] (filename.epub). Alias -e
+
--epub +[filename/wildcard]
+
produces an epub document, [sisu version >=2 ] (filename.epub). +Alias -e
--exc-*
-
exclude output feature, overrides configuration -settings --exc-ocn, (exclude object citation numbering, (switches off object -citation numbering ) , affects html (seg, scroll), epub, xhtml, xml, pdf) -; --exc-toc, (exclude table of contents, affects html (scroll), epub, pdf) -; --exc-links-to-manifest, --exc-manifest-links, (exclude links to manifest, affects -html (seg, scroll)); --exc-search-form, (exclude search form, affects html -(seg, scroll), manifest); --exc-minitoc, (exclude mini table of contents, -affects html (seg), concordance, manifest); --exc-manifest-minitoc, (exclude -mini table of contents, affects manifest); --exc-html-minitoc, (exclude mini -table of contents, affects html (seg), concordance); --exc-html-navigation, -(exclude navigation, affects html (seg)); --exc-html-navigation-bar, (exclude -navigation bar, affects html (seg)); --exc-html-search-form, (exclude search -form, affects html (seg, scroll)); --exc-html-right-pane, (exclude right pane/column, -affects html (seg, scroll)); --exc-html-top-band, (exclude top band, affects -html (seg, scroll), concordance (minitoc forced on to provide seg navigation)); ---exc-segsubtoc (exclude sub table of contents, affects html (seg), epub) -; see also --inc-*
+
exclude output feature, overrides configuration settings --exc-ocn, +(exclude object citation numbering, (switches off object citation numbering +) , affects html (seg, scroll), epub, xhtml, xml, pdf) ; --exc-toc, (exclude +table of contents, affects html (scroll), epub, pdf) ; --exc-links-to-manifest, +--exc-manifest-links, (exclude links to manifest, affects html (seg, scroll)); +--exc-search-form, (exclude search form, affects html (seg, scroll), manifest); +--exc-minitoc, (exclude mini table of contents, affects html (seg), concordance, +manifest); --exc-manifest-minitoc, (exclude mini table of contents, affects +manifest); --exc-html-minitoc, (exclude mini table of contents, affects html +(seg), concordance); --exc-html-navigation, (exclude navigation, affects html +(seg)); --exc-html-navigation-bar, (exclude navigation bar, affects html (seg)); +--exc-html-search-form, (exclude search form, affects html (seg, scroll)); --exc-html-right-pane, +(exclude right pane/column, affects html (seg, scroll)); --exc-html-top-band, +(exclude top band, affects html (seg, scroll), concordance (minitoc forced +on to provide seg navigation)); --exc-segsubtoc (exclude sub table of contents, +affects html (seg), epub) ; see also --inc-*
-F [--webserv=webrick]
see --sample-search-form
-
-f [optional string -part of filename]
+
-f [optional string part of filename]
see --find
--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
+
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
-G [optional string part of filename]
@@ -305,193 +304,192 @@ language subdirectories). Alias -f, --glob, -G
see --git
--git [filename/wildcard]
-
produces -or updates markup source file structure in a git repo (experimental and -subject to change). Alias -g
+
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
+
--glob +[optional string part of filename]
+
see --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.
+
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.
+ +
--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
-
--help [topic] +
--html-scroll [filename/wildcard]
-
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.
+
produces html output, the document in a single file (scroll.html) only. Compare +--html-seg and --html
-
--html [filename/wildcard]
+
--html-seg [filename/wildcard]
produces html output, segmented -text with table of contents (toc.html and index.html) and the document in -a single file (scroll.html). Alias -h
+text with table of contents (toc.html and index.html). Compare --html-scroll +and --html
-I [filename/wildcard]
see --texinfo
-
-i -[filename/wildcard]
-
see --manpage
+
-i [filename/wildcard]
+
see --manpage
--inc-*
-
include output feature, overrides -configuration settings, (usually the default if none set), has precedence -over --exc-* (exclude output feature). Some detail provided under --exc-*, see ---exc-*
+
include output feature, overrides configuration settings, (usually +the default if none set), has precedence over --exc-* (exclude output feature). +Some detail provided under --exc-*, see --exc-*
-j [filename/wildcard]
-
copies images associated with a file for use -by html, xhtml & xml outputs (automatically invoked by --dump & redirect).
+
copies images associated with a file for use by html, xhtml & xml outputs (automatically +invoked by --dump & redirect).
-
-k -
+
-k
see --color-off
--keep-processing-files [filename/wildcard/url]
-
see --maintenance -
+
see --maintenance
-L
prints license information.
-M [filename/wildcard/url]
-
see --maintenance -
+
see --maintenance
-m [filename/wildcard/url]
see --dal (document abstraction level/layer)
-
--machine -[filename/wildcard/url]
-
see --dal (document abstraction level/layer)
+
--machine [filename/wildcard/url]
+
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. -
+
--maintenance [filename/wildcard/url]
+
maintenance mode, interim +processing files are preserved and their locations indicated. (also see +-V). Aliases -M and --keep-processing-files.
--manpage [filename/wildcard]
-
produces man page of file, not suitable for -all outputs. Alias -i
+
produces +man page of file, not suitable for all outputs. Alias -i
-N [filename/wildcard/url]
-
document digest or document -content certificate ( DCC ) as md5 digest tree of the document: the digest -for the document, and digests for each object contained within the document -(together with information on software versions that produced it) (digest.txt). --NV for verbose digest output to screen.
- -
-n [filename/wildcard/url]
-
skip the -creation of intermediate processing files (document abstraction) if they -already exist, this skips the equivalent of -m which is otherwise assumed -by most processing flags.
+
document digest or document content certificate ( DCC ) as md5 digest tree +of the document: the digest for the document, and digests for each object +contained within the document (together with information on software versions +that produced it) (digest.txt). -NV for verbose digest output to screen.
+ +
-n +[filename/wildcard/url]
+
skip the creation of intermediate processing files +(document abstraction) if they already exist, this skips the equivalent +of -m which is otherwise assumed by most processing flags.
--no-*
see --exc-*
-
-o [filename/wildcard/url]
-
see --odt -
+
-o +[filename/wildcard/url]
+
see --odt
--odf [filename/wildcard/url]
see --odt
-
--odt [filename/wildcard/url]
-
output -basic document in opendocument file format (opendocument.odt). Alias -o
+
--odt +[filename/wildcard/url]
+
output basic document in opendocument file format +(opendocument.odt). Alias -o
-
--output-by-* -
-
select output directory structure from 3 alternatives: --output-by-language, -(language directory (based on language code) with filetype (html, epub, -pdf etc.) subdirectories); --output-by-filetype, (filetype directories with -language code as part of filename); --output-by-filename, (filename directories -with language code as part of filename). This is configurable. Alias --by-* -
+
--output-by-*
+
select output directory structure from +3 alternatives: --output-by-language, (language directory (based on language +code) with filetype (html, epub, pdf etc.) subdirectories); --output-by-filetype, +(filetype directories with language code as part of filename); --output-by-filename, +(filename directories with language code as part of filename). This is configurable. +Alias --by-*
-P [language_directory/filename language_directory]
see --po4a
-
-p [filename/wildcard] -
+
-p +[filename/wildcard]
see --pdf
--pdf [filename/wildcard]
-
produces LaTeX pdf (portrait.pdf & landscape.pdf). -Default paper size is set in config file, or document header, or provided -with additional command line parameter, e.g. --papersize-a4 preset sizes include: -’A4’, U.S. ’letter’ and ’legal’ and book sizes ’A5’ and ’B5’ (system defaults to A4). -Alias -p
+
produces LaTeX pdf +(portrait.pdf & landscape.pdf). Default paper size is set in config file, or +document header, or provided with additional command line parameter, e.g. +--papersize-a4 preset sizes include: ’A4’, U.S. ’letter’ and ’legal’ and book sizes +’A5’ and ’B5’ (system defaults to A4). Alias -p
--pg [instruction] [filename]
-
database PostgreSQL ( --pgsql may be -used instead) possible instructions, include: --createdb; --create; --dropall; ---import [filename]; --update [filename]; --remove [filename]; see database section -below. Alias -D
+
database +PostgreSQL ( --pgsql may be used instead) possible instructions, include: +--createdb; --create; --dropall; --import [filename]; --update [filename]; --remove +[filename]; see database section below. Alias -D
-
--po [language_directory/filename language_directory]
-
see --po4a -
+
--po [language_directory/filename +language_directory]
+
see --po4a
--po4a [language_directory/filename language_directory]
-
produces .pot and -po files for the file in the languages specified by the language directory. -SiSU markup is placed in subdirectories named with the language code, e.g. -en/ fr/ es/. The sisu config file must set the output directory structure -to multilingual. v3, experimental
+
produces .pot and po files for the file in the languages specified by the +language directory. SiSU markup is placed in subdirectories named with the +language code, e.g. en/ fr/ es/. The sisu config file must set the output +directory structure to multilingual. v3, experimental
-
-Q [filename/wildcard]
+
-Q [filename/wildcard] +
see --qrcode
-
-q [filename/wildcard] -
+
-q [filename/wildcard]
see --quiet
--qrcode [filename/wildcard]
-
generate QR code image of metadata -(used in manifest). v3 only.
+
generate +QR code image of metadata (used in manifest). v3 only.
--quiet [filename/wildcard]
-
quiet less output -to screen.
+
quiet less output to screen.
-R [filename/wildcard]
see --rsync
-r [filename/wildcard]
-
see --scp -
+
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). Compare --dump
+
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
--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
+
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
-S
-
see --sisupod -
+
see --sisupod
-S [filename/wildcard]
see --sisupod
@@ -499,110 +497,102 @@ used together with other flags, it is not). Also see --scp. Alias -R
-s [filename/wildcard]
see --source
-
--sample-search-form -[--webserv=webrick]
-
generate examples of (naive) cgi search form for SQLite -and PgSQL depends on your already having used sisu to populate an SQLite -and/or PgSQL database, (the SQLite version scans the output directories -for existing sisu_sqlite databases, so it is first necessary to create -them, before generating the search form) see -d -D and the database section -below. If the optional parameter --webserv=webrick is passed, the cgi examples -created will be set up to use the default port set for use by the webrick -server, (otherwise the port is left blank and the system setting used, -usually 80). The samples are dumped in the present work directory which -must be writable, (with screen instructions given that they be copied to -the cgi-bin directory). Alias -F
+
--sample-search-form [--webserv=webrick]
+
generate examples of (naive) cgi search form for SQLite and PgSQL depends +on your already having used sisu to populate an SQLite and/or PgSQL database, +(the SQLite version scans the output directories for existing sisu_sqlite +databases, so it is first necessary to create them, before generating the +search form) see -d -D and the database section below. If the optional parameter +--webserv=webrick is passed, the cgi examples created will be set up to use +the default port set for use by the webrick server, (otherwise the port +is left blank and the system setting used, usually 80). The samples are +dumped in the present work directory which must be writable, (with screen +instructions given that they be copied to the cgi-bin directory). Alias -F
--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
- -
--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: --createdb; ---create; --dropall; --import [filename]; --update [filename]; --remove [filename]); -see database section below. Alias -d
+
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
+ +
--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: --createdb; --create; --dropall; --import [filename]; --update +[filename]; --remove [filename]); see database section below. Alias -d
--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 is tested only -with zsh). Alias -S
+
produces a sisupod a zipped sisu directory of markup files including sisu +markup source files and the directories local configuration file, images +and skins. Note: this only includes the configuration files or skins contained +in is tested only with zsh). Alias -S
--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
+
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
--source [filename/wildcard]
-
copies sisu markup file to output directory. -Alias -s
+
copies sisu markup file to output directory. Alias -s
-T [filename/wildcard (*.termsheet.rb)]
-
standard form document builder, -preprocessing feature
+
standard form document builder, preprocessing feature
-t [filename/wildcard]
see --txt
-
--texinfo [filename/wildcard] -
-
produces texinfo and info file, (view with pinfo). Alias -I
+
--texinfo [filename/wildcard]
+
produces texinfo and info file, (view with +pinfo). Alias -I
-
--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
+
--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
-U [filename/wildcard]
see --urls
-u [filename/wildcard]
-
provides url mapping -of output files for the flags requested for processing, also see -U
- -
--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
+
provides url mapping of output files for the flags +requested for processing, also see -U
+ +
--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
-V
-
on its own, -provides SiSU version and environment information (sisu --help env)
+
on its own, provides SiSU version +and environment information (sisu --help env)
-
-V [filename/wildcard] -
+
-V [filename/wildcard]
even more verbose than the -v flag.
-v
-- cgit v1.2.3