link news file

[phorkie.git] / README.rst

diff --git a/README.rst b/README.rst
index a755d3a3879c0da2daf844df642fb318d94c5af8..034266a0e5e29f5f170a9f2b279a5dc819e05ecd 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -1,10 +1,14 @@
-************************************
-phorkie - PHP and Git based pastebin
-************************************
+****************************
+phorkie - Git based pastebin
+****************************

 Self-hosted pastebin software written in PHP.
 Pastes are editable, may have multiple files and are stored in git repositories.
 
 Self-hosted pastebin software written in PHP.
 Pastes are editable, may have multiple files and are stored in git repositories.
 

-Project page: http://sourceforge.net/p/phorkie/
+`Homepage <https://cweiske.de/phorkie.htm>`__
+| `Bug tracker <https://github.com/cweiske/phorkie/issues>`__
+| `Git repository <https://git.cweiske.de/phorkie.git>`__
+· `GitHub mirror <https://github.com/cweiske/phorkie/>`__
+| `News <https://cweiske.de/phorkie-news.htm>`__

 
 .. contents:: Table of Contents
 
 
 .. contents:: Table of Contents
 


@@ -22,7 +26,9 @@ Features
   - add new files
   - delete existing files
   - replace file with upload
   - add new files
   - delete existing files
   - replace file with upload

+- embedding of pastes in your blog (via JavaScript or oEmbed)

 - multiple files in one paste
 - multiple files in one paste

+  - option to edit single files in a multi-file paste

 - syntax highlighting with GeSHi
 - rST and Markdown rendering
 - image upload + display
 - syntax highlighting with GeSHi
 - rST and Markdown rendering
 - image upload + display


@@ -40,6 +46,19 @@ Features
 - webhook support - get notified when pastes are created, edited or deleted
 - atom feed for new and updated pastes
 - notifies remote instances via linkbacks when a paste has been forked
 - webhook support - get notified when pastes are created, edited or deleted
 - atom feed for new and updated pastes
 - notifies remote instances via linkbacks when a paste has been forked

+- text file detection for unknown file types
+
+
+========
+Download
+========
+phorkie is released as self-contained ``.phar`` file that includes
+all dependencies, as well as a normal zip file.
+
+.. LATESTRELEASE
+
+See `phorkie downloads page <http://cweiske.de/phorkie-download.htm>`_
+for all released versions.

 
 
 ============
 
 
 ============


@@ -48,7 +67,7 @@ Installation
 
 .phar
 =====
 
 .phar
 =====

-Download ``phorkie-0.4.0.phar`` and put it in your web server's document root
+Download ``phorkie-0.8.0.phar`` and put it in your web server's document root

 directory.
 
 No further setup needed.
 directory.
 
 No further setup needed.


@@ -57,17 +76,21 @@ No further setup needed.
    PHP handle ``.phar`` files.
 
    Unfortunately, no Linux distribution has this activated by default.
    PHP handle ``.phar`` files.
 
    Unfortunately, no Linux distribution has this activated by default.

+   You can do it yourself, though - see
+   `Enable .phar handling in your web server`__.

 
 .. warning:: PHP has some bugs in its .phar handling code (e.g. with FPM).
 
    So currently, the ``.phar`` option is considered experimental.
 
 
 .. warning:: PHP has some bugs in its .phar handling code (e.g. with FPM).
 
    So currently, the ``.phar`` option is considered experimental.
 

+__ http://cweiske.de/tagebuch/phar-webserver.htm
+

 
 Zip package
 ===========
 1. Unzip the phorkie release file::
 
 
 Zip package
 ===========
 1. Unzip the phorkie release file::
 

-   $ tar xjvf phorkie-0.4.0.tar.bz2
+   $ tar xjvf phorkie-0.8.0.tar.bz2

 
 2. Create the git directories::
 
 
 2. Create the git directories::
 


@@ -97,6 +120,10 @@ Zip package
 
 7. Go to http://yourhost/
 
 
 7. Go to http://yourhost/
 

+8. If you like phorkie, send a mail to `cweiske+phorkie@cweiske.de`__
+
+__ mailto:cweiske+phorkie@cweiske.de
+

 
 Dependencies
 ============
 
 Dependencies
 ============


