mirrors/zathura
1
0
Fork 0
mirror of https://git.pwmt.org/pwmt/zathura.git synced 2025-01-16 06:05:50 +01:00
Code Issues Projects Releases Packages Wiki Activity

Merge branch 'feature/sphinx' into develop

Browse source
This commit is contained in:
Moritz Lipp 2014-04-20 01:45:59 +02:00
commit fb088e1fe0
31 changed files with 1321 additions and 273 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
.gitignore vendored
View file

@ -13,9 +13,12 @@ zathura.pc
gcov/ gcov/
*.swp *.swp
version.h version.h
doc/ ./doc/_build
*.tmp *.tmp
zathura.1 zathura.1
zathurarc.5 zathurarc.5
.version-checks/ .version-checks/
dbus-interface-definitions.c dbus-interface-definitions.c
.ycm_extra_conf.py
.ropeproject
compile_commands.json

42
Makefile
View file

@ -99,7 +99,6 @@ clean:
${PROJECT}-debug \ ${PROJECT}-debug \
.depend \ .depend \
${PROJECT}.pc \ ${PROJECT}.pc \
doc \
version.h \ version.h \
version.h.tmp \ version.h.tmp \
dbus-interface-definitions.c \ dbus-interface-definitions.c \
@ -111,6 +110,7 @@ ifneq "$(wildcard ${RSTTOMAN})" ""
endif endif
$(QUIET)$(MAKE) -C tests clean $(QUIET)$(MAKE) -C tests clean
$(QUIET)$(MAKE) -C po clean $(QUIET)$(MAKE) -C po clean
$(QUIET)$(MAKE) -C doc clean
${PROJECT}-debug: ${DOBJECTS} ${PROJECT}-debug: ${DOBJECTS}
$(ECHO) CC -o $@ $(ECHO) CC -o $@
@ -142,12 +142,26 @@ dist: clean build-manpages
$(QUIET)mkdir -p ${PROJECT}-${VERSION} $(QUIET)mkdir -p ${PROJECT}-${VERSION}
$(QUIET)mkdir -p ${PROJECT}-${VERSION}/tests $(QUIET)mkdir -p ${PROJECT}-${VERSION}/tests
$(QUIET)mkdir -p ${PROJECT}-${VERSION}/po $(QUIET)mkdir -p ${PROJECT}-${VERSION}/po
$(QUIET)cp LICENSE Makefile config.mk common.mk README AUTHORS Doxyfile \ $(QUIET)mkdir -p ${PROJECT}-${VERSION}/doc
$(QUIET)cp LICENSE Makefile config.mk common.mk README AUTHORS \
${PROJECT}.1.rst ${PROJECT}rc.5.rst ${OSOURCE} ${HEADER} ${PROJECT}.pc.in \ ${PROJECT}.1.rst ${PROJECT}rc.5.rst ${OSOURCE} ${HEADER} ${PROJECT}.pc.in \
${PROJECT}.desktop version.h.in \ ${PROJECT}.desktop version.h.in \
${PROJECT}.1 ${PROJECT}rc.5 \ ${PROJECT}.1 ${PROJECT}rc.5 \
${PROJECT}-${VERSION} ${PROJECT}-${VERSION}
$(QUIET)cp -r data ${PROJECT}-${VERSION} $(QUIET)cp -r data ${PROJECT}-${VERSION}
$(QUIET)cp -r \
doc/Makefile \
doc/Doxyfile \
doc/config.mk \
doc/conf.py \
doc/*.rst \
doc/requirements.txt \
doc/api \
doc/configuration \
doc/installation \
doc/man \
doc/usage \
${PROJECT}-${VERSION}/doc
$(QUIET)cp tests/Makefile tests/config.mk tests/*.c \ $(QUIET)cp tests/Makefile tests/config.mk tests/*.c \
${PROJECT}-${VERSION}/tests ${PROJECT}-${VERSION}/tests
$(QUIET)cp po/Makefile po/*.po ${PROJECT}-${VERSION}/po $(QUIET)cp po/Makefile po/*.po ${PROJECT}-${VERSION}/po
@ -156,7 +170,7 @@ dist: clean build-manpages
$(QUIET)rm -rf ${PROJECT}-${VERSION} $(QUIET)rm -rf ${PROJECT}-${VERSION}
doc: doc:
$(QUIET)doxygen Doxyfile $(QUIET)make -C doc
gcov: clean gcov: clean
$(QUIET)CFLAGS="${CFLAGS} -fprofile-arcs -ftest-coverage" LDFLAGS="${LDFLAGS} -fprofile-arcs" ${MAKE} $(PROJECT) $(QUIET)CFLAGS="${CFLAGS} -fprofile-arcs -ftest-coverage" LDFLAGS="${LDFLAGS} -fprofile-arcs" ${MAKE} $(PROJECT)
@ -170,29 +184,17 @@ po:
update-po: update-po:
$(QUIET)${MAKE} -C po update-po $(QUIET)${MAKE} -C po update-po
ifneq "$(wildcard ${RSTTOMAN})" ""
%.1 %.5: config.mk
$(QUIET)sed "s/VERSION/${VERSION}/g" < $@.rst > $@.tmp
$(QUIET)${RSTTOMAN} $@.tmp > $@.out.tmp
$(QUIET)mv $@.out.tmp $@
$(QUIET)rm $@.tmp
${PROJECT}.1: ${PROJECT}.1.rst
${PROJECT}rc.5: ${PROJECT}rc.5.rst
build-manpages: ${PROJECT}.1 ${PROJECT}rc.5
else
build-manpages: build-manpages:
endif $(QUIET)${MAKE} -C doc man
install-manpages: build-manpages install-manpages: build-manpages
$(ECHO) installing manual pages $(ECHO) installing manual pages
$(QUIET)mkdir -m 755 -p ${DESTDIR}${MANPREFIX}/man1 ${DESTDIR}${MANPREFIX}/man5 $(QUIET)mkdir -m 755 -p ${DESTDIR}${MANPREFIX}/man1 ${DESTDIR}${MANPREFIX}/man5
ifneq "$(wildcard ${PROJECT}.1)" "" ifneq "$(wildcard ./doc/_build/man/${PROJECT}.1)" ""
$(QUIET)install -m 644 ${PROJECT}.1 ${DESTDIR}${MANPREFIX}/man1 $(QUIET)install -m 644 ./doc/_build/man/${PROJECT}.1 ${DESTDIR}${MANPREFIX}/man1
endif endif
ifneq "$(wildcard ${PROJECT}rc.5)" "" ifneq "$(wildcard ./doc/_build/man/${PROJECT}rc.5)" ""
$(QUIET)install -m 644 ${PROJECT}rc.5 ${DESTDIR}${MANPREFIX}/man5 $(QUIET)install -m 644 ./doc/_build/man/${PROJECT}rc.5 ${DESTDIR}${MANPREFIX}/man5
endif endif
install-headers: ${PROJECT}.pc install-headers: ${PROJECT}.pc

3
README
View file

@ -31,6 +31,9 @@ WITH_MAGIC=0.
If you pass these flags as a command line argument to make, you have to ensure 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. 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 Installation
------------ ------------
To build and install zathura: To build and install zathura:

3
config.mk
View file

@ -48,9 +48,6 @@ PLUGINDIR ?= ${LIBDIR}/zathura
# locale directory # locale directory
LOCALEDIR ?= ${PREFIX}/share/locale LOCALEDIR ?= ${PREFIX}/share/locale
# rst2man
RSTTOMAN ?= /usr/bin/rst2man
# libs # libs
GTK_INC ?= $(shell pkg-config --cflags gtk+-3.0) GTK_INC ?= $(shell pkg-config --cflags gtk+-3.0)
GTK_LIB ?= $(shell pkg-config --libs gtk+-3.0) GTK_LIB ?= $(shell pkg-config --libs gtk+-3.0)

10
Doxyfile → doc/Doxyfile
View file

@ -2,7 +2,7 @@
# General information # General information
PROJECT_NAME = zathura PROJECT_NAME = zathura
OUTPUT_DIRECTORY = ./doc/ OUTPUT_DIRECTORY = ./_build/doxygen/
OUTPUT_LANGUAGE = English OUTPUT_LANGUAGE = English
TAB_SIZE = 2 TAB_SIZE = 2
EXTRACT_ALL = YES EXTRACT_ALL = YES
@ -16,15 +16,15 @@ WARNINGS = YES
WARN_IF_UNDOCUMENTED = YES WARN_IF_UNDOCUMENTED = YES
# Input files # Input files
INPUT = INPUT = ../
EXCLUDE = ./tests EXCLUDE = ./tests ./doc
FILE_PATTERNS = *.h *.c FILE_PATTERNS = *.h *.c
RECURSIVE = YES RECURSIVE = YES
# Output files # Output files
GENERATE_HTML = YES GENERATE_HTML = NO
GENERATE_LATEX = NO GENERATE_LATEX = NO
GENERATE_RTF = NO GENERATE_RTF = NO
GENERATE_XML = NO GENERATE_XML = YES
SOURCE_BROWSER = YES SOURCE_BROWSER = YES

28
doc/Makefile Normal file
View file

@ -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: 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: init
$(QUIET)$(DOXYGEN_BIN) Doxyfile
.PHONY: clean html man

20
doc/api/index.rst Normal file
View file

@ -0,0 +1,20 @@
API and Development
===================
This guide should give a short introduction in the way zathura's plugin
system works and how you can write your own plugin and let zathura use
it.
zathura's plugin system is quite simple. At startup zathura searches
through a specified directory for shared objects and tries to load them
as plugins. Each plugin has to register itself by a name, its version, a
special function as well as its supported mimetypes to zathura. After
the registration of the plugin zathura will automatically use it to open
files with the previous defined mimetypes. That's it.
.. toctree::
:maxdepth: 2
:hidden:
plugin

245
doc/api/plugin-development.rst Normal file
View file

@ -0,0 +1,245 @@
Example - A minimalistic PDF plugin
===================================
In this section we are going to develop a simplified version of the
`zathura-pdf-poppler <../zathura-pdf-poppler>`_ plugin. For the sake of
simplicity we are not discussing the build process of the plugin because
we would recommend you to adapt our Makefiles from existing plugins. In
addition we avoid most of the error handling that should be implemented.
Prerequisites
~~~~~~~~~~~~~
In order to use the following described functions and macros you have to
include the *plugin-api.h* header file:
::
#include <zathura/plugin-api.h>
This automatically loads other header files for the
*zathura\_document\_t*, *zathura\_page\_t* as well as all the other
types that are necessary automatically.
Register the plugin
~~~~~~~~~~~~~~~~~~~
As previously described each plugin has to register itself to zathura so
that it can be used properly. Therefore we have introduced a macro
called *ZATHURA\_PLUGIN\_REGISTER* which expects several parameters:
- Plugin name *The name of the plugin*
- Major version *The plugins major version*
- Minor version *The plugins minor version*
- Revision *The plugins revision*
- Open function *The open function*
- Mimetypes *A character array of supported mime types*
In our case we are going to register our plugin "my plugin" with its
version 1.0.1, the register function *register\_functions* and the list
of supported mimetypes.
::
ZATHURA_PLUGIN_REGISTER(
"plugin-tutorial",
0, 1, 0,
register_functions,
ZATHURA_PLUGIN_MIMETYPES({
"application/pdf"
})
)
This macro will automatically generate among others a function called
*plugin\_register* which is used to register the plugin to zathura when
it has been loaded.
Register the plugin functions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In our macro we have defined that the function *register\_functions* is
used to install our functions which will implement a certain
functionality in the struct:
::
void
register_functions(zathura_plugin_functions_t* functions)
{
functions->document_open = plugin_document_open;
functions->document_free = plugin_document_free;
functions->page_init = plugin_page_init;
functions->page_clear = plugin_page_clear;
functions->page_render_cairo = plugin_page_render_cairo;
}
We are now going to give a short overview about the used functions in
the above code snippet. For a complete documentation you should checkout
the documentation of `zathura\_document\_functions\_t <../../doxygen>`_.
A document instance consists out of a *zathura\_document\_t* document
object that contains information about the document itself and a defined
number of *zathura\_page\_t* page objects. There are several functions
defined for those two types and they have to be implemented by the
plugin. For our simple plugin which will only be capable of rendering a
page we will need one function that is capable of opening the PDF
document and setting up all necessary objects for further usage and one
function which will clean up all the allocated objects afterwards. In
addition we need two of those functions for page objects as well and one
function that will actually implement the rendering process.
Open and closing a document
~~~~~~~~~~~~~~~~~~~~~~~~~~~
The first thing we have to do when opening a document is to initialize
all necessary objects and values that we are going to need for the
future use of the plugin. Therefore we have to implement our
*pdf\_document\_open* function:
::
zathura_error_t
plugin_document_open(zathura_document_t* document)
{
/* get path and password */
const char* path = zathura_document_get_path(document);
const char* password = zathura_document_get_password(document);
/* create document data */
char* uri = g_filename_to_uri(path, NULL, NULL);
PopplerDocument* poppler_document = poppler_document_new_from_file(uri, password, NULL);
g_free(uri);
if (poppler_document == NULL) {
return ZATHURA_ERROR_UNKNOWN;
}
/* save poppler document for further usage */
zathura_document_set_data(document, poppler_document);
/* get number of pages */
unsigned int number_of_pages = poppler_document_get_n_pages(poppler_document);
zathura_document_set_number_of_pages(document, number_of_pages);
return ZATHURA_ERROR_OK;
}
To open the document we retrieve the *path* and the optional *password*
of the document to create an instance of *PopplerDocument* which
represents a document in the poppler library. If this fails for any
reason (e.g.: the path does not exist, the user provided the incorrect
password) we tell zathura that this function failed for an unknown
reason. If we are lucky we continue and save the created
*poppler\_document* object in the custom data field of the document so
that we can access it later on. After that we determine the number of
pages that the document contains so that zathura can initialize every
single page.
Since we have allocated the *poppler\_document* object we have to make
sure that its resources will be freed when it is no longer needed. This
happens in our *pdf\_document\_free* function:
::
zathura_error_t
plugin_document_free(zathura_document_t* document, PopplerDocument* poppler_document)
{
g_object_unref(poppler_document);
return ZATHURA_ERROR_OK;
}
Page initialization
~~~~~~~~~~~~~~~~~~~
Each page has to be initialized so that zathura knows about its
dimension. In addition this stage is used to store additional data in
the page that will be used for further use with it. Therefore we are
implementing *pdf\_page\_init* which will save the width and the height
of the page in the given structure:
::
zathura_error_t
plugin_page_init(zathura_page_t* page)
{
unsigned int page_index = zathura_page_get_index(page);
zathura_document_t* document = zathura_page_get_document(page);
PopplerDocument* poppler_document = zathura_document_get_data(document);
/* create poppler page */
PopplerPage* poppler_page = poppler_document_get_page(poppler_document, page_index);
zathura_page_set_data(page, poppler_page);
/* get page dimensions */
double width, height;
poppler_page_get_size(poppler_page, &width, &height);
zathura_page_set_width(page, width);
zathura_page_set_height(page, height);
return ZATHURA_ERROR_OK;
}
And we have to make sure that all requested resources are freed in the
end:
::
zathura_error_t
plugin_page_clear(zathura_page_t* page, PopplerPage* poppler_page)
{
g_object_unref(poppler_page);
return ZATHURA_ERROR_OK;
}
Render a page
~~~~~~~~~~~~~
After we have setup the document and the page objects we are ready to
implement the render function which finally will be able to draw our
page on a widget so that it can be viewed with zathura. This function
has two additional parameters to the already known *zathura\_page\_t*
object: One of them is a *cairo\_t* object which will be used to render
the page, the other one is a flag called *printing* which determines if
the rendered page should be rendered for the print process of zathura.
For instance if this flag is set to true you should not render any
rectangles around links in the document because they are totally
worthless on paper:
::
zathura_error_t
pdf_page_render_cairo(zathura_page_t* page, cairo_t* cairo, bool printing)
{
if (printing == false) {
poppler_page_render(poppler_page, cairo);
} else {
poppler_page_render_for_printing(poppler_page, cairo);
}
return ZATHURA_ERROR_OK;
}
In this case the *pdf\_page\_render\_cairo* function is very simplistic
since all the work is done by the *poppler* library. In your case you
might have to do some magic here to draw the page to the cairo object.
Make sure to check out the source code of our plugins.
Installation of the plugin
~~~~~~~~~~~~~~~~~~~~~~~~~~
As we suggested earlier the easiest way to build and install the plugin
is to duplicate the *Makefile* (as long with its *common.mk* and
*config.mk* files of one of our plugins. It already contains all
necessary targets for building, installing and debugging the plugin.
Otherwise you could build the above plugin with the following command:
::
$ gcc -std=c99 -shared -fPIC -pedantic -Wall `pkg-config --cflags --libs poppler-glib zathura` \
-o pdf.so pdf.c
After that you have to copy the *pdf.so* file into the directory where
zathura looks for plugins (this is by default: */usr/lib/zathura*).

26
doc/api/plugin.rst Normal file
View file

@ -0,0 +1,26 @@
Plugin system
=============
zathura's plugin system is quite simple. At startup zathura searches
through a specified directory for shared objects and tries to load them
as plugins. Each plugin has to register itself by a name, its version, a
special function as well as its supported mimetypes to zathura. After
the registration of the plugin zathura will automatically use it to open
files with the previous defined mimetypes. That's it.
Each plugin has to implement a basic set of functionality so that it can
be used in a meaningful way with zathura. For instance it would not make
any sense if the plugin was not able to render any page at all. On the
contrary the export of images out of the document might not be
considered as that important.
We have predefined a certain set of functionality that a plugin can have
and that can be used by zathura if it has been implemented by the
plugin. When a plugin is loaded, zathura calls a certain function that
the plugin **must implemented** in order to work correctly. This
function gets a data structure which has to be filled with function
pointers by the plugin, which are then used by the main application.
.. toctree::
plugin-development

57
doc/conf.py Normal file
View file

@ -0,0 +1,57 @@
#!/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 = [
('man/zathura.1', 'zathura', 'a document viewer', ['pwmt.org'], 1),
('man/zathurarc.5', 'zathurarc', 'a document viewer', ['pwmt.org'], 5)
]
# -- 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"
}

