giblish 0.8.2 → 2.0.0.pre.alpha1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56f7e50e079748482350108862650f943cd6266864b285a1845808443dd46489
-  data.tar.gz: '0911983f515dd0e8719ef9836b69182f5e148b17101414cc703c080ee4681370'
+  metadata.gz: 8dc5f7111b85423074f87986b2750ce3fa61dbf4364331a80481d0d5cc881673
+  data.tar.gz: 53fd77b1ac62eec70539e744950cfc8f121532f9639eb2bcb860d6142443474f
 SHA512:
-  metadata.gz: 57c8f2974c53343bca7b7bd92e2417441e1c203acbac40e3e35df0502a72eb8d305bc611850c8772675f75938df61c7f4c8032124273677c7ed7e95249066ef3
-  data.tar.gz: 056b23e064ec6b71c96ef6071e5e8fe870693c0950999bea083c23e45d678287c8390f1da4343710ec853e5969632fb1e940fc9177ed7d1a5d430bcff3faa3f6
+  metadata.gz: baa8d72424dc2cb581e90bf383849cb8043b13ca1aed2c5fe3a4b1d9a20aedccf69f6ac9936e7439ae1887074bf274a47553907bce1ce78decd68da207ca3b91
+  data.tar.gz: b579918b4aa8c68d0f9e1ac57a878e3279b3c8404e6f5e677e91859a6af45983feaca033bf051eff56ac7e4f45556f13faa5b79a7bbcb7fc47f18684b5fa952f

data/.github/workflows/unit_tests.yml