@@ -107,6 +134,8 @@ on your machine:
 
 - Git v1.7.5 or later
 - PHP v5.3.0 or later
 
 - Git v1.7.5 or later
 - PHP v5.3.0 or later

+
+  - optionally the ``mbstring`` extension

 - PEAR v1.9.2 or later
 
 ::
 - PEAR v1.9.2 or later
 
 ::


@@ -149,7 +178,15 @@ phorkie makes use of an Elasticsearch__ installation, if you have one.
 
 It is used to provide search capabilities and the list of recent pastes.
 
 
 It is used to provide search capabilities and the list of recent pastes.
 

+Elasticsearch version 2.0 is supported.
+
+You have to install the `delete-by-query`__ plugin::
+
+    $ cd /usr/share/elasticsearch
+    $ bin/plugin install delete-by-query
+

 __ http://www.elasticsearch.org/
 __ http://www.elasticsearch.org/

+__ https://www.elastic.co/guide/en/elasticsearch/plugins/2.0/plugins-delete-by-query.html

 
 
 Setup
 
 
 Setup


@@ -295,23 +332,29 @@ URLs
   Index page.
 ``/[0-9]+``
   Display page for paste
   Index page.
 ``/[0-9]+``
   Display page for paste

-``/[0-9]/edit``
+``/[0-9]+/edit``

   Edit the paste
   Edit the paste

+``/[0-9]+/edit/(.+)``
+  Edit a single file of the paste
+``/[0-9]+/embed``
+  JavaScript code that embeds the whole paste in a HTML page
+``/[0-9]+/embed/(.+)``
+  JavaScript code that embeds a single file in a HTML page

 ``/[0-9]+/raw/(.+)``
   Display raw file contents
 ``/[0-9]+/raw/(.+)``
   Display raw file contents

-``/[0-9]/tool/[a-zA-Z]+/(.+)``
+``/[0-9]+/tool/[a-zA-Z]+/(.+)``

   Run a tool on the given file
   Run a tool on the given file

-``/[0-9]/rev/[a-z0-9]+``
+``/[0-9]+/rev/[a-z0-9]+``

   Show specific revision of the paste
   Show specific revision of the paste

-``/[0-9]/delete``
+``/[0-9]+/delete``

   Delete the paste
   Delete the paste

-``/[0-9]/doap``
+``/[0-9]+/doap``

   Show DOAP document for paste
   Show DOAP document for paste

-``/[0-9]/fork``
+``/[0-9]+/fork``

   Create a fork of the paste
 ``/search?q=..(&page=[0-9]+)?``
   Search for term, with optional page
   Create a fork of the paste
 ``/search?q=..(&page=[0-9]+)?``
   Search for term, with optional page

-``/list(/[0-9])?``
+``/list(/[0-9]+)?``

   List all pastes, with optional page
 ``/fork-remote``
   Fork a remote URL
   List all pastes, with optional page
 ``/fork-remote``
   Fork a remote URL


@@ -352,17 +395,22 @@ If you use nginx, place the following lines into your ``server`` block:
     rewrite ^/([0-9]+)/delete/confirm$ /delete.php?id=$1&confirm=1;
     rewrite ^/([0-9]+)/doap$ /doap.php?id=$1;
     rewrite ^/([0-9]+)/edit$ /edit.php?id=$1;
     rewrite ^/([0-9]+)/delete/confirm$ /delete.php?id=$1&confirm=1;
     rewrite ^/([0-9]+)/doap$ /doap.php?id=$1;
     rewrite ^/([0-9]+)/edit$ /edit.php?id=$1;

+    rewrite ^/([0-9]+)/edit/(.+)$ /edit.php?id=$1&file=$2;
+    rewrite ^/([0-9]+)/embed$ /embed.php?id=$1;
+    rewrite ^/([0-9]+)/embed/(.+)$ /embed.php?id=$1&file=$2;

     rewrite ^/([0-9]+)/fork$ /fork.php?id=$1;
     rewrite ^/([0-9]+)/raw/(.+)$ /raw.php?id=$1&file=$2;
     rewrite ^/([0-9]+)/rev/(.+)$ /revision.php?id=$1&rev=$2;
     rewrite ^/([0-9]+)/fork$ /fork.php?id=$1;
     rewrite ^/([0-9]+)/raw/(.+)$ /raw.php?id=$1&file=$2;
     rewrite ^/([0-9]+)/rev/(.+)$ /revision.php?id=$1&rev=$2;

