X-Git-Url: https://git.cweiske.de/phancap.git/blobdiff_plain/5b85ef225aef0b9052c3797861fc79cdabd1c2f4..bac895b61a812c1b0f014bae483fac8507fc44ee:/README.rst
diff --git a/README.rst b/README.rst
index 3b71795..818eafd 100644
--- a/README.rst
+++ b/README.rst
@@ -2,11 +2,71 @@
phancap - website screenshot service
************************************
-Web service to create website screenshots.
+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_.
+* Generated images get meta data embedded:
+
+ * URL of captured page
+ * Capture settings
+
+
+.. 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:
@@ -84,6 +207,11 @@ __ 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::
@@ -137,90 +265,69 @@ Creating the HMAC digest with sha1, the calculated string and our key
9a12eac5ff859f9306eaaf5a18b9a931fe10b89d
-This is the signature; it gets appended the URL as ``asignature`` parameter.
+This is the signature; it gets appended to the URL as ``asignature`` parameter.
============
Dependencies
============
-- `cutycapt `_
-- imagemagick's ``convert``
-- ``xvfb-run``
+- External tools:
+ - `cutycapt `_
+ - `exiftool `_
+ - `imagemagick's `_ ``convert``
+ - ``xvfb-run``
+- Libraries (already included in the ``.phar``):
-=======================
-Technical brainstorming
+ - PEAR's ``System.php``
+
+
+=============
+About phancap
+=============
+
+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:
+
+* http://code.google.com/p/browsershots/ (python)
+* https://github.com/gre/screenshot-webservice (scala)
+
+
+===========
+Development
+===========
+
+Releasing a new version
=======================
-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
+#. Update ``ChangeLog``
+#. Change version number in ``build.xml``
+#. Run ``phing``
+#. Deploy the new files in ``dist/``
+#. Tag the new version in git