From 520128d4486320eca4efbc6cefb208004d2ec4f0 Mon Sep 17 00:00:00 2001 From: Ralph Amissah Date: Tue, 26 Jul 2011 20:36:23 -0400 Subject: v2 v3: manpage * commands: --qrcode -Q; update shortcut options * markup.sst: indent update; publisher --- man/man1/sisu.1 | 627 ++++++++++++++++++++++++++++++++------------------------ 1 file changed, 363 insertions(+), 264 deletions(-) (limited to 'man') diff --git a/man/man1/sisu.1 b/man/man1/sisu.1 index 2994ef64..0b9a2fce 100644 --- a/man/man1/sisu.1 +++ b/man/man1/sisu.1 @@ -1,4 +1,4 @@ -.TH "sisu" "1" "2011-06-24" "3.0.13-beta-rb1.9.2p180" "SiSU" +.TH "sisu" "1" "2011-07-26" "3.0.14-beta-rb1.9.2p180" "SiSU" .br .SH NAME .br @@ -34,18 +34,18 @@ RALPH AMISSAH .br .B SiSU -is a framework for document structuring, publishing (in multiple open -standard formats) and search, comprising of: (a) a lightweight document -structure and presentation markup syntax; and (b) an accompanying engine for -generating standard document format outputs from documents prepared in sisu -markup syntax, which is able to produce multiple standard outputs (including -the population of sql databases) that (can) share a common numbering system for -the citation of text within a document. +is a framework for document structuring, publishing (in multiple open standard +formats) and search, comprising of: (a) a lightweight document structure and +presentation markup syntax; and (b) an accompanying engine for generating +standard document format outputs from documents prepared in sisu markup syntax, +which is able to produce multiple standard outputs (including the population of +sql databases) that (can) share a common numbering system for the citation of +text within a document. .br .B SiSU -is developed under an open source, software libre license (GPL3). Its use -case for development is work with medium to large document sets and cope with +is developed under an open source, software libre license (GPL3). Its use case +for development is work with medium to large document sets and cope with evolving document formats/ representation technologies. Documents are prepared once, and generated as need be to update the technical presentation or add additional output formats. Various output formats (including search related @@ -94,28 +94,28 @@ content. .br In preparing a .B SiSU -document you optionally provide semantic information related to the document -in a document header, and in marking up the substantive text provide -information on the structure of the document, primarily indicating heading -levels and footnotes. You also provide information on basic text attributes -where used. The rest is automatic, sisu from this information custom builds[^2] -the different forms of output requested. +document you optionally provide semantic information related to the document in +a document header, and in marking up the substantive text provide information +on the structure of the document, primarily indicating heading levels and +footnotes. You also provide information on basic text attributes where used. +The rest is automatic, sisu from this information custom builds[^2] the +different forms of output requested. .br .B SiSU works with an abstraction of the document based on its structure which is comprised of its headings[^3] and objects[^4], which enables .B SiSU -to represent the document in many different ways, and to take advantage of -the strengths of different ways of presenting documents. The objects are -numbered, and these numbers can be used to provide a common basis for citing -material within a document across the different output format types. This is -significant as page numbers are not well suited to the digital age, in web -publishing, changing a browser's default font or using a different browser can -mean that text will appear on a different page; and publishing in different -formats, html, landscape and portrait pdf etc. again page numbers are not -useful to cite text. Dealing with documents at an object level together with -object numbering also has implications for search that +to represent the document in many different ways, and to take advantage of the +strengths of different ways of presenting documents. The objects are numbered, +and these numbers can be used to provide a common basis for citing material +within a document across the different output format types. This is significant +as page numbers are not well suited to the digital age, in web publishing, +changing a browser's default font or using a different browser can mean that +text will appear on a different page; and publishing in different formats, +html, landscape and portrait pdf etc. again page numbers are not useful to cite +text. Dealing with documents at an object level together with object numbering +also has implications for search that .B SiSU is able to take advantage of. @@ -134,8 +134,8 @@ relies on software, the markup is uncomplicated and minimalistic which guarantees that future engines can be written to run against it. It is also easily converted to other formats, which means documents prepared in .B SiSU -can be migrated to other document formats. Further security is provided by -the fact that the software itself, +can be migrated to other document formats. Further security is provided by the +fact that the software itself, .B SiSU is available under GPL3 a licence that guarantees that the source code will always be open, and free as in libre, which means that that code base can be @@ -189,19 +189,19 @@ content prepared in .br .B SiSU -is a document publishing system, that from a simple single marked\-up -document, produces multiple output formats including: plaintext, html, xhtml, -XML, epub, odt (odf text), LaTeX, pdf, info, and SQL (PostgreSQL and SQLite), -which share text object numbers ("object citation numbering") and the same -document structure information. For more see: +is a document publishing system, that from a simple single marked\-up document, +produces multiple output formats including: plaintext, html, xhtml, XML, epub, +odt (odf text), LaTeX, pdf, info, and SQL (PostgreSQL and SQLite), which share +text object numbers ("object citation numbering") and the same document +structure information. For more see: .SH 2.2 DOCUMENT PROCESSING COMMAND FLAGS .TP .B \-a [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 \ +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) @@ -212,9 +212,9 @@ see \-\-xhtml .TP .B \-\-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 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 .TP @@ -266,8 +266,7 @@ see \-\-sqlite .TP .B \-\-epub [filename/wildcard] -produces an epub document, [sisu \ version \ >=2 \ ] (filename.epub). Alias -\-e +produces an epub document, [sisu \ version \ >=2 \ ] (filename.epub). Alias \-e .TP .B \-e [filename/wildcard] @@ -391,8 +390,7 @@ see \-\-odt .TP .B \-\-odt [filename/wildcard/url] -output basic document in opendocument file format (opendocument.odt). Alias -\-o +output basic document in opendocument file format (opendocument.odt). Alias \-o .TP .B \-o [filename/wildcard/url] @@ -400,8 +398,8 @@ see \-\-odt .TP .B \-\-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 +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 @@ -433,10 +431,18 @@ see \-\-po4a .B \-p [filename/wildcard] see \-\-pdf +.TP +.B \-\-qrcode [filename/wildcard] +generate QR code image of metadata (used in manifest). v3 only. + .TP .B \-\-quiet [filename/wildcard] quiet less output to screen. +.TP +.B \-Q [filename/wildcard] +see \-\-qrcode + .TP .B \-q [filename/wildcard] see \-\-quiet @@ -469,8 +475,7 @@ so it is first necessary to create them, before generating the search form) see 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). \-Fv (in addition to the above) -provides some information on setting up hyperestraier for sisu. Alias \-F +that they be copied to the cgi\-bin directory). Alias \-F .TP .B \-\-scp [filename/wildcard] @@ -480,9 +485,9 @@ that you have your "keys" and ssh agent in place. Also see \-\-rsync. Alias \-r .TP .B \-\-sqlite \-\-[instruction] [filename] -database type default set to sqlite, (for which \-\-sqlite may be used -instead) or to specify another database \-\-db\-[pgsql, \ sqlite] (however see -\-D) possible instructions include: \-\-createdb; \-\-create; \-\-dropall; +database type default set to sqlite, (for which \-\-sqlite may be used instead) +or to specify another database \-\-db\-[pgsql, \ sqlite] (however see \-D) +possible instructions include: \-\-createdb; \-\-create; \-\-dropall; \-\-import [filename]; \-\-update [filename]; \-\-remove [filename]; see database section below. Alias \-d @@ -496,24 +501,23 @@ option is tested only with zsh). Alias \-S .TP .B \-\-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. +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. .B 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 +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 .TP .B \-\-source [filename/wildcard] @@ -537,9 +541,9 @@ produces texinfo and info file, (view with pinfo). Alias \-I .TP .B \-\-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 \ +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 @@ -578,13 +582,13 @@ normally omitted. .TP .B \-\-v3 [filename/wildcard] -invokes the sisu v3 document parser/generator. Currently under development -and incomplete, v3 requires >= ruby1.9.2p180. You may run sisu3 instead. +invokes the sisu v3 document parser/generator. Currently under development and +incomplete, v3 requires >= ruby1.9.2p180. You may run sisu3 instead. .TP .B \-\-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 +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 .TP @@ -609,10 +613,10 @@ see \-\-verbose .TP .B \-\-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 \ +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 .TP @@ -662,10 +666,10 @@ processing flags. .TP .B \-\-zap [filename/wildcard] -Zap, if used with other processing flags deletes output files of the type -about to be processed, prior to processing. If \-Z is used as the lone -processing related flag (or in conjunction with a combination of \-[mMvVq]), -will remove the related document output directory. Alias \-Z +Zap, if used with other processing flags deletes output files of the type about +to be processed, prior to processing. If \-Z is used as the lone processing +related flag (or in conjunction with a combination of \-[mMvVq]), will remove +the related document output directory. Alias \-Z .TP .B \-Z [filename/wildcard] @@ -716,18 +720,18 @@ where database name would be SiSU_[present \ working \ directory \ name \ .TP .B \-\-pg \-v \-\-import -[filename/wildcard] imports data specified to postgresql db (rb.dbi) [ \ \-dv -\ \-\-import \ sqlite \ equivalent] +[filename/wildcard] imports data specified to postgresql db (rb.dbi) [ \ \-dv \ +\-\-import \ sqlite \ equivalent] .TP .B \-\-pg \-v \-\-update -[filename/wildcard] updates/imports specified data to postgresql db (rb.dbi) -[ \ \-dv \ \-\-update \ sqlite \ equivalent] +[filename/wildcard] updates/imports specified data to postgresql db (rb.dbi) [ +\ \-dv \ \-\-update \ sqlite \ equivalent] .TP .B \-\-pg \-\-remove -[filename/wildcard] removes specified data to postgresql db (rb.dbi) [ \ \-d -\ \-\-remove \ sqlite \ equivalent] +[filename/wildcard] removes specified data to postgresql db (rb.dbi) [ \ \-d \ +\-\-remove \ sqlite \ equivalent] .TP .B \-\-pg \-\-dropall @@ -742,45 +746,45 @@ The \-v is for verbose output. .TP .B \-\-update [filename/wildcard] -Checks existing file output and runs the flags required to update this -output. This means that if only html and pdf output was requested on previous -runs, only the \-hp files will be applied, and only these will be generated -this time, together with the summary. This can be very convenient, if you offer +Checks existing file output and runs the flags required to update this output. +This means that if only html and pdf output was requested on previous runs, +only the \-hp files will be applied, and only these will be generated this +time, together with the summary. This can be very convenient, if you offer different outputs of different files, and just want to do the same again. .TP .B \-0 to \-5 [filename \ or \ wildcard] -Default shorthand mappings (note that the defaults can be changed/configured -in the sisurc.yml file): +Default shorthand mappings (for v3, note that the defaults can be +changed/configured in the sisurc.yml file): .TP .B \-0 -\-mNhwpAobxXyYv [this \ is \ the \ default \ action \ run \ when \ no \ +\-NQhewpotbxXyYv [this \ is \ the \ default \ action \ run \ when \ no \ options \ are \ give, \ i.e. \ on \ 'sisu \ [filename]'] .TP .B \-1 -\-mhewpy +\-Qhewpoty .TP .B \-2 -\-mhewpaoy +\-NQhewpotbxXy .TP .B \-3 -\-mhewpAobxXyY +\-NQhewpotbxXyY .TP .B \-4 -\-mhewpAobxXDyY \-\-import +\-NQhewpotbxXDyY \-\-update .TP .B \-5 -\-mhewpAobxXDyY \-\-update +\-NQhewpotbxXDyYv \-\-update .br -add \-v for verbose mode and \-c for color, e.g. sisu \-2vc [filename \ or \ -wildcard] +add \-v for verbose mode and \-c to toggle color state, e.g. sisu \-2vc +[filename \ or \ wildcard] .br consider \-u for appended url info or \-v for verbose output @@ -998,8 +1002,8 @@ an alternative presentation of markup syntax: .br With .B 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: +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 .SH 8. MARKUP OF HEADERS @@ -1029,7 +1033,9 @@ to this one: % SiSU master 2.0 @title: SiSU :subtitle: Manual - @creator: :author: Amissah, Ralph + @creator: + :author: Amissah, Ralph + @publisher: \ [publisher \ name] @rights: Copyright (C) Ralph Amissah 2007, License GPL 3 @classify: :type: information @@ -1191,9 +1197,9 @@ another) .br .B :A~ [heading \ text] -Top level heading [this \ usually \ has \ similar \ content \ to \ the \ -title \ @title: \ ] NOTE: the heading levels described here are in 0.38 -notation, see heading +Top level heading [this \ usually \ has \ similar \ content \ to \ the \ title +\ @title: \ ] NOTE: the heading levels described here are in 0.38 notation, see +heading .br .B :B~ [heading \ text] @@ -1205,22 +1211,22 @@ Third level heading [this \ is \ a \ heading \ level \ divider] .br .B 1~ [heading \ text] -Top level heading preceding substantive text of document or sub\-heading 2, -the heading level that would normally be marked 1. or 2. or 3. etc. in a -document, and the level on which sisu by default would break html output into -named segments, names are provided automatically if none are given (a number), +Top level heading preceding substantive text of document or sub\-heading 2, the +heading level that would normally be marked 1. or 2. or 3. etc. in a document, +and the level on which sisu by default would break html output into named +segments, names are provided automatically if none are given (a number), otherwise takes the form 1~my_filename_for_this_segment .br .B 2~ [heading \ text] -Second level heading preceding substantive text of document or sub\-heading 3 -, the heading level that would normally be marked 1.1 or 1.2 or 1.3 or 2.1 etc. +Second level heading preceding substantive text of document or sub\-heading 3, +the heading level that would normally be marked 1.1 or 1.2 or 1.3 or 2.1 etc. in a document. .br .B 3~ [heading \ text] -Third level heading preceding substantive text of document, that would -normally be marked 1.1.1 or 1.1.2 or 1.2.1 or 2.1.1 etc. in a document +Third level heading preceding substantive text of document, that would normally +be marked 1.1.1 or 1.1.2 or 1.2.1 or 2.1.1 etc. in a document .nf 1~filename level 1 heading, @@ -1255,7 +1261,7 @@ normally be marked 1.1.1 or 1.1.2 or 1.2.1 or 2.1.1 etc. in a document .br +{inserted text}+ .br - \\-{strikethrough}\\- + \-{strikethrough}\- .br #{monospace}# .fi @@ -1268,8 +1274,8 @@ normal text, .B emphasis, .B bold text, .I italics, -.I underscore -, "citation", ^superscript^, [subscript], ++inserted text++, +.I underscore, +"citation", ^superscript^, [subscript], ++inserted text++, \-\-strikethrough\-\-, monospace .br @@ -1277,8 +1283,8 @@ normal text .br .B emphasis -[note: \ can \ be \ configured \ to \ be \ represented \ by \ bold, \ italics -\ or \ underscore] +[note: \ can \ be \ configured \ to \ be \ represented \ by \ bold, \ italics \ +or \ underscore] .br .B bold text @@ -1372,7 +1378,32 @@ Numbered List (not to be confused with headings/titles, (document structure)) _# numbered list numbered list indented a., b., c., d., etc. .fi -.SH 9.4 FOOTNOTES / ENDNOTES +.SH 9.4 HANGING INDENTS + +.br +.B markup example: + +.nf + _0_1 first line no indent, + rest of paragraph indented one step + _1_0 first line indented, + rest of paragraph no indent + in each case level may be 0\-9 +.fi + +.br +.B resulting output: + +.br + first line no indent, rest of paragraph indented one step + +.br +first line indented, rest of paragraph no indent + +.br +in each case level may be 0\-9 + +.SH 9.5 FOOTNOTES / ENDNOTES .br Footnotes and endnotes are marked up at the location where they would be @@ -1454,9 +1485,9 @@ normal text [^+2] continues .br the standard and pair notation cannot be mixed in the same document -.SH 9.5 LINKS +.SH 9.6 LINKS -.SH 9.5.1 NAKED URLS WITHIN TEXT, DEALING WITH URLS +.SH 9.6.1 NAKED URLS WITHIN TEXT, DEALING WITH URLS .br urls found within text are marked up automatically. A url within text is @@ -1511,7 +1542,7 @@ blocks are discussed later in this document deb\-src http://www.jus.uio.no/sisu/archive unstable main non\-free .fi -.SH 9.5.2 LINKING TEXT +.SH 9.6.2 LINKING TEXT .br To link text or an image to a url the markup is as follows @@ -1546,8 +1577,6 @@ automatically as a footnote .br about SiSU [^14] markup -.SH 9.5.3 LINKING IMAGES - .br .B markup example: @@ -1602,9 +1631,9 @@ note at a heading level the same is automatically achieved by providing names to headings 1, 2 and 3 i.e. 2~[name] and 3~[name] or in the case of auto\-heading numbering, without further intervention. -.SH 9.6 GROUPED TEXT +.SH 9.7 GROUPED TEXT -.SH 9.6.1 TABLES +.SH 9.7.1 TABLES .br Tables may be prepared in two either of two forms @@ -1645,7 +1674,7 @@ information in each column Very active contributors*** | 0| 31| 190| 692| 1,639| 3,016 No. of English language articles| 25| 16,000| 101,000| 190,000| 320,000| 630,000 No. of articles, all languages | 25| 19,000| 138,000| 490,000| 862,000|1,600,000 - \\* Contributed at least ten times; \\** at least 5 times in last month; \\*\** more than 100 times in last month. + \e* Contributed at least ten times; \e** at least 5 times in last month; \e*\e** more than 100 times in last month. .fi .br @@ -1660,7 +1689,7 @@ information in each column * Contributed at least ten times; ** at least 5 times in last month; *** more than 100 times in last month. -.SH 9.6.2 POEM +.SH 9.7.2 POEM .br .B basic markup: @@ -1816,7 +1845,7 @@ than 100 times in last month. death."' .br -.SH 9.6.3 GROUP +.SH 9.7.3 GROUP .br .B basic markup: @@ -1976,15 +2005,15 @@ than 100 times in last month. death."' .br -.SH 9.6.4 CODE +.SH 9.7.4 CODE .br 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 .B 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. +markup. You cannot however use code tags to escape code tags. They are however +used in the same way as group or poem tags. .br A code\-block is treated as an object and given a single object number. [an \ @@ -2044,8 +2073,8 @@ some \ later \ time] .br From .B SiSU -2.7.7 on you can number codeblocks by placing a hash after the opening code -tag code{# as demonstrated here: +2.7.7 on you can number codeblocks by placing a hash after the opening code tag +code{# as demonstrated here: .nf 1 | `Fury said to a @@ -2094,9 +2123,9 @@ tag code{# as demonstrated here: 44 | death."' .fi -.SH 9.7 ADDITIONAL BREAKS \- LINEBREAKS WITHIN OBJECTS, COLUMN AND PAGE\-BREAKS +.SH 9.8 ADDITIONAL BREAKS \- LINEBREAKS WITHIN OBJECTS, COLUMN AND PAGE\-BREAKS -.SH 9.7.1 LINE\-BREAKS +.SH 9.8.1 LINE\-BREAKS .br To break a line within a "paragraph object", two backslashes \e\e @@ -2115,7 +2144,7 @@ The html break br enclosed in angle brackets (though undocumented) is available in versions prior to 3.0.13 and 2.9.7 (it remains available for the time being, but is depreciated). -.SH 9.7.2 PAGE BREAKS +.SH 9.8.2 PAGE BREAKS .br Page breaks are only relevant and honored in some output formats. A page break @@ -2140,7 +2169,7 @@ page new <:pn> breaks the page, starts a new page. page break <:pb> breaks a column, starts a new column, if using columns, else breaks the page, starts a new page. -.SH 9.8 BOOK INDEX +.SH 9.9 BOOK INDEX .br To make an index append to paragraph the book index term relates to it, using @@ -2216,15 +2245,15 @@ 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 .B \.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 +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 .B \.sst regular markup file, or .B \.ssi -(insert/information) A secondary file of the composite document is built -prior to processing with the same prefix and the suffix +(insert/information) A secondary file of the composite document is built prior +to processing with the same prefix and the suffix .B \._sst .br @@ -2418,8 +2447,7 @@ which numerically increments an asterisk and plus respectively .br .B SiSU -0.38 introduced alternative experimental header and heading/structure -markers, +0.38 introduced alternative experimental header and heading/structure markers, .nf @headername: and headers :A~ :B~ :C~ 1~ 2~ 3~ @@ -2470,9 +2498,9 @@ those levels this is captured by the following file 'rename' instruction: .nf - rename 's/\.s[123]$/\.sst/' *.s{1,2,3} - rename 's/\.r[123]$/\.ssm/' *.r{1,2,3} - rename 's/\.si$/\.ssi/' *.si + rename 's/\e.s[123]$/\e.sst/' *.s{1,2,3} + rename 's/\e.r[123]$/\e.ssm/' *.r{1,2,3} + rename 's/\e.si$/\e.ssi/' *.si .fi .br @@ -2500,8 +2528,8 @@ relied upon .br .B 0.16 (2005w25/2) substantial changes introduced to make markup cleaner, header -0~title type, and headings [1\-6]~ introduced, also percentage sign (%) at start -of a text line as comment marker +0~title type, and headings [1\-6]~ introduced, also percentage sign (%) at +start of a text line as comment marker .br .B SiSU @@ -2531,19 +2559,19 @@ has plaintext and binary filetypes, and can process either type of document. .B SiSU documents are prepared as plain\-text (utf\-8) files with .B SiSU -markup. They may make reference to and contain images (for example), which -are stored in the directory beneath them _sisu/image. +markup. They may make reference to and contain images (for example), which are +stored in the directory beneath them _sisu/image. .B SiSU -plaintext markup files are of three types that may be distinguished by the -file extension used: regular text \.sst; master documents, composite documents -that incorporate other text, which can be any regular text or text insert; and +plaintext markup files are of three types that may be distinguished by the file +extension used: regular text \.sst; master documents, composite documents that +incorporate other text, which can be any regular text or text insert; and inserts the contents of which are like regular text except these are marked \.ssi and are not processed. .br .B SiSU -processing can be done directly against a sisu documents; which may be -located locally or on a remote server for which a url is provided. +processing can be done directly against a sisu documents; which may be located +locally or on a remote server for which a url is provided. .br .B SiSU @@ -2556,8 +2584,8 @@ source markup can be shared with the command: .br The most common form of document in -.B SiSU -, see the section on +.B SiSU, +see the section on .B SiSU markup. @@ -2574,8 +2602,8 @@ Composite documents which incorporate other .B SiSU documents which may be either regular .B SiSU -text \.sst which may be generated independently, or inserts prepared solely -for the purpose of being incorporated into one or more master documents. +text \.sst which may be generated independently, or inserts prepared solely for +the purpose of being incorporated into one or more master documents. .br The mechanism by which master files incorporate other documents is described as @@ -2609,8 +2637,8 @@ into one or more master documents. They resemble regular .B SiSU text files except they are ignored by the .B SiSU -processor. Making a file a \.ssi file is a quick and convenient way of -flagging that it is not intended that the file should be processed on its own. +processor. Making a file a \.ssi file is a quick and convenient way of flagging +that it is not intended that the file should be processed on its own. .SH 12.2 SISUPOD, ZIPPED BINARY CONTAINER (SISUPOD.ZIP, \.SSP) @@ -2624,8 +2652,8 @@ to include sound and multimedia\-files) .br .B SiSU -plaintext files rely on a recognised directory structure to find contents -such as images associated with documents, but all images for example for all +plaintext files rely on a recognised directory structure to find contents such +as images associated with documents, but all images for example for all documents contained in a directory are located in the sub\-directory _sisu/image. Without the ability to create a sisupod it can be inconvenient to manually identify all other files associated with a document. A sisupod @@ -2654,8 +2682,8 @@ Alternatively, make a pod of the contents of a whole directory: .br .B SiSU -processing can be done directly against a sisupod; which may be located -locally or on a remote server for which a url is provided. +processing can be done directly against a sisupod; which may be located locally +or on a remote server for which a url is provided. .br @@ -2797,8 +2825,8 @@ configuration file is a yaml file, which means indentation is significant. .br .B SiSU -resource configuration is determined by looking at the following files if -they exist: +resource configuration is determined by looking at the following files if they +exist: .br ./_sisu/sisurc.yml @@ -2920,8 +2948,8 @@ list) may be found in: .br CSS files to modify the appearance of .B 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 +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. .br @@ -3081,8 +3109,8 @@ has richer text markup. .br In addition to this .B SiSU -has the ability to populate a relational sql type database with documents at -an object level, with objects numbers that are shared across different output +has the ability to populate a relational sql type database with documents at an +object level, with objects numbers that are shared across different output types, which make them searchable with that degree of granularity. Basically, your match criteria is met by these documents and at these locations within each document, which can be viewed within the database directly or in various @@ -3109,8 +3137,8 @@ four tables: subject, (the Dublin Core...); .br - * another the substantive texts by individual "paragraph" (or object) \- along - with structural information, each paragraph being identifiable by its + * another the substantive texts by individual "paragraph" (or object) \- + along with structural information, each paragraph being identifiable by its paragraph number (if it has one which almost all of them do), and the substantive text of each paragraph quite naturally being searchable (both in formatted and clean text versions for searching); and @@ -3130,10 +3158,10 @@ There is of course the possibility to add further structures. .br At this level .B SiSU -loads a relational database with documents chunked into objects, their -smallest logical structurally constituent parts, as text objects, with their -object citation number and all other structural information needed to construct -the document. Text is stored (at this text object level) with and without +loads a relational database with documents chunked into objects, their smallest +logical structurally constituent parts, as text objects, with their object +citation number and all other structural information needed to construct the +document. Text is stored (at this text object level) with and without elementary markup tagging, the stripped version being so as to facilitate ease of searching. @@ -3141,8 +3169,8 @@ of searching. Being able to search a relational database at an object level with the .B SiSU citation system is an effective way of locating content generated by -.B SiSU -. As individual text objects of a document stored (and indexed) together with +.B SiSU. +As individual text objects of a document stored (and indexed) together with object numbers, and all versions of the document have the same numbering, complex searches can be tailored to return just the locations of the search results relevant for all available output formats, with live links to the @@ -3259,7 +3287,8 @@ to populate an sqlite database, this being part of sisu \-d [instruction] [filename/wildcard \ if \ required] .br - sisu \-d \-\-(sqlite|pg) \-\-[instruction] [filename/wildcard \ if \ required] + sisu \-d \-\-(sqlite|pg) \-\-[instruction] [filename/wildcard \ if \ + required] .SH 23.4 COMMANDS @@ -3277,9 +3306,9 @@ may be used interchangeably. .TP .B \-\-sqlite \-\-createall -initial step, creates required relations (tables, indexes) in existing -(sqlite) database (a database should be created manually and given the same -name as working directory, as requested) (rb.dbi) +initial step, creates required relations (tables, indexes) in existing (sqlite) +database (a database should be created manually and given the same name as +working directory, as requested) (rb.dbi) .TP .B sisu \-d \-\-createdb @@ -3484,9 +3513,9 @@ Ralph Amissah or .br .B 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 +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 .B SiSU documents can either be sisu marked up files in plaintext \.sst or \.ssm or; zipped sisu files, sisupod.zip or filename.ssp @@ -3552,8 +3581,8 @@ machine using either rsync, or scp. .br In order to do this some ssh authentication agent and keychain or similar tool will need to be configured. Once that is done the placement on a remote host -can be done seamlessly with the \-r (for scp) or \-R (for rsync) flag, which may -be used in conjunction with other processing flags, e.g. +can be done seamlessly with the \-r (for scp) or \-R (for rsync) flag, which +may be used in conjunction with other processing flags, e.g. .nf sisu \-3R sisu_remote.sst @@ -3567,8 +3596,8 @@ 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 \-r +\-\-delete parameter is sent, useful for cleaning the remote directory (when +\-R is used together with other flags, it is not). Also see \-r .TP .B \-r [filename/wildcard] @@ -3715,11 +3744,11 @@ is only dependent on the programming language in which it is written .B Ruby, and .B SiSU -will be able to generate html, EPUB, various XMLs, including ODF (and will -also produce LaTeX). Dependencies required for further actions, though it -relies on the installation of additional dependencies which the source tarball -does not take care of, for things like using a database (postgresql or -sqlite)[^24] or converting LaTeX to pdf. +will be able to generate html, EPUB, various XMLs, including ODF (and will also +produce LaTeX). Dependencies required for further actions, though it relies on +the installation of additional dependencies which the source tarball does not +take care of, for things like using a database (postgresql or sqlite)[^24] or +converting LaTeX to pdf. .br .B setup.rb @@ -3945,9 +3974,8 @@ Additional markup samples are packaged separately in the file: .br On .B Debian -they are available in non\-free[^28] to include them it is necessary to -include non\-free in your /etc/apt/source.list or obtain them from the sisu home -site. +they are available in non\-free[^28] to include them it is necessary to include +non\-free in your /etc/apt/source.list or obtain them from the sisu home site. .SH 30. EDITOR FILES, SYNTAX HIGHLIGHTING .br @@ -3956,10 +3984,10 @@ site. The directory: .br - \./data/sisu/v2/conf/editor\-syntax\-etc/ + ./data/sisu/v2/conf/editor\-syntax\-etc/ .br - \./data/sisu/v3/conf/editor\-syntax\-etc/ + ./data/sisu/v3/conf/editor\-syntax\-etc/ .br /usr/share/sisu/v2/conf/editor\-syntax\-etc @@ -4159,8 +4187,8 @@ ways of representing documents, (or indeed to create new ones). .br .br -* sparse/minimal markup (clean utf\-8 source texts). Documents are prepared in a -single UTF\-8 file using a minimalistic mnemonic syntax. Typical literature, +* 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. @@ -4177,11 +4205,11 @@ semantic information related to the document (header information, extended beyond the Dublin core and easily further extended as required); the headers may also contain processing instructions. .B SiSU -markup is primarily an abstraction of document structure and document -metadata to permit taking advantage of the basic strengths of existing -alternative practical standard ways of representing documents [be \ that \ -browser \ viewing, \ paper \ publication, \ sql \ search \ etc.] (html, epub, -xml, odf, latex, pdf, sql) +markup is primarily an abstraction of document structure and document metadata +to permit taking advantage of the basic strengths of existing alternative +practical standard ways of representing documents [be \ that \ browser \ +viewing, \ paper \ publication, \ sql \ search \ etc.] (html, epub, xml, odf, +latex, pdf, sql) .br * for output produces reasonably elegant output of established industry and @@ -4212,8 +4240,8 @@ amongst the output formats currently supported are: * pdf (via LaTeX) .br - * sql \- population of an sql database, (at the same object level that is used - to cite text within a document) + * sql \- population of an sql database, (at the same object level that is + used to cite text within a document) .br Also produces: concordance files; document content certificates (md5 or sha256 @@ -4277,8 +4305,8 @@ may be processed locally to produce the desired document outputs .br * for basic document generation, the only software dependency is -.B Ruby -, and a few standard Unix tools (this covers plaintext, HTML, EPUB, XML, ODF, +.B Ruby, +and a few standard Unix tools (this covers plaintext, HTML, EPUB, XML, ODF, LaTeX). To use a database you of course need that, and to convert the LaTeX generated to pdf, a latex processor like tetex or texlive. @@ -4292,8 +4320,8 @@ markup is available for a number of text editors. .br .B SiSU -is less about document layout than about finding a way with little markup to -be able to construct an abstract representation of a document that makes it +is less about document layout than about finding a way with little markup to be +able to construct an abstract representation of a document that makes it possible to produce multiple representations of it which may be rather different from each other and used for different purposes, whether layout and publishing, or search of content @@ -4381,8 +4409,8 @@ Note .B SiSU documentation is prepared in .B SiSU -and output is available in multiple formats including amongst others html, -pdf, odf and epub, which may be also be accessed via the html pages[^29] +and output is available in multiple formats including amongst others html, pdf, +odf and epub, which may be also be accessed via the html pages[^29] .SH 33.2.1 WWW.SISUDOC.ORG @@ -4437,111 +4465,174 @@ file:///usr/share/doc/sisu/html/sisu.1.html .br -1. objects include: headings, paragraphs, verse, tables, images, but not +.TP +.BI 1. +objects include: headings, paragraphs, verse, tables, images, but not footnotes/endnotes which are numbered separately and tied to the object from which they are referenced. .br -2. i.e. the html, pdf, epub, odf outputs are each built individually and +.TP +.BI 2. +i.e. the html, pdf, epub, odf outputs are each built individually and optimised for that form of presentation, rather than for example the html being a saved version of the odf, or the pdf being a saved version of the html. .br -3. the different heading levels +.TP +.BI 3. +the different heading levels .br -4. units of text, primarily paragraphs and headings, also any tables, poems, -code\-blocks +.TP +.BI 4. +units of text, primarily paragraphs and headings, also any tables, poems, +code-blocks .br -5. Specification submitted by Adobe to ISO to become a full open ISO +.TP +.BI 5. +Specification submitted by Adobe to ISO to become a full open ISO specification - .br -6. ISO standard ISO/IEC 26300:2006 + .br -7. An open standard format for e\-books +.TP +.BI 6. +ISO standard ISO/IEC 26300:2006 .br -*1. square brackets +.TP +.BI 7. +An open standard format for e-books .br -*2. square brackets +.TP +.BI *1. +square brackets .br -+1. square brackets +.TP +.BI *2. +square brackets .br -8. +.TP +.BI +1. +square brackets .br -9. +.TP +.BI 8. + .br -10. From sometime after SiSU 0.58 it should be possible to describe SiSU -markup using SiSU, which though not an original design goal is useful. +.TP +.BI 9. + .br -11. files should be prepared using UTF\-8 character encoding +.TP +.BI 10. +From sometime after SiSU 0.58 it should be possible to describe SiSU markup +using SiSU, which though not an original design goal is useful. .br -12. a footnote or endnote +.TP +.BI 11. +files should be prepared using UTF-8 character encoding .br -13. self contained endnote marker & endnote in one +.TP +.BI 12. +a footnote or endnote + +.br +.TP +.BI 13. +self contained endnote marker & endnote in one .br -* unnumbered asterisk footnote/endnote, insert multiple asterisks if -required +.TP +.BI *. +unnumbered asterisk footnote/endnote, insert multiple asterisks if required + +.br +.TP +.BI **. +another unnumbered asterisk footnote/endnote .br -** another unnumbered asterisk footnote/endnote +.TP +.BI *3. +editors notes, numbered asterisk footnote/endnote series .br -*3. editors notes, numbered asterisk footnote/endnote series +.TP +.BI +2. +editors notes, numbered asterisk footnote/endnote series .br -+2. editors notes, numbered asterisk footnote/endnote series +.TP +.BI 14. + .br -14 +.TP +.BI 15. + .br -15. +.TP +.BI 16. +Table from the Wealth of Networks by Yochai Benkler .br -16. Table from the Wealth of Networks by Yochai Benkler .br -17. .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. +.TP +.BI 17. +\.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. .br -19. +.TP +.BI 19. + + .br .br .br -20. +.TP +.BI 20. + + .br .br -21. +.TP +.BI 21. + .br -22. (which could be extended further with current back\-end). As regards -scaling of the database, it is as scalable as the database (here Postgresql) -and hardware allow. +.TP +.BI 22. +(which could be extended further with current back-end). As regards scaling +of the database, it is as scalable as the database (here Postgresql) and +hardware allow. .br -23. of this feature when demonstrated to an IBM software innovations evaluator +.TP +.BI 23. +of this feature when demonstrated to an IBM software innovations evaluator in 2004 he said to paraphrase: this could be of interest to us. We have large document management systems, you can search hundreds of thousands of documents and we can tell you which documents meet your search criteria, but there is no @@ -4549,16 +4640,24 @@ way we can tell you without opening each document where within each your matches are found. .br -24. There is nothing to stop MySQL support being added in future. +.TP +.BI 24. +There is nothing to stop MySQL support being added in future. .br -25. +.TP +.BI 25. + .br -26. +.TP +.BI 26. + .br -27. +.TP +.BI 27. + .br 28. the -- cgit v1.2.3