From 7997984e00647c6f51d0692d8a4a8d92f6bcb26e Mon Sep 17 00:00:00 2001 From: Ralph Amissah Date: Mon, 3 Oct 2011 21:14:59 -0400 Subject: v2 v3: documentation, small update --- data/doc/sisu/CHANGELOG_v2 | 3 + data/doc/sisu/CHANGELOG_v3 | 3 + .../markup-samples/sisu_manual/_sisu/v3/sisurc.yml | 12 +- data/doc/sisu/markup-samples/sisu_manual/sisu.ssm | 6 +- .../markup-samples/sisu_manual/sisu_commands.sst | 2 +- .../sisu_manual/sisu_content_directories.ssi | 164 ++++++++++++++++++++- .../sisu_manual/sisu_introduction.sst | 4 +- .../markup-samples/sisu_manual/sisu_markup.sst | 4 +- 8 files changed, 177 insertions(+), 21 deletions(-) diff --git a/data/doc/sisu/CHANGELOG_v2 b/data/doc/sisu/CHANGELOG_v2 index 6eaa68c7..2aaf56d8 100644 --- a/data/doc/sisu/CHANGELOG_v2 +++ b/data/doc/sisu/CHANGELOG_v2 @@ -18,6 +18,9 @@ http://git.sisudoc.org/?p=code/sisu.git;a=log;h=refs/tags/debian/sisu_3.1.0-1 * bin/sisu, default sisu version 3 + * documentation, small update + * sisu source + %% 2.9.8 (2011-09-24:38/6) [see 3.0.19.orig.tar.gz] http://git.sisudoc.org/?p=code/sisu.git;a=log;h=refs/tags/sisu-3.0.19 http://git.sisudoc.org/?p=code/sisu.git;a=log;h=refs/tags/debian/sisu_3.0.19-1 diff --git a/data/doc/sisu/CHANGELOG_v3 b/data/doc/sisu/CHANGELOG_v3 index 04626745..2309a045 100644 --- a/data/doc/sisu/CHANGELOG_v3 +++ b/data/doc/sisu/CHANGELOG_v3 @@ -41,6 +41,9 @@ http://www.jus.uio.no/sisu/pkg/src/sisu_3.1.0.orig.tar.xz * vim syntax, :texpdf_font_mono: added to @make: + * documentation, small update + * sisu source + %% 3.0.19.orig.tar.xz (2011-09-24:38/6) http://git.sisudoc.org/?p=code/sisu.git;a=log;h=refs/tags/sisu-3.0.19 http://git.sisudoc.org/?p=code/sisu.git;a=log;h=refs/tags/debian/sisu_3.0.19-1 diff --git a/data/doc/sisu/markup-samples/sisu_manual/_sisu/v3/sisurc.yml b/data/doc/sisu/markup-samples/sisu_manual/_sisu/v3/sisurc.yml index ed452402..3ef1a6db 100644 --- a/data/doc/sisu/markup-samples/sisu_manual/_sisu/v3/sisurc.yml +++ b/data/doc/sisu/markup-samples/sisu_manual/_sisu/v3/sisurc.yml @@ -49,12 +49,12 @@ show_output_on: 'filesystem_url' #% flag - set (non-default) processing flag shortcuts -1, -2 etc. (here adding colour and verbosity as default) flag: color: true # making colour default -c is toggle, and will now toggle colour off - default: '-NhewpotbxXyYv' # -m run by default; includes verbose - i: '-Nhewpoty' # -m run by default - ii: '-NhewpotbxX' # -m run by default - iii: '-NhewpotbxXY' # -m run by default - iv: '-NhewpotbxXiIY' # -m run by default - v: '-NhewpotbxXYDv --update' # -m run by default; includes verbose +# default: '-NhewpotbxXyYv' # -m run by default; includes verbose +# i: '-Nhewpoty' # -m run by default +# ii: '-NhewpotbxX' # -m run by default +# iii: '-NhewpotbxXY' # -m run by default +# iv: '-NhewpotbxXiIY' # -m run by default +# v: '-NhewpotbxXYDv --update' # -m run by default; includes verbose #% papersize, (LaTeX/pdf) current values A4, US_letter, book_b5, book_a5, US_legal, easily extensible default: diff --git a/data/doc/sisu/markup-samples/sisu_manual/sisu.ssm b/data/doc/sisu/markup-samples/sisu_manual/sisu.ssm index 89d8556a..aed55649 100644 --- a/data/doc/sisu/markup-samples/sisu_manual/sisu.ssm +++ b/data/doc/sisu/markup-samples/sisu_manual/sisu.ssm @@ -5,7 +5,7 @@ @creator: :author: Amissah, Ralph -@rights: Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL 3 +@rights: Copyright (C) Ralph Amissah 2011, part of SiSU documentation, License GPL 3 @classify: :type: information @@ -19,14 +19,14 @@ :created: 2002-08-28 :issued: 2002-08-28 :available: 2002-08-28 - :modified: 2011-03-09 + :modified: 2011-09-18 @make: :num_top: 1 :breaks: new=C; break=1 :skin: skin_sisu_manual :bold: /Gnu|Debian|Ruby|SiSU/ - :manpage: name=sisu - documents: markup, structuring, publishing in multiple standard formats, and search; synopsis=sisu [-abcDdFehIiMmNnopqRrSsTtUuVvwXxYyZz0-9] [filename/wildcard] . sisu [-Ddcv] [instruction] [filename/wildcard] . sisu [-CcFLSVvW] . sisu --v2 [operations] . sisu --v3 [operations] . sisu3 [operations] + :manpage: name=sisu - documents: markup, structuring, publishing in multiple standard formats, and search; synopsis=sisu [-abCcDdeFGghIikLMmNnoPpQqRrSsTtUuVvWwXxYyZ_0-9] [filename/wildcard] . sisu [-Ddcv] [instruction] [filename/wildcard] . sisu [-CcFLSVvW] . sisu [operations] . sisu --v3 [operations] . sisu --v2 [operations] . sisu2 [operations] @links: { SiSU Homepage }http://www.sisudoc.org/ 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 86ac41cf..b24abde7 100644 --- a/data/doc/sisu/markup-samples/sisu_manual/sisu_commands.sst +++ b/data/doc/sisu/markup-samples/sisu_manual/sisu_commands.sst @@ -21,7 +21,7 @@ :issued: 2002-08-28 :available: 2002-08-28 :published: 2007-09-16 - :modified: 2011-03-04 + :modified: 2011-09-18 @make: :num_top: 1 diff --git a/data/doc/sisu/markup-samples/sisu_manual/sisu_content_directories.ssi b/data/doc/sisu/markup-samples/sisu_manual/sisu_content_directories.ssi index dedd38f4..b7e09434 100644 --- a/data/doc/sisu/markup-samples/sisu_manual/sisu_content_directories.ssi +++ b/data/doc/sisu/markup-samples/sisu_manual/sisu_content_directories.ssi @@ -22,13 +22,13 @@ :B~? Content Directories -1~organising_content Organising Content +1~organising_content Organising Content - Directory Structure and Mapping -2~ Directory Structure and Mapping +SiSU v3 has new options for the source directory tree, and output directory structures of which there are 3 alternatives. -The output directory root can be set in the sisurc.yml file. Under the root, subdirectories are made for each directory in which a document set resides. If you have a directory named poems or conventions, that directory will be created under the output directory root and the output for all documents contained in the directory of a particular name will be generated to subdirectories beneath that directory (poem or conventions). A document will be placed in a subdirectory of the same name as the document with the filetype identifier stripped (.sst .ssm) +2~ Document Source Directory -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. +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. 3~ General Directories @@ -36,7 +36,15 @@ code{ ./subject_name/ -% files stored at this level e.g. sisu_manual.sst +% files stored at this level e.g. sisu_manual.sst or +% for sisu v3 may be under language sub-directories +% e.g. + +./subject_name/en + +./subject_name/fr + +./subject_name/es ./subject_name/_sisu @@ -50,12 +58,154 @@ code{ ./subject_name/_sisu/image -% images for documents contained in this directory +}code -./subject_name/_sisu/mm +2~ Document Output Directory Structures + +3~ Output Directory Root + +The output directory root can be set in the sisurc.yml file. Under the root, subdirectories are made for each directory in which a document set resides. If you have a directory named poems or conventions, that directory will be created under the output directory root and the output for all documents contained in the directory of a particular name will be generated to subdirectories beneath that directory (poem or conventions). A document will be placed in a subdirectory of the same name as the document with the filetype identifier stripped (.sst .ssm) + +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 + +There are 3 possibile output structures described as being, by language, by filetype or by filename, the selection is made in sisurc.yml + +code{ + +#% output_dir_structure_by: language; filetype; or filename +output_dir_structure_by: language #(language & filetype, preferred?) +#output_dir_structure_by: filetype +#output_dir_structure_by: filename #(default, closest to original v1 & v2) }code +3~ By Language + +The by language directory structure places output files + +The by language directory structure separates output files by language code (all files of a given language), and within the language directory by filetype. + +Its selection is configured in sisurc.yml + +output_dir_structure_by: language + +% works for html epub odf, pdf, sortof for info NOT for man pages + +code{ + + ├── en + │   ├── epub + │   ├── hashes + │   ├── html + │   │   └── viral_spiral.david_bollier + │   ├── manifest + │   │   └── qrcode + │   ├── odt + │   ├── pdf + │   ├── sitemaps + │   ├── txt + │   ├── xhtml + │   └── xml + ├── po4a + │   └── live-manual + │   ├── po + │   │   └── fr + │   └── pot + └── _sisu + ├── css + ├── image + ├── image_sys -> ../../_sisu/image_sys + └── xml + ├── rnc + ├── rng + └── xsd + +}code + +#by: language +subject_dir/en/manifest/filename.html + +3~ 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. + +Its selection is configured in sisurc.yml + +output_dir_structure_by: filetype + +% works for html epub odf, pdf, sortof for info NOT for man pages + +code{ + + ├── epub + ├── hashes + ├── html + │   └── viral_spiral.david_bollier + ├── manifest + │   └── qrcode + ├── odt + ├── pdf + ├── po4a + │   └── live-manual + │   ├── po + │   │   └── fr + │   └── pot + ├── _sisu + │   ├── css + │   ├── image + │   ├── image_sys -> ../../_sisu/image_sys + │   └── xml + │   ├── rnc + │   ├── rng + │   └── xsd + ├── sitemaps + ├── txt + ├── xhtml + └── xml + +}code + +#by: filetype +subject_dir/html/filename/manifest.en.html + +3~ By Filename + +The by filename directory structure places most output of a particular file (the different filetypes) in a common directory. + +Its selection is configured in sisurc.yml + +output_dir_structure_by: filename + +% works for html epub odf, pdf, sortof for info NOT for man pages + +code{ + + ├── epub + ├── po4a + │   └── live-manual + │   ├── po + │   │   └── fr + │   └── pot + ├── _sisu + │   ├── css + │   ├── image + │   ├── image_sys -> ../../_sisu/image_sys + │   └── xml + │   ├── rnc + │   ├── rng + │   └── xsd + ├── sitemaps + ├── src + │   └── pod + └── viral_spiral.david_bollier + +}code + +#by: filename +subject_dir/filename/manifest.en.html + 3~ Remote Directories code{ diff --git a/data/doc/sisu/markup-samples/sisu_manual/sisu_introduction.sst b/data/doc/sisu/markup-samples/sisu_manual/sisu_introduction.sst index a94e9145..4908b68f 100644 --- a/data/doc/sisu/markup-samples/sisu_manual/sisu_introduction.sst +++ b/data/doc/sisu/markup-samples/sisu_manual/sisu_introduction.sst @@ -7,7 +7,7 @@ :author: Amissah, Ralph @rights: - :copyright: Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL 3 + :copyright: Copyright (C) Ralph Amissah 2011, part of SiSU documentation, License GPL 3 % used_by: manual @@ -20,7 +20,7 @@ :created: 2002-08-28 :issued: 2002-08-28 :available: 2002-08-28 - :modified: 2011-02-07 + :modified: 2011-09-18 @make: :num_top: 1 diff --git a/data/doc/sisu/markup-samples/sisu_manual/sisu_markup.sst b/data/doc/sisu/markup-samples/sisu_manual/sisu_markup.sst index 735f00ea..046b1f2b 100644 --- a/data/doc/sisu/markup-samples/sisu_manual/sisu_markup.sst +++ b/data/doc/sisu/markup-samples/sisu_manual/sisu_markup.sst @@ -1266,9 +1266,9 @@ code{ }code -:C~ Markup Syntax History +1~syntax_history Markup Syntax History -1~ Notes related to Files-types and Markup Syntax +2~ Notes related to Files-types and Markup Syntax 2.0 introduced new headers and is therefore incompatible with 1.0 though otherwise the same with the addition of a couple of tags (i.e. a superset) -- cgit v1.2.3