X-Git-Url: https://git.cweiske.de/phancap.git/blobdiff_plain/62875bdbecc633496c712bc2fc5e0ef8f54733e3..d318de50fdbb9dbde25af97ff4dc8c5246591f21:/README.rst
diff --git a/README.rst b/README.rst
index 606ed74..c45c4e5 100644
--- a/README.rst
+++ b/README.rst
@@ -2,83 +2,312 @@
phancap - website screenshot service
************************************
-Software to create screenshots and thumbnails of websites via an API.
+Web service (API) to create website screenshots.
Self-hosted and written in PHP. Caching included.
+*phancap* is useful for:
+
+- Show screenshots for websites in your bookmarking application
+- Archive a HTML page as PDF for later viewing
+
+
+.. contents::
+
+
+========
+Features
+========
+
+* Configurable browser size
+* Configurable screenshot size
+* Clip and full page rendering (full height)
+* JPG, PNG and PDF output (PDFs are searchable)
+* Authentication
+* Can run on a normal web server without GUI. See dependencies_.
+
+
+.. note::
+ *phancap* does not rely on a "real" browser.
+ Currently ``cutycapt`` is utilized, which uses a pretty bare webkit to render
+ the pages.
+ Do not expect pixel-for-pixel identical rendering as your desktop browser.
+
+
+===============
+Getting started
+===============
+
+Basic setup
+===========
+#. Download the ``.phar`` file and put it onto your web server
+#. Open the phar file in your browser
+
+ If you only see text beginning with `` 'secret1',
+ 'user2' => 'secret2',
+ )
+
+The signature algorithm is as follows:
+
+#. Parameters ``atimestamp`` (current unix timestamp) and
+ ``atoken`` (username) have to be added to the URL parameters
+
+#. URL parameters are normalized as described in
+ `OAuth Parameters Normalization`__:
+
+ #. Sort parameters list by name
+ #. Name and value are `raw-url-encoded`__
+ #. Name and value are concatenated with ``=`` as separator
+ #. The resulting strings are concatenated with ``&`` as separator
+
+#. URL parameter string is used together with the secret key
+ to create a `HMAC-SHA1`__ digest
+
+#. Digest is appended to the URL as ``asignature``
+
+__ http://tools.ietf.org/html/rfc5849#section-3.4.1.3.2
+__ http://tools.ietf.org/html/rfc5849#section-3.6
+__ http://tools.ietf.org/html/rfc5849#section-3.4.2
+
+
+Example
+=======
+
+.. note::
+
+ The ``docs/`` directory contains an example PHP client implementation.
+
+We want to create a screenshot of ``http://example.org/`` in size 400x300,
+using the browser size of 1024x768::
+
+ http://example.org/phancap/get.php?swidth=400&sheight=300&url=http%3A%2F%2Fexample.org%2F&bwidth=1024&bheight=768
+
+Phancap's config file contains::
+
+ $access = array(
+ 'user' => 'secret'
+ );
+
+Our parameters are thus:
+
+============== =====
+Name Value
+============== =====
+``swidth`` ``400``
+``sheight`` ``300``
+``url`` ``http://example.org/``
+``bwidth`` ``1024``
+``bheight`` ``768``
+============== =====
+
+At first, we need to add parameters ``atimestamp`` and ``atoken``.
+``atimestamp`` is the current unix timestamp.
+``atoken`` is our user name: ``user``.
+
+Now the parameter list is sorted:
+
+============== =====
+Name Value
+============== =====
+``atimestamp`` ``1396353987``
+``atoken`` ``user``
+``bheight`` ``768``
+``bwidth`` ``1024``
+``sheight`` ``300``
+``swidth`` ``400``
+``url`` ``http://example.org/``
+============== =====
+
+The parameters are raw-url-encoded. The only value that changes is the url,
+it becomes ``http%3A%2F%2Fexample.org%2F``.
+
+Concatenating the name/value pairs leads to the following string::
+
+ atimestamp=1396353987&atoken=user&bheight=768&bwidth=1024&sheight=300&swidth=400&url=http%3A%2F%2Fexample.org%2F
+
+Creating the HMAC digest with sha1, the calculated string and our key
+``secret`` gives us the following string::
+
+ 9a12eac5ff859f9306eaaf5a18b9a931fe10b89d
+
+This is the signature; it gets appended to the URL as ``asignature`` parameter.
+
+
+============
+Dependencies
+============
+- External tools:
+
+ - `cutycapt `_
+ - `imagemagick's `_ ``convert``
+ - ``xvfb-run``
+
+- Libraries (already included in the ``.phar``):
+
+ - PEAR's ``System.php``
+
+
+=======
+License
+=======
+``phancap`` is licensed under the `AGPL v3`__ or later.
+
+__ http://www.gnu.org/licenses/agpl.html
+
+
+========
+Homepage
+========
+Web site
+ http://cweiske.de/phancap.htm
+
+Source code
+ http://git.cweiske.de/phancap.git
+
+ Mirror: https://github.com/cweiske/phancap
+
+
+======
+Author
+======
+Written by Christian Weiske, cweiske@cweiske.de
+
+
+============
+Alternatives
+============
+All of those are open source:
-Tools to make website screenshots
-=================================
-- `cutycapt `_
-- `khtml2png `_ (outdated)
-- `phantomjs `_
-- `python-webkit2png `_
-- `wkhtmltopdf `_
-- wkhtmltoimage
-
-
-Possible parameters
-===================
-
-Page request parameters
------------------------
-- url
-- bwidth (browser width / resolution)
-- bheight (browser height / resolution)
-- delay (capture X seconds after page loaded)
-- useragent (user agent header string)
-- accepted languages (Accept-Language header)
-- cookie (set cookie data)
-- referer (custom referer header)
-- post data (send POST data as if filled out a form)
-
-Screenshot configuration
-------------------------
-- width (of thumbnail)
-- height (of thumbnail)
-- output format (jpg, png, pdf)
-- mode: screen or page (full page height or screen size only)
- - page aka fullpage
-- quality (jpeg image quality)
-
-Misc
-----
-- callback URL (to notify when screenshot is ready)
-- sync/async (wait for response or just get a 202 accepted)
-- cache (to force a fresh screenshot with cache=0,
- otherwise seconds the cache may be old)
-- api key
-- token (md5 hash of query string)
-
-API parameter sources
----------------------
-- http://api1.thumbalizr.com/
-- http://url2png.com/docs/
-- http://webthumb.bluga.net/apidoc
-- http://www.page2images.com/Create-website-screenshot-online-API
-- http://browshot.com/api/documentation
-
-
-Other website screenshot services
-=================================
-- http://browsershots.org/
-- http://browshot.com/
-- http://ctrlq.org/screenshots/
-- http://grabz.it/
-- http://url2png.com/
-- http://usersnap.com/
-- http://websnapr.com/
-- http://webthumb.bluga.net/
-- http://www.page2images.com/
-- http://www.shrinktheweb.com/
-- http://www.thumbalizr.com/
-- http://www.url2picture.com/
-
-
-Other website screenshot software
-=================================
-- https://github.com/microweber/screen
+* http://code.google.com/p/browsershots/ (python)
+* https://github.com/gre/screenshot-webservice (scala)