Update Vcs-* headers.
[debian/nanobloggertrackback.git] / README
1 nanobloggertrackback - adding trackback functionality to nanoblogger
2 ====================================================================
3
4 Copyright and Licence
5 ---------------------
6
7 Copyright: gregor herrmann <gregor+debian@comodo.priv.at>, 2005, 2006, 2007
8 License: Released under the GNU GPL 2 or later (cf. COPYING)
9
10 Original tb.cgi:
11 The standalone implementation can be downloaded from
12 http://www.movabletype.org/downloads/tb-standalone.tar.gz
13 It is released under the Artistic License. The terms of the Artistic License
14 are described at http://www.perl.com/language/misc/Artistic.html.
15 Docs:
16 http://www.sixapart.com/movabletype/docs/tb-standalone
17 Copyright 2002 Benjamin Trott
18
19 Purpose
20 -------
21
22 nanobloggertrackback adds active and passive trackback functionality to
23 nanoblogger, i.e. it let's the user (automatically or manually) send
24 trackback pings to referenced blog entries and receive trackback pings from
25 other sites.
26 Additionally it shows received trackbacks in the blog pages and offers the
27 possibility to delete them.
28
29 Installation
30 ------------
31
32 a) Automatic
33 ------------
34
35 nb_tb-setup should automagically copy and patch all necessary files.
36 If it breaks something: Don't get nervous, it creates a backup of your
37 $BLOG_DIR in $HOME/nb.bak.
38 It does _not_ copy the nanoblogger plugins though (they are supposed to be
39 used systemwide, and nb_tb-setup just adjust one specific blog). - See
40 below under "Manual".
41
42 b) Manual
43 ---------
44
45 * Create the following directories:
46   $BLOG_DIR/tb
47   $BLOG_DIR/tb/data
48   $BLOG_DIR/tb/rss
49   $BLOG_DIR/tb/pings
50   
51   ./data and ./rss must be writeable for the user under which the webserver
52   is running!
53
54 * Change the beginning of tb.cgi:
55   Replace BLOGDIR, BLOGURL, PASSWORD, and EMAIL with meaningful values.
56
57 * Copy tb.cgi to your webserver's cgi-bin directory or somewhere else, where
58   the webserver can execute it.
59
60 * You may want to add the contents of nb_tb.css to your currently used
61   nanoblogger css file.
62
63 * Copy header.txt and footer.txt to $BLOG_DIR/tb.
64
65 * Change $BLOGDIR/templates/entry.htm
66   Use the patch in entry.diff or add the required lines manually:
67
68   | <a href="${TB_PATH}?__mode=list&amp;tb_id=$NB_EntryID" onclick="window.open(this.href, 'trackback', 'width=480,height=480,scrollbars=yes,status=yes'); return false">TrackBack</a>
69
70     e.g. between the categories and the comments line
71
72   <div class="tb">
73   $NB_TrackBacks
74   </div>
75
76     e.g. after the comments line, if you want to see the trackbacks directly
77     under each entry.
78
79   <!--
80   <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
81            xmlns:dc="http://purl.org/dc/elements/1.1/"
82            xmlns:trackback="http://madskills.com/public/xml/rss/module/trackback/">
83   <rdf:Description
84       rdf:about="${ARCHIVES_PATH}$NB_EntryPermalink"
85       dc:title="$NB_EntryTitle"
86       dc:identifier="${ARCHIVES_PATH}$NB_EntryPermalink" />
87       trackback:ping="${TB_PATH}/$NB_EntryID"
88   </rdf:RDF>
89
90     at the end of entry.htm
91
92 * In order to activate the whole stuff you have to add two lines to your
93   blog.conf:
94   TB_PATH="$CGIURL/tb.cgi"
95     where $CGIURL is the full URL to tb.cgi, e.g. http://www.example.com/cgi-bin
96   SEND_TRACKBACK_PING="1"
97     if you want nanoblogger to send trackback pings automatically to each
98     URL found in a modified entry.
99   Absolute links have to be turned on in blog.conf:
100   ABSOLUTE_LINKS="1"
101
102 * If nobody on your system has done this already: Copy trackbacklist.sh and
103   trackbackping.sh to nanobloggers plugins/entry/mod/ directory.
104
105 Usage
106 -----
107
108 a) Receiving trackback pings
109 ----------------------------
110
111 If everything is set up correctly other bloggers can send you trackback
112 pings, either manually (the trackback URL can be found now in each entry of
113 your blog) or automatically (that's what the RDF stuff in entry.htm is for).
114 You can view trackbacks from others either directly under each entry or by
115 clicking on the Trackbacks link; there you can (after logging in) also
116 delete trackbacks.
117 You are informed by a short email if someone else sends a trackback ping to
118 one of your posts.
119 (Now you know what the $PASSWORD and $EMAIL variables are for ;-).)
120
121 b) Sending trackback pings
122 --------------------------
123
124 If you want to send a trackback ping manually go to
125 $CGIURL/tb.cgi?__mode=send_form
126 If you turn on SEND_TRACKBACK_PING in blog.conf trackback pings are sent
127 automatically to each referenced URL in a modified blog entry (but only
128 once; a list is kept in $BLOG_DIR/tb/pings).