Add configuration documentation

doc/api/index.rst

@@ -1,2 +1,9 @@
 API and Development
 ===================
+
+.. toctree::
+   :maxdepth: 1
+
+   plugin-development
+
+

doc/conf.py

@@ -7,7 +7,10 @@ import sphinx_rtd_theme
 
 # -- General configuration ------------------------------------------------
 
-extensions     = ['sphinx.ext.todo', 'breathe']
+extensions     = [
+    'sphinx.ext.todo',
+    'breathe'
+]
 source_suffix  = '.rst'
 master_doc     = 'index'
 templates_path = ['_templates']

doc/configuration/index.rst

@@ -1,2 +1,25 @@
 Configuration
 =============
+
+.. toctree::
+   :maxdepth: 1
+
+   set
+   map
+   options
+
+The customization of zathura is be managed via a configuration file
+called *zathurarc*. By default zathura will evaluate the following
+files:
+
+-  */etc/zathurarc*
+-  *$XDG\_CONFIG\_HOME/zathura/zathurarc* (default:
+   ~/.config/zathura/zathurarc)
+
+The *zathurarc* file is a simple plain text file that can be populated
+with various commands to change the behaviour and the look of zathura
+which we are going to describe in the following subsections. Each line
+(besides empty lines and comments (which start with a prepended *#*) is
+evaluated on its own, so it is not possible to write multiple commands
+in one single line.
+

doc/configuration/map.rst

@@ -0,0 +1,266 @@
+map - Mapping a shortcut
+========================
+
+It is possible to map or remap new key bindings to shortcut functions
+which allows a high level of customization. The *:map* command can also
+be used in the *zathurarc* file to make those changes permanent:
+
+::
+
+    map [mode] <binding> <shortcut function> <argument>
+
+Mode
+----
+
+The *map* command expects several arguments where only the *binding* as
+well as the *shortcut-function* argument is required. Since zathura uses
+several modes it is possible to map bindings only for a specific mode by
+passing the *mode* argument which can take one of the following values:
+
+-  normal (default)
+-  visual
+-  insert
+-  fullscreen
+-  index
+
+The brackets around the value are mandatory.
+
+Single key binding
+~~~~~~~~~~~~~~~~~~
+
+The (possible) second argument defines the used key binding that should
+be mapped to the shortcut function and is structured like the following.
+On the one hand it is possible to just assign single letters, numbers or
+signs to it:
+
+::
+
+    map a shortcut_function
+    map b shortcut_function
+    map c shortcut_function
+    map 1 shortcut_function
+    map 2 shortcut_function
+    map 3 shortcut_function
+    map ! shortcut_function
+    map ? shortcut_function
+
+Using modifiers
+---------------
+
+It is also possible to use modifiers like the *Control* or *Alt* button
+on the keyboard. It is possible to use the following modifiers:
+
+-  A - *Alt*
+-  C - *Control*
+-  S - *Shift*
+
+Now it is required to define the *binding* with the following structure:
+
+::
+
+    map <A-a> shortcut_function
+    map <C-a> shortcut_function
+
+Special keys
+------------
+
+zathura allows it also to assign keys like the space bar or the tab
+button which also have to be written in between angle brackets. The
+following special keys are currently available:
+
++--------------+--------------------+
+| Identifier   | Description        |
++==============+====================+
+| BackSpace    | *Back space*       |
++--------------+--------------------+
+| CapsLock     | *Caps lock*        |
++--------------+--------------------+
+| Esc          | *Escape*           |
++--------------+--------------------+
+| Down         | *Arrow down*       |
++--------------+--------------------+
+| Up           | *Arrow up*         |
++--------------+--------------------+
+| Left         | *Arrow left*       |
++--------------+--------------------+
+| Right        | *Arrow right*      |
++--------------+--------------------+
+| F1           | *F1*               |
++--------------+--------------------+
+| F2           | *F2*               |
++--------------+--------------------+
+| F3           | *F3*               |
++--------------+--------------------+
+| F4           | *F4*               |
++--------------+--------------------+
+| F5           | *F5*               |
++--------------+--------------------+
+| F6           | *F6*               |
++--------------+--------------------+
+| F7           | *F7*               |
++--------------+--------------------+
+| F8           | *F8*               |
++--------------+--------------------+
+| F9           | *F9*               |
++--------------+--------------------+
+| F10          | *F10*              |
++--------------+--------------------+
+| F11          | *F11*              |
++--------------+--------------------+
+| F12          | *F12*              |
++--------------+--------------------+
+| PageDown     | *Page Down*        |
++--------------+--------------------+
+| PageUp       | *Page Up*          |
++--------------+--------------------+
+| Return       | *Return*           |
++--------------+--------------------+
+| Space        | *Space*            |
++--------------+--------------------+
+| Super        | *Windows button*   |
++--------------+--------------------+
+| Tab          | *Tab*              |
++--------------+--------------------+
+
+Of course it is possible to combine those special keys with a modifier.
+The usage of those keys should be explained by the following examples:
+
+::
+
+    map <Space> shortcut_function
+    map <C-Space> shortcut_function
+
+Mouse buttons
+-------------
+
+It is also possible to map mouse buttons to shortcuts by using the
+following special keys:
+
++--------------+--------------------+
+| Identifier   | Description        |
++==============+====================+
+| Button1      | *Mouse button 1*   |
++--------------+--------------------+
+| Button2      | *Mouse button 2*   |
++--------------+--------------------+
+| Button3      | *Mouse button 3*   |
++--------------+--------------------+
+| Button4      | *Mouse button 4*   |
++--------------+--------------------+
+| Button5      | *Mouse button 5*   |
++--------------+--------------------+
+
+They can also be combined with modifiers:
+
+::
+
+    map <Button1> shortcut_function
+    map <C-Button1> shortcut_function
+
+Buffer commands
+---------------
+
+If a mapping does not match one of the previous definition but is still
+a valid mapping it will be mapped as a buffer command:
+
+::
+
+    map abc quit
+    map test quit
+
+Shortcut functions
+------------------
+
+The following shortcut functions can be mapped:
+
++----------------------+----------------------------------------+
+| Function             | Description                            |
++======================+========================================+
+| abort                | *Switch back to normal mode*           |
++----------------------+----------------------------------------+
+| adjust\_window       | *Adjust page width*                    |
++----------------------+----------------------------------------+
+| change\_mode         | *Change current mode*                  |
++----------------------+----------------------------------------+
+| follow               | *Follow a link*                        |
++----------------------+----------------------------------------+
+| focus\_inputbar      | *Focus inputbar*                       |
++----------------------+----------------------------------------+
+| goto                 | *Go to a certain page*                 |
++----------------------+----------------------------------------+
+| index\_navigate      | *Navigate through the index*           |
++----------------------+----------------------------------------+
+| navigate             | *Navigate to the next/previous page*   |
++----------------------+----------------------------------------+
+| quit                 | *Quit zathura*                         |
++----------------------+----------------------------------------+
+| recolor              | *Recolor the pages*                    |
++----------------------+----------------------------------------+
+| reload               | *Reload the document*                  |
++----------------------+----------------------------------------+
+| rotate               | *Rotate the page*                      |
++----------------------+----------------------------------------+
+| scroll               | *Scroll*                               |
++----------------------+----------------------------------------+
+| search               | *Search next/previous item*            |
++----------------------+----------------------------------------+
+| set                  | *Set an option*                        |
++----------------------+----------------------------------------+
+| toggle\_fullscreen   | *Toggle fullscreen*                    |
++----------------------+----------------------------------------+
+| toggle\_index        | *Show or hide index*                   |
++----------------------+----------------------------------------+
+| toggle\_inputbar     | *Show or hide inputbar*                |
++----------------------+----------------------------------------+
+| toggle\_statusbar    | *Show or hide statusbar*               |
++----------------------+----------------------------------------+
+| zoom                 | *Zoom in or out*                       |
++----------------------+----------------------------------------+
+
+Pass arguments
+--------------
+
+Some shortcut function require or have optional arguments which
+influence the behaviour of them. Those can be passed as the last
+argument:
+
+::
+
+    map <C-i> zoom in
+    map <C-o> zoom out
+
+Possible arguments are:
+
+-  bottom
+-  default
+-  down
+-  full-down
+-  full-up
+-  half-down
+-  half-up
+-  in
+-  left
+-  next
+-  out
+-  previous
+-  right
+-  specific
+-  top
+-  up
+-  best-fit
+-  width
+-  rotate-cw
+-  rotate-ccw
+
+unmap - Removing a shortcut
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In addition to mapping or remaping custom key bindings it is possible to
+remove existing ones by using the *:unmap* command. The command is used
+in the following way (the explanation of the parameters is described in
+the *map* section of this document
+
+::
+
+    unmap [mode] <binding>
+

doc/configuration/options.rst

@@ -0,0 +1,164 @@
+Configuration options
+=====================
+
+General settings
+----------------
+
+.. describe:: abort-clear-search
+
+  Defines if the search results should be cleared on abort.
+
+   :type: Boolean
+   :default: True
+
+.. describe:: adjust-open
+
+  Defines which auto adjustment mode should be used if a document is
+  loaded. Possible options are "best-fit" and "width".
+
+	 :type: String
+	 :default: best-fit
+
+.. describe:: advance-ds-per-row
+
+  Defines if the number of pages per row should be honored when advancing
+  a page.
+
+	 :type: Boolean
+	 :default: false
+
+.. describe:: database
+
+  Defines the used database backend. Possible options are 'plain' and
+  'sqlite'
+
+	 :type: String
+	 :default: plain
+
+.. describe:: highlight-color
+
+  Defines the color that is used for highlighting parts of the document
+  (e.g.: show search results)
+
+	 :type: String
+	 :default: #9FBC00
+
+.. describe:: highlight-active-color
+
+  Defines the color that is used to show the current selected highlighted
+  element (e.g: current search result)
+
+	 :type: String
+	 :default: #00BC00
+
+.. describe:: highlight-transparency
+
+  Defines the opacity of a highlighted element
+
+	 :type: Float
+	 :default: 0.5
+
+.. describe:: page-padding
+
+  The page padding defines the gap in pixels between each rendered page.
+
+	 :type: Integer
+	 :default: 1
+
+.. describe:: page-store-threshold
+
+  Pages that are not visible get unloaded after some time. Every page that
+  has not been visible for page-store-treshold seconds will be unloaded.
+
+	 :type: Integer
+	 :default: 30
+
+.. describe:: page-store-interval
+
+  Defines the amount of seconds between the check to unload invisible
+  pages.
+
+	 :type: Integer
+	 :default: 30
+
+.. describe:: pages-per-row
+
+  Defines the number of pages that are rendered next to each other in a
+  row.
+
+	 :type: Integer
+	 :default: 1
+
+.. describe:: recolor
+
+  En/Disables recoloring
+
+	 :type: Boolean
+	 :default: false
+
+.. describe:: recolor-darkcolor
+
+  Defines the color value that is used to represent dark colors in
+  recoloring mode
+
+	 :type: String
+	 :default: #FFFFFF
+
+.. describe:: recolor-lightcolor
+
+  Defines the color value that is used to represent light colors in
+  recoloring mode
+
+	 :type: String
+	 :default: #000000
+
+.. describe:: render-loading
+
+  Defines if the "Loading..." text should be displayed if a page is
+  rendered.
+
+	 :type: Boolean
+	 :default: true
+
+.. describe:: scroll-step
+
+  Defines the step size of scrolling by calling the scroll command once
+
+	 :type: Float
+	 :default: 40
+
+.. describe:: scroll-wrap
+
+  Defines if the last/first page should be wrapped
+
+	 :type: Boolean
+	 :default: false
+
+.. describe:: zoom-max
+
+  Defines the maximum percentage that the zoom level can be
+
+	 :type: Integer
+	 :default: 1000
+
+.. describe:: zoom-min
+
+  Defines the minimum percentage that the zoom level can be
+
+	 :type: Integer
+	 :default: 10
+
+.. describe:: zoom-step
+
+  Defines the amount of percent that is zoomed in or out on each comand.
+
+	 :type: Integer
+	 :default: 10
+
+Girara settings
+---------------
+
+Most of the options affecting the appearance of zathura are derived from
+the options that are offered by our user interface library called girara
+and can be found in its `documentation </projects/girara/options>`_.
+Those values can also be set via the *zathurarc* file.

doc/configuration/set.rst

@@ -0,0 +1,37 @@
+set - Changing options
+======================
+
+In addition to the build-in *:set* command zathura offers more options
+to be changed and makes those changes permanent. To overwrite an option
+you just have to add a line structured like the following
+
+::
+
+    set <option> <new value>
+
+The *option* field has to be replaced with the name of the option that
+should be changed and the *new value* field has to be replaced with the
+new value the option should get. The type of the value can be one of the
+following:
+
+-  INT - An integer number
+-  FLOAT - A floating point number
+-  STRING - A character string
+-  BOOL - A boolean value ("true" for true, "false" for false)
+
+In addition we advice you to check the options to get a more detailed
+view of the options that can be changed and which values they should be
+set to.
+
+The following example should give some deeper insight of how the *set*
+command can be used
+
+::
+
+    set option1 5
+    set option2 2.0
+    set option3 hello
+    set option4 hello\ world
+    set option5 "hello world"
+    set option6 "#00BB00"
+

doc/usage/index.rst

@@ -1,2 +1,7 @@
+*****
 Usage
-=====
+*****
+
+Commandline invocation
+======================
+.. include:: synopsis.rst