anchor.diff:   |     |   |- file2.adoc
    |     |- ...
   
  -The parameters that is sent to the cgi script via the html form generated
  -by giblish are:
  -
  -  * searchphrase -> the text string to search for
  -  * ignorecase -> wether to ignore case or not
  -  * useregexp -> wether the searchphrase above is treated as a regexp or
  -    ordinary text
  -  * css -> the css file name to use when styling the search result page
  -  * topdir -> the absolute path to the root of the generated document tree
  -  * reltop -> <clarify this>
  +== 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.
  +
  +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.
  + . Refer to a document using the syntax pass:[<<:docid:#DOC_ID#>>].
  + . Run giblish with the -d switch when generating documents.
  +
  +Using doc ids makes it possible for giblish to do two things:
  +
  + . Make the reference from one document to another work even if one of the documents
  +   have been moved within the 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).
  +
  +=== Example of using the docid feature
  +
  +Example document one::
  +
  +[source,asciidoc]
  +----
  += Document one
  +:toc:
  +:numbered:
  +:docid: D-001
  +
  +== Purpose
  +
  +To illustrate the use of doc id
  +----
  +
  +Example document two::
  +[source,asciidoc]
  +----
  += Document two
  +:toc:
  +:numbered:
  +:docid: D-002
  +
  +== Purpose
  +
  +To illustrate the use of doc id. You can refer to document one as <<:docid:D-001>>. 
  +----
  +
  +
  +[[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
  +
  + 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 the `css`, `fonts` and `images` directories found under
  +   `<working_dir>/path/to/my/resources` to `my_dst_root/web_assets`
  + * link all generated html files to the css found at
  +   `/web_assets/css/mylayout.css`
  +
  +=== 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.
  + * 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 generated pdf will use the theme found at
  +   `<working_dir>/path/to/my/resources/themes/mylayout.yml`
  +
  +=== 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.
  +
  +=== Generate html from giblish git repo using giblish css
  +
  +Assuming you have cloned this git repo to `~/github/giblish` you can do:
  +
  + giblish -g "master" -r ~/github/giblish/resources ~/github/giblish my_dst_root
  +
  +The above will check-out all branches matching the regexp "master" and convert
  +the .adoc or .ADOC files under the dir `my_src_root` to html and place the
  +resulting files under the `my_dst_root/<branch_name>` dir.
  +
  +An index page named `index.html` is generated in each `my_dst_root/<branch_name`
  +dir containing links and some info about the converted files.
  +
  +A summary page containing links to all branches will be generated directly in
  +the `my_dst_root` dir.
  +====
  +
  +.Generate pdf from giblish git repo using the giblish pdf theme
  +====
  +Assuming you have cloned this git repo to `~/github/giblish` you can do:
  +
  + giblish -f pdf -g "master" -r ~/github/giblish/resources ~/github/giblish my_dst_root
  +
  +The above will check-out all branches matching the regexp "master" and convert
  +the .adoc or .ADOC files under the dir `my_src_root` to pdf and place the
  +resulting files under the `my_dst_root/<branch_name>` dir.
  +
  +An index page named `index.pdf` is generated in each `my_dst_root/<branch_name`
  +dir containing links and some info about the converted files.
  +
  +A summary page containing links to all branches will be generated directly in
  +the `my_dst_root` dir.
  +====
  +
  +.Advanced usage; Publish a static html site from a git repo with search capabilities
  +====
  +giblish can be used to inject a tree of html docs suitable for serving via a web
  +server (e.g. Apache). Below is an example how to create such a tree. If you
  +combine this with a server side git hook that invokes this script after push,
  +you will have a way of auto publish your latest documents and/or documents at
  +specific git tags. A document management system including nice index pages and
  +text search capabilities
  +
  +Assumptions:
  +
  + * You have a running web server that serves pages from directory root
  +   `/var/www/html`
  + * You want to access the generated docs from http://your_web_site.com/proddocs
  + * The git repo containing the source docs has its working dir at `~/gh/myrepo`
  + * You only want to publish the documents in the subfolder `common/Documents` in
  +   your git repo.
  + * You want to use your own css named `mylayout.css` that internally references
  +   fonts and images using relative paths.
  + * You have the css and its referenced fonts and images in subfolders
  +   of the git repo at `common/resources/css common/resources/fonts common/resources/images`
  + * You want to publish the documentation as it looked for your release tags
  +   myprod-v1.0-final, myprod-v2.0-final, ...
  +
  + giblish -m -t "-final$" -r ~/gh/myrepo/common/resources -s mylayout -w /var/www/html ~/gh/myrepo/common/Documents /var/www/html/proddocs
  +
  +The above will create a tree of html docs under `/var/www/html/proddocs`. Each
  +tag will get its own subdir (e.g. `/var/www/html/proddocs/myprod_v1.0_final`).
  +The css and referenced assets will be copied to a 'web_assets' dir for each
  +subdir and also to the .../proddocs dir.
  +
  +The `-w` switch above will strip the `/var/www/html` from the css link so that
  +the paths to the css will be correct in the context of the serving of the
  +pages via the web server.
  +
  +The `-m` switch above will build a database (JSON file) with enough information
  +to enable a cgi-script to provide a text-search capability for your users. The
  +cgi-script must be located at http://your_web_site.com/cgi-bin/giblish-search.cgi
  +and this gem provides a default implementation that you can copy from the .../lib
  +folder to the correct destination.
  +====
  +
  
positive.code:  |     |- branch_2_top_dir
   |           | ...
  
  assume that the file tree looks like this when not
  rendering a git branch:
  
  .When rendering documents not in a git branch
   dst_root_dir
   |- index.html
  
negative.code: 
   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.
  
  == Text search implementation
  
  The text search enables a user to search for a text string and receive matching
  sections in the documentation tree.
  
  giblish ties together the following three pieces to enable the text search:
  
  . the source text of all adoc files together with a JSON file that maps sections to
  their line numbers.
  ** giblish collects this 'search data' when it generates the
  html files to the destination directory. The JSON file and all adoc source files
  are copied to a well-known place in the destination tree (see below).
  . an html form somewhere on the rendered pages where the user can input search queries and
    initiate a search.
  ** giblish injects such an html form in the generated index page when the user
  specifies the '-m' switch.
  . a server side script that handles a user request to search the documents for a specific
    text string and presents the result to the user.
  ** this gem contains an implementation of such a server side script. It is intended to be
     run as a cgi script and requires ruby and grep to be installed on the server where it runs.
  
  === Search data and html form parameters
  
  