7
doc/config.mk Normal file
View file

@ -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

25
doc/configuration/index.rst Normal file
View file

@ -0,0 +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.

266
doc/configuration/map.rst Normal file
View file

@ -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>

164
doc/configuration/options.rst Normal file
View file

@ -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.

37
doc/configuration/set.rst Normal file
View file

@ -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"

14
doc/faq.rst Normal file
View file

@ -0,0 +1,14 @@
FAQ
===
Set colors have no effect
-------------------------
If you want to overwrite a color you need to make sure that you either escape
the hash tag or put the new value between paranthesis.
::
set color red
set color \#000000
set color "#000000"

23
doc/index.rst Normal file
View file

@ -0,0 +1,23 @@
.. 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
.. toctree::
:hidden:
man/zathura.1
man/zathurarc.5

87
doc/installation/index.rst Normal file
View file

@ -0,0 +1,87 @@
Installation
============
Dependencies
------------
The core of zathura depends on two external libraries,
`girara </projects/girara/>`_, our simplistic user interface library and
`GTK+ <http://www.gtk.org/>`_, 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 </projects/girara/>`_, our simplistic user interface library
(>= 0.1.8)
- `GTK+ <http://www.gtk.org/>`_, a cross-platform widget toolkit (>=
2.28)
Optional and build dependencies
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- `sqlite3 <https://www.sqlite.org/>`_, a SQL database engine
- `intltool <https://launchpad.net/intltool>`_, utility scripts for
internationalization
- `check <http://check.sourceforge.net/>`_, a unit testing framework
for C
- libmagic from `file <http://www.darwinsys.com/file/>`_, a file type
guesser
- `docutils <http://docutils.sourceforge.net>`_, 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-<version>.tar.gz
$ cd zathura-<version>
$ make
$ make install
Known supported distributions
-----------------------------
- `Arch
Linux <http://www.archlinux.org/packages/community/x86_64/zathura>`_
- `Debian <http://packages.debian.org/en/sid/zathura>`_
- `Fedora <http://pkgs.org/fedora-rawhide/fedora-i386/zathura-0.0.8.5.fc17.i686.rpm.html>`_
- `Gentoo <http://packages.gentoo.org/package/app-text/zathura>`_
- `Ubuntu <http://packages.ubuntu.com/precise/zathura>`_
- `OpenBSD <http://openports.se/textproc/zathura>`_
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.

