aboutsummaryrefslogtreecommitdiffhomepage
path: root/man
diff options
context:
space:
mode:
authorRalph Amissah <ralph@amissah.com>2014-02-05 01:27:25 -0500
committerRalph Amissah <ralph@amissah.com>2014-02-05 01:27:25 -0500
commit4e7fb32481df6e47db28888ff1e8a63d39aa92c4 (patch)
tree254a9e1ce784d24538db843f6bbbbe9a87ea622f /man
parentsisu manual update (diff)
README & manpage (sisu.1) updatesisu_5.3.1
Diffstat (limited to 'man')
-rw-r--r--man/man1/sisu.1209
1 files changed, 46 insertions, 163 deletions
diff --git a/man/man1/sisu.1 b/man/man1/sisu.1
index a692a9f4..f6bb6b5b 100644
--- a/man/man1/sisu.1
+++ b/man/man1/sisu.1
@@ -1,4 +1,4 @@
-.TH "sisu" "1" "2013-11-27" "5.1.0" "SiSU"
+.TH "sisu" "1" "2014-02-05" "6.0.1" "SiSU"
.br
.SH NAME
.br
@@ -37,197 +37,68 @@ 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.
-
-.BR
-.B SiSU
-is developed under an open source, software libre license (
-.I GPLv3
-). 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
-output) share a common mechanism for cross-output-format citation.
-.BR
.B SiSU
-both defines a markup syntax and provides an engine that produces open
-standards format outputs from documents prepared with
+is a lightweight markup based document creation and publishing framework that
+is controlled from the command line. Prepare documents for
.B SiSU
-markup. From a single lightly prepared document sisu custom builds several
-standard output formats which share a common (text object) numbering system for
-citation of content within a document (that also has implications for search).
-The sisu engine works with an abstraction of the document's structure and
-content from which it is possible to generate different forms of representation
-of the document. Significantly
+using your text editor of choice, then use
.B SiSU
-markup is more sparse than html and outputs which include
-.I HTML,
-.I EPUB,
-.I ODT
-(Open Document Format text),
-.I LaTeX,
-landscape and portrait
-.I PDF,
-all of which can be added to and updated.
-.B SiSU
-is also able to populate
-.I SQL
-type databases at an object level, which means that searches can be made with
-that degree of granularity.
+to generate various output document formats.
.BR
-Source document preparation and output generation is a two step process: (i)
-document source is prepared, that is, marked up in sisu markup syntax and (ii)
-the desired output subsequently generated by running the sisu engine against
-document source. Output representations if updated (in the sisu engine) can be
-generated by re-running the engine against the prepared source. Using
-.B SiSU
-markup applied to a document,
+From a single lightly prepared document (plain-text
+.I UTF-8
+) sisu custom builds several standard output formats which share a common (text
+object) numbering system for citation of content within a document (that also
+has implications for search). The sisu engine works with an abstraction of the
+document's structure and content from which it is possible to generate
+different forms of representation of the document.
.B SiSU
-custom builds (to take advantage of the strengths of different ways of
-representing documents) various standard open output formats including plain
-text,
+produces: plain-text,
.I HTML,
.I XHTML,
.I XML,
.I EPUB,
-.I ODT,
-.I LaTeX
-or
-.I PDF
-files, and populate an
+.I ODF:
+.I ODT
+(Opendocument),
+.I LaTeX,
+.I PDF,
+and populates an
.I SQL
-database with objects[^1] (equating generally to paragraph-sized chunks) so
-searches may be performed and matches returned with that degree of granularity
-( e.g. your search criteria is met by these documents and at these locations
-within each document). Document output formats share a common object numbering
-system for locating content. This is particularly suitable for "published"
-works (finalized texts as opposed to works that are frequently changed or
-updated) for which it provides a fixed means of reference of content.
+database (
+.I PostgreSQL
+or
+.I SQLite
+) with text objects, roughly, paragraph sized chunks so that document searches
+are done at this level of granularity.
.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.
+Outputs share a common citation numbering system, associated with text objects
+and any semantic meta-data provided about the document.
.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
-.B SiSU
-is able to take advantage of.
-.BR
-One of the challenges of maintaining documents is to keep them in a format that
-allows use of them independently of proprietary platforms. Consider issues
-related to dealing with legacy proprietary formats today and what guarantee you
-have that old proprietary formats will remain (or can be read without
-proprietary software/equipment) in 15 years time, or the way the way in which
-html has evolved over its relatively short span of existence.
-.B SiSU
-provides the flexibility of producing documents in multiple non-proprietary
-open formats including
-.I HTML,
-.I EPUB,
-[^5]
-.I ODT,
-[^6]
-.I PDF
-[^7]
-.I ODF,
-[^8]. Whilst
.B SiSU
-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,
-.B SiSU
-is available under
-.I GPLv3
-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 used, updated and further
-developed as required under the terms of its license. Another challenge is to
-keep up with a moving target.
-.B SiSU
-permits new forms of output to be added as they become important, (Open
-Document Format text was added in 2006 when it became an ISO standard for
-office applications and the archival of documents),
-.I EPUB
-was introduced in 2009; and allows the technical representations existing
-output to be updated (
-.I HTML
-has evolved and the related module has been updated repeatedly over the years,
-presumably when the World Wide Web Consortium (w3c) finalises
-.I HTML
-5 which is currently under development, the
-.I HTML
-module will again be updated allowing all existing documents to be regenerated
-as
-.I HTML
-5).
+also provides concordance files, document content certificates and manifests of
+generated output. Book indexes may be made.
.BR
-The document formats are written to the file-system and available for indexing
-by independent indexing tools, whether off the web like Google and Yahoo or on
-the site like Lucene and Hyperestraier.
+Some document markup samples are provided in the package sisu -markup-samples.
+Homepages:
-.BR
-.B SiSU
-also provides other features such as concordance files and document content
-certificates, and the working against an abstraction of document structure has
-further possibilities for the research and development of other document
-representations, the availability of objects is useful for example for topic
-maps and thesauri, together with the flexibility of
-.B SiSU
-offers great possibilities.
+* <http://www.sisudoc.org/>
-.BR
-.B SiSU
-is primarily for published works, which can take advantage of the citation
-system to reliably reference its documents.
-.B SiSU
-works well in a complementary manner with such collaborative technologies as
-Wikis, which can take advantage of and be used to discuss the substance of
-content prepared in
-.B SiSU.
-
-.BR
-<http://www.sisudoc.org/>
+* <http://www.jus.uio.no/sisu>
-.BR
-<http://www.jus.uio.no/sisu>
.SH COMMANDS SUMMARY
.SH DESCRIPTION
.BR
+
.B SiSU
is a document publishing system, that from a simple single marked-up document,
produces multiple output formats including:
@@ -428,6 +299,9 @@ produces html output, the document in a single file (scroll.html) only. Compare
produces html output, segmented text with table of contents (toc.html and
index.html). Compare --html-scroll and --html
.TP
+.B --html-strict [filename/wildcard]
+produces html with --strict option. see --strict
+.TP
.B -I [filename/wildcard]
see --texinfo
.TP
@@ -498,6 +372,9 @@ see --exc-*
.B -o [filename/wildcard/url]
see --odt
.TP
+.B --ocn
+see --inc-ocn and --exc-ocn
+.TP
.B --odf [filename/wildcard/url]
see --odt
.TP
@@ -702,6 +579,10 @@ for sending). See the -S option without [filename/wildcard]. Alias -S
.B --source [filename/wildcard]
copies sisu markup file to output directory. Alias -s
.TP
+.B --strict
+together with --html, produces more w3c compliant html, for example not having
+purely numeric identifiers for text, the location object url#33 becomes url#o33
+.TP
.B -T [filename/wildcard (*.termsheet.rb)]
standard form document builder, preprocessing feature
.TP
@@ -2279,6 +2160,8 @@ 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).
+.BR
+To draw a dividing line dividing paragraphs, see the section on page breaks.
.SH PAGE BREAKS
.BR