From 9dffba29dd1000452563204e4e6887df1d5bb2c9 Mon Sep 17 00:00:00 2001 From: Ralph Amissah Date: Tue, 30 Jul 2013 21:36:53 -0400 Subject: v5: output structure by, monolingual alternative, documentation --- data/doc/sisu/CHANGELOG_v5 | 1 + data/doc/sisu/html/sisu.1.html | 235 ++++++++++++--------- .../sisu_manual/_sisu/rc/sisurc_by_fn.yml | 2 + .../sisu_manual/_sisu/rc/sisurc_by_ft.yml | 2 + .../markup-samples/sisu_manual/sisu_commands.sst | 13 ++ man/man1/sisu.1 | 41 ++-- 6 files changed, 185 insertions(+), 109 deletions(-) diff --git a/data/doc/sisu/CHANGELOG_v5 b/data/doc/sisu/CHANGELOG_v5 index f34a4537..9b092a5d 100644 --- a/data/doc/sisu/CHANGELOG_v5 +++ b/data/doc/sisu/CHANGELOG_v5 @@ -45,6 +45,7 @@ http://www.jus.uio.no/sisu/pkg/src/sisu_5.0.8.orig.tar.xz --default-language='en' --default-lang-en if used together with --monolingual and --by-filetype or --by-filename the selected default language document will not have a language code in the output filename + * documentation %% 5.0.7.orig.tar.xz (2013-06-25:25/2) http://sources.sisudoc.org/gitweb/?p=code/sisu.git;a=shortlog;h=refs/tags/sisu_5.0.7 diff --git a/data/doc/sisu/html/sisu.1.html b/data/doc/sisu/html/sisu.1.html index 6f4eb681..65a92c9a 100644 --- a/data/doc/sisu/html/sisu.1.html +++ b/data/doc/sisu/html/sisu.1.html @@ -285,12 +285,14 @@ 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
+
see --sample-search-form +
-f [optional string part of filename]
see --find
-
--find [optional string part of filename]
+
--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 @@ -299,7 +301,8 @@ match given string in directory (including language subdirectories). Alias
-G [optional string part of filename]
see --find
-
-g [filename/wildcard]
+
-g [filename/wildcard] +
see --git
--git [filename/wildcard]
@@ -311,7 +314,8 @@ structure in a git repo (experimental and subject to change). Alias -g
see --find
-h [filename/wildcard]
-
see --html
+
see --html +
--harvest *.ss[tm]
makes two lists of sisu output based on the sisu markup @@ -347,100 +351,122 @@ and --html
see --texinfo
-i [filename/wildcard]
-
see --manpage
+
see --manpage +
+ +
--i18n-*
+
these flags affect output by filetype and filename): --i18n-mono (--monolingual) +output filenames without language code for default language (’en’ or as set); +--i18n-multi (--multilingual) language code provided as part of the output filename, +this is the default. Where output is in one language only the language code +may not be desired. see also --output-by-*
--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 +
-M [filename/wildcard/url]
see --maintenance
-m [filename/wildcard/url]
-
see --dal (document abstraction level/layer)
+
see +--dal (document abstraction level/layer)
-
--machine [filename/wildcard/url]
+
--machine [filename/wildcard/url] +
see --dal (document abstraction level/layer)
-
--maintenance [filename/wildcard/url]
+
--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]
+
--manpage [filename/wildcard] +
produces man page of file, not suitable for all outputs. Alias -i
+
--monolingual +
+
see --i18n-*
+ +
--multilingual
+
see --i18n-*
+
-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.
+
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.
+
-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]
+
-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-*
+
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
--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=* -

-

--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 +
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=* +

+

