
  About
=========

Documancer is programmer's documentation browser with fulltext searching.
It has several advantages over using web browser or specialized format-specific
viewers (such as info):

 * Unified UI for all documentation formats (currently only HTML and man and 
   info pages are supported)
 * The GUI is better suited for documentation reading that generic web browser
 * Documancer can create fulltext index for the docs and enables the user
   to quickly search it
 * Bookmarks and indexes are manual-specific, which reduces false matches and
   chaos in bookmarks


  Requirements
================

Documancer requires several other programs and libraries:
- Python >= 2.3
- Mozilla >= 1.3
- wxPython >= 2.4.0
- Perl
- PyLucene or Java
- wxMozilla >= 0.5.3

Recommended:
wxPython >= 2.5.3, PyLucene >= 0.9.6, Python >= 2.4


  Installation
================

The usual way:
  ./configure && make && make install

If you are upgrading from version 0.1.x, you will have to setup everything
again because the way books configurations are stored changed in 0.2.0. It is
recommended to delete your old ~/.documancer directory before using newer
version.

Installing wxPython and wxMozilla (before installing Documancer): 
1. Install Mozilla (you must have Mozilla's headers as well (usually in
   mozilla-dev(el) package in your distribution, version at least 1.3).
2. Install wxPython. Note that both wxPython and Mozilla must be compiled with
   same (major) version of GCC! This is a problem if you are using RPMs
   from www.wxpython.org because they were compiled with gcc-2.96 while most
   current distributions come with Mozilla compiled with gcc-3.x. The best
   is to compile wxPython yourself (e.g. from .src.rpm) with system's default
   compiler or use the version that is part of your distribution.
3. Install wxMozilla. Use ./configure --enable-python, otherwise the Python
   module needed by Documancer won't be installed.


  Usage
=========

The basic concept of Documancer is books concept. A *book* is one piece of
documentation (a manual or info section). You have to add books to Documancer
before you can use it.

 Adding books
--------------

Go to 'File/Configure books' menu. There's a (initially empty) list of books.
Click on 'New' and fill-in information in the dialog that appeared. 'Title' is
arbitrary descriptive text that is used in the UI to identify the book.
'Location' tells Documancer where to find the data. It is made of two parts:
documentation kind identification (HTML, Info pages, Man pages) and URL that is 
kind-specific:

  * HTML: absolute filename of book's entry page (usually index.html, 
    e.g. "/usr/share/doc/doxygen/index.html")

  * Info pages: info node name (e.g. "autoconf") or "index.html" (which will
    display index of all info manuals installed in the system)

  * Man pages: "index.html" for the list of all sections, "${section_number}/"
    for index of particular section or "${section_number}/%{manpage}.html" for
    particular manpage


 Keyboard shortcuts
--------------------

    Alt-Left         go back in browsing history
    Alt-Right        go forward in browsing history
    Alt-B            focus bookmarks list
    Alt-I            focus search query text box
    Alt-L            focus search results
    Alt-O            focus the browser window


  License
===========

The code is released under GPL version 2. If you'd like to reuse the code under
a non-GPL OpenSource license, feel free to contact me, I'm not a GPL fanatic.


  Author
==========

mailto:vslavik@fastmail.fm