117
doc/man/_bindings.txt Normal file
View file

@ -0,0 +1,117 @@
General
J, PgDn
Go to the next page
K, PgUp
Go to the previous page
h, k, j, l
Scroll to the left, down, up or right direction
Left, Down, Up, Right
Scroll to the left, down, up or right direction
^t, ^d, ^u, ^y
Scroll a half page left, down, up or right
t, ^f, ^b, space, <S-space>, y
Scroll a full page left, down, up or right
gg, G, nG
Goto to the first, the last or to the nth page
H, L
Goto top or bottom of the current page
^o, ^i
Move backward and forward through the jump list
^j, ^k
Bisect forward and backward between the last two jump points
^c, Escape
Abort
a, s
Adjust window in best-fit or width mode
/, ?
Search for text
n, N
Search for the next or previous result
o, O
Open document
f
Follow links
F
Display link target
\:
Enter command
r
Rotate by 90 degrees
^r
Recolor
R
Reload document
Tab
Show index and switch to **Index mode**
d
Toggle dual page view
F5
Switch to fullscreen mode
^m
Toggle inputbar
^n
Toggle statusbar
+, -, =
Zoom in, out or to the original size
zI, zO, z0
Zoom in, out or to the original size
n=
Zoom to size n
mX
Set a quickmark to a letter or number X
'X
Goto quickmark saved at letter or number X
q
Quit
Fullscreen mode
J, K
Go to the next or previous page
space, <S-space>, <BackSpace>
Scroll a full page down or up
gg, G, nG
Goto to the first, the last or to the nth page
^c, Escape
Abort
F5
Switch to normal mode
+, -, =
Zoom in, out or to the original size
zI, zO, z0
Zoom in, out or to the original size
n=
Zoom to size n
q
Quit
Index mode
k, j
Move to upper or lower entry
l
Expand entry
L
Expand all entries
h
Collapse entry
H
Collapse all entries
space, Return
Select and open entry
Mouse bindings
Scroll
Scroll up or down
^Scroll
Zoom in or out
Hold Button2
Pan the document
Button1
Follow link