--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
@@ -478,7 +504,8 @@ include: --createdb; --create; --dropall; --import [filename]; --update [filenam language_directory]
see --po4a
-
--po4a [language_directory/filename language_directory]
+
--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 @@ -495,13 +522,15 @@ directory structure to multilingual. v3, experimental
generate QR code image of metadata (used in manifest). v3 only.
-
--quiet [filename/wildcard]
+
--quiet [filename/wildcard] +
quiet less output to screen.
-R [filename/wildcard]
see --rsync
-
-r [filename/wildcard]
+
-r [filename/wildcard] +
see --scp
--redirect[=directory_path] [filename/wildcard]
@@ -523,7 +552,8 @@ with other flags, it is not). Also see --scp. Alias -R
-S
see --sisupod
-
-S [filename/wildcard]
+
-S [filename/wildcard] +
see --sisupod
-s [filename/wildcard]
@@ -564,10 +594,11 @@ same output directory base path (possible instructions include: --createdb; 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 @@ -589,18 +620,22 @@ 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]
+
--texinfo [filename/wildcard] +
produces texinfo and info file, (view with pinfo). Alias -I
-
--txt [filename/wildcard]
+
--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 @@ -612,10 +647,11 @@ paragraph --unix for unix linefeed (default) --msdos for msdos linefeed). Alias
see --urls
-u [filename/wildcard]
-
provides url mapping of output files for the flags -requested for processing, also see -U
+
provides url mapping +of output files for the flags requested for processing, also see -U
-
--urls [filename/wildcard]
+
--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 @@ -625,10 +661,11 @@ 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
@@ -842,20 +879,21 @@ in the sisu_manual, available at:

The manual can be generated from source, found respectively, either within the SiSU tarball or installed locally at: -

-

/usr/share/doc/sisu/markup-samples/sisu_manual +

./data/doc/sisu/markup-samples/sisu_manual -

move to the respective directory and type e.g.: +

/usr/share/doc/sisu/markup-samples/sisu_manual +

move to the respective +directory and type e.g.:

sisu sisu_manual.ssm -

Sisu -Man Pages

- -

If SiSU is installed on your system usual man commands should -be available, try: -

man sisu -

Most SiSU man pages are generated directly -from sisu documents that are used to prepare the sisu manual, the sources -files for which are located within the SiSU tarball at: +

Sisu Man Pages

+ +

If SiSU is +installed on your system usual man commands should be available, try: +

+ man sisu +

Most SiSU man pages are generated directly from sisu documents +that are used to prepare the sisu manual, the sources files for which are +located within the SiSU tarball at:

./data/doc/sisu/markup-samples/sisu_manual

Once installed, directory equivalent to: @@ -1260,16 +1298,21 @@ first line indented, rest of paragraph no indent

in each case level may

be 0-9 -

live-build A collection of scripts used to build customized Debian
- Livesystems.
+

+

live-build A collection of scripts used to build customized
+ Debian +

Livesystems.
.I live-build
was formerly known as live-helper, and even earlier known as live-package.
-

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.
+

+

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.
+

Footnotes / Endnotes

Footnotes and endnotes are marked up at the location @@ -2610,8 +2653,7 @@ be created manually and given the same name as working directory, as requested)

sisu -D --create
creates database tables where no database tables existed - -

before +before

sisu -D --Dropall
@@ -2715,8 +2757,7 @@ of the same name).
sisu -d --recreate
destroys existing database and builds - -

a new empty database structure +a new empty database structure

