update url mapping docs
[phorkie.git] / README.rst
1 ************************************
2 phorkie - PHP and Git based pastebin
3 ************************************
4 Self-hosted pastebin software written in PHP.
5 Pastes are editable, may have multiple files and are stored in git repositories.
6
7 Homepage: http://sourceforge.net/p/phorkie/
8
9 .. contents:: Table of Contents
10
11 ========
12 Features
13 ========
14 - every paste is a git repository
15
16   - repositories can be cloned
17   - clone url can be displayed
18 - paste editing
19
20   - add new files
21   - delete existing files
22   - replace file with upload
23 - multiple files in one paste
24 - syntax highlighting with GeSHi
25 - rST rendering
26 - image upload + display
27 - external tool support
28
29   - xmllint
30   - php syntax check
31 - history in the sidebar
32
33   - old files can be downloaded easily
34
35 ============
36 Dependencies
37 ============
38 phorkie stands on the shoulders of giants.
39
40
41 Install VersionControl_Git
42 ==========================
43 ::
44
45   $ pear install versioncontrol_git-alpha
46
47 Install Services_Libravatar
48 ==========================
49 ::
50
51   $ pear install services_libravatar-alpha
52
53
54 Install Date_HumanDiff
55 ======================
56 ::
57
58   $ pear install https://github.com/downloads/cweiske/Date_HumanDiff/Date_HumanDiff-0.1.0.tgz
59
60
61 Install GeSHi
62 =============
63 ::
64
65   $ pear channel-discover mediawiki.googlecode.com/svn
66   $ pear install mediawiki/geshi
67
68 Note that this version of GeSHi is a bit outdated, but it's the fastest
69 way to install it.
70
71
72 Install Twig
73 ============
74 ::
75
76   $ pear channel-discover pear.twig-project.org
77   $ pear install twig/Twig
78
79
80 =====
81 HowTo
82 =====
83
84 Make git repositories clonable
85 ==============================
86 To make git repositories clonable, you need to install ``git-daemon``
87 (``git-daemon-run`` package on Debian/Ubuntu).
88
89 Now make the repositories available by symlinking the paste repository
90 directory (``$GLOBALS['phorkie']['cfg']['repos']`` setting) into
91 ``/var/cache/git``, e.g.::
92
93   $ ln -s /home/user/www/paste/repos/git /var/cache/git/paste
94
95 Edit your ``config.php`` and set the ``$GLOBALS['phorkie']['cfg']['git']['public']``
96 setting to ``git://$yourhostname/git/paste/``.
97 The rest will be appended automatically.
98
99
100 You're on your own to setup writable repositories.
101
102
103 =================
104 Technical details
105 =================
106
107 TODO
108 ====
109 - OpenID-Login to get username+email as authorship information
110 - filters (xmllint --format, rapper)
111 - document how to keep disk usage low (block size)
112 - comments
113 - when 2 people edit, merge changes
114 - diff changes
115 - configurable highlights
116 - Atom feed for new pastes
117 - Atom feed for paste changes
118
119
120 URLs
121 ====
122
123 ``/``
124   Index page. Shows form for new paste
125 ``/[0-9]+``
126   Display page for paste
127 ``/[0-9]/edit``
128   Edit the paste
129 ``/[0-9]+/raw/(.+)``
130   Display raw file contents
131 ``/[0-9]/tool/[a-zA-Z]+/(.+)``
132   Run a tool on the given file
133 ``/[0-9]/rev/[a-z0-9]+``
134   Show specific revision of the paste
135 ``/[0-9]/delete``
136   Delete the paste
137 ``/[0-9]/fork``
138   Create a fork of the paste
139 ``/search?q=..(&page=[0-9]+)?``
140   Search for term, with optional page
141 ``/list(/[0-9])?``
142   List all pastes, with optional page
143
144
145 Internal directory layout
146 =========================
147 ::
148
149   repos/
150     work/
151       1/ - work directory for paste #1
152       2/ - work directory for paste #2
153     git/
154       1.git/ - git repository for paste #1
155         description - Description for the repository
156       2.git/ - git repository for paste #2
157
158
159 Search
160 ======
161 Use ``ack-grep``
162
163
164
165