aboutsummaryrefslogtreecommitdiffhomepage
path: root/data/doc/manuals_generated/sisu_manual/man/sisu_search.1
diff options
context:
space:
mode:
authorRalph Amissah <ralph@amissah.com>2007-09-24 15:43:13 +0100
committerRalph Amissah <ralph@amissah.com>2007-09-24 15:43:46 +0100
commita6d72d829e5fda70528759c6de8dc3e141278fb4 (patch)
treeea12a53041d4cb69be0aad3dc0af7bf827efbcd6 /data/doc/manuals_generated/sisu_manual/man/sisu_search.1
parentchangelog update (diff)
documentation regenerated, large diff
Diffstat (limited to 'data/doc/manuals_generated/sisu_manual/man/sisu_search.1')
-rw-r--r--data/doc/manuals_generated/sisu_manual/man/sisu_search.1639
1 files changed, 0 insertions, 639 deletions
diff --git a/data/doc/manuals_generated/sisu_manual/man/sisu_search.1 b/data/doc/manuals_generated/sisu_manual/man/sisu_search.1
deleted file mode 100644
index a052ee34..00000000
--- a/data/doc/manuals_generated/sisu_manual/man/sisu_search.1
+++ /dev/null
@@ -1,639 +0,0 @@
-.TH "sisu_search" "1" "2007-09-16" "0.59.0" "SiSU - SiSU information Structuring Universe"
-.SH
-SISU \- SISU INFORMATION STRUCTURING UNIVERSE \- SEARCH \ [0.58],
-RALPH AMISSAH
-.BR
-
-.SH
-SISU SEARCH
-.BR
-
-.SH
-1. SISU SEARCH \- INTRODUCTION
-.BR
-
-.BR
-.B SiSU
-output can easily and conveniently be indexed by a number of standalone
-indexing tools, such as Lucene, Hyperestraier.
-
-.BR
-Because the document structure of sites created is clearly defined, and the
-text object citation system is available hypothetically at least, for all forms
-of output, it is possible to search the sql database, and either read results
-from that database, or just as simply map the results to the html output, which
-has richer text markup.
-
-.BR
-In addition to this
-.B SiSU
-has the ability to populate a relational sql type database with documents at
-an object level, with objects numbers that are shared across different output
-types, which make them searchable with that degree of granularity. Basically,
-your match criteria is met by these documents and at these locations within
-each document, which can be viewed within the database directly or in various
-output formats.
-
-.SH
-2. SQL
-.BR
-
-.SH
-2.1 POPULATING SQL TYPE DATABASES
-
-.BR
-.B SiSU
-feeds sisu markupd documents into sql type databases PostgreSQL[^1] and/or
-SQLite[^2] database together with information related to document structure.
-
-.BR
-This is one of the more interesting output forms, as all the structural data of
-the documents are retained (though can be ignored by the user of the database
-should they so choose). All site texts/documents are (currently) streamed to
-four tables:
-
-.BR
- * one containing semantic (and other) headers, including, title, author,
- subject, (the Dublin Core...);
-
-.BR
- * another the substantive texts by individual \"paragraph\" (or object) \-
- along with structural information, each paragraph being identifiable by its
- paragraph number (if it has one which almost all of them do), and the
- substantive text of each paragraph quite naturally being searchable (both in
- formatted and clean text versions for searching); and
-
-.BR
- * a third containing endnotes cross\-referenced back to the paragraph from
- which they are referenced (both in formatted and clean text versions for
- searching).
-
-.BR
- * a fourth table with a one to one relation with the headers table contains
- full text versions of output, eg. pdf, html, xml, and ascii.
-
-.BR
-There is of course the possibility to add further structures.
-
-.BR
-At this level
-.B SiSU
-loads a relational database with documents chunked into objects, their
-smallest logical structurally constituent parts, as text objects, with their
-object citation number and all other structural information needed to construct
-the document. Text is stored (at this text object level) with and without
-elementary markup tagging, the stripped version being so as to facilitate ease
-of searching.
-
-.BR
-Being able to search a relational database at an object level with the
-.B SiSU
-citation system is an effective way of locating content generated by
-.B SiSU
-. As individual text objects of a document stored (and indexed) together with
-object numbers, and all versions of the document have the same numbering,
-complex searches can be tailored to return just the locations of the search
-results relevant for all available output formats, with live links to the
-precise locations in the database or in html/xml documents; or, the structural
-information provided makes it possible to search the full contents of the
-database and have headings in which search content appears, or to search only
-headings etc. (as the Dublin Core is incorporated it is easy to make use of
-that as well).
-
-.SH
-3. POSTGRESQL
-.BR
-
-.SH
-3.1 NAME
-
-.BR
-.B SiSU
-\- Structured information, Serialized Units \- a document publishing system,
-postgresql dependency package
-
-.SH
-3.2 DESCRIPTION
-
-.BR
-Information related to using postgresql with sisu (and related to the
-sisu_postgresql dependency package, which is a dummy package to install
-dependencies needed for
-.B SiSU
-to populate a postgresql database, this being part of
-.B SiSU
-\- man sisu).
-
-.SH
-3.3 SYNOPSIS
-
-.BR
- sisu \-D \ [instruction] \ [filename/wildcard \ if \ required]
-
-.BR
- sisu \-D \-\-pg \-\-[instruction] \ [filename/wildcard \ if \ required]
-
-.SH
-3.4 COMMANDS
-
-.BR
-Mappings to two databases are provided by default, postgresql and sqlite, the
-same commands are used within sisu to construct and populate databases however
-\-d (lowercase) denotes sqlite and \-D (uppercase) denotes postgresql,
-alternatively \-\-sqlite or \-\-pgsql may be used
-
-.BR
-.B \-D or \-\-pgsql
-may be used interchangeably.
-
-.SH
-3.4.1 CREATE AND DESTROY DATABASE
-
-.TP
-.B \ \-\-pgsql \ \-\-createall
-\ initial \ step, \ creates \ required \ relations \ (tables, \ indexes) \ in
-\ existing \ (postgresql) \ database \ (a \ database \ should \ be \ created \
-manually \ and \ given \ the \ same \ name \ as \ working \ directory, \ as \
-requested) \ (rb.dbi) \
-
-.TP
-.B \ sisu \ \-D \ \-\-createdb
-\ creates \ database \ where \ no \ database \ existed \ before \
-
-.TP
-.B \ sisu \ \-D \ \-\-create
-\ creates \ database \ tables \ where \ no \ database \ tables \ existed \
-before \
-
-.TP
-.B \ sisu \ \-D \ \-\-Dropall
-\ destroys \ database \ (including \ all \ its \ content)! \ kills \ data \
-and \ drops \ tables, \ indexes \ and \ database \ associated \ with \ a \
-given \ directory \ (and \ directories \ of \ the \ same \ name). \
-
-.TP
-.B \ sisu \ \-D \ \-\-recreate
-\ destroys \ existing \ database \ and \ builds \ a \ new \ empty \ database
-\ structure \
-
-.SH
-3.4.2 IMPORT AND REMOVE DOCUMENTS
-
-.TP
-.B \ sisu \ \-D \ \-\-import \ \-v \ \ [filename/wildcard]
-populates database with the contents of the file. Imports documents(s)
-specified to a postgresql database (at an object level).
-
-.TP
-.B \ sisu \ \-D \ \-\-update \ \-v \ \ [filename/wildcard]
-updates file contents in database
-
-.TP
-.B \ sisu \ \-D \ \-\-remove \ \-v \ \ [filename/wildcard]
-removes specified document from postgresql database.
-
-.SH
-4. SQLITE
-.BR
-
-.SH
-4.1 NAME
-
-.BR
-.B SiSU
-\- Structured information, Serialized Units \- a document publishing system.
-
-.SH
-4.2 DESCRIPTION
-
-.BR
-Information related to using sqlite with sisu (and related to the sisu_sqlite
-dependency package, which is a dummy package to install dependencies needed for
-.B SiSU
-to populate an sqlite database, this being part of
-.B SiSU
-\- man sisu).
-
-.SH
-4.3 SYNOPSIS
-
-.BR
- sisu \-d \ [instruction] \ [filename/wildcard \ if \ required]
-
-.BR
- sisu \-d \-\-(sqlite|pg) \-\-[instruction] \ [filename/wildcard \ if \
- required]
-
-.SH
-4.4 COMMANDS
-
-.BR
-Mappings to two databases are provided by default, postgresql and sqlite, the
-same commands are used within sisu to construct and populate databases however
-\-d (lowercase) denotes sqlite and \-D (uppercase) denotes postgresql,
-alternatively \-\-sqlite or \-\-pgsql may be used
-
-.BR
-.B \-d or \-\-sqlite
-may be used interchangeably.
-
-.SH
-4.4.1 CREATE AND DESTROY DATABASE
-
-.TP
-.B \ \-\-sqlite \ \-\-createall
-\ initial \ step, \ creates \ required \ relations \ (tables, \ indexes) \ in
-\ existing \ (sqlite) \ database \ (a \ database \ should \ be \ created \
-manually \ and \ given \ the \ same \ name \ as \ working \ directory, \ as \
-requested) \ (rb.dbi) \
-
-.TP
-.B \ sisu \ \-d \ \-\-createdb
-\ creates \ database \ where \ no \ database \ existed \ before \
-
-.TP
-.B \ sisu \ \-d \ \-\-create
-\ creates \ database \ tables \ where \ no \ database \ tables \ existed \
-before \
-
-.TP
-.B \ sisu \ \-d \ \-\-dropall
-\ destroys \ database \ (including \ all \ its \ content)! \ kills \ data \
-and \ drops \ tables, \ indexes \ and \ database \ associated \ with \ a \
-given \ directory \ (and \ directories \ of \ the \ same \ name). \
-
-.TP
-.B \ sisu \ \-d \ \-\-recreate
-\ destroys \ existing \ database \ and \ builds \ a \ new \ empty \ database
-\ structure \
-
-.SH
-4.4.2 IMPORT AND REMOVE DOCUMENTS
-
-.TP
-.B \ sisu \ \-d \ \-\-import \ \-v \ \ [filename/wildcard]
-populates database with the contents of the file. Imports documents(s)
-specified to an sqlite database (at an object level).
-
-.TP
-.B \ sisu \ \-d \ \-\-update \ \-v \ \ [filename/wildcard]
-updates file contents in database
-
-.TP
-.B \ sisu \ \-d \ \-\-remove \ \-v \ \ [filename/wildcard]
-removes specified document from sqlite database.
-
-.SH
-5. INTRODUCTION
-.BR
-
-.SH
-5.1 SEARCH \- DATABASE FRONTEND SAMPLE, UTILISING DATABASE AND SISU FEATURES,
-INCLUDING OBJECT CITATION NUMBERING (BACKEND CURRENTLY POSTGRESQL)
-
-.BR
-Sample search frontend <http://search.sisudoc.org> \ [^3] A small database and
-sample query front\-end (search from) that makes use of the citation system,
-.I object citation numbering
-to demonstrates functionality.[^4]
-
-.BR
-.B SiSU
-can provide information on which documents are matched and at what locations
-within each document the matches are found. These results are relevant across
-all outputs using object citation numbering, which includes html, XML, LaTeX,
-PDF and indeed the SQL database. You can then refer to one of the other outputs
-or in the SQL database expand the text within the matched objects (paragraphs)
-in the documents matched.
-
-.BR
-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.[^5]
-
-.TP
-.B \ sisu \ \-F \ \-\-webserv\-webrick
-\ builds \ a \ cgi \ web \ search \ frontend \ for \ the \ database \ created
-\
-
-.BR
-The following is feedback on the setup on a machine provided by the help
-command:
-
-.BR
- sisu \-\-help sql
-
-
-.nf
- Postgresql
- user: ralph
- current db set: SiSU_sisu
- port: 5432
- dbi connect: DBI:Pg:database=SiSU_sisu;port=5432
- sqlite
- current db set: /home/ralph/sisu_www/sisu/sisu_sqlite.db
- dbi connect DBI:SQLite:/home/ralph/sisu_www/sisu/sisu_sqlite.db
-.fi
-
-.BR
-Note on databases built
-
-.BR
-By default, \ [unless \ otherwise \ specified] databases are built on a
-directory basis, from collections of documents within that directory. The name
-of the directory you choose to work from is used as the database name, i.e. if
-you are working in a directory called /home/ralph/ebook the database SiSU_ebook
-is used. \ [otherwise \ a \ manual \ mapping \ for \ the \ collection \ is \
-necessary]
-
-.SH
-5.2 SEARCH FORM
-
-.TP
-.B \ sisu \ \-F
-\ generates \ a \ sample \ search \ form, \ which \ must \ be \ copied \ to \
-the \ web\-server \ cgi \ directory \
-
-.TP
-.B \ sisu \ \-F \ \-\-webserv\-webrick
-\ generates \ a \ sample \ search \ form \ for \ use \ with \ the \ webrick \
-server, \ which \ must \ be \ copied \ to \ the \ web\-server \ cgi \ directory
-\
-
-.TP
-.B \ sisu \ \-Fv
-\ as \ above, \ and \ provides \ some \ information \ on \ setting \ up \
-hyperestraier \
-
-.TP
-.B \ sisu \ \-W
-\ starts \ the \ webrick \ server \ which \ should \ be \ available \
-wherever \ sisu \ is \ properly \ installed \
-
-.BR
-The generated search form must be copied manually to the webserver directory as
-instructed
-
-.SH
-6. HYPERESTRAIER
-.BR
-
-.BR
-See the documentation for hyperestraier:
-
-.BR
- <http://hyperestraier.sourceforge.net/>
-
-.BR
- /usr/share/doc/hyperestraier/index.html
-
-.BR
- man estcmd
-
-.BR
-on sisu_hyperestraier:
-
-.BR
- man sisu_hyperestraier
-
-.BR
- /usr/share/doc/sisu/sisu_markup/sisu_hyperestraier/index.html
-
-.BR
-NOTE: the examples that follow assume that sisu output is placed in the
-directory /home/ralph/sisu_www
-
-.BR
-(A) to generate the index within the webserver directory to be indexed:
-
-.BR
- estcmd gather \-sd \ [index \ name] \ [directory \ path \ to \ index]
-
-.BR
-the following are examples that will need to be tailored according to your
-needs:
-
-.BR
- cd /home/ralph/sisu_www
-
-.BR
- estcmd gather \-sd casket /home/ralph/sisu_www
-
-.BR
-you may use the \'find\' command together with \'egrep\' to limit indexing to
-particular document collection directories within the web server directory:
-
-.BR
- find /home/ralph/sisu_www \-type f | egrep
- \'/home/ralph/sisu_www/sisu/.+?.html$\' |estcmd gather \-sd casket \-
-
-.BR
-Check which directories in the webserver/output directory (~/sisu_www or
-elsewhere depending on configuration) you wish to include in the search index.
-
-.BR
-As sisu duplicates output in multiple file formats, it it is probably
-preferable to limit the estraier index to html output, and as it may also be
-desirable to exclude files \'plain.txt\', \'toc.html\' and
-\'concordance.html\', as these duplicate information held in other html output
-e.g.
-
-.BR
- find /home/ralph/sisu_www \-type f | egrep
- \'/sisu_www/(sisu|bookmarks)/.+?.html$\' | egrep \-v
- \'(doc|concordance).html$\' |estcmd gather \-sd casket \-
-
-.BR
-from your current document preparation/markup directory, you would construct a
-rune along the following lines:
-
-.BR
- find /home/ralph/sisu_www \-type f | egrep \'/home/ralph/sisu_www/([specify \
- first \ directory \ for \ inclusion]|[specify \ second \ directory \ for \
- inclusion]|[another \ directory \ for \ inclusion? \ ...])/.+?.html$\' |
- egrep \-v \'(doc|concordance).html$\' |estcmd gather \-sd
- /home/ralph/sisu_www/casket \-
-
-.BR
-(B) to set up the search form
-
-.BR
-(i) copy estseek.cgi to your cgi directory and set file permissions to 755:
-
-.BR
- sudo cp \-vi /usr/lib/estraier/estseek.cgi /usr/lib/cgi\-bin
-
-.BR
- sudo chmod \-v 755 /usr/lib/cgi\-bin/estseek.cgi
-
-.BR
- sudo cp \-v /usr/share/hyperestraier/estseek.* /usr/lib/cgi\-bin
-
-.BR
- \ [see \ estraier \ documentation \ for \ paths]
-
-.BR
-(ii) edit estseek.conf, with attention to the lines starting \'indexname:\' and
-\'replace:\':
-
-.BR
- indexname: /home/ralph/sisu_www/casket
-
-.BR
- replace: ^file:///home/ralph/sisu_www{{!}}http://localhost
-
-.BR
- replace: /index.html?${{!}}/
-
-.BR
-(C) to test using webrick, start webrick:
-
-.BR
- sisu \-W
-
-.BR
-and try open the url: <http://localhost:8081/cgi\-bin/estseek.cgi>
-
-.SH
-DOCUMENT INFORMATION (METADATA)
-.BR
-
-.SH
-METADATA
-.BR
-
-.BR
-Document Manifest @
-<http://www.jus.uio.no/sisu/sisu_manual/sisu_search/sisu_manifest.html>
-
-.BR
-.B Dublin Core
-(DC)
-
-.BR
-.I DC tags included with this document are provided here.
-
-.BR
-DC Title:
-.I SiSU \- SiSU information Structuring Universe \- Search \ [0.58]
-
-.BR
-DC Creator:
-.I Ralph Amissah
-
-.BR
-DC Rights:
-.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL
-3
-
-.BR
-DC Type:
-.I information
-
-.BR
-DC Date created:
-.I 2002\-08\-28
-
-.BR
-DC Date issued:
-.I 2002\-08\-28
-
-.BR
-DC Date available:
-.I 2002\-08\-28
-
-.BR
-DC Date modified:
-.I 2007\-09\-16
-
-.BR
-DC Date:
-.I 2007\-09\-16
-
-.BR
-.B Version Information
-
-.BR
-Sourcefile:
-.I sisu_search._sst
-
-.BR
-Filetype:
-.I SiSU text insert 0.58
-
-.BR
-Sourcefile Digest, MD5(sisu_search._sst)=
-.I 52c1d6d3c3082e6b236c65debc733a05
-
-.BR
-Skin_Digest:
-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
-.B Generated
-
-.BR
-Document (metaverse) last generated:
-.I Sun Sep 23 04:13:48 +0100 2007
-
-.BR
-Generated by:
-.I SiSU
-.I 0.59.0
-of 2007w38/0 (2007\-09\-23)
-
-.BR
-Ruby version:
-.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux]
-
-.TP
-.BI 1.
-<http://www.postgresql.org/>
- <http://advocacy.postgresql.org/>
- <http://en.wikipedia.org/wiki/Postgresql>
-.TP
-.BI 2.
-<http://www.hwaci.com/sw/sqlite/>
- <http://en.wikipedia.org/wiki/Sqlite>
-.TP
-.BI 3.
-<http://search.sisudoc.org>
-.TP
-.BI 4.
-(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 5.
-of this feature when demonstrated to an IBM software innovations evaluator in
-2004 he said to paraphrase: this could be of interest to us. We have large
-document management systems, you can search hundreds of thousands of documents
-and we can tell you which documents meet your search criteria, but there is no
-way we can tell you without opening each document where within each your
-matches are found.
-
-.TP
-Other versions of this document:
-.TP
-manifest: <http://www.jus.uio.no/sisu/sisu_search/sisu_manifest.html>
-.TP
-html: <http://www.jus.uio.no/sisu/sisu_search/toc.html>
-.TP
-pdf: <http://www.jus.uio.no/sisu/sisu_search/portrait.pdf>
-.TP
-pdf: <http://www.jus.uio.no/sisu/sisu_search/landscape.pdf>
-." .TP
-." manpage: http://www.jus.uio.no/sisu/sisu_search/sisu_search.1
-.TP
-at: <http://www.jus.uio.no/sisu>
-.TP
-.TP
-* Generated by: SiSU 0.59.0 of 2007w38/0 (2007-09-23)
-.TP
-* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux]
-.TP
-* Last Generated on: Sun Sep 23 04:13:52 +0100 2007
-.TP
-* SiSU http://www.jus.uio.no/sisu