diff --git a/data/doc/sisu/markup-samples/sisu_manual/_sisu/rc/sisurc_by_fn.yml b/data/doc/sisu/markup-samples/sisu_manual/_sisu/rc/sisurc_by_fn.yml index 34d4a662..9bcc416e 100644 --- a/data/doc/sisu/markup-samples/sisu_manual/_sisu/rc/sisurc_by_fn.yml +++ b/data/doc/sisu/markup-samples/sisu_manual/_sisu/rc/sisurc_by_fn.yml @@ -96,6 +96,8 @@ db: #% output_dir_structure_by: language (language_and_filetype); filetype; or filename (original v1 & v2) output_dir_structure_by: filename +#% lingual: 'multi' | 'mono' (multi default) +#lingual: multi permission_set: zap: true diff --git a/data/doc/sisu/markup-samples/sisu_manual/_sisu/rc/sisurc_by_ft.yml b/data/doc/sisu/markup-samples/sisu_manual/_sisu/rc/sisurc_by_ft.yml index 57440498..bf34d249 100644 --- a/data/doc/sisu/markup-samples/sisu_manual/_sisu/rc/sisurc_by_ft.yml +++ b/data/doc/sisu/markup-samples/sisu_manual/_sisu/rc/sisurc_by_ft.yml @@ -96,6 +96,8 @@ db: #% output_dir_structure_by: language (language_and_filetype); filetype; or filename (original v1 & v2) output_dir_structure_by: filetype +#% lingual: 'multi' | 'mono' (multi default) +#lingual: multi permission_set: zap: true diff --git a/data/doc/sisu/markup-samples/sisu_manual/sisu_commands.sst b/data/doc/sisu/markup-samples/sisu_manual/sisu_commands.sst index 491c03fd..8e8926ad 100644 --- a/data/doc/sisu/markup-samples/sisu_manual/sisu_commands.sst +++ b/data/doc/sisu/markup-samples/sisu_manual/sisu_commands.sst @@ -156,6 +156,13 @@ see --texinfo !_ -i [filename/wildcard] \\ see --manpage +!_ --i18n-* \\ +these flags affect output by filetype and filename): +--i18n-mono (--monolingual) output filenames without language code for default language ('en' or as set); +--i18n-multi (--multilingual) language code provided as part of the output filename, this is the default. +Where output is in one language only the language code may not be desired. +see also --output-by-* + !_ --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-* @@ -184,6 +191,12 @@ maintenance mode, interim processing files are preserved and their locations ind !_ --manpage [filename/wildcard] \\ produces man page of file, not suitable for all outputs. Alias -i +!_ --monolingual \\ +see --i18n-* + +!_ --multilingual \\ +see --i18n-* + !_ -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. diff --git a/man/man1/sisu.1 b/man/man1/sisu.1 index 2bafb76b..8292187d 100644 --- a/man/man1/sisu.1 +++ b/man/man1/sisu.1 @@ -1,4 +1,4 @@ -.TH "sisu" "1" "2013-02-22" "4.0.9" "SiSU" +.TH "sisu" "1" "2013-07-25" "4.1.8" "SiSU" .br .SH NAME .br @@ -422,6 +422,13 @@ see --texinfo .B -i [filename/wildcard] see --manpage .TP +.B --i18n-* +these flags affect output by filetype and filename): --i18n-mono +(--monolingual) output filenames without language code for default language +('en' or as set); --i18n-multi (--multilingual) language code provided as part +of the output filename, this is the default. Where output is in one language +only the language code may not be desired. see also --output-by-* (v5) +.TP .B --inc-* include output feature, overrides configuration settings, (usually the default if none set), has precedence over --exc-* (exclude output feature). Some detail @@ -453,6 +460,12 @@ indicated. (also see -V). Aliases -M and --keep-processing-files. .B --manpage [filename/wildcard] produces man page of file, not suitable for all outputs. Alias -i .TP +.B --monolingual +see --i18n-* +.TP +.B --multilingual +see --i18n-* +.TP .B -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 @@ -927,7 +940,7 @@ The most up to date information on sisu should be contained in the sisu_manual, available at: .BR - + .BR The manual can be generated from source, found respectively, either within the @@ -935,16 +948,16 @@ The manual can be generated from source, found respectively, either within the tarball or installed locally at: .BR - ./data/doc/sisu/markup-samples/sisu_manual +\./data/doc/sisu/markup-samples/sisu_manual .BR - /usr/share/doc/sisu/markup-samples/sisu_manual +/usr/share/doc/sisu/markup-samples/sisu_manual .BR move to the respective directory and type e.g.: .BR - sisu sisu_manual.ssm +sisu sisu_manual.ssm .SH SISU MAN PAGES @@ -954,7 +967,7 @@ If is installed on your system usual man commands should be available, try: .BR - man sisu +man sisu .BR Most @@ -1512,7 +1525,9 @@ in each case level may be 0-9 .BR .B live-build - A collection of scripts used to build customized Debian + A collection of scripts used to build customized +.B Debian + Livesystems. .I live-build was formerly known as live-helper, and even earlier known as live-package. @@ -1520,9 +1535,12 @@ in each case level may be 0-9 .BR .B 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. + A collection of scripts used to build customized +.B Debian + Livesystems. +.I live-build + was formerly known as live-helper, and even earlier known as live-package. + .SH FOOTNOTES / ENDNOTES .BR @@ -1837,8 +1855,7 @@ information in each column .BR .B markup example: -[^18] - +[^17] .nf !_ Table 3.1: Contributors to Wikipedia, January 2001 - June 2005 -- cgit v1.2.3