From 7bce5bb321a8c5be13e5ee7b3b7ae1919c83702a Mon Sep 17 00:00:00 2001 From: Moritz Lipp Date: Tue, 8 Apr 2014 22:05:13 +0200 Subject: [PATCH] Add configuration documentation --- doc/api/index.rst | 7 + doc/conf.py | 5 +- doc/configuration/index.rst | 23 +++ doc/configuration/map.rst | 266 ++++++++++++++++++++++++++++++++++ doc/configuration/options.rst | 164 +++++++++++++++++++++ doc/configuration/set.rst | 37 +++++ doc/usage/index.rst | 7 +- 7 files changed, 507 insertions(+), 2 deletions(-) create mode 100644 doc/configuration/map.rst create mode 100644 doc/configuration/options.rst create mode 100644 doc/configuration/set.rst diff --git a/doc/api/index.rst b/doc/api/index.rst index 8feb527..6bab589 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -1,2 +1,9 @@ API and Development =================== + +.. toctree:: + :maxdepth: 1 + + plugin-development + + diff --git a/doc/conf.py b/doc/conf.py index fbb8c52..e9be721 100644 --- a/doc/conf.py +++ b/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'] diff --git a/doc/configuration/index.rst b/doc/configuration/index.rst index 6e79ebd..072f32a 100644 --- a/doc/configuration/index.rst +++ b/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. + diff --git a/doc/configuration/map.rst b/doc/configuration/map.rst new file mode 100644 index 0000000..0e0ed6c --- /dev/null +++ b/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] + +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 shortcut_function + map 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 shortcut_function + map 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 shortcut_function + map 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 zoom in + map 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] + diff --git a/doc/configuration/options.rst b/doc/configuration/options.rst new file mode 100644 index 0000000..cc43286 --- /dev/null +++ b/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 `_. +Those values can also be set via the *zathurarc* file. diff --git a/doc/configuration/set.rst b/doc/configuration/set.rst new file mode 100644 index 0000000..0e0e066 --- /dev/null +++ b/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