3
doc/man/_bugs.txt Normal file
View file

@ -0,0 +1,3 @@
If GDK_NATIVE_WINDOWS is enabled you will experience problems with large
documents. In this case zathura might crash or pages cannot be rendered
properly. Disabling GDK_NATIVE_WINDOWS fixes this issue.

35
doc/man/_commands.txt Normal file
View file

@ -0,0 +1,35 @@
bmark
Save a bookmark
bdelete
Delete a bookmark
blist
List bookmarks
close
Close document
exec
Execute an external command
info
Show document information
help
Show help page
open
Open a document
offset
Set page offset
print
Print document
write(!)
Save document (and force overwriting)
export
Export attachments

4
doc/man/_configuration.txt Normal file
View file

@ -0,0 +1,4 @@
The default appearance and behaviour of zathura can be overwritten by modifying
the *zathurarc* file (default path: ~/.config/zathura/zathurarc). For a detailed
description please consult zathurarc(5).

42
doc/man/_options.txt Normal file
View file

@ -0,0 +1,42 @@
-x, --reparent=xid
Reparents to window specified by xid
-c, --config-dir=path
Path to the config directory
-d, --data-dir=path
Path to the data directory
-p, --plugins-dir=path
Path to the directory containing plugins
-w, --password=password
The documents password. If multiple documents are opened at once, the
password will be used for the first one and zathura will ask for the
passwords of the remaining files if needed .
-P, --page=number
Opens the document at the given page number. Pages are numbered starting
with 1, and negative numbers indicate page numbers starting from the end
of the document, -1 being the last page.
-l, --debug=level
Set log debug level (debug, info, warning, error)
-s, --synctex
Enables synctex support
-x, --synctex-editor-command=command
Set the synctex editor command
--synctex-forward=input
Jump to the given position. The switch expects the same format as specified for synctex's view -i.
--fork
Fork into background
--version
Display version string and exit
--help
Display help and exit

