diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/man1/sisu.1 | 209 |
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 |