From ba917f174bdcf852e0d5c49bc0c1cc30c9075d8d Mon Sep 17 00:00:00 2001 From: Sebastian Ramacher Date: Tue, 18 Feb 2014 16:36:04 +0100 Subject: [PATCH 01/65] Make the documentation match the code Signed-off-by: Sebastian Ramacher --- zathurarc.5.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/zathurarc.5.rst b/zathurarc.5.rst index 1559870..5d44a48 100644 --- a/zathurarc.5.rst +++ b/zathurarc.5.rst @@ -697,7 +697,7 @@ Defines the proportion of the current viewing area that should be visible after scrolling a full page. * Value type: Float -* Default value: 0.1 +* Default value: 0 scroll-wrap ^^^^^^^^^^^ From ab9f5515b5fe136bcdc419bd871714acde4743f6 Mon Sep 17 00:00:00 2001 From: Sebastian Ramacher Date: Sat, 22 Feb 2014 22:18:17 +0100 Subject: [PATCH 02/65] Start documenting shortcut functions in more detail Signed-off-by: Sebastian Ramacher --- zathurarc.5.rst | 120 +++++++++++++++++++++++++++++++++++++----------- 1 file changed, 94 insertions(+), 26 deletions(-) diff --git a/zathurarc.5.rst b/zathurarc.5.rst index 5d44a48..c73cf19 100644 --- a/zathurarc.5.rst +++ b/zathurarc.5.rst @@ -206,35 +206,103 @@ Shortcut functions ^^^^^^^^^^^^^^^^^^ The following shortcut functions can be mapped: +* ``abort`` -:: + Switch back to normal mode. - Function Description +* ``adjust_window`` - abort Switch back to normal mode - adjust_window Adjust page width - change_mode Change current mode - display_link Display link target - focus_inputbar Focus inputbar - follow Follow a link - goto Go to a certain page - jumplist Move forwards/backwards in the jumplist - navigate Navigate to the next/previous page - navigate_index Navigate through the index - print Show the print dialog - 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_page_mode Toggle between one and multiple pages per row - toggle_statusbar Show or hide statusbar - zoom Zoom in or out + Adjust page width. Possible arguments are ``best-fit`` and ``width``. + +* ``change_mode`` + + Change current mode. Pass the desired mode as argument. + +* ``display_link``: + + Display link target. + +* ``focus_inputbar`` + + Focus inputbar. + +* ``follow`` + + Follow a link. + +* ``goto`` + + Go to a certain page. + +* ``jumplist`` + + Move forwards/backwards in the jumplist. + +* ``navigate`` + + Navigate to the next/previous page. + +* ``navigate_index`` + + Navigate through the index. + +* ``print`` + + Show the print dialog. + +* ``quit`` + + Quit zathura. + +* ``recolor`` + + Recolor pages. + +* ``reload`` + + Reload the document. + +* ``rotate`` + + Rotate the page. Pass ``rotate-ccw`` as argument for counterclockwise rotation + and ``rotate-cw`` for clockwise rotation. + +* ``scroll`` + + Scroll. + +* ``search`` + + Search next/previous item. Pass ``forward`` as argument to search for the next + hit and ``backward`` to search for the previous hit. + +* ``set`` + + Set an option. + +* ``toggle_fullscreen`` + + Toggle fullscreen. + +* ``toggle_index`` + + Show or hide index. + +* ``toggle_inputbar`` + + Show or hide inputbar. + +* ``toggle_page_mode`` + + Toggle between one and multiple pages per row. + +* ``toggle_statusbar`` + + Show or hide statusbar. + +* ``zoom`` + + Zoom in or out. Pass arguments ^^^^^^^^^^^^^^ From 797b83bfed22da6f18eee97e5db949f7f78fbe6c Mon Sep 17 00:00:00 2001 From: Sebastian Ramacher Date: Mon, 7 Apr 2014 15:48:12 +0200 Subject: [PATCH 03/65] Some more debug output for synctex Signed-off-by: Sebastian Ramacher --- dbus-interface.c | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/dbus-interface.c b/dbus-interface.c index eeee0f4..42be64c 100644 --- a/dbus-interface.c +++ b/dbus-interface.c @@ -170,7 +170,8 @@ highlight_rects(zathura_t* zathura, unsigned int page, document_draw_search_results(zathura, true); - if (rectangles[page] == NULL || girara_list_size(rectangles[page]) == 0) { + girara_list_t* rect_list = rectangles[page]; + if (rect_list == NULL || girara_list_size(rect_list) == 0) { page_set(zathura, page); return; } @@ -195,7 +196,13 @@ highlight_rects(zathura_t* zathura, unsigned int page, /* Need to adjust rectangle to page scale and orientation */ zathura_page_t* doc_page = zathura_document_get_page(zathura->document, page); - zathura_rectangle_t* rect = girara_list_nth(rectangles[page], 0); + zathura_rectangle_t* rect = girara_list_nth(rect_list, 0); + if (rect == NULL) { + girara_debug("List of rects is broken."); + page_set(zathura, page); + return; + } + zathura_rectangle_t rectangle = recalc_rectangle(doc_page, *rect); /* compute the center of the rectangle, which will be aligned to the center @@ -283,6 +290,7 @@ handle_method_call(GDBusConnection* UNUSED(connection), &secondary_iter); if (page >= number_of_pages) { + girara_debug("Got invalid page number."); GVariant* result = g_variant_new("(b)", false); g_variant_iter_free(iter); g_variant_iter_free(secondary_iter); From 2d785cc20db2c7a2a162556585130762ba92a6f4 Mon Sep 17 00:00:00 2001 From: Sebastian Ramacher Date: Mon, 7 Apr 2014 16:00:19 +0200 Subject: [PATCH 04/65] Check indices before accessing the list Signed-off-by: Sebastian Ramacher --- page-widget.c | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/page-widget.c b/page-widget.c index ae1cb19..98b983a 100644 --- a/page-widget.c +++ b/page-widget.c @@ -310,9 +310,9 @@ zathura_page_widget_set_property(GObject* object, guint prop_id, const GValue* v priv->search.current = girara_list_size(priv->search.list); } else { priv->search.current = val; - zathura_rectangle_t* rect = girara_list_nth(priv->search.list, priv->search.current); - zathura_rectangle_t rectangle = recalc_rectangle(priv->page, *rect); - if (priv->search.draw) { + if (priv->search.draw == true && val >= 0 && val < (signed) girara_list_size(priv->search.list)) { + zathura_rectangle_t* rect = girara_list_nth(priv->search.list, priv->search.current); + zathura_rectangle_t rectangle = recalc_rectangle(priv->page, *rect); redraw_rect(pageview, &rectangle); } } From 950a52b612cbf39239cfe6c6db6c9e84922828f0 Mon Sep 17 00:00:00 2001 From: Sebastian Ramacher Date: Mon, 7 Apr 2014 16:16:47 +0200 Subject: [PATCH 05/65] Another round of debug output for synctex. Signed-off-by: Sebastian Ramacher --- dbus-interface.c | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/dbus-interface.c b/dbus-interface.c index 42be64c..f628bf5 100644 --- a/dbus-interface.c +++ b/dbus-interface.c @@ -172,6 +172,7 @@ highlight_rects(zathura_t* zathura, unsigned int page, girara_list_t* rect_list = rectangles[page]; if (rect_list == NULL || girara_list_size(rect_list) == 0) { + girara_debug("No rectangles for the given page. Jumping to page %u.", page); page_set(zathura, page); return; } @@ -198,7 +199,7 @@ highlight_rects(zathura_t* zathura, unsigned int page, zathura_page_t* doc_page = zathura_document_get_page(zathura->document, page); zathura_rectangle_t* rect = girara_list_nth(rect_list, 0); if (rect == NULL) { - girara_debug("List of rects is broken."); + girara_debug("List of rectangles is broken. Jumping to page %u.", page); page_set(zathura, page); return; } @@ -216,6 +217,7 @@ highlight_rects(zathura_t* zathura, unsigned int page, } /* move to position */ + girara_debug("Jumping to page %u position (%f, %f).", page, pos_x, pos_y); zathura_jumplist_add(zathura); position_set(zathura, pos_x, pos_y); zathura_jumplist_add(zathura); From 06205940bb7be768d95af42266fdd187b7c504e1 Mon Sep 17 00:00:00 2001 From: Sebastian Ramacher Date: Mon, 7 Apr 2014 16:36:48 +0200 Subject: [PATCH 06/65] Do not call HighlightRects if there was no usable output from synctex view Signed-off-by: Sebastian Ramacher --- main.c | 2 +- synctex.c | 8 ++++++++ 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/main.c b/main.c index fa2b484..002860e 100644 --- a/main.c +++ b/main.c @@ -110,7 +110,7 @@ main(int argc, char* argv[]) free(real_path); return 0; } else { - girara_error("Could not find open instance for '%s'", real_path); + girara_error("Could not find open instance for '%s' or got no usable output from 'synctex view'.", real_path); free(real_path); return -1; } diff --git a/synctex.c b/synctex.c index 05d1edd..949ac54 100644 --- a/synctex.c +++ b/synctex.c @@ -1,6 +1,7 @@ /* See LICENSE file for license and copyright information */ #include +#include #include "synctex.h" #include "zathura.h" @@ -259,6 +260,13 @@ synctex_rectangles_from_position(const char* filename, const char* position, g_scanner_destroy(scanner); close(output); + if (ret == false) { + girara_debug("Got no usable output from running synctex view."); + girara_list_free(hitlist); + girara_list_free(other_rects); + return NULL; + } + if (page != NULL) { *page = rpage; } From df25afd5ed978f2b5d1b94d6dcb7366f14d53361 Mon Sep 17 00:00:00 2001 From: Sebastian Ramacher Date: Mon, 7 Apr 2014 16:39:31 +0200 Subject: [PATCH 07/65] Add a note about column and line numbers Signed-off-by: Sebastian Ramacher --- zathura.1.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/zathura.1.rst b/zathura.1.rst index 18f704a..fd98143 100644 --- a/zathura.1.rst +++ b/zathura.1.rst @@ -61,7 +61,8 @@ OPTIONS --synctex-forward [input] Jump to the given position. The switch expcects the same format as specified - for syntex's view -i. + for synctex's view -i. Please note that synctex starts counting at 0, so line + and column numbers need to be adjusted accordingly. --synctex-pid [pid] If not -1, forward synctex input to process with the given pid. Otherwise, try From 8bd390d39627c61cc1939d028805a3a7e3da588d Mon Sep 17 00:00:00 2001 From: Moritz Lipp Date: Tue, 8 Apr 2014 19:56:31 +0200 Subject: [PATCH 08/65] Use sphinx for documentation --- .gitignore | 5 +++- Makefile | 4 +-- README | 3 +++ Doxyfile => doc/Doxyfile | 10 +++---- doc/Makefile | 28 ++++++++++++++++++++ doc/api/index.rst | 2 ++ doc/conf.py | 53 +++++++++++++++++++++++++++++++++++++ doc/config.mk | 7 +++++ doc/configuration/index.rst | 2 ++ doc/faq.rst | 2 ++ doc/index.rst | 25 +++++++++++++++++ doc/installation/index.rst | 2 ++ doc/requirements.txt | 7 +++++ doc/usage/index.rst | 2 ++ 14 files changed, 144 insertions(+), 8 deletions(-) rename Doxyfile => doc/Doxyfile (80%) create mode 100644 doc/Makefile create mode 100644 doc/api/index.rst create mode 100644 doc/conf.py create mode 100644 doc/config.mk create mode 100644 doc/configuration/index.rst create mode 100644 doc/faq.rst create mode 100644 doc/index.rst create mode 100644 doc/installation/index.rst create mode 100644 doc/requirements.txt create mode 100644 doc/usage/index.rst diff --git a/.gitignore b/.gitignore index 4fdda19..3288eef 100644 --- a/.gitignore +++ b/.gitignore @@ -13,9 +13,12 @@ zathura.pc gcov/ *.swp version.h -doc/ +./doc/_build *.tmp zathura.1 zathurarc.5 .version-checks/ dbus-interface-definitions.c +.ycm_extra_conf.py +.ropeproject +compile_commands.json diff --git a/Makefile b/Makefile index 9f3c0ba..3600061 100644 --- a/Makefile +++ b/Makefile @@ -99,7 +99,6 @@ clean: ${PROJECT}-debug \ .depend \ ${PROJECT}.pc \ - doc \ version.h \ version.h.tmp \ dbus-interface-definitions.c \ @@ -111,6 +110,7 @@ ifneq "$(wildcard ${RSTTOMAN})" "" endif $(QUIET)$(MAKE) -C tests clean $(QUIET)$(MAKE) -C po clean + $(QUIET)$(MAKE) -C doc clean ${PROJECT}-debug: ${DOBJECTS} $(ECHO) CC -o $@ @@ -156,7 +156,7 @@ dist: clean build-manpages $(QUIET)rm -rf ${PROJECT}-${VERSION} doc: - $(QUIET)doxygen Doxyfile + $(QUIET)make -C doc gcov: clean $(QUIET)CFLAGS="${CFLAGS} -fprofile-arcs -ftest-coverage" LDFLAGS="${LDFLAGS} -fprofile-arcs" ${MAKE} $(PROJECT) diff --git a/README b/README index 04bf619..fbdb441 100644 --- a/README +++ b/README @@ -31,6 +31,9 @@ WITH_MAGIC=0. If you pass these flags as a command line argument to make, you have to ensure to pass the same flags when executing the install target. +If you want to build zathuras documentation, please install all python +dependencies from the ./doc/requirements.txt file. + Installation ------------ To build and install zathura: diff --git a/Doxyfile b/doc/Doxyfile similarity index 80% rename from Doxyfile rename to doc/Doxyfile index f52ac20..632180a 100644 --- a/Doxyfile +++ b/doc/Doxyfile @@ -2,7 +2,7 @@ # General information PROJECT_NAME = zathura -OUTPUT_DIRECTORY = ./doc/ +OUTPUT_DIRECTORY = ./_build/doxygen/ OUTPUT_LANGUAGE = English TAB_SIZE = 2 EXTRACT_ALL = YES @@ -16,15 +16,15 @@ WARNINGS = YES WARN_IF_UNDOCUMENTED = YES # Input files -INPUT = -EXCLUDE = ./tests +INPUT = ../ +EXCLUDE = ./tests ./doc FILE_PATTERNS = *.h *.c RECURSIVE = YES # Output files -GENERATE_HTML = YES +GENERATE_HTML = NO GENERATE_LATEX = NO GENERATE_RTF = NO -GENERATE_XML = NO +GENERATE_XML = YES SOURCE_BROWSER = YES diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..731e659 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,28 @@ +# See LICENSE file for license and copyright information +# +include ../config.mk +include ../common.mk +include config.mk + +ifeq ($(shell which $(SPHINX_BIN) >/dev/null 2>&1; echo $$?), 1) + $(error The '$(SPHINX_BIN)' command was not found.) +endif + +all: init html man + +init: + $(QUIET)mkdir -p $(SPHINX_BUILDDIR)/ + +clean: + $(QUIET)rm -rf $(SPHINX_BUILDDIR)/ + +html: doxygen + $(QUIET)$(SPHINX_BIN) -b html $(SPHINX_OPTS) $(SPHINX_BUILDDIR)/html + +man: doxygen + $(QUIET)$(SPHINX_BIN) -b man $(SPHINX_OPTS) $(SPHINX_BUILDDIR)/man + +doxygen: + $(QUIET)$(DOXYGEN_BIN) Doxyfile + +.PHONY: clean html man diff --git a/doc/api/index.rst b/doc/api/index.rst new file mode 100644 index 0000000..8feb527 --- /dev/null +++ b/doc/api/index.rst @@ -0,0 +1,2 @@ +API and Development +=================== diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 0000000..763487d --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,53 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# +# See LICENSE file for license and copyright information + +import sphinx_rtd_theme + +# -- General configuration ------------------------------------------------ + +extensions = ['sphinx.ext.todo', 'breathe'] +source_suffix = '.rst' +master_doc = 'index' +templates_path = ['_templates'] +exclude_patterns = ['_build'] + +pygments_style = 'sphinx' + + +# -- Project configuration ------------------------------------------------ + +project = 'zathura' +copyright = '2014, pwmt.org' +version = '0.2.7' +release = '0.2.7' + + +# -- Options for HTML output ---------------------------------------------- + +html_theme = 'sphinx_rtd_theme' +html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] +html_static_path = ['_static'] +htmlhelp_basename = 'zathuradoc' + + +# -- Options for manual page output --------------------------------------- + +man_pages = [ + ('index', 'zathura', 'zathura Documentation', ['pwmt.org'], 1) +] + + +# -- Options for breathe --------------------------------------- + +breathe_projects = { "zathura": "_build/doxygen/xml" } +breathe_default_project = "zathura" +breathe_build_directory = "_build" +breathe_projects_source = { + "zathura": "../" +} +breathe_domain_by_extension = { + "h" : "c", + "c" : "c" +} diff --git a/doc/config.mk b/doc/config.mk new file mode 100644 index 0000000..553c28c --- /dev/null +++ b/doc/config.mk @@ -0,0 +1,7 @@ +# See LICENSE file for license and copyright information + +SPHINX_BIN = sphinx-build +SPHINX_BUILDDIR = _build +SPHINX_OPTS = -d $(SPHINX_BUILDDIR)/doctrees . + +DOXYGEN_BIN = doxygen diff --git a/doc/configuration/index.rst b/doc/configuration/index.rst new file mode 100644 index 0000000..6e79ebd --- /dev/null +++ b/doc/configuration/index.rst @@ -0,0 +1,2 @@ +Configuration +============= diff --git a/doc/faq.rst b/doc/faq.rst new file mode 100644 index 0000000..cde88d8 --- /dev/null +++ b/doc/faq.rst @@ -0,0 +1,2 @@ +FAQ +=== diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 0000000..025df07 --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,25 @@ +.. zathura documentation master file, created by + sphinx-quickstart on Tue Apr 8 18:33:05 2014. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to zathura's documentation! +=================================== + +.. toctree:: + :maxdepth: 2 + :numbered: + + installation/index + usage/index + configuration/index + api/index + faq + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/doc/installation/index.rst b/doc/installation/index.rst new file mode 100644 index 0000000..11e4437 --- /dev/null +++ b/doc/installation/index.rst @@ -0,0 +1,2 @@ +Installation +============ diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 0000000..f70a534 --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,7 @@ +Jinja2==2.7.2 +MarkupSafe==0.19 +Pygments==1.6 +Sphinx==1.2.2 +breathe==1.2.0 +docutils==0.11 +sphinx-rtd-theme==0.1.6 diff --git a/doc/usage/index.rst b/doc/usage/index.rst new file mode 100644 index 0000000..d4b9a15 --- /dev/null +++ b/doc/usage/index.rst @@ -0,0 +1,2 @@ +Usage +===== From 89a491d1bf013f994f013a85a6355a4f2c46b643 Mon Sep 17 00:00:00 2001 From: Moritz Lipp Date: Tue, 8 Apr 2014 20:47:08 +0200 Subject: [PATCH 09/65] Add installation and manpage documentation --- doc/conf.py | 2 +- doc/index.rst | 9 ++-- doc/installation/index.rst | 85 ++++++++++++++++++++++++++++++++++++++ doc/manpage.rst | 15 +++++++ 4 files changed, 104 insertions(+), 7 deletions(-) create mode 100644 doc/manpage.rst diff --git a/doc/conf.py b/doc/conf.py index 763487d..fbb8c52 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -35,7 +35,7 @@ htmlhelp_basename = 'zathuradoc' # -- Options for manual page output --------------------------------------- man_pages = [ - ('index', 'zathura', 'zathura Documentation', ['pwmt.org'], 1) + ('manpage', 'zathura', 'a document viewer', ['pwmt.org'], 1) ] diff --git a/doc/index.rst b/doc/index.rst index 025df07..3b090a6 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -16,10 +16,7 @@ Welcome to zathura's documentation! api/index faq -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` +.. toctree:: + :hidden: + manpage diff --git a/doc/installation/index.rst b/doc/installation/index.rst index 11e4437..a0f9a9d 100644 --- a/doc/installation/index.rst +++ b/doc/installation/index.rst @@ -1,2 +1,87 @@ Installation ============ + +Dependencies +------------ + +The core of zathura depends on two external libraries, +`girara `_, our simplistic user interface library and +`GTK+ `_, a cross-platform widget toolkit. +Depending on which filetypes should be supported you are going to need +additional libraries to build those file type plugins. + +Core dependencies +~~~~~~~~~~~~~~~~~ + +- `girara `_, our simplistic user interface library + (>= 0.1.8) +- `GTK+ `_, a cross-platform widget toolkit (>= + 2.28) + +Optional and build dependencies +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- `sqlite3 `_, a SQL database engine +- `intltool `_, utility scripts for + internationalization +- `check `_, a unit testing framework + for C +- libmagic from `file `_, a file type + guesser +- `docutils `_, documentation + utilities + +Stable version +-------------- + +Since zathura packages are available in many distributions it is +recommended to install it from there with your prefered package manager. +Otherwise you can grab the latest version of the source code from our +website and build it by hand: + +:: + + $ tar xfv zathura-.tar.gz + $ cd zathura- + $ make + $ make install + +Known supported distributions +----------------------------- + +- `Arch + Linux `_ +- `Debian `_ +- `Fedora `_ +- `Gentoo `_ +- `Ubuntu `_ +- `OpenBSD `_ + +Developer version +----------------- + +If you are interested in testing the very latest versions with all its +new features, that we are working on, type in the following commands. At +first you have to install the latest version of girara: + +:: + + $ git clone git://pwmt.org/girara.git + $ cd girara + $ git checkout --track -b develop origin/develop + $ make + $ make install + +After the successful installation of the user interface library, grab +the latest version of zathura and install it: + +:: + + $ git clone git://pwmt.org/zathura.git + $ cd zathura + $ git checkout --track -b develop origin/develop + $ make + $ make install + +For the installation of a file type plugin check the +`plugins <../plugins>`_ section. diff --git a/doc/manpage.rst b/doc/manpage.rst new file mode 100644 index 0000000..90235c5 --- /dev/null +++ b/doc/manpage.rst @@ -0,0 +1,15 @@ +Manpage +======= + +Synopsis +-------- + +Description +----------- + +Usage +----- + +See Also +-------- +:manpage:`zathurarc(5)` From d3a2fd8b316103769b625cba0532b2748f41a3dd Mon Sep 17 00:00:00 2001 From: Moritz Lipp Date: Tue, 8 Apr 2014 21:09:54 +0200 Subject: [PATCH 10/65] Fix documentation index --- doc/index.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/index.rst b/doc/index.rst index 3b090a6..a6de674 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -10,13 +10,13 @@ Welcome to zathura's documentation! :maxdepth: 2 :numbered: - installation/index - usage/index - configuration/index - api/index - faq + installation/index + usage/index + configuration/index + api/index + faq .. toctree:: - :hidden: + :hidden: manpage From 7bce5bb321a8c5be13e5ee7b3b7ae1919c83702a Mon Sep 17 00:00:00 2001 From: Moritz Lipp Date: Tue, 8 Apr 2014 22:05:13 +0200 Subject: [PATCH 11/65] 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