.. -*- mode: rst -*-
Pancake
=======

This is a CLI/Emacs web/gopher/file browser.

It utilizes pandoc and external downloaders such as curl, adding
support for Gopher directories, plain text files, and RDF, and
invoking external applications (e.g., image and PDF viewers) depending
on its configuration.

User interaction capabilities are rather basic, as it is intended to
be combined with software that provides better user interfaces – such
as emacs, tmux, screen.


Installation
------------

Retrieval
~~~~~~~~~

There is a few ways to get a recent version of pancake:

- source and binary distributions:
  https://defanor.uberspace.net/projects/pancake/
- git repository: https://git.uberspace.net/pancake/
- github: https://github.com/defanor/pancake/


Pancake
~~~~~~~

``cabal install`` would build and install pancake and its
documentation. Alternatively, basic Debian packages and binary
releases are available.


Emacs interface
~~~~~~~~~~~~~~~

``M-x package-install-file RET /path/to/pancake.el RET``. To set it as
your default emacs browser::

  (require 'pancake)
  (setq browse-url-browser-function 'pancake)

To load and show all images automatically (not just after saving them
manually)::

  (add-hook 'pancake-display-hook 'pancake-load-images)

Though it might be desirable to write a wrapper to only show those on
specific websites, e.g. webcomics, and perhaps specific images only.

Commands
--------

:quit or EOF: quit pancake
:[: back
:]: forward
:load config[ <path>]: load configuration from a specified file or
                       reload it from the default one
:help: show a help message
:?: show current URI
:RET (empty): show the next page, if pagination is enabled
:<URI>: follow an URI, possibly relative to the current one
:<type> <URI>: same as above, but explicitly set a document type
               (html, txt, org, markdown, etc)
:[,]<number>: follow a link
:,: reload current document
:save <URI>[ <path>]: retrieve data and save it
:save [,]<number>[ <path>]: save linked data
:save ,[ <path>]: save current document
:<shortcut> <query>: run a query using a shortcut defined in the
                     configuration (e.g., search)
:set width[ <columns>]: set terminal/window width manually
:set position[ <line>]: set current terminal/window line
:redisplay: redisplay current document

pancake-mode provides additional aliases and commands, see built-in
emacs documentation (``C-h m``) for those.


Configuration
-------------

Default configuration will be written into XDG configuration directory
on ``pancake`` invocation if it's missing.


Uncluttering
~~~~~~~~~~~~

XSLT can be used to extract useful data from HTML documents, and XSLTs
for a few websites are provided by default. They can be read from
``unclutter`` subdirectory in either pancake's XDG config directory
(for custom XSLTs), or a data directory (for predefined XSLTs).


Screenshots
-----------

.. image:: https://defanor.uberspace.net/projects/pancake/gopher.png
.. image:: https://defanor.uberspace.net/projects/pancake/web-gnu.png
.. image:: https://defanor.uberspace.net/projects/pancake/emacs.png