From c5e3e37e66ac980c2a9a458bfdc7455e831ad1ab Mon Sep 17 00:00:00 2001 From: Ralph Amissah Date: Sat, 29 Sep 2007 16:00:32 +0100 Subject: start preparing sisu-auto-generated man pages for 0.60 release --- man/man1/sisu.1 | 1535 ++++++++++++++++++++++------------------------- man/man1/sisu_webrick.1 | 12 +- 2 files changed, 721 insertions(+), 826 deletions(-) (limited to 'man/man1') diff --git a/man/man1/sisu.1 b/man/man1/sisu.1 index 11c5dc72..8cbb0056 100644 --- a/man/man1/sisu.1 +++ b/man/man1/sisu.1 @@ -1,4 +1,12 @@ -.TH "sisu" "1" "2007-08-30" "0.59.1" "SiSU" +.TH "sisu" "1" "2007-09-29" "0.59.1" "SiSU" +.SH NAME +sisu \- documents: markup, structuring, publishing in multiple standard formats, and search +.SH SYNOPSIS +sisu [\-abcDdFHhIiMmNnopqRrSsTtUuVvwXxYyZz0\-9] [filename/wildcard ] +.BR +sisu [\-Ddcv] [instruction] +.BR +sisu [\-CcFLSVvW] .SH SISU \- MANUAL, RALPH AMISSAH @@ -14,24 +22,21 @@ WHAT IS SISU? .BR .B SiSU -is a system for document markup, publishing (in multiple open standard -formats) and search - -.BR -.B SiSU -[^1] is a[^2] framework for document structuring, publishing 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 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). It has been -developed in the context of coping with large document sets with evolving -markup related technologies, for which you want multiple output formats, a -common mechanism for cross\-output\-format citation, and search. +is developed under an open source, software libre license (GPL3). Its use +case for development is to cope with medium to large document sets with +evolving markup related technologies, which should be prepared once, and for +which you want multiple output formats that can be updated and a common +mechanism for cross\-output\-format citation, and search. .BR .B SiSU @@ -50,10 +55,7 @@ landscape and portrait pdfs, Open Document Format (ODF), all of which can be added to and updated. .B SiSU is also able to populate SQL type databases at an object level, which means -that searches can be made with that degree of granularity. Results of objects -(primarily paragraphs and headings) can be viewed directly in the database, or -just the object numbers shown \- your search criteria is met in these documents -and at these locations within each document. +that searches can be made with that degree of granularity. .BR Source document preparation and output generation is a two step process: (i) @@ -64,9 +66,10 @@ generated by re\-running the engine against the prepared source. Using .B SiSU markup applied to a document, .B SiSU -custom builds various standard open output formats including plain text, -HTML, XHTML, XML, OpenDocument, LaTeX or PDF files, and populate an SQL -database with objects[^3] (equating generally to paragraph\-sized chunks) so +custom builds (to take advantage of the strengths of different ways of +representing documents) various standard open output formats including plain +text, HTML, XHTML, XML, OpenDocument, LaTeX or PDF files, and populate an 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 @@ -81,19 +84,20 @@ 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[^4] +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 frame[^5] and the objects[^6] it contains, which enables +comprised of its structure (or frame)[^3] and the objects[^4] it contains, +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 base for citing material within a document across the different output format types. This is -significant as page numbers are not suited to the digital age, in web +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 means that text appears on different pages; and in publishing in different formats, html, landscape and portrait pdf etc. again page numbers are of no use @@ -111,7 +115,7 @@ time, or the way the way in which html has evolved over its relatively short span of existence. .B SiSU provides the flexibility of outputing documents in multiple non\-proprietary -open formats including html, pdf[^7] and the ISO standard ODF.[^8] Whilst +open formats including html, pdf[^5] and the ISO standard ODF.[^6] 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 @@ -122,15 +126,16 @@ 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 -used updated and further developed as required under the terms of its license. +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), and existing output to be updated -(html has evolved and the related module has been updated repeatedly over the -years, presumably when the World Wide Web Consortium (w3c) finalises html 5 -which is currently under development, the html module will again be updated -allowing all existing documents to be regenerated as html 5). +Document Format text was added in 2006 when it became an ISO standard for +office applications and the archival of documents), and existing output to be +updated (html has evolved and the related module has been updated repeatedly +over the years, presumably when the World Wide Web Consortium (w3c) finalises +html 5 which is currently under development, the html module will again be +updated allowing all existing documents to be regenerated as html 5). .BR The document formats are written to the file\-system and available for indexing @@ -163,362 +168,11 @@ content prepared in .SH -2. HOW DOES SISU WORK? +2. COMMANDS SUMMARY .BR -.BR -.B SiSU -markup is fairly minimalistic, it consists of: a (largely optional) document -header, made up of information about the document (such as when it was -published, who authored it, and granting what rights) and any processing -instructions; and markup within the substantive text of the document, which is -related to document structure and typeface. -.B SiSU -must be able to discern the structure of a document, (text headings and their -levels in relation to each other), either from information provided in the -document header or from markup within the text (or from a combination of both). -Processing is done against an abstraction of the document comprising of -information on the document\'s structure and its objects,[2] which the program -serializes (providing the object numbers) and which are assigned hash sum -values based on their content. This abstraction of information about document -structure, objects, (and hash sums), provides considerable flexibility in -representing documents different ways and for different purposes (e.g. search, -document layout, publishing, content certification, concordance etc.), and -makes it possible to take advantage of some of the strengths of established -ways of representing documents, (or indeed to create new ones). - .SH -3. SUMMARY OF FEATURES -.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, -documents like \"War and Peace\" require almost no markup, and most of the -headers are optional. - -.BR -* markup is easily readable/parsable by the human eye, (basic markup is simpler -and more sparse than the most basic HTML), \ [this \ may \ also \ be \ -converted \ to \ XML \ representations \ of \ the \ same \ input/source \ -document]. - -.BR -* markup defines document structure (this may be done once in a header -pattern\-match description, or for heading levels individually); basic text -attributes (bold, italics, underscore, strike\-through etc.) as required; and -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, xml, -odf, latex, pdf, sql) - -.BR -* for output produces reasonably elegant output of established industry and -institutionally accepted open standard formats.[3] takes advantage of the -different strengths of various standard formats for representing documents, -amongst the output formats currently supported are: - -.BR - * html \- both as a single scrollable text and a segmented document - -.BR - * xhtml - -.BR - * XML \- both in sax and dom style xml structures for further development as - required - -.BR - * ODF \- open document format, the iso standard for document storage - -.BR - * LaTeX \- used to generate pdf - -.BR - * pdf (via LaTeX) - -.BR - * 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 -digests of headings, paragraphs, images etc.) and html manifests (and sitemaps -of content). (b) takes advantage of the strengths implicit in these very -different output types, (e.g. PDFs produced using typesetting of LaTeX, -databases populated with documents at an individual object/paragraph level, -making possible granular search (and related possibilities)) - -.BR -* ensuring content can be cited in a meaningful way regardless of selected -output format. Online publishing (and publishing in multiple document formats) -lacks a useful way of citing text internally within documents (important to -academics generally and to lawyers) as page numbers are meaningless across -browsers and formats. sisu seeks to provide a common way of pinpoint the text -within a document, (which can be utilized for citation and by search engines). -The outputs share a common numbering system that is meaningful (to man and -machine) across all digital outputs whether paper, screen, or database -oriented, (pdf, HTML, xml, sqlite, postgresql), this numbering system can be -used to reference content. - -.BR -* Granular search within documents. SQL databases are populated at an object -level (roughly headings, paragraphs, verse, tables) and become searchable with -that degree of granularity, the output information provides the -object/paragraph numbers which are relevant across all generated outputs; it is -also possible to look at just the matching paragraphs of the documents in the -database; \ [output \ indexing \ also \ work \ well \ with \ search \ indexing -\ tools \ like \ hyperestraier]. - -.BR -* long term maintainability of document collections in a world of changing -formats, having a very sparsely marked\-up source document base. there is a -considerable degree of future\-proofing, output representations are -\"upgradeable\", and new document formats may be added. e.g. addition of odf -(open document text) module in 2006 and in future html5 output sometime in -future, without modification of existing prepared texts - -.BR -* SQL search aside, documents are generated as required and static once -generated. - -.BR -* documents produced are static files, and may be batch processed, this needs -to be done only once but may be repeated for various reasons as desired -(updated content, addition of new output formats, updated technology document -presentations/representations) - -.BR -* document source (plaintext utf\-8) if shared on the net may be used as input -and processed locally to produce the different document outputs - -.BR -* document source may be bundled together (automatically) with associated -documents (multiple language versions or master document with inclusions) and -images and sent as a zip file called a sisupod, if shared on the net these too -may be processed locally to produce the desired document outputs - -.BR -* generated document outputs may automatically be posted to remote sites. - -.BR -* for basic document generation, the only software dependency is -.B Ruby -, and a few standard Unix tools (this covers plaintext, HTML, 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. - -.BR -* as a developers tool it is flexible and extensible - -.BR -Syntax highlighting for -.B SiSU -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 -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 - -.BR -i.e. to be able to take advantage from this minimal preparation starting point -of some of the strengths of rather different established ways of representing -documents for different purposes, whether for search (relational database, or -indexed flat files generated for that purpose whether of complete documents, or -say of files made up of objects), online viewing (e.g. html, xml, pdf), or -paper publication (e.g. pdf)... - -.BR -the solution arrived at is by extracting structural information about the -document (about headings within the document) and by tracking objects (which -are serialized and also given hash values) in the manner described. It makes -possible representations that are quite different from those offered at -present. For example objects could be saved individually and identified by -their hashes, with an index of how the objects relate to each other to form a -document. - -.SH -4. HELP -.BR - -.SH -4.1 SISU MANUAL - -.BR -The most up to date information on sisu should be contained in the sisu_manual, -available at: - -.BR - - -.BR -and (from -.B SiSU -0.59 onwards) installed locally at: - -.BR - /usr/share/doc/sisu/sisu_manual/ - -.BR -or equivalent directory - -.BR -Within the -.B SiSU -tarball at: - -.BR - \./data/doc/sisu/sisu_manual/ - -.SH -4.2 SISU MAN PAGES - -.BR -If -.B SiSU -is installed on your system usual man commands should be available, try: - -.BR - man sisu - -.BR - man sisu_markup - -.BR - man sisu_commands - -.BR -Most -.B 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 -.B SiSU -tarball at: - -.BR - \./data/doc/sisu/sisu_manual/ - -.BR -Once installed, directory equivalent to: - -.BR - /usr/share/doc/sisu/sisu_manual/ - -.BR -Available man pages are converted back to html using man2html: - -.BR - /usr/share/doc/sisu/html/ - -.BR - \./data/doc/sisu/html/ - -.BR -The -.B SiSU -man pages can be viewed online at:[^9] - -.BR -An online version of the sisu man page is available here: - -.BR -* various sisu man pages \ [^10] - -.BR -* sisu.1 \ [^11] - -.BR -* sisu.8 \ [^12] - -.BR -* sisu_examples.1 \ [^13] - -.BR -* sisu_webrick.1 \ [^14] - -.SH -4.3 SISU BUILT\-IN INTERACTIVE HELP - -.BR -This is particularly useful when current installation information is obtained -as the interactive help is able to provide information on your sisu -configuration and setup. - -.BR - sisu \-\-help - -.BR - sisu \-\-help \ [subject] - -.BR - sisu \-\-help env \ [for \ feedback \ on \ the \ way \ your \ system \ is \ - setup \ with \ regard \ to \ sisu] - -.BR - sisu \-V \ [same \ as \ above \ command] - -.BR - sisu \-\-help commands - -.BR - sisu \-\-help markup - -.BR -Apart from real\-time information on your current configuration the -.B SiSU -manual and man pages are likely to contain more up\-to\-date information than -the sisu interactive help (for example on commands and markup). - -.BR -NOTE: Running the command sisu (alone without any flags, filenames or -wildcards) brings up the interactive help, as does any sisu command that is not -recognised. Enter to escape. - -.SH -4.4 HELP SOURCES - -.BR -For lists of alternative help sources, see: - -.BR -.B man page - -.BR - man sisu_help_sources - -.BR -.B man2html - -.BR - /usr/share/doc/sisu/sisu_manual/sisu_help_sources/index.html - -.BR -.B sisu generated html - -.BR - /usr/share/doc/sisu/html/sisu_help_sources/index.html - -.BR - - -.BR - - -.SH -5. COMMANDS SUMMARY -.BR - -.SH -5.1 SYNOPSIS +2.1 SYNOPSIS .BR .B SiSU @@ -539,7 +193,7 @@ Note: commands should be issued from within the directory that contains the marked up files, cd to markup directory. .SH -5.2 DESCRIPTION +2.2 DESCRIPTION .BR .B SiSU @@ -551,7 +205,7 @@ numbered text objects (\"object citation numbering\") and the same document structure information. For more see: .SH -5.3 DOCUMENT PROCESSING COMMAND FLAGS +2.3 DOCUMENT PROCESSING COMMAND FLAGS .TP .B \ \-a \ \ [filename/wildcard] @@ -640,6 +294,10 @@ system, and works with most web servers). \ [behaviour \ switched \ after \ .B \ \-I \ \ [filename/wildcard] produces texinfo and info file, (view with pinfo). +.TP +.B \ \-i \ \ [filename/wildcard] +produces man page of file, not suitable for all outputs. + .TP .B \ \-L \ prints \ license \ information. \ @@ -820,7 +478,7 @@ produces php (zend) \ [this \ feature \ is \ disabled \ for \ the \ time \ being] .SH -6. COMMAND LINE MODIFIERS +3. COMMAND LINE MODIFIERS .BR .TP @@ -845,7 +503,7 @@ sign sign .SH -7. DATABASE COMMANDS +4. DATABASE COMMANDS .BR .BR @@ -891,7 +549,7 @@ alphanumerics and underscores. The v in e.g. \-Dv is for verbose output. .SH -8. SHORTCUTS, SHORTHAND FOR MULTIPLE FLAGS +5. SHORTCUTS, SHORTHAND FOR MULTIPLE FLAGS .BR .TP @@ -940,7 +598,7 @@ wildcard] consider \-u for appended url info or \-v for verbose output .SH -8.0.1 COMMAND LINE WITH FLAGS \- BATCH PROCESSING +5.0.1 COMMAND LINE WITH FLAGS \- BATCH PROCESSING .BR In the data directory run sisu \-mh filename or wildcard eg. \"sisu \-h @@ -948,20 +606,175 @@ cisg.sst\" or \"sisu \-h *.{sst,ssm}\" to produce html version of all documents. .BR -Running sisu (alone without any flags, filenames or wildcards) brings up the -interactive help, as does any sisu command that is not recognised. Enter to -escape. +Running sisu (alone without any flags, filenames or wildcards) brings up the +interactive help, as does any sisu command that is not recognised. Enter to +escape. + +.SH +6. HELP +.BR + +.SH +6.1 SISU MANUAL + +.BR +The most up to date information on sisu should be contained in the sisu_manual, +available at: + +.BR + + +.BR +and (from +.B SiSU +0.59 onwards) installed locally at: + +.BR + /usr/share/doc/sisu/sisu_manual/ + +.BR +or equivalent directory + +.BR +Within the +.B SiSU +tarball at: + +.BR + \./data/doc/sisu/sisu_manual/ + +.SH +6.2 SISU MAN PAGES + +.BR +If +.B SiSU +is installed on your system usual man commands should be available, try: + +.BR + man sisu + +.BR + man sisu_markup + +.BR + man sisu_commands + +.BR +Most +.B 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 +.B SiSU +tarball at: + +.BR + \./data/doc/sisu/sisu_manual/ + +.BR +Once installed, directory equivalent to: + +.BR + /usr/share/doc/sisu/sisu_manual/ + +.BR +Available man pages are converted back to html using man2html: + +.BR + /usr/share/doc/sisu/html/ + +.BR + \./data/doc/sisu/html/ + +.BR +An online version of the sisu man page is available here: + +.BR +* various sisu man pages \ [^7] + +.BR +* sisu.1 \ [^8] + +.SH +6.3 SISU BUILT\-IN INTERACTIVE HELP + +.BR +This is particularly useful for getting the current sisu setup/environment +information: + +.BR + sisu \-\-help + +.BR + sisu \-\-help \ [subject] + +.BR + sisu \-\-help commands + +.BR + sisu \-\-help markup + +.BR + sisu \-\-help env \ [for \ feedback \ on \ the \ way \ your \ system \ is \ + setup \ with \ regard \ to \ sisu] + +.BR + sisu \-V \ [environment \ information, \ same \ as \ above \ command] + +.BR + sisu (on its own provides version and some help information) + +.BR +Apart from real\-time information on your current configuration the +.B SiSU +manual and man pages are likely to contain more up\-to\-date information than +the sisu interactive help (for example on commands and markup). + +.BR +NOTE: Running the command sisu (alone without any flags, filenames or +wildcards) brings up the interactive help, as does any sisu command that is not +recognised. Enter to escape. + +.SH +6.4 HELP SOURCES + +.BR +For lists of alternative help sources, see: + +.BR +.B man page + +.BR + man sisu_help_sources + +.BR +.B man2html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_help_sources/index.html + +.BR +.B sisu generated html + +.BR + /usr/share/doc/sisu/html/sisu_help_sources/index.html + +.BR + + +.BR + .SH -9. INTRODUCTION TO SISU MARKUP[^15] +7. INTRODUCTION TO SISU MARKUP[^9] .BR .SH -9.1 SUMMARY +7.1 SUMMARY .BR .B SiSU -source documents are plaintext (UTF\-8)[^16] files +source documents are plaintext (UTF\-8)[^10] files .BR All paragraphs are separated by an empty line. @@ -1003,10 +816,10 @@ Some interactive help on markup is available, by typing sisu and selecting markup or sisu \-\-help markup .SH -9.2 MARKUP EXAMPLES +7.2 MARKUP EXAMPLES .SH -9.2.1 ONLINE +7.2.1 ONLINE .BR Online markup examples are available together with the respective outputs @@ -1027,7 +840,7 @@ an alternative presentation of markup syntax: .SH -9.2.2 INSTALLED +7.2.2 INSTALLED .BR With @@ -1038,7 +851,7 @@ sisu\-markup\-samples is installed also under: /usr/share/doc/sisu/sisu_markup_samples/non\-free .SH -10. MARKUP OF HEADERS +8. MARKUP OF HEADERS .BR .BR @@ -1058,7 +871,7 @@ a space and the comment: .fi .SH -10.1 SAMPLE HEADER +8.1 SAMPLE HEADER .BR This current document has a header similar to this one (without the comments): @@ -1093,7 +906,7 @@ This current document has a header similar to this one (without the comments): .fi .SH -10.2 AVAILABLE HEADERS +8.2 AVAILABLE HEADERS .BR Header tags appear at the beginning of a document and provide meta information @@ -1319,6 +1132,16 @@ skins change default settings related to the appearance of documents generated, such as the urls of the home site, and the icon/logo for the document or site. +.TP +.B \ @man: \ 8; +\ name=sisu \ \- \ documents: \ markup, \ structuring, \ publishing \ in \ +multiple \ standard \ formats, \ and \ search; \ synopsis=sisu \ \ +[\-abcDdFHhIiMmNnopqRrSsTtUuVvwXxYyZz0\-9] \ [filename/wildcard \ ] +sisu \ [\-Ddcv] \ [instruction] +sisu \ [\-CcFLSVvW] +the man page category number (default 1) and special tags used in preparing +man page headings + .BR .B @links: { @@ -1335,11 +1158,11 @@ sample: \ free_as_in_freedom.richard_stallman_crusade_for_free_software.sam_williams.sst] .SH -11. MARKUP OF SUBSTANTIVE TEXT +9. MARKUP OF SUBSTANTIVE TEXT .BR .SH -11.1 HEADING LEVELS +9.1 HEADING LEVELS .BR Heading levels are :A~ ,:B~ ,:C~ ,1~ ,2~ ,3~ \... :A \- :C being part / section @@ -1388,7 +1211,7 @@ normally be marked 1.1.1 or 1.1.2 or 1.2.1 or 2.1.1 etc. in a document .fi .SH -11.2 FONT ATTRIBUTES +9.2 FONT ATTRIBUTES .BR .B markup example: @@ -1450,7 +1273,7 @@ normal text strikethrough .SH -11.3 INDENTATION AND BULLETS +9.3 INDENTATION AND BULLETS .BR .B markup example: @@ -1513,7 +1336,7 @@ Numbered List (not to be confused with headings/titles, (document structure)) .fi .SH -11.4 FOOTNOTES / ENDNOTES +9.4 FOOTNOTES / ENDNOTES .BR Footnotes and endnotes not distinguished in markup. They are automatically @@ -1532,7 +1355,7 @@ document output selected will have either footnotes or endnotes. .B resulting output: .BR -[^17] +[^11] .BR .B markup example: @@ -1546,7 +1369,7 @@ document output selected will have either footnotes or endnotes. .B resulting output: .BR -normal text[^18] continues +normal text[^12] continues .BR .B markup example: @@ -1599,10 +1422,10 @@ normal text \ [^+2] continues the standard and pair notation cannot be mixed in the same document .SH -11.5 LINKS +9.5 LINKS .SH -11.5.1 NAKED URLS WITHIN TEXT, DEALING WITH URLS +9.5.1 NAKED URLS WITHIN TEXT, DEALING WITH URLS .BR urls are found within text and marked up automatically. A url within text is @@ -1671,7 +1494,7 @@ To link text or an image to a url the markup is as follows .fi .SH -11.5.2 LINKING TEXT +9.5.2 LINKING TEXT .BR .B resulting output: @@ -1695,10 +1518,10 @@ automatically as a footnote .B resulting output: .BR -about SiSU \ [^19] markup +about SiSU \ [^13] markup .SH -11.5.3 LINKING IMAGES +9.5.3 LINKING IMAGES .BR .B markup example: @@ -1722,7 +1545,7 @@ about SiSU \ [^19] markup tux.png 64x80 \"Gnu/Linux \- a better way\" .BR -[ \ ruby_logo \ (png \ missing) \ ] \ [^20] +[ \ ruby_logo \ (png \ missing) \ ] \ [^14] .BR GnuDebianLinuxRubyBetterWay.png 100x101 \"Way Better \- with Gnu/Linux, Debian @@ -1749,10 +1572,10 @@ 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 -11.6 GROUPED TEXT +9.6 GROUPED TEXT .SH -11.6.1 TABLES +9.6.1 TABLES .BR Tables may be prepared in two either of two forms @@ -1783,7 +1606,7 @@ information in each column .BR .B markup example: -[^21] +[^15] .nf @@ -1811,7 +1634,7 @@ information in each column than 100 times in last month. .SH -11.6.2 POEM +9.6.2 POEM .BR .B basic markup: @@ -1971,7 +1794,7 @@ than 100 times in last month. .P .SH -11.6.3 GROUP +9.6.3 GROUP .BR .B basic markup: @@ -2131,7 +1954,7 @@ than 100 times in last month. .P .SH -11.6.4 CODE +9.6.4 CODE .BR Code tags are used to escape regular sisu markup, and have been used @@ -2197,7 +2020,7 @@ some \ later \ time] .fi .SH -12. COMPOSITE DOCUMENTS MARKUP +10. COMPOSITE DOCUMENTS MARKUP .BR .BR @@ -2252,13 +2075,34 @@ MARKUP SYNTAX HISTORY .BR .SH -13. NOTES RELATED TO FILES\-TYPES AND MARKUP SYNTAX +11. NOTES RELATED TO FILES\-TYPES AND MARKUP SYNTAX .BR .BR 0.38 is substantially current, depreciated 0.16 supported, though file names were changed at 0.37 +.BR +* sisu \-\-query=[sisu \ version \ \ [0.38] or \'history] + +.BR +provides a short history of changes to +.B SiSU +markup + +.BR +.B 0.57 +(2007w34/4) +.B SiSU +0.57 is the same as 0.42 with the introduction of some a shortcut to use the +headers @title and @creator in the first heading \ [expanded \ using \ the \ +contents \ of \ the \ headers \ @title: \ and \ @author:] + + +.nf + :A~ @title by @author +.fi + .BR .B 0.52 (2007w14/6) declared document type identifier at start of text/document: @@ -2288,17 +2132,112 @@ variations include \' .B 0.42 (2006w27/4) * (asterisk) type endnotes, used e.g. in relation to author +.BR +.B SiSU +0.42 is the same as 0.38 with the introduction of some additional endnote +types, + +.BR +Introduces some variations on endnotes, in particular the use of the asterisk + + +.nf + ~{* for example for describing an author }~ and ~{** for describing a second author }~ +.fi + +.BR +* for example for describing an author + +.BR +** for describing a second author + +.BR +and + + +.nf + ~[* \ my \ note \ ]~ or ~[+ \ another \ note \ ]~ +.fi + +.BR +which numerically increments an asterisk and plus respectively + +.BR +*1 my note +1 another note + .BR .B 0.38 (2006w15/7) introduced new/alternative notation for headers, e.g. @title: (instead of 0~title), and accompanying document structure markup, :A,:B,:C,1,2,3 (maps to previous 1,2,3,4,5,6) +.BR +.B SiSU +0.38 introduced alternative experimental header and heading/structure +markers, + + +.nf + @headername: and headers :A~ :B~ :C~ 1~ 2~ 3~ +.fi + +.BR +as the equivalent of: + + +.nf + 0~headername and headers 1~ 2~ 3~ 4~ 5~ 6~ +.fi + +.BR +The internal document markup of +.B SiSU +0.16 remains valid and standard Though note that +.B SiSU +0.37 introduced a new file naming convention + +.BR +.B SiSU +has in effect two sets of levels to be considered, using 0.38 notation A\-C +headings/levels, pre\-ordinary paragraphs /pre\-substantive text, and 1\-3 +headings/levels, levels which are followed by ordinary text. This may be +conceptualised as levels A,B,C, 1,2,3, and using such letter number notation, +in effect: A must exist, optional B and C may follow in sequence (not strict) 1 +must exist, optional 2 and 3 may follow in sequence i.e. there are two +independent heading level sequences A,B,C and 1,2,3 (using the 0.16 standard +notation 1,2,3 and 4,5,6) on the positive side: the 0.38 A,B,C,1,2,3 +alternative makes explicit an aspect of structuring documents in +.B SiSU +that is not otherwise obvious to the newcomer (though it appears more +complicated, is more in your face and likely to be understood fairly quickly); +the substantive text follows levels 1,2,3 and it is \'nice\' to do most work in +those levels + .BR .B 0.37 (2006w09/7) introduced new file naming convention, \.sst (text), \.ssm (master), \.ssi (insert), markup syntax unchanged +.BR +.B SiSU +0.37 introduced new file naming convention, using the file extensions \.sst + \.ssm and \.ssi to replace \.s1 \.s2 \.s3 \.r1 \.r2 \.r3 and \.si + +.BR +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 +.fi + +.BR +The internal document markup remains unchanged, from +.B SiSU +0.16 + .BR .B 0.35 (2005w52/3) sisupod, zipped content file introduced @@ -2322,8 +2261,23 @@ relied upon 0~title type, and headings \ [1\-6]~ introduced, also percentage sign (%) at start of a text line as comment marker +.BR +.B SiSU +0.16 (0.15 development branch) introduced the use of + +.BR +the header 0~ and headings/structure 1~ 2~ 3~ 4~ 5~ 6~ + +.BR +in place of the 0.1 header, heading/structure notation + +.BR +.B SiSU +0.1 headers and headings structure represented by header 0{~ and +headings/structure 1{ 2{ 3{ 4{~ 5{ 6{ + .SH -14. SISU FILETYPES +12. SISU FILETYPES .BR .BR @@ -2331,7 +2285,7 @@ start of a text line as comment marker has plaintext and binary filetypes, and can process either type of document. .SH -14.1 \.SST \.SSM \.SSI MARKED UP PLAIN TEXT +12.1 \.SST \.SSM \.SSI MARKED UP PLAIN TEXT .BR .B SiSU @@ -2344,7 +2298,7 @@ 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. + \.ssi and are not processed. .BR .B SiSU @@ -2359,7 +2313,7 @@ source markup can be shared with the command: sisu \-s \ [filename] .SH -14.1.1 SISU TEXT \- REGULAR FILES (.SST) +12.1.1 SISU TEXT \- REGULAR FILES (.SST) .BR The most common form of document in @@ -2375,7 +2329,7 @@ markup. .SH -14.1.2 SISU MASTER FILES (.SSM) +12.1.2 SISU MASTER FILES (.SSM) .BR Composite documents which incorporate other @@ -2401,7 +2355,7 @@ contain other documents. .BR Note: a secondary file of the composite document is built prior to processing -with the same prefix and the suffix \._sst \ [^22] +with the same prefix and the suffix \._sst \ [^16] .BR @@ -2410,7 +2364,7 @@ with the same prefix and the suffix \._sst \ [^22] .SH -14.1.3 SISU INSERT FILES (.SSI) +12.1.3 SISU INSERT FILES (.SSI) .BR Inserts are documents prepared solely for the purpose of being incorporated @@ -2422,7 +2376,7 @@ 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 -14.2 SISUPOD, ZIPPED BINARY CONTAINER (SISUPOD.ZIP, \.SSP) +12.2 SISUPOD, ZIPPED BINARY CONTAINER (SISUPOD.ZIP, \.SSP) .BR A sisupod is a zipped @@ -2474,11 +2428,11 @@ locally or on a remote server for which a url is provided. .SH -15. EXPERIMENTAL ALTERNATIVE INPUT REPRESENTATIONS +13. EXPERIMENTAL ALTERNATIVE INPUT REPRESENTATIONS .BR .SH -15.1 ALTERNATIVE XML +13.1 ALTERNATIVE XML .BR .B SiSU @@ -2514,7 +2468,7 @@ or the same: sisu \-\-from\-sxml \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]] .SH -15.1.1 XML SAX REPRESENTATION +13.1.1 XML SAX REPRESENTATION .BR To convert from sst to simple xml (sax) representation: @@ -2536,7 +2490,7 @@ or the same: sisu \-\-from\-sxml \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]] .SH -15.1.2 XML DOM REPRESENTATION +13.1.2 XML DOM REPRESENTATION .BR To convert from sst to simple xml (dom) representation: @@ -2558,7 +2512,7 @@ or the same: sisu \-\-from\-sxml \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]] .SH -15.1.3 XML NODE REPRESENTATION +13.1.3 XML NODE REPRESENTATION .BR To convert from sst to simple xml (node) representation: @@ -2580,11 +2534,11 @@ or the same: sisu \-\-from\-sxml \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]] .SH -16. CONFIGURATION +14. CONFIGURATION .BR .SH -16.1 DETERMINING THE CURRENT CONFIGURATION +14.1 DETERMINING THE CURRENT CONFIGURATION .BR Information on the current configuration of @@ -2605,7 +2559,7 @@ Either of these should be executed from within a directory that contains sisu markup source documents. .SH -16.2 CONFIGURATION FILES (CONFIG.YML) +14.2 CONFIGURATION FILES (CONFIG.YML) .BR .B SiSU @@ -2650,7 +2604,7 @@ If is installed a sample sisurc.yml may be found in /etc/sisu/sisurc.yml .SH -17. SKINS +15. SKINS .BR .BR @@ -2687,7 +2641,7 @@ The skin itself is a ruby file which modifies the default appearances set in the program. .SH -17.1 DOCUMENT SKIN +15.1 DOCUMENT SKIN .BR Documents take on a document skin, if the header of the document specifies a @@ -2699,7 +2653,7 @@ skin to be used. .fi .SH -17.2 DIRECTORY SKIN +15.2 DIRECTORY SKIN .BR A directory may be mapped on to a particular skin, so all documents within that @@ -2713,13 +2667,13 @@ A personal habit is to place all skins within the doc directory, and symbolic links as needed from the site, or dir directories as required. .SH -17.3 SITE SKIN +15.3 SITE SKIN .BR A site skin, modifies the program default skin. .SH -17.4 SAMPLE SKINS +15.4 SAMPLE SKINS .BR With @@ -2745,14 +2699,14 @@ list) may be found in: directory) .SH -18. CSS \- CASCADING STYLE SHEETS (FOR HTML, XHTML AND XML) +16. CSS \- CASCADING STYLE SHEETS (FOR HTML, XHTML AND XML) .BR .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 + \./_sisu/css; ~/.sisu/css or; /etc/sisu/css and these will be copied to the output directories with the command sisu \-CC. .BR @@ -2778,14 +2732,14 @@ The default homepage may use homepage.css or html.css .BR Under consideration is to permit the placement of a CSS file with a different name in directory _sisu/css directory or equivalent, and change the default CSS -file that is looked for in a skin.[^23] +file that is looked for in a skin.[^17] .SH -19. ORGANISING CONTENT +17. ORGANISING CONTENT .BR .SH -19.1 DIRECTORY STRUCTURE AND MAPPING +17.1 DIRECTORY STRUCTURE AND MAPPING .BR The output directory root can be set in the sisurc.yml file. Under the root, @@ -2814,10 +2768,10 @@ directory basis and resulting documents will take on the appropriate different appearance. .SH -19.2 ORGANISING CONTENT +17.2 ORGANISING CONTENT .SH -20. HOMEPAGES +18. HOMEPAGES .BR .BR @@ -2845,7 +2799,7 @@ subject. Each directory can/should have its own homepage. See the section on directory structure and organisation of content. .SH -20.1 HOME PAGE AND OTHER CUSTOM BUILT PAGES IN A SUB\-DIRECTORY +18.1 HOME PAGE AND OTHER CUSTOM BUILT PAGES IN A SUB\-DIRECTORY .BR Custom built pages, including the home page index.html may be placed within the @@ -2857,7 +2811,7 @@ they are copied to the root of the output directory with the command: sisu \-CC .SH -20.2 HOME PAGE WITHIN A SKIN +18.2 HOME PAGE WITHIN A SKIN .BR Skins are described in a separate section, but basically are a file written in @@ -2890,11 +2844,11 @@ skin_poems.rb .fi .SH -21. MARKUP AND OUTPUT EXAMPLES +19. MARKUP AND OUTPUT EXAMPLES .BR .SH -21.1 MARKUP EXAMPLES +19.1 MARKUP EXAMPLES .BR Current markup examples and document output samples are provided at @@ -2910,7 +2864,7 @@ header, and an indication that the levels to be taken into account by the program in generating its output are. .SH -22. SISU SEARCH \- INTRODUCTION +20. SISU SEARCH \- INTRODUCTION .BR .BR @@ -2936,16 +2890,16 @@ each document, which can be viewed within the database directly or in various output formats. .SH -23. SQL +21. SQL .BR .SH -23.1 POPULATING SQL TYPE DATABASES +21.1 POPULATING SQL TYPE DATABASES .BR .B SiSU -feeds sisu markupd documents into sql type databases PostgreSQL[^24] and/or -SQLite[^25] database together with information related to document structure. +feeds sisu markupd documents into sql type databases PostgreSQL[^18] and/or +SQLite[^19] database together with information related to document structure. .BR This is one of the more interesting output forms, as all the structural data of @@ -3002,11 +2956,11 @@ headings etc. (as the Dublin Core is incorporated it is easy to make use of that as well). .SH -24. POSTGRESQL +22. POSTGRESQL .BR .SH -24.1 NAME +22.1 NAME .BR .B SiSU @@ -3014,7 +2968,7 @@ that as well). postgresql dependency package .SH -24.2 DESCRIPTION +22.2 DESCRIPTION .BR Information related to using postgresql with sisu (and related to the @@ -3026,7 +2980,7 @@ to populate a postgresql database, this being part of \- man sisu). .SH -24.3 SYNOPSIS +22.3 SYNOPSIS .BR sisu \-D \ [instruction] \ [filename/wildcard \ if \ required] @@ -3035,7 +2989,7 @@ to populate a postgresql database, this being part of sisu \-D \-\-pg \-\-[instruction] \ [filename/wildcard \ if \ required] .SH -24.4 COMMANDS +22.4 COMMANDS .BR Mappings to two databases are provided by default, postgresql and sqlite, the @@ -3048,7 +3002,7 @@ alternatively \-\-sqlite or \-\-pgsql may be used may be used interchangeably. .SH -24.4.1 CREATE AND DESTROY DATABASE +22.4.1 CREATE AND DESTROY DATABASE .TP .B \ \-\-pgsql \ \-\-createall @@ -3078,7 +3032,7 @@ given \ directory \ (and \ directories \ of \ the \ same \ name). \ \ structure \ .SH -24.4.2 IMPORT AND REMOVE DOCUMENTS +22.4.2 IMPORT AND REMOVE DOCUMENTS .TP .B \ sisu \ \-D \ \-\-import \ \-v \ \ [filename/wildcard] @@ -3094,18 +3048,18 @@ updates file contents in database removes specified document from postgresql database. .SH -25. SQLITE +23. SQLITE .BR .SH -25.1 NAME +23.1 NAME .BR .B SiSU \- Structured information, Serialized Units \- a document publishing system. .SH -25.2 DESCRIPTION +23.2 DESCRIPTION .BR Information related to using sqlite with sisu (and related to the sisu_sqlite @@ -3116,7 +3070,7 @@ to populate an sqlite database, this being part of \- man sisu). .SH -25.3 SYNOPSIS +23.3 SYNOPSIS .BR sisu \-d \ [instruction] \ [filename/wildcard \ if \ required] @@ -3126,7 +3080,7 @@ to populate an sqlite database, this being part of required] .SH -25.4 COMMANDS +23.4 COMMANDS .BR Mappings to two databases are provided by default, postgresql and sqlite, the @@ -3139,7 +3093,7 @@ alternatively \-\-sqlite or \-\-pgsql may be used may be used interchangeably. .SH -25.4.1 CREATE AND DESTROY DATABASE +23.4.1 CREATE AND DESTROY DATABASE .TP .B \ \-\-sqlite \ \-\-createall @@ -3169,7 +3123,7 @@ given \ directory \ (and \ directories \ of \ the \ same \ name). \ \ structure \ .SH -25.4.2 IMPORT AND REMOVE DOCUMENTS +23.4.2 IMPORT AND REMOVE DOCUMENTS .TP .B \ sisu \ \-d \ \-\-import \ \-v \ \ [filename/wildcard] @@ -3185,18 +3139,18 @@ updates file contents in database removes specified document from sqlite database. .SH -26. INTRODUCTION +24. INTRODUCTION .BR .SH -26.1 SEARCH \- DATABASE FRONTEND SAMPLE, UTILISING DATABASE AND SISU FEATURES, +24.1 SEARCH \- DATABASE FRONTEND SAMPLE, UTILISING DATABASE AND SISU FEATURES, INCLUDING OBJECT CITATION NUMBERING (BACKEND CURRENTLY POSTGRESQL) .BR -Sample search frontend \ [^26] A small database and +Sample search frontend \ [^20] A small database and sample query front\-end (search from) that makes use of the citation system, .I object citation numbering -to demonstrates functionality.[^27] +to demonstrates functionality.[^21] .BR .B SiSU @@ -3211,7 +3165,7 @@ in the documents matched. Note you may set results either for documents matched and object number locations within each matched document meeting the search criteria; or display the names of the documents matched along with the objects (paragraphs) that -meet the search criteria.[^28] +meet the search criteria.[^22] .TP .B \ sisu \ \-F \ \-\-webserv\-webrick @@ -3249,7 +3203,7 @@ is used. \ [otherwise \ a \ manual \ mapping \ for \ the \ collection \ is \ necessary] .SH -26.2 SEARCH FORM +24.2 SEARCH FORM .TP .B \ sisu \ \-F @@ -3277,7 +3231,7 @@ The generated search form must be copied manually to the webserver directory as instructed .SH -27. HYPERESTRAIER +25. HYPERESTRAIER .BR .BR @@ -3397,18 +3351,18 @@ rune along the following lines: and try open the url: .SH -28. SISU_WEBRICK +26. SISU_WEBRICK .BR .SH -28.1 NAME +26.1 NAME .BR .B SiSU \- Structured information, Serialized Units \- a document publishing system .SH -28.2 SYNOPSIS +26.2 SYNOPSIS .BR sisu_webrick \ [port] @@ -3420,7 +3374,7 @@ or sisu \-W \ [port] .SH -28.3 DESCRIPTION +26.3 DESCRIPTION .BR sisu_webrick is part of @@ -3439,7 +3393,7 @@ yaml file: ~/.sisu/sisurc.yml a sample of which is provided as /etc/sisu/sisurc.yml (or in the equivalent directory on your system). .SH -28.4 SUMMARY OF MAN PAGE +26.4 SUMMARY OF MAN PAGE .BR sisu_webrick, may be started on it\'s own with the command: sisu_webrick \ @@ -3449,7 +3403,7 @@ sisu_webrick, may be started on it\'s own with the command: sisu_webrick \ where no port is given and settings are unchanged the default port is 8081 .SH -28.5 DOCUMENT PROCESSING COMMAND FLAGS +26.5 DOCUMENT PROCESSING COMMAND FLAGS .BR sisu \-W \ [port] starts @@ -3460,7 +3414,7 @@ output directories, on the port provided, or if no port is provided and the defaults have not been changed in ~/.sisu/sisurc.yaml then on port 8081 .SH -28.6 FURTHER INFORMATION +26.6 FURTHER INFORMATION .BR For more information on @@ -3471,13 +3425,13 @@ see: or man sisu .SH -28.7 AUTHOR +26.7 AUTHOR .BR Ralph Amissah ralph@amissah.com or ralph.amissah@gmail.com .SH -28.8 SEE ALSO +26.8 SEE ALSO .BR sisu(1) @@ -3489,7 +3443,7 @@ Ralph Amissah ralph@amissah.com or ralph.amissah@gmail.com sisu(8) .SH -29. REMOTE SOURCE DOCUMENTS +27. REMOTE SOURCE DOCUMENTS .BR .BR @@ -3554,7 +3508,7 @@ REMOTE DOCUMENT OUTPUT .BR .SH -30. REMOTE OUTPUT +28. REMOTE OUTPUT .BR .BR @@ -3575,7 +3529,7 @@ may be used in conjunction with other processing flags, e.g. .fi .SH -30.1 COMMANDS +28.1 COMMANDS .TP .B \ \-R \ \ [filename/wildcard] @@ -3593,13 +3547,13 @@ sisurc.yml has been provided with information on hostname and username, and that you have your \"keys\" and ssh agent in place. Also see \-R .SH -30.2 CONFIGURATION +28.2 CONFIGURATION .BR [expand \ on \ the \ setting \ up \ of \ an \ ssh\-agent \ / \ keychain] .SH -31. REMOTE SERVERS +29. REMOTE SERVERS .BR .BR @@ -3613,11 +3567,11 @@ which you are logged on using a terminal, and commands and operations would be pretty much the same as they would be on your local machine. .SH -32. QUICKSTART \- GETTING STARTED HOWTO +30. QUICKSTART \- GETTING STARTED HOWTO .BR .SH -32.1 INSTALLATION +30.1 INSTALLATION .BR Installation is currently most straightforward and tested on the @@ -3626,7 +3580,7 @@ platform, as there are packages for the installation of sisu and all requirements for what it does. .SH -32.1.1 DEBIAN INSTALLATION +30.1.1 DEBIAN INSTALLATION .BR .B SiSU @@ -3692,7 +3646,7 @@ components of sisu are to be used. Installing just the package sisu will provide basic functionality. .SH -32.1.2 RPM INSTALLATION +30.1.2 RPM INSTALLATION .BR RPMs are provided though untested, they are prepared by running alien against @@ -3711,7 +3665,7 @@ as root type: rpm \-i \ [rpm \ package \ name] .SH -32.1.3 INSTALLATION FROM SOURCE +30.1.3 INSTALLATION FROM SOURCE .BR To install @@ -3742,7 +3696,7 @@ is only dependent on the programming language in which it is written will be able to generate html, 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)[^29] or +take care of, for things like using a database (postgresql or sqlite)[^23] or converting LaTeX to pdf. .BR @@ -3820,7 +3774,7 @@ For a list of alternative actions you may type: ruby install \-T .SH -32.2 TESTING SISU, GENERATING OUTPUT +30.2 TESTING SISU, GENERATING OUTPUT .BR To check which version of sisu is installed: @@ -3848,7 +3802,7 @@ change directory to the appropriate one: cd /usr/share/doc/sisu/sisu_markup_samples/dfsg .SH -32.2.1 BASIC TEXT, PLAINTEXT, HTML, XML, ODF +30.2.1 BASIC TEXT, PLAINTEXT, HTML, XML, ODF .BR Having moved to the directory that contains the markup samples (see @@ -3862,7 +3816,7 @@ this will generate html including a concordance file, opendocument text format, plaintext, XHTML and various forms of XML, and OpenDocument text .SH -32.2.2 LATEX / PDF +30.2.2 LATEX / PDF .BR Assuming a LaTeX engine such as tetex or texlive is installed with the required @@ -3886,7 +3840,7 @@ file, opendocument text format, plaintext, XHTML and various forms of XML, and OpenDocument text and pdf .SH -32.2.3 RELATIONAL DATABASE \- POSTGRESQL, SQLITE +30.2.3 RELATIONAL DATABASE \- POSTGRESQL, SQLITE .BR Relational databases need some setting up \- you must have permission to create @@ -3910,10 +3864,10 @@ sisu \-\-pgsql \-v \-\-import free_as_in_freedom.rms_and_free_software.sam_williams.sst .SH -32.3 GETTING HELP +30.3 GETTING HELP .SH -32.3.1 THE MAN PAGES +30.3.1 THE MAN PAGES .BR Type: @@ -3926,16 +3880,16 @@ The man pages are also available online, though not always kept as up to date as within the package itself: .BR -* sisu.1 \ [^30] +* sisu.1 \ [^24] .BR -* sisu.8 \ [^31] +* sisu.8 \ [^25] .BR -* man directory \ [^32] +* man directory \ [^26] .SH -32.3.2 BUILT IN HELP +30.3.2 BUILT IN HELP .BR sisu \-\-help @@ -3950,7 +3904,7 @@ sisu \-\-help \-\-commands sisu \-\-help \-\-markup .SH -32.3.3 THE HOME PAGE +30.3.3 THE HOME PAGE .BR @@ -3959,7 +3913,7 @@ sisu \-\-help \-\-markup .SH -32.4 MARKUP SAMPLES +30.4 MARKUP SAMPLES .BR A number of markup samples (along with output) are available off: @@ -3976,12 +3930,12 @@ Additional markup samples are packaged separately in the file: .BR On .B Debian -they are available in non\-free[^33] to include them it is necessary to +they are available in non\-free[^27] 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 -33. EDITOR FILES, SYNTAX HIGHLIGHTING +31. EDITOR FILES, SYNTAX HIGHLIGHTING .BR .BR @@ -4140,25 +4094,209 @@ comments: assumes dark background; no display line\-wrap files: .BR - package is the most comprehensive sisu syntax highlighting and editor - environment provided to date (is for vim/ gvim, and is separate from the - contents of this directory) + package is the most comprehensive sisu syntax highlighting and editor + environment provided to date (is for vim/ gvim, and is separate from the + contents of this directory) + +.BR + status: this includes: syntax highlighting; vim folds; some error checking + +.BR + comments: this editor features display line wrap + +.BR +NOTE: + +.BR +[ +.B \ SiSU +\ parses \ files \ with \ long \ lines \ or \ line \ breaks, \ but, \ display +\ linewrap \ (without \ line\-breaks) \ is \ a \ convenient \ editor \ feature +\ to \ have \ for \ sisu \ markup] + +.SH +32. HOW DOES SISU WORK? +.BR + +.BR +.B SiSU +markup is fairly minimalistic, it consists of: a (largely optional) document +header, made up of information about the document (such as when it was +published, who authored it, and granting what rights) and any processing +instructions; and markup within the substantive text of the document, which is +related to document structure and typeface. +.B SiSU +must be able to discern the structure of a document, (text headings and their +levels in relation to each other), either from information provided in the +document header or from markup within the text (or from a combination of both). +Processing is done against an abstraction of the document comprising of +information on the document\'s structure and its objects,[2] which the program +serializes (providing the object numbers) and which are assigned hash sum +values based on their content. This abstraction of information about document +structure, objects, (and hash sums), provides considerable flexibility in +representing documents different ways and for different purposes (e.g. search, +document layout, publishing, content certification, concordance etc.), and +makes it possible to take advantage of some of the strengths of established +ways of representing documents, (or indeed to create new ones). + +.SH +33. SUMMARY OF FEATURES +.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, +documents like \"War and Peace\" require almost no markup, and most of the +headers are optional. + +.BR +* markup is easily readable/parsable by the human eye, (basic markup is simpler +and more sparse than the most basic HTML), \ [this \ may \ also \ be \ +converted \ to \ XML \ representations \ of \ the \ same \ input/source \ +document]. + +.BR +* markup defines document structure (this may be done once in a header +pattern\-match description, or for heading levels individually); basic text +attributes (bold, italics, underscore, strike\-through etc.) as required; and +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, xml, +odf, latex, pdf, sql) + +.BR +* for output produces reasonably elegant output of established industry and +institutionally accepted open standard formats.[3] takes advantage of the +different strengths of various standard formats for representing documents, +amongst the output formats currently supported are: + +.BR + * html \- both as a single scrollable text and a segmented document + +.BR + * xhtml + +.BR + * XML \- both in sax and dom style xml structures for further development as + required + +.BR + * ODF \- open document format, the iso standard for document storage + +.BR + * LaTeX \- used to generate pdf + +.BR + * pdf (via LaTeX) + +.BR + * 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 +digests of headings, paragraphs, images etc.) and html manifests (and sitemaps +of content). (b) takes advantage of the strengths implicit in these very +different output types, (e.g. PDFs produced using typesetting of LaTeX, +databases populated with documents at an individual object/paragraph level, +making possible granular search (and related possibilities)) + +.BR +* ensuring content can be cited in a meaningful way regardless of selected +output format. Online publishing (and publishing in multiple document formats) +lacks a useful way of citing text internally within documents (important to +academics generally and to lawyers) as page numbers are meaningless across +browsers and formats. sisu seeks to provide a common way of pinpoint the text +within a document, (which can be utilized for citation and by search engines). +The outputs share a common numbering system that is meaningful (to man and +machine) across all digital outputs whether paper, screen, or database +oriented, (pdf, HTML, xml, sqlite, postgresql), this numbering system can be +used to reference content. + +.BR +* Granular search within documents. SQL databases are populated at an object +level (roughly headings, paragraphs, verse, tables) and become searchable with +that degree of granularity, the output information provides the +object/paragraph numbers which are relevant across all generated outputs; it is +also possible to look at just the matching paragraphs of the documents in the +database; \ [output \ indexing \ also \ work \ well \ with \ search \ indexing +\ tools \ like \ hyperestraier]. + +.BR +* long term maintainability of document collections in a world of changing +formats, having a very sparsely marked\-up source document base. there is a +considerable degree of future\-proofing, output representations are +\"upgradeable\", and new document formats may be added. e.g. addition of odf +(open document text) module in 2006 and in future html5 output sometime in +future, without modification of existing prepared texts + +.BR +* SQL search aside, documents are generated as required and static once +generated. + +.BR +* documents produced are static files, and may be batch processed, this needs +to be done only once but may be repeated for various reasons as desired +(updated content, addition of new output formats, updated technology document +presentations/representations) + +.BR +* document source (plaintext utf\-8) if shared on the net may be used as input +and processed locally to produce the different document outputs + +.BR +* document source may be bundled together (automatically) with associated +documents (multiple language versions or master document with inclusions) and +images and sent as a zip file called a sisupod, if shared on the net these too +may be processed locally to produce the desired document outputs + +.BR +* generated document outputs may automatically be posted to remote sites. + +.BR +* for basic document generation, the only software dependency is +.B Ruby +, and a few standard Unix tools (this covers plaintext, HTML, 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. + +.BR +* as a developers tool it is flexible and extensible .BR - status: this includes: syntax highlighting; vim folds; some error checking +Syntax highlighting for +.B SiSU +markup is available for a number of text editors. .BR - comments: this editor features display line wrap +.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 +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 .BR -NOTE: +i.e. to be able to take advantage from this minimal preparation starting point +of some of the strengths of rather different established ways of representing +documents for different purposes, whether for search (relational database, or +indexed flat files generated for that purpose whether of complete documents, or +say of files made up of objects), online viewing (e.g. html, xml, pdf), or +paper publication (e.g. pdf)... .BR -[ -.B \ SiSU -\ parses \ files \ with \ long \ lines \ or \ line \ breaks, \ but, \ display -\ linewrap \ (without \ line\-breaks) \ is \ a \ convenient \ editor \ feature -\ to \ have \ for \ sisu \ markup] +the solution arrived at is by extracting structural information about the +document (about headings within the document) and by tracking objects (which +are serialized and also given hash values) in the manner described. It makes +possible representations that are quite different from those offered at +present. For example objects could be saved individually and identified by +their hashes, with an index of how the objects relate to each other to form a +document. .SH 34. HELP SOURCES @@ -4226,65 +4364,20 @@ Alternative sources for this help sources page listed here: .BR man sisu -.BR - man sisu_commands - .BR man 7 sisu_complete -.BR - man sisu_configuration - -.BR - man 8 sisu_faq - -.BR - man sisu_filetypes - -.BR - man sisu_help - -.BR - man sisu_help_sources - -.BR - man 8 sisu_howto - -.BR - man sisu_introduction - -.BR - man sisu_markup - -.BR - man sisu_output_overview - .BR man 7 sisu_pdf .BR man 7 sisu_postgresql -.BR - man 8 sisu_quickstart - -.BR - man 8 sisu_remote - -.BR - man 8 sisu_search - -.BR - man sisu_skin - .BR man 7 sisu_sqlite .BR - man 8 sisu_syntax_highlighting - -.BR - man 7 sisu_vim + man sisu_termsheet .BR man sisu_webrick @@ -4298,7 +4391,7 @@ Note documentation is prepared in .B SiSU and output is available in multiple formats including amongst others html, -pdf, and odf which may be also be accessed via the html pages[^34] +pdf, and odf which may be also be accessed via the html pages[^28] .SH 34.2.1 LOCALLY INSTALLED @@ -4315,74 +4408,20 @@ pdf, and odf which may be also be accessed via the html pages[^34] .BR /usr/share/doc/sisu/sisu_manual/sisu/index.html -.BR - /usr/share/doc/sisu/sisu_manual/sisu_commands/index.html - .BR /usr/share/doc/sisu/sisu_manual/sisu_complete/index.html -.BR - /usr/share/doc/sisu/sisu_manual/sisu_configuration/index.html - -.BR - /usr/share/doc/sisu/sisu_manual/sisu_description/index.html - -.BR - /usr/share/doc/sisu/sisu_manual/sisu_examples/index.html - -.BR - /usr/share/doc/sisu/sisu_manual/sisu_faq/index.html - -.BR - /usr/share/doc/sisu/sisu_manual/sisu_filetypes/index.html - -.BR - /usr/share/doc/sisu/sisu_manual/sisu_help/index.html - -.BR - /usr/share/doc/sisu/sisu_manual/sisu_help_sources/index.html - -.BR - /usr/share/doc/sisu/sisu_manual/sisu_howto/index.html - -.BR - /usr/share/doc/sisu/sisu_manual/sisu_introduction/index.html - -.BR - /usr/share/doc/sisu/sisu_manual/sisu_manual/index.html - -.BR - /usr/share/doc/sisu/sisu_manual/sisu_markup/index.html - -.BR - /usr/share/doc/sisu/sisu_manual/sisu_output_overview/index.html - .BR /usr/share/doc/sisu/sisu_manual/sisu_pdf/index.html .BR /usr/share/doc/sisu/sisu_manual/sisu_postgresql/index.html -.BR - /usr/share/doc/sisu/sisu_manual/sisu_quickstart/index.html - -.BR - /usr/share/doc/sisu/sisu_manual/sisu_remote/index.html - -.BR - /usr/share/doc/sisu/sisu_manual/sisu_search/index.html - -.BR - /usr/share/doc/sisu/sisu_manual/sisu_skin/index.html - .BR /usr/share/doc/sisu/sisu_manual/sisu_sqlite/index.html .BR - /usr/share/doc/sisu/sisu_manual/sisu_syntax_highlighting/index.html - -.BR - /usr/share/doc/sisu/sisu_manual/sisu_vim/index.html + /usr/share/doc/sisu/sisu_manual/sisu_termsheet/index.html .BR /usr/share/doc/sisu/sisu_manual/sisu_webrick/index.html @@ -4550,13 +4589,13 @@ pdf, and odf which may be also be accessed via the html pages[^34] .SH -34.2.4 MAN2HTML +34.3 MAN2HTML .SH -34.2.5 LOCALLY INSTALLED +34.3.1 LOCALLY INSTALLED .BR - + .BR @@ -4567,62 +4606,20 @@ pdf, and odf which may be also be accessed via the html pages[^34] .BR /usr/share/doc/sisu/html/sisu.1.html -.BR - /usr/share/doc/sisu/html/sisu_commands.1.html - -.BR - /usr/share/doc/sisu/html/sisu_complete.7.html - -.BR - /usr/share/doc/sisu/html/sisu_configuration.1.html - -.BR - /usr/share/doc/sisu/html/sisu_faq.8.html - -.BR - /usr/share/doc/sisu/html/sisu_help.1.html - -.BR - /usr/share/doc/sisu/html/sisu_help_sources.1.html - -.BR - /usr/share/doc/sisu/html/sisu_howto.8.html - -.BR - /usr/share/doc/sisu/html/sisu_markup.1.html - .BR /usr/share/doc/sisu/html/sisu_pdf.7.html .BR /usr/share/doc/sisu/html/sisu_postgresql.7.html -.BR - /usr/share/doc/sisu/html/sisu_quickstart.8.html - -.BR - /usr/share/doc/sisu/html/sisu_remote.8.html - -.BR - /usr/share/doc/sisu/html/sisu_search.8.html - -.BR - /usr/share/doc/sisu/html/sisu_skin.1.html - .BR /usr/share/doc/sisu/html/sisu_sqlite.7.html -.BR - /usr/share/doc/sisu/html/sisu_syntax_highlighting.8.html - -.BR - /usr/share/doc/sisu/html/sisu_vim.7.html - .BR /usr/share/doc/sisu/html/sisu_webrick.1.html .SH -34.2.6 WWW.SISUDOC.ORG +34.3.2 WWW.SISUDOC.ORG .BR @@ -4636,65 +4633,26 @@ pdf, and odf which may be also be accessed via the html pages[^34] .BR -.BR - - .BR -.BR - - -.BR - - -.BR - - -.BR - - -.BR - - -.BR - - .BR .BR -.BR - - -.BR - - -.BR - - -.BR - - .BR -.BR - - -.BR - - .BR .SH -34.2.7 WWW.JUS.UIO.NO/SISU +34.3.3 WWW.JUS.UIO.NO/SISU .BR - + .BR @@ -4705,57 +4663,18 @@ pdf, and odf which may be also be accessed via the html pages[^34] .BR -.BR - - .BR -.BR - - -.BR - - -.BR - - -.BR - - -.BR - - -.BR - - .BR .BR -.BR - - -.BR - - -.BR - - -.BR - - .BR -.BR - - -.BR - - .BR @@ -4768,8 +4687,7 @@ METADATA .BR .BR -Document Manifest @ - +Document Manifest @ .BR .B Dublin Core @@ -4809,11 +4727,11 @@ DC Date available: .BR DC Date modified: -.I 2007\-08\-30 +.I 2007\-09\-29 .BR DC Date: -.I 2007\-08\-30 +.I 2007\-09\-29 .BR .B Version Information @@ -4828,11 +4746,11 @@ Filetype: .BR Sourcefile Digest, MD5(sisu._sst)= -.I 104416276094558eeb6bd0320281ae0d +.I 5f973d9b8e96b9f3fabc280e9d0a18e0 .BR Skin_Digest: -MD5(/home/ralph/grotto/theatre/dbld/builds/sisu/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= .I 20fc43cf3eb6590bc3399a1aef65c5a9 .BR @@ -4840,7 +4758,7 @@ MD5(/home/ralph/grotto/theatre/dbld/builds/sisu/sisu/data/doc/sisu/sisu_markup_s .BR Document (metaverse) last generated: -.I Tue Sep 25 02:54:41 +0100 2007 +.I Sat Sep 29 15:46:29 +0100 2007 .BR Generated by: @@ -4854,63 +4772,30 @@ Ruby version: .TP .BI 1. -\" \.B SiSU -information Structuring Universe\" or \"Structured information, Serialized -Units\". - also chosen for the meaning of the Finnish term "sisu". -.TP -.BI 2. -Unix command line oriented -.TP -.BI 3. 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. .TP -.BI 4. +.BI 2. i.e. the html, pdf, 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. .TP -.BI 5. +.BI 3. the different heading levels .TP -.BI 6. +.BI 4. units of text, primarily paragraphs and headings, also any tables, poems, code-blocks .TP -.BI 7. +.BI 5. Specification submitted by Adobe to ISO to become a full open ISO specification .TP -.BI 8. +.BI 6. ISO/IEC 26300:2006 .TP -.BI 9. -generated from source using rman - - With regard to -.B SiSU -man pages the formatting generated for markup syntax is not quite right, for -that you might prefer the links under: - -.TP -.BI 10. - -.TP -.BI 11. - -.TP -.BI 12. - -.TP -.BI 13. - -.TP -.BI 14. - -.TP .BI *1. square brackets .TP @@ -4920,17 +4805,23 @@ square brackets .BI +1. square brackets .TP -.BI 15. +.BI 7. + +.TP +.BI 8. + +.TP +.BI 9. 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 16. +.BI 10. files should be prepared using UTF-8 character encoding .TP -.BI 17. +.BI 11. a footnote or endnote .TP -.BI 18. +.BI 12. self contained endnote marker & endnote in one .TP .BI *. @@ -4945,47 +4836,47 @@ editors notes, numbered asterisk footnote/endnote series .BI +2. editors notes, numbered asterisk footnote/endnote series .TP -.BI 19. +.BI 13. .TP -.BI 20. +.BI 14. .TP -.BI 21. +.BI 15. Table from the Wealth of Networks by Yochai Benkler .TP -.BI 22. +.BI 16. \.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 23. +.BI 17. \.B SiSU has worked this way in the past, though this was dropped as it was thought the complexity outweighed the flexibility, however, the balance was rather fine and this behaviour could be reinstated. .TP -.BI 24. +.BI 18. .TP -.BI 25. +.BI 19. .TP -.BI 26. +.BI 20. .TP -.BI 27. +.BI 21. (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 28. +.BI 22. 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 @@ -4993,25 +4884,25 @@ and we can tell you which documents meet your search criteria, but there is no way we can tell you without opening each document where within each your matches are found. .TP -.BI 29. +.BI 23. There is nothing to stop MySQL support being added in future. .TP -.BI 30. +.BI 24. .TP -.BI 31. +.BI 25. .TP -.BI 32. +.BI 26. .TP -.BI 33. +.BI 27. the \.B Debian Free Software guidelines require that everything distributed within \.B Debian can be changed - and the documents are authors\' works that while freely distributable are not freely changeable. .TP -.BI 34. +.BI 28. named index.html or more extensively through sisu_manifest.html .TP @@ -5034,6 +4925,6 @@ at: .TP * Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] .TP -* Last Generated on: Tue Sep 25 02:54:48 +0100 2007 +* Last Generated on: Sat Sep 29 15:46:29 +0100 2007 .TP * SiSU http://www.jus.uio.no/sisu diff --git a/man/man1/sisu_webrick.1 b/man/man1/sisu_webrick.1 index 6d8cc219..a1677f1c 100644 --- a/man/man1/sisu_webrick.1 +++ b/man/man1/sisu_webrick.1 @@ -1,4 +1,8 @@ .TH "sisu_webrick" "1" "2007-09-16" "0.59.1" "SiSU" +.SH NAME +sisu \- documents: structuring, publishing in multiple formats, and search +.SH SYNOPSIS +sisu \-W .SH SISU \- SISU_WEBRICK, RALPH AMISSAH @@ -110,7 +114,7 @@ METADATA .BR Document Manifest @ - + .BR .B Dublin Core @@ -169,7 +173,7 @@ Filetype: .BR Sourcefile Digest, MD5(sisu_webrick.sst)= -.I 3d9a36a867ddc771d75083c5a7eea2bc +.I 11fb0494766a9b6d3ce091bf41241973 .BR Skin_Digest: MD5(/etc/sisu/skin/doc/skin_sisu.rb)= @@ -180,7 +184,7 @@ Skin_Digest: MD5(/etc/sisu/skin/doc/skin_sisu.rb)= .BR Document (metaverse) last generated: -.I Tue Sep 25 02:54:44 +0100 2007 +.I Sat Sep 29 15:49:36 +0100 2007 .BR Generated by: @@ -213,6 +217,6 @@ at: .TP * Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] .TP -* Last Generated on: Tue Sep 25 02:54:51 +0100 2007 +* Last Generated on: Sat Sep 29 15:49:36 +0100 2007 .TP * SiSU http://www.jus.uio.no/sisu -- cgit v1.2.3