8
doc/man/_synctex.txt Normal file
View file

@ -0,0 +1,8 @@
Both synctex forward and backwards synchronization are supported by zathura, To
enable synctex forward synchronization, please look at the *--syntex* and
*--synctex-editor* options. To support synctex backwards synchronization,
zathura provides a D-Bus interface that can be called by the editor. For
convince zathura also knows how to parse the output of the *synctex view*
command. It is enough to pass the arguments to *synctex view*'s *-i* option to
zathura via *--syntex-forward* and zathura will pass the information to the
correct instance.

2
doc/man/_synopsis.txt Normal file
View file

@ -0,0 +1,2 @@
zathura [-e XID] [-c PATH] [-d PATH] [-p PATH] [-w PASSWORD] [-p NUMBER]
[--fork] [-l LEVEL] [-s] [-x CMD] [--synctex-forward INPUT] <files>

41
doc/man/zathura.1.rst Normal file
View file

@ -0,0 +1,41 @@
Manpage
=======
Synopsis
--------
.. include:: _synopsis.txt
Options
-------
.. include:: _options.txt
Mouse and key bindings
----------------------
.. include:: _bindings.txt
Commands
---------
.. include:: _commands.txt
Configuration
-------------
.. include:: _configuration.txt
Synctex support
---------------
.. include:: _synctex.txt
Known bugs
----------
.. include:: _bugs.txt
See Also
--------
`zathurarc(5)`