@@ -0,0 +1,30 @@
+name: Giblish CI checks
+
+on:
+  push:
+    branches: [personal/rillbert/*, main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ["3.0", "3.1"]
+
+    steps:
+      - name: Install binutils
+        run: |
+          sudo apt -y install binutils
+      - name: Install needed packages
+        run: |
+          sudo apt-get -y install libpango1.0-dev graphviz
+      - name: Checkout Giblish
+        uses: actions/checkout@v2
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+          bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+      - name: Run tests
+        run: |
+          bundle exec rake

data/.gitignore

@@ -9,6 +9,7 @@
 /test/tmp/
 /test/version_tmp/
 /tmp/
+/.vscode/
 
 # Used by dotenv library to load environment variables.
 # .env
@@ -42,12 +43,15 @@ build-iPhoneSimulator/
 
 # for a library or gem, you might want to ignore these files since the code is
 # intended to run in multiple environments; otherwise, check them in:
-# Gemfile.lock
-# .ruby-version
-# .ruby-gemset
+Gemfile.lock
+.ruby-version
+.ruby-gemset
 
 # unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
 .rvmrc
 
 # RubyMine idea files
 /.idea/
+
+# Local playground
+sandbox.rb

data/.ruby-version

@@ -1 +1 @@
-2.7.3
+3.1.2

data/Changelog.adoc

@@ -0,0 +1,59 @@
+= giblish changelog
+
+== Not yet in place
+
+ * Update docs for giblish.
+ ** write detailed instructions on howto setup the doc generation examples
+ * Update the default css for giblish html generation.
+
+== v1.0.0
+
+This release includes a complete refactoring of almost the entire code base.
+
+Breaking changes::
+ * The '-w' flag is removed  
+ * The text search parameters interface has changed completely. A written specification of this interface is included in the docs.
+ * The '-r' flag will, for html generation, *copy everything* under the given directory to the target location.
+ ** the previous restriction on folder names has been removed.
+ * The '-s' flag now instructs giblish to use any matching style found under the resource directory given by the '-r' flag. The exact path is no longer necessary.
+ * The doc attribute `:icons: font` is now set by default.
+ * The source highlighter attributes are now set as follows by default:
+ ** :source-highlighter: rouge  :rouge-css: style  :rouge-style: github
+ * The format of the index pages has been updated
+
+Changes/New functionality::
+ * Rouge is used as source highlighter and the default is to use the following attributes:
+ ** :rouge-css: style
+ ** :rouge-style: github
+ * A --server-css-path flag can be used to set a path to the css file used by generated html documents when served via a web server.
+ * A --server-search-path flag can be used to set the URI path to the location of a server-side search script that can supply the user with search results.
+ * A --copy-asset-folders flag can be used to copying full directories from the source to the destination tree.
+ * Index pages are generated for each subdirectory in the target document tree.
+ * The format of the git summary page has been updated and more info included.
+ * The text search server-side cgi script has been rewritten.
+ * The text search for web-server-served html docs has been updated in the following ways:
+ ** the asciidoc 'include' directive is supported by expanding them and include the resulting text in the search database.
+ ** the implementation of the server-side search tools are written completely in ruby and does no longer depend on an external 'grep' tool.
+ ** almost all needed infrastructure for implementing a server-side search script has been implemented within the 'giblish' gem.
+ * The asciidoctor toolchain dependencies are updated to the latest versions (at the time of release).
+ 
+
+== v0.8.0
+
+ * *Breaking change* require ruby 2.7
+ * update asciidoctor tool deps to latest versions
+
+== v0.7.0
+
+ * *Breaking change* include the entire path in the -i and -j options
+ * *Breaking change* change the meaning of the -w flag (and rename the long form to --web-path)
+   and add the -mp flag.
+   This was done as a means to remove the hard-coded arguments to the search box html so that one
+   can generate html docs to a destination that is not the same as the one where they are deployed
+   on a web server.
+ * take the idprefix and idseparator into account when indexing sections for text search
+ * Add the font awesome css as link to search box and use the magnifying glass icon
+ * update README file
+ * handle the case where a 'index.adoc' file exists by making the basename configurable using the
+   '--index-basename' flag.
+ * update the dependencies to the latest asciidoctor-pdf release

data/README.adoc

@@ -0,0 +1,261 @@
+= giblish
+:docid: G-001
+:numbered:
+
+image::https://github.com/rillbert/giblish/actions/workflows/unit_tests.yml/badge.svg["Build Status"]
+
+[abstract] 
+== Purpose
+
+giblish converts a source directory tree containing AsciiDoc files to a destination directory tree containing the corresponding html or pdf files. It adds some handy tools for easier navigation of the resulting destination tree.
+
+== Examples
+
+IMPORTANT: The examples below are *not* the official documentation for the corresponding projects.
+
+[cols="1,1,5"]
+|===
+|Project |Link to example |Comment
+
+|The `giblish` documentation
+|https://www.rillbert.se/giblish_examples/giblish/main/index.html[here]
+|The documentation of giblish (same as you find in GitHub).
+
+|Raspberry Pi documentation
+|https://www.rillbert.se/giblish_examples/rpi_docs/giblish_example/index.html[example]
+|The original documentation site uses Jekyl for site generation, the link points to a mirror where some small tweaks to the docs were made to make them suitable for generation with giblish.
+
+|The *old* asciidoctor docs
+|https://www.rillbert.se/giblish_examples/asciidoctor_docs/master/newindex.html[example]
+|An example of how giblish can generate the master branch of the official asciidoc.org documentation git repo can be found at
+
+|===
+
+== `giblish` features
+
+The features of giblish include:
+
+ * An index page listing all rendered documents with clickable links.
+ * If the source directory tree is part of a git repository, giblish can generate separate html/pdf trees for branches and/or tags that match a user specified regexp (see examples below).
+ * Document ids - Note: the implementation of this is giblish-specific and thus you need to render your adoc files using giblish to make this work as intended. You can use document ids to:
+ ** Reference one doc in the source tree from another doc without depending on file names or relative paths. The referenced doc can thus be moved within the source tree or change its file name and the reference will still be valid.
+ ** Validate doc id references during document rendering and thus be alerted to any invalid doc id references.
+ ** Let giblish generate a clickable graph of all document references (requires graphviz and the 'dot' tool).
+ * A stripped-down, but nonetheless useful, text-search of your html documents. This requires that you publish your docs to a web-server and setup an application on that same web-server. `giblish` provides most of the scaffolding though.
+
+== Dependencies and credits
+
+Giblish uses the awesome *asciidoctor* and *asciidoctor-pdf* projects under the hood. Thank you @mojavelinux and others for making these brilliant tools available!!
+
+== Installation
+
+ gem install giblish
+
+Want to get started straight away? Go directly to the <<usage_examples>>.
+
+=== Some caveats
+
+When using giblish for generating docs the following applies:
+
+ * giblish *will overwrite* files with the same name in the destination directory.
+ * giblish requires that the git working tree and index of the repo containing source documents are clean when generating documentation.
+ * giblish will make explicit check-outs of all the branches or tags that matches the selection criteria. The working dir of the source git repo will thus have the last branch that giblish checked-out as the current branch after doc generation.
+
+== Contributing
+
+If you want to contribute to giblish, great :) Use the standard GitHub flow of forking the repo and submit a pull request.
+
+Pull requests must meet the following to be considered for merging:
+
+ * Tests have been added for new or updated functionality
+ * The code has been linted using the `standardrb` tool. 
+ ** The version of standardrb shall be the same as the one used in the target branch for the PR. 
+
+To develop on giblish, you:
+
+ . Install ruby on your local machine (rbenv is a good choice for handling ruby installations)
+ . Install necessary dependencies to install the ruby 'mathematica' gem, see eg https://github.com/gjtorikian/mathematical/blob/47041d5492cc7c5f04105031430fb44119406f49/script/install_linux_deps
+ . Install graphviz
+ . Clone or fork the repository
+ . Run the `bin/setup` script from a bash prompt
+
+== Document ids and the reference graph
+
+NOTE: This is a non-standard extension of asciidoc. If you use this feature, you will need to generate your documents using giblish to make this work as intended.
+
+giblish extends the cross reference concept in asciidoc with a _document id_ mechanism. To use this, you need to:
+
+ . Add a `:docid:` entry in your document's header section. The doc id can consist of up to 10 characters and must be unique within the set of documents generated by giblish.
+ . Refer to a document using the syntax `pass:[<<:docid:a_doc_id>>]` where `a_doc_id` is the doc id of a document in the same git repo.
+ . Run giblish with the -d switch when generating documents.
+
+Using doc ids makes it possible for giblish to do two things:
+
+ . Make references from one document in the tree to another work even if one of the documents have been moved within the document source tree.
+ . Produce a clickable 'map' of the generated documents where the different references are clearly seen. This feature require that the 'dot' tool, part of the graphwiz package is installed on the machine where giblish is run.
+
+The use of the -d switch makes giblish parse the document twice, once to map up the doc ids and all references to them, once to actually generate the output documentation. Thus, you pay a performance penalty but this should not be a big inconvenience since the generation is quite fast in itself.
+
+=== Example of using the docid feature
+
+Consider that you have two documents located somewhere in the same folder tree, document one and document two. You could then use the docid feature of giblish to refer to one document from the other as in the example below.
+
+Example document one::
+
+[source,asciidoc]
+----
+= Document one
+:toc:
+:numbered:
+:docid: G-001
+
+== Purpose
+
+To illustrate the use of doc id.
+----
+
+Example document two::
+[source,asciidoc]
+----
+= Document two
+:toc:
+:numbered:
+:docid: G-002
+
+== Purpose
+
+To illustrate the use of doc id. You can refer to document one as <<:docid:G-001>>. This will display a clickable link with the doc id (G-001 in this case).
+
+You can use the same syntax as the normal asciidoc cross-ref but replace 'xref' with ':docid:' as shown below:
+
+ * <<:docid:G-002#purpose>> to refer to a specific section or anchor.
+ * <<:docid:G-002#purpose,The purpose section>> to refer to a specific section and display a specific text for the link.
+----
+
+The above reference will work even if either document changes location or file name as long as both documents are parsed by giblish in the same run.
+
+[[usage_examples]]
+== Usage Examples
+
+Here follows a number of usages for giblish in increasing order of complexity.
+
+=== Get available options
+
+ giblish -h
+
+=== Giblish html 'hello world'
+
+ giblish my_src_root my_dst_root
+
+ * convert all .adoc or .ADOC files under the dir `my_src_root` to html and place the resulting files under the `my_dst_root` dir.
+ * generate an index page named `index.html` that contains links and some info about the converted files. The file is placed in the `my_dst_root` dir.
+
+The default asciidoctor css will be used in the html conversion.
+
+=== Giblish pdf 'hello world'
+
+ giblish -f pdf my_src_root my_dst_root
+
+ * convert all .adoc or .ADOC files under the dir `my_src_root` to pdf and place the resulting files under the `my_dst_root` dir.
+ * generate an index page named `index.pdf` that contains links and some info about the converted files. The file is placed in the `my_dst_root` dir.
+
+The default asciidoctor pdf theme will be used in the pdf conversion.
+
+=== Using a custom css for the generated html
+
+Generate html that can be browsed locally from file:://<my_dst_root>.
+
+ giblish -r path/to/my/resources -s mylayout my_src_root my_dst_root
+
+ * convert all .adoc or .ADOC files under the dir `my_src_root` to html and place the resulting files under the `my_dst_root` dir.
+ * generate an index page named `index.html` that contains links and some info about the converted files. The file is placed in the `my_dst_root` dir.
+ * copy everything found under `<working_dir>/path/to/my/resources` to `my_dst_root/web_assets`
+ * link all generated html files to the mylayout.css found somewhere under `/web_assets`
+
+=== Using a custom pdf theme for the generated pdfs
+
+ giblish -f pdf -r path/to/my/resources -s mylayout my_src_root my_dst_root
+
+ * convert all .adoc or .ADOC files under the dir `my_src_root` to pdf and place the resulting files under the `my_dst_root` dir. some info about the converted files. The file is placed in the `my_dst_root` dir.
+ * the pdfs will be rendered using the theme file named mylayout.yml found somewhere under `<working_dir>/path/to/my/resources`
+
+=== Generate html from multiple git branches
+
+ giblish -g "feature" my_src_root my_dst_root
+
+ * check-out each branch matching the regexp "feature" in turn
+ * for each checked-out branch,
+ ** convert the .adoc or .ADOC files under the dir `my_src_root` to html.
+ ** place the resulting files under the `my_dst_root/<branch_name>` dir.
+ ** generate an index page named `index.html` that contains links and some info about the converted files. The file is placed in the `my_dst_root/<branch_name` dir.
+ * generate a summary page containing links to a all branches and place it in the `my_dst_root` dir.
+
+// === Publish the asciidoctor.org documents with text search
+
+// giblish can be used to generate html docs suitable for serving via a web server (e.g. Apache). You can use the cgi script included in the giblish gem to provide text search capabilities.
+
+// Here is an example of how to publish the docs in the official asciidoctor.org git repo to a web server, including index pages and text search.
+
+// NOTE: No consideration has been taken to how permissions are set up on the web server. Just running the below commands as-is on e.g.a standard apache set-up will bail out with 'permission denied' errors.
+
+// ==== Generating the html documents
+
+// The example assumes that you have one machine where you generate the documents and another machine that runs a web server to which you have ssh access.
+
+// The generated docs shall be accessible via _www.example.com/adocorg/with_search_
+
+// You need to provide two pieces of deployment info to giblish when generating the documents:
+
+//  * the uri path where to access the deployed docs (/adocorg/with_search in this example)
+//  * the path in the local file system on the web server where the search data can be accessed
+//    (/var/www/html/site_1/adocorg/with_search in this example)
+
+// The following commands will generate the asciidoctor.org documentation and deploy the result to the web server.
+
+//  . Clone the asciidoctor doc repo to your development machine
+// +
+//  git clone https://github.com/asciidoctor/asciidoctor.org.git
+
+//  . Generate the html documentation with the correct deployment info
+// +
+//  giblish -j '^.*_include.*' -m -mp /var/www/html/site_1/adocorg/with_search -w /adocorg/with_search -g master --index-basename "myindex" asciidoctor.org/docs ./generated_docs
+// +
+// Explanation of the parameters and arguments::
+//  * *pass:[-j '^.*_include.*']* - exclude everything in the __include_ directory. (the
+//                                  asciidoctor.org repo stores partial docs here).
+//  * *-m* - assemble the necessary search data to support text search and include this data as part of
+//           the generated documents.
+//  * *-mp /var/www/html/site_1/adocorg/with_search* - the file system path on the deployment machine where
+//                                                     the search data is located
+//  * *-w /adocorg/with_search* - the uri path to the deployed docs
+//  * *-g master* - publish all git branches that matches the regexp 'master' (i.e. only the 'master'
+//                  branch).
+//  * *--index-basename "myindex"* - change the default name (index) that giblish uses for the generated
+//                                   index page. This is needed since asciidoctor.org contains an
+//                                   "index.adoc" file that would otherwise be overwritten by giblish.
+//  * *asciidoctor.org/docs* - the root of the source document tree.
+//  * *./generated_docs* - a temporary storage for the generated html docs on the local system.
+// +
+
+//  . Copy the generated files to the web server
+
+//  scp -r ./generated_docs rillbert@my.web.server.org:/var/www/adocorg/with_search/.
+// +
+
+
+// ==== Copy the text search script to the web server
+
+// This only needs to be done once (or if a new version of giblish breaks the currently used API).
+
+// IMPORTANT: The current version of giblish expects the script to be found at the URI path `/cgi-bin/giblish-search.cgi`. This might be customizable in future versions but is currently hard-coded. Thus, if your web-server serves pages at www.mywebsite.com, the search script must be accessible at www.mywebsite.com/cgi-bin/giblish-search.cgi
+
+//  . Find the server side script that implements text search that is included with giblish
+
+//  gem which giblish
+// +
+
+// In my case this returns `/var/lib/ruby/gems/2.4.0/gems/giblish-0.5.2/lib/giblish.rb`. This means that I will find the script in the same directory, i.e. `/var/lib/ruby/gems/2.4.0/gems/giblish-0.5.2/lib`.
+
+//  . Copy the server side script to the /cgi-bin dir on the web server. In this example the cgi-bin dir is configured to be `/var/www/cgi-bin`
+// +
+//  scp /var/lib/ruby/gems/2.4.0/gems/giblish-0.5.2/lib/giblish-search.cgi rillbert@my.web.server.org:/var/www/cgi-bin/giblish-search.cgi

data/docs/concepts/text_search.adoc

@@ -0,0 +1,213 @@
+= giblish text search
+:docid: G-004
+:imagesdir: text_search_im
+
+== Overview
+
+giblish includes an implementation of full text search for html documents if they are published via a web server. Two things must be met to enable this functionality:
+
+ . A specific set of options must be given to giblish during the generation of the html documents. This will ensure that giblish:
+ .. copies a search index to the same tree as the generated html documents.
+ .. includes an html form at the top of each generated document that the user can interact with to send search queries.
+ . A server-side search application must be setup on the web server that hosts the generated html docs. 
+ .. The application must be invoked as a result of a search query from one of the generated html documents and return the corresponding search result to the user.
+ .. The same instance of a search application can be used for multiple document repositories deployed on the same web server.
+
+The server-side script can be implemented in many ways, the giblish gem provides helper classes that implement most of the heavy-lifting. It also contains template scripts for using CGI or a sinatra web app hosted in the Phusion Passenger application server to initiate a search.
+
+The specification of the search query parameters can be found in <<:docid:G-002>>.
+
+== Text search using CGI
+
+CGI is the solution with fewest external dependencies (and worst performance). Below is an overview of the involved actors.
+
+.CGI script example
+image::cgi-search_request.svg[]
+
+Giblish contains two template scripts to get you started:
+
+ . gibsearch.rb - a naive implementation of a CGI script in ruby that uses the helper classes provided by giblish to retrieve and format an html response triggered by a search request to a web server.
+ . wserv_development.rb - a naive implementation of a boot-strap script for an instance of Webrick, a web server written in ruby, that serves html pages on localhost:8000
+
+IMPORTANT: The template scripts in giblish are provided as examples and are not tested in any form of production use.
+
+.Using CGI and ruby's built-in Webrick server
+====
+This is the most basic example, it assumes that all documents and tools are run on a local machine. To publish documents to the world, you would replace Webrick with Apache, Nginx or other, more production-friendly web server.
+
+[source,bash]
+----
+# install giblish
+gem install giblish
+
+# install webrick
+gem install webrick
+
+# cd to your directory of choice, called top_dir in this example
+cd top_dir
+
+# clone the repo containing the docs (using the giblish repo as 
+# an example)
+git clone https://github.com/rillbert/giblish.git
+
+# generate html docs from all 1.x tags
+giblish -t "^v1" -m giblish html_docs
+
+# Copy the cgi template provided in the giblish gem to the directory
+# for the html docs.
+# The template is named 'gibsearch.rb' and resides under 
+# 'web_apps/cgi_search' relative to the dir of the installed
+# giblish gem. 
+# The below uses bash to find the template, copy and rename it to 
+# 'gibsearch.cgi' to make it smoother to use the cgi binding in webrick.
+cp "$(dirname $(gem which giblish))/../web_apps/cgi_search/gibsearch.rb" html_docs/gibsearch.cgi 
+
+# copy a boot-strap script for Webrick from the giblish gem
+cp "$(dirname $(gem which giblish))/../scripts/wserv_development.rb"
+
+# start a web server using the boot-strap script
+#
+# If you deviate from this example regarding paths, you need to 
+# adjust the boot-strap script accordingly
+ruby wserv_development.rb
+
+# browse to localhost:8000
+firefox localhost:8000
+
+# click on one of the 1.x tags to see the docs for that tag
+
+# search docs using the form in the index page.
+----
+====
+
+== Text search using a web application hosted by Passenger
+
+This setup has more dependencies than the CGI example. The upsides are e.g. stateful execution, better performance, more versatile.
+
+This example uses Apache2, Passenger and Sinatra to deploy the server-side text search as a web application. There are a gazillion other tech stacks/permutations to provide the same functionality.
+
+IMPORTANT: Full installation instructions of Apache2, Passenger or their interconnection is out of scope for this example. Security is also out of scope so you will probably want to harden this before using it in production.
+
+.Passenger web-app example
+image::search_request.svg[]
+
+=== Setup a sinatra app under apache/passenger
+
+This example is based on the info found in these links: 
+
+ * https://www.phusionpassenger.com/library/walkthroughs/deploy/ruby/ownserver/apache/oss/bionic/deploy_app.html#nonrails_preparing-the-app-s-environment
+ * https://newbedev.com/how-do-i-set-up-a-sinatra-app-under-apache-with-passenger 
+
+
+.Deploy a text search application under Apache/Passenger
+====
+Preconditions::
+ * You have a working installation of 
+ ** Apache (version >= 2.4)
+ ** Ruby (version >= 2.7)
+ ** giblish (version >= 1.0)
+ * The generated html documents are stored under `/var/www/html/mydomain`
+ * The web server will serve the docs from the domain `www.mydomain.se`
+ * The search script is accessible via the url `www.mydomain.se:1233/gibsearch`
+
+.Setup Passenger under apache
+[source, bash]
+----
+# list available modules
+sudo apachectl -M
+
+# install the apache passenger module
+sudo apt install libapache2-mod-passenger 
+
+# check that passanger is running
+sudo /usr/sbin/passenger-memory-stats 
+
+# determining the ruby command for passenger (Ex: /usr/bin/ruby2.7)
+passenger-config about ruby-command
+
+# install sinatra
+sudo gem install sinatra --no-document
+
+# add an apache 'site-available' config file for your app
+sudo nano /etc/apache2/sites-available/100-gibsearch.conf
+
+# use the following as a starting point for your config file but
+# tweak it to your situation
+<VirtualHost *:1233>
+    ServerName mydomain.se
+
+    # Tell Apache and Passenger where your app's 'public' directory is
+    # NOTE: Passenger requires a 'public' dir even if it is empty
+    DocumentRoot /var/www/mydoain/apps/gibsearch/public
+
+    PassengerRuby /usr/bin/ruby2.7
+
+    # Relax Apache security settings
+    <Directory /var/www/mydomain/apps/gibsearch/public>
+      Allow from all
+      Options -MultiViews
+      Require all granted
+    </Directory>
+</VirtualHost>
+
+# add an entry in Apache's ports.conf file
+cd /etc/apache2/
+sudo nano ports.conf 
+
+# add the following line in the ports.conf file and save it
+Listen 1233
+
+# symlink site-available to sites-enabled
+sudo ln -s /etc/apache2/sites-available/100-gibsearch.conf .
+
+# restart apache
+sudo apache2ctl restart 
+----
+
+.Deploy the text search web application
+[source,bash]
+----
+# the giblish gem contains a template application called 
+# 'sinatra_search' that you can use to start out with.
+#
+# copy the files from the giblish gem to where you want to deploy
+# the web app under apache, eg:
+cd /var/www/mydomain/apps/
+cp -r "$(dirname $(gem which giblish))/../web_apps/sinatra_search" gibsearch
+
+# when you're done, you should have something similar to this on your 
+# server
+$ tree gibsearch/
+gibsearch/
+|----- config.ru
+|----- public
+|   |-- dummy.txt
+|----- sinatra_search.rb
+|-- tmp
+    |-- restart.txt
+
+# you will want to tweak:
+#  the URL_PATH_MAPPINGS hash in the sinatra_search.rb file 
+# to your situation.
+
+# you can restart your app using
+touch gibsearch/tmp/restart.txt
+
+----
+
+.Generate docs compatible with the text search web application
+[source,bash]
+----
+# cd to your directory of choice, called top_dir in this example
+cd top_dir
+
+# clone the repo containing the docs (using the giblish repo as 
+# an example)
+git clone https://github.com/rillbert/giblish.git
+
+# generate html docs from all 1.x tags
+cd /var/www/html/mydomain
+giblish -c -t "^v1" -m --server-search-path www.mydomain.se:1233/gibsearch giblish html_docs
+ 
+----
+====

data/docs/concepts/text_search_im/cgi-search_request.puml

@@ -0,0 +1,35 @@
+@startuml
+!theme cerulean-outline
+' !theme spacelab
+hide footbox
+autonumber
+
+title "Using CGI for search requests"
+
+actor       Viewer       as Vi
+
+box "The Document Hosting Server" #EEEEEE
+participant "Web Server" as Webserv
+participant "Search Result\nGenerator\n(CGI)"   as Searcher
+note over of Searcher
+  The CGI script could use the
+  ""Giblish::RequestManager""
+  class to do most of the work.
+end note
+database "Search index"   as Index
+end box
+
+Vi -> Webserv     : Search Query\n(html POST)
+Webserv -> Searcher : Invoke CGI\nscript
+Searcher -> Index : Search the\nindex
+Searcher -> Webserv : Return serch\nresult (html)
+note right
+  Giblish contains help classes 
+  that provide most of the heavy 
+  lifting for retrieving and
+  formatting the search result.
+end note
+Webserv -> Vi  : return  search\nresult
+@enduml
+
+