From 268a9c5cea06f2c0b999039d76dc5c33d7e304bf Mon Sep 17 00:00:00 2001 From: Ralph Amissah Date: Sat, 8 Feb 2014 23:42:22 -0500 Subject: documentation, minor update --- man/man1/sisu.1 | 167 ++++++++++++++++++++++++++++---------------------------- 1 file changed, 84 insertions(+), 83 deletions(-) (limited to 'man') diff --git a/man/man1/sisu.1 b/man/man1/sisu.1 index f6bb6b5b..478f1f6f 100644 --- a/man/man1/sisu.1 +++ b/man/man1/sisu.1 @@ -1,4 +1,4 @@ -.TH "sisu" "1" "2014-02-05" "6.0.1" "SiSU" +.TH "sisu" "1" "2014-02-05" "6.0.3" "SiSU" .br .SH NAME .br @@ -913,16 +913,15 @@ Available man pages are converted back to html using man2html: An online version of the sisu man page is available here: .BR -* various sisu man pages [^9] +* various sisu man pages [^1] .BR -* sisu.1 [^10] - +* sisu.1 [^2] .SH SISU BUILT-IN INTERACTIVE HELP, [DISCONTINUED] .BR This fell out of date and has been discontinued. -.SH INTRODUCTION TO SISU MARKUP[^11] +.SH INTRODUCTION TO SISU MARKUP[^3] .SH SUMMARY @@ -932,7 +931,7 @@ source documents are .I plaintext ( .I UTF-8 -)[^12] files +)[^4] files .BR All paragraphs are separated by an empty line. @@ -1473,7 +1472,7 @@ determines whether footnotes or endnotes will be produced .B resulting output: .BR -[^13] +[^5] .BR .B markup example: @@ -1485,7 +1484,7 @@ normal text~{ self contained endnote marker & endnote in one }~ continues .B resulting output: .BR -normal text[^14] continues +normal text[^6] continues .BR .B markup example: @@ -1620,7 +1619,7 @@ about {~^ SiSU }http://url.org markup .B resulting output: .BR -aboutSiSU [^15] markup +aboutSiSU [^7] markup .BR Internal document links to a tagged location, including an ocn @@ -1684,7 +1683,7 @@ GnuDebianLinuxRubyBetterWay.png 100x101 "Way Better - with Gnu/Linux, Debian and Ruby" .BR -ruby_logo.png 70x90 "Ruby" [^16] +ruby_logo.png 70x90 "Ruby" [^8] .BR .B linked url footnote shortcut @@ -1769,7 +1768,7 @@ information in each column .BR .B markup example: -[^18] +[^10] .nf !_ Table 3.1: Contributors to Wikipedia, January 2001 - June 2005 @@ -2404,7 +2403,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 [^19] +with the same prefix and the suffix ._sst [^11] .SH SISU INSERT FILES (.SSI) .BR @@ -2594,7 +2593,7 @@ 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.[^20] +name in directory _sisu/css directory or equivalent.[^12] .SH ORGANISING CONTENT - DIRECTORY STRUCTURE AND MAPPING @@ -3067,9 +3066,9 @@ output formats. .B SiSU feeds sisu markupd documents into sql type databases .I PostgreSQL -[^21] and/or +[^13] and/or .I SQLite -[^22] database together with information related to document structure. +[^14] database together with information related to document structure. .BR This is one of the more interesting output forms, as all the structural data of @@ -3290,14 +3289,63 @@ removes specified document from sqlite database. .SH INTRODUCTION +.SH SETUP SEARCH FORM + + +.BR +You will need a web server, httpd with cgi enabled, and a postgresql database +to which you are able to create databases. + +.BR +Setup postgresql, make sure you are able to create and write to the database, +e.g.: +.nf +sudo su postgres + createuser -d -a ralph +.fi + + +.BR +You then need to create the database that sisu will use, for sisu manual in the +directory manual/en for example, (when you try to populate a database that does +not exist sisu prompts as to whether it exists): +.nf +createdb SiSUv6a_manual +.fi + + +.BR + +.B SiSU +is then able to create the required tables that allow you to populate the +database with documents in the directory for which it has been created: +.nf +sisu --pg --createall -v +.fi + + +.BR +You can then start to populate the database, in this example with a single +document: +.nf +sisu --pg --update -v en/sisu_manual.ssm +.fi + + +.BR +To create a sample search form, from within the same directory run: + +.BR +A sample setup for nginx is provided that assumes data will be stored under +/srv/www and cgi scripts under /srv/cgi .SH SEARCH - DATABASE FRONTEND SAMPLE, UTILISING DATABASE AND SISU FEATURES, INCLUDING OBJECT CITATION NUMBERING (BACKEND CURRENTLY POSTGRESQL) .BR -Sample search frontend [^23] A small database and -sample query front-end (search from) that makes use of the citation system, -.I object citation numbering -to demonstrates functionality.[^24] +Sample search frontend [^15] A small database and +sample query front-end (search from) that makes use of the citation system, .I +object citation numbering +to demonstrates functionality.[^16] .BR .B SiSU @@ -3321,7 +3369,7 @@ 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.[^25] +meet the search criteria.[^17] .TP .B sisu -F --webserv-webrick @@ -3626,53 +3674,6 @@ 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. - -.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 -.TP -.BI 2. -i.e. the HTML, PDF, EPUB, ODT 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 -.TP -.BI 3. -the different heading levels - -.BR -.TP -.BI 4. -units of text, primarily paragraphs and headings, also any tables, poems, -code-blocks - -.BR -.TP -.BI 5. -An open standard format for e-books - -.BR -.TP -.BI 6. -Open Document Format ( ODF ) text - -.BR -.TP -.BI 7. -Specification submitted by Adobe to ISO to become a full open ISO -specification - -.BR -.TP -.BI 8. -ISO standard ISO/IEC 26300:2006 - -.BR .TP .BI *1. square brackets @@ -3689,33 +3690,33 @@ square brackets .BR .TP -.BI 9. +.BI 1. .BR .TP -.BI 10. +.BI 2. .BR .TP -.BI 11. +.BI 3. 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 .TP -.BI 12. +.BI 4. files should be prepared using UTF-8 character encoding .BR .TP -.BI 13. +.BI 5. a footnote or endnote .BR .TP -.BI 14. +.BI 6. self contained endnote marker & endnote in one .BR @@ -3740,23 +3741,23 @@ editors notes, numbered plus symbol footnote/endnote series .BR .TP -.BI 15. +.BI 7. .BR .TP -.BI 16. +.BI 8. .BR .TP -.BI 18. +.BI 10. Table from the Wealth of Networks by Yochai Benkler .BR .TP -.BI 19. +.BI 11. \.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 @@ -3765,37 +3766,37 @@ appropriate suffix to use. .BR .TP -.BI 20. +.BI 12. 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. .BR .TP -.BI 21. +.BI 13. .BR .TP -.BI 22. +.BI 14. .BR .TP -.BI 23. +.BI 15. .BR .TP -.BI 24. +.BI 16. (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 .TP -.BI 25. +.BI 17. 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 -- cgit v1.2.3