0
zathurarc.5.rst → doc/man/zathurarc.5.rst
View file

7
doc/requirements.txt Normal file
View file

@ -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

6
doc/usage/commands.rst Normal file
View file

@ -0,0 +1,6 @@
Commands
========
By pressing colon one can execute different commands in zathura:
.. include:: ../man/_commands.txt

23
doc/usage/index.rst Normal file
View file

@ -0,0 +1,23 @@
.. 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
.. toctree::
:hidden:
man/zathura.1
man/zathurarc.5

244
zathura.1.rst
View file

@ -1,244 +0,0 @@
=======
zathura
=======
-----------------
a document viewer
-----------------
:Author: pwmt.org
:Date: VERSION
:Manual section: 1
SYNOPOSIS
=========
| zathura [OPTION]...
| zathura [OPTION]... FILE [FILE ...]
| zathura --syntex-forward INPUT FILE
DESCRIPTION
===========
zathura is a highly customizable and functional document viewer. It provides a
minimalistic and space saving interface as well as an easy usage that mainly
focuses on keyboard interaction.
OPTIONS
=======
-e [xid], --reparent [xid]
Reparents to window specified by xid
-c [path], --config-dir [path]
Path to the config directory
-d [path], --data-dir [path]
Path to the data directory
-p [path], --plugins-dir [path]
Path to the directory containing plugins
-w [password], --password [password]
The documents password. If multiple documents are opened at once, the password
will be used for the first one and zathura will ask for the passwords of the
remaining files if needed.
-P [number], --page [number]
Open the document at the given page number. Pages are numbered starting with
1, and negative numbers indicate page numbers starting from the end of the
document, -1 being the last page.
--fork
Fork into the background
-l [level], --debug [level]
Set log debug level (debug, info, warning, error)
-s, --synctex
Enable synctex support for backwards synchronization.
-x [cmd], --synctex-editor-command [cmd]
Set the synctex editor command for backwards synchronization.
--synctex-forward [input]
Jump to the given position. The switch expcects the same format as specified
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
all zathura process to find the correct one.
--mode [mode]
Switch to mode (presentation, fullscreen) after opening a document.
MOUSE AND KEY BINDINGS
======================
J, PgDn
Go to the next page
K, PgUp
Go to the previous page
h, k, j, l
Scroll to the left, down, up or right direction
Left, Down, Up, Right
Scroll to the left, down, up or right direction
^t, ^d, ^u, ^y
Scroll a half page left, down, up or right
t, ^f, ^b, space, <S-space>, y
Scroll a full page left, down, up or right
gg, G, nG
Goto to the first, the last or to the nth page
H, L
Goto top or bottom of the current page
^o, ^i
Move backward and forward through the jump list
^j, ^k
Bisect forward and backward between the last two jump points
^c, Escape
Abort
a, s
Adjust window in best-fit or width mode
/, ?
Search for text
n, N
Search for the next or previous result
o, O
Open document
f
Follow links
F
Display link target
\:
Enter command
r
Rotate by 90 degrees
^r
Recolor
R
Reload document
Tab
Show index and switch to **Index mode**
d
Toggle dual page view
F5
Switch to fullscreen mode
^m
Toggle inputbar
^n
Toggle statusbar
+, -, =
Zoom in, out or to the original size
zI, zO, z0
Zoom in, out or to the original size
n=
Zoom to size n
mX
Set a quickmark to a letter or number X
'X
Goto quickmark saved at letter or number X
q
Quit
Fullscreen mode
---------------
J, K
Go to the next or previous page
space, <S-space>, <BackSpace>
Scroll a full page down or up
gg, G, nG
Goto to the first, the last or to the nth page
^c, Escape
Abort
F5
Switch to normal mode
+, -, =
Zoom in, out or to the original size
zI, zO, z0
Zoom in, out or to the original size
n=
Zoom to size n
q
Quit
Index mode
----------
k, j
Move to upper or lower entry
l
Expand entry
L
Expand all entries
h
Collapse entry
H
Collapse all entries
space, Return
Select and open entry
Mouse bindings
--------------
Scroll
Scroll up or down
^Scroll
Zoom in or out
Hold Button2
Pan the document
Button1
Follow link
COMMANDS
========
bmark
Save a bookmark
bdelete
Delete a bookmark
blist
List bookmarks
close
Close document
exec
Execute an external command
info
Show document information
help
Show help page
open, o
Open a document
offset
Set page offset
print
Print document
write, write!
Save document (and force overwriting)
export
Export attachments
CONFIGURATION
=============
The default appearance and behaviour of zathura can be overwritten by modifying
the *zathurarc* file (default path: ~/.config/zathura/zathurarc). For a detailed
description please consult zathurarc(5).
SYNCTEX SUPPORT
===============
Both synctex forward and backwards synchronization are supported by zathura, To
enable synctex forward synchronization, please look at the *--syntex* and
*--synctex-editor* options. To support synctex backwards synchronization,
zathura provides a D-Bus interface that can be called by the editor. For
convince zathura also knows how to parse the output of the *synctex view*
command. It is enough to pass the arguments to *synctex view*'s *-i* option to
zathura via *--syntex-forward* and zathura will pass the information to the
correct instance.
KNOWN BUGS
==========
If GDK_NATIVE_WINDOWS is enabled you will experience problems with large
documents. In this case zathura might crash or pages cannot be rendered
properly. Disabling GDK_NATIVE_WINDOWS fixes this issue.
SEE ALSO
========
zathurarc(5)