fix internal layout description
[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
32 ============
33 Dependencies
34 ============
35 phorkie stands on the shoulders of giants.
36
37
38 Install VersionControl_Git
39 ==========================
40 ::
41
42   $ pear install versioncontrol_git-alpha
43
44
45 Install GeSHi
46 =============
47 ::
48
49   $ pear channel-discover mediawiki.googlecode.com/svn
50   $ pear install mediawiki/geshi
51
52 Note that this version of GeSHi is a bit outdated, but it's the fastest
53 way to install it.
54
55
56 Install Twig
57 ============
58 ::
59
60   $ pear channel-discover pear.twig-project.org
61   $ pear install twig/Twig
62
63
64 =====
65 HowTo
66 =====
67
68 Make git repositories clonable
69 ==============================
70 To make git repositories clonable, you need to install ``git-daemon``
71 (``git-daemon-run`` package on Debian/Ubuntu).
72
73 Now make the repositories available by symlinking the paste repository
74 directory (``$GLOBALS['phorkie']['cfg']['repos']`` setting) into
75 ``/var/cache/git``, e.g.::
76
77   $ ln -s /home/user/www/paste/repos/git /var/cache/git/paste
78
79 Edit your ``config.php`` and set the ``$GLOBALS['phorkie']['cfg']['git']['public']``
80 setting to ``git://$yourhostname/git/paste/``.
81 The rest will be appended automatically.
82
83
84 You're on your own to setup writable repositories.
85
86
87 =================
88 Technical details
89 =================
90
91 TODO
92 ====
93 - search
94 - OpenID-Login to get username+email as authorship information
95 - sidebar: history
96 - document how to keep disk usage low (block size)
97 - comments
98 - when 2 people edit, merge changes
99 - diff changes
100 - configurable highlights
101
102
103 URLs
104 ====
105
106 ``/``
107   Index page. Shows form for new paste
108 ``/[0-9]+``
109   Display page for paste
110 ``/[0-9]/edit``
111   Edit the paste
112 ``/[0-9]+/raw/(.+)``
113   Display raw file contents
114 ``/[0-9]/delete``
115   Delete the paste
116 ``/search(/.+)?``
117   Search for term
118 ``/list(/[0-9])?``
119   List all pastes
120
121
122 Internal directory layout
123 =========================
124 ::
125
126   repos/
127     work/
128       1/ - work directory for paste #1
129       2/ - work directory for paste #2
130     git/
131       1.git/ - git repository for paste #1
132         description - Description for the repository
133       2.git/ - git repository for paste #2
134
135
136 Search
137 ======
138 Use ``ack-grep``
139
140
141
142