-    rewrite ^/([0-9]+)/rev-raw/(.+)$ /raw.php?id=$1&rev=$2&file=$3;
+    rewrite ^/([0-9]+)/rev-raw/(.+)/(.+)$ /raw.php?id=$1&rev=$2&file=$3;

     rewrite ^/([0-9]+)/tool/([^/]+)/(.+)$ /tool.php?id=$1&tool=$2&file=$3;
 
     rewrite ^/fork-remote$ /fork-remote.php;
     rewrite ^/help$ /help.php;
     rewrite ^/new$ /new.php;
     rewrite ^/([0-9]+)/tool/([^/]+)/(.+)$ /tool.php?id=$1&tool=$2&file=$3;
 
     rewrite ^/fork-remote$ /fork-remote.php;
     rewrite ^/help$ /help.php;
     rewrite ^/new$ /new.php;

+

     rewrite ^/feed/new$ /feed-new.php;
     rewrite ^/feed/updated$ /feed-updated.php;
     rewrite ^/feed/new$ /feed-new.php;
     rewrite ^/feed/updated$ /feed-updated.php;

+

     rewrite ^/list$ /list.php;
     rewrite ^/list/([0-9]+)$ /list.php?page=$1;
 
     rewrite ^/list$ /list.php;
     rewrite ^/list/([0-9]+)$ /list.php?page=$1;
 


@@ -373,3 +421,64 @@ If you use nginx, place the following lines into your ``server`` block:
     rewrite ^/setup$ /setup.php;
     rewrite ^/user$ /user.php;
   }
     rewrite ^/setup$ /setup.php;
     rewrite ^/user$ /user.php;
   }

+
+Lighttpd rewrites
+=================
+
+::
+
+    url.rewrite-once += (
+        "^/([0-9]+)$" => "/display.php?id=$1",
+        "^/([0-9]+)/delete$" => "/delete.php?id=$1",
+        "^/([0-9]+)/delete/confirm" => "/delete.php?&id=$1&confirm=1",
+        "^/([0-9]+)/doap$" => "/doap.php?id=$1",
+        "^/([0-9]+)/edit$" => "/edit.php?id=$1",
+        "^/([0-9]+)/edit/(.+)" => "/edit.php?id=$1&file=$2",
+        "^/([0-9]+)/embed$" => "/embed.php?id=$1",
+        "^/([0-9]+)/embed/(.+)$" => "/embed.php?id=$1",
+        "^/([0-9]+)/fork$" => "/fork.php?id=$1",
+        "^/([0-9]+)/raw/(.+)$" => "/raw.php?id=$1&file=$2",
+        "^/([0-9]+)/rev/(.+)$" => "/revision.php?id=$1&rev=$2",
+        "^/([0-9]+)/rev-raw/(.+)/(.+)$" => "/raw.php?id=$1&rev=$2&file=$3",
+        "^/([0-9]+)/tool/([^/]+)/(.+)$" => "/tool.php?id=$1&tool=$2&file=$3",
+
+        "^/fork-remote$" => "/fork-remote.php",
+        "^/help$" => "/help.php",
+        "^/new$" => "/new.php",
+
+        "^/feed/new$" => "/feed-new.php",
+        "^/feed/updated$" => "/feed-updated.php",
+
+        "^/list$" => "/list.php",
+        "^/list/([0-9]+)$" => "/list.php?page=$1",
+
+        "^/search$" => "/search.php",
+        "^/search/([0-9]+)$" => "/search.php?page=$1",
+
+        "^/login$" => "/login.php",
+        "^/setup$" => "/setup.php",
+        "^/user$" => "/user.php"
+    )
+
+
+===========
+Development
+===========
+
+Releasing a new version
+=======================
+
+#. Update ``ChangeLog``, ``NEWS.rst``, ``build.xml`` and ``README.rst``.
+#. Update local dependencies::
+
+    $ phing collectdeps
+#. Build ``.tar.bz2`` and ``.phar`` release files with::
+
+    $ phing zip
+    $ phing phar
+#. Test.
+#. Tag the release in git
+#. Run the script to update the homepage
+
+    $ cd /home/cweiske/Dev/html/cweiske.de
+    $ ./scripts/update-phorkie.sh