anchor.diff:  
   giblish is used to convert a source directory tree containing AsciiDoc files to
   a destination directory tree containing the corresponding html or pdf files
  -and add some handy tools for easier navigation of the resulting files.
  -
  -The tools include:
  +and adds some handy tools for easier navigation of the resulting files.
  +
  +The added tools include:
   
    * An index page listing all rendered documents with clickable links
  + * A (stripped-down but nonetheless useful) text-search of your (html) documents (requires
  +   that you view your docs via a web-server.
  + * 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 sourc
  +    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 documents (requires
  -   that you view your docs via a web-server.
  - * 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).
  +
  +NOTE: giblish shall be considered stable from a usage perspective, please report bugs to the issue tracker. It's API however, is to be considered alpha, meaning that future versions may break the current usage of cmd line flags, generated artifacts or other functionality.
   
   == Dependencies and credits
   
  
positive.code: 
   gem install giblish
  
  == Some random notes
  
  When using giblish for generating docs the following applies:
  
   * giblish *will overwrite* files with the same name in the destination directory.
   * make sure that the git working tree and index of the source git repo are clean
     when generating docs from a git repo.
   * 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.
  
  == Usage Examples
  
  .Get available options
  ====
   giblish -h
  ====
  
  .Giblish 'hello world'
  ====
   giblish my_src_root my_dst_root
  
  The above will 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. An index page
  named `index.html` is generated in the `my_dst_root` dir containing links and
  some info about the converted files.
  
  The default asciidoctor css will be used in the html conversion.
  ====
  
  .Using a different css
  ====
   giblish -r ./path/to/my/resources -s mylayout my_src_root my_dst_root
  
  The above will 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. An index page
  named `index.html` is generated in the `my_dst_root` dir containing links and
  some info about the converted files.
  
  A css named mylayout.css must be found in the dir
  `<working_dir/path/to/my/resources/css`. The resulting html files will link
  to this css. Fonts and images used from the css must be found under
  `<working_dir/path/to/my/resources/fonts` and
  `<working_dir/path/to/my/resources/images` respectively.
  ====
  
  .Generate html from multiple git branches
  ====
   giblish -g "feature" my_src_root my_dst_root
  
  The above will check-out all branches matching the regexp "feature" 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 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.
  ====
  
  == Text search implementation
  
  The text search enables a user to search for a text string and receive matching
  sections in the documentation tree.
  
  To make this work, three things are needed
  
   . the source text of all adoc files together with a JSON file that maps sections to
     their line numbers. This 'search data' is collected by giblish 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 in the rendered pages that receives the user input (text string
     and other parameters) to start 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
   ** receive a text string to search for
   ** parses the search data for matches to the text string
   ** presents the result to the user
  
  This gem contains an example implementation of a server side script. It is implemented
  in ruby and uses 'grep' to parse the search data. It then generates a result page where
  each matching section is shown and when clicked, will navigate the user to that section
  in the corresponding document.
  
  === Search data and html form parameters
  
  
negative.code:  |     |   |- file2.adoc
   |     |- ...
  
  == 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.
  ====
  
  