annotate README.txt @ 9:825833a5c4a7 default tip

update metadata
author Jeff Hammel <k0scist@gmail.com>
date Tue, 03 Nov 2020 08:18:53 -0800
parents 872f98a484d2
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
1 commentator
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
2 ===========
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
3
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
4 WSGI commenting middleware
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
5
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
6 To use
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
7 ------
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
8
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
9 Make a factory wrapping your app in the commentator middleware.
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
10 Currently, commentator only pickles comments. To the constructor of
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
11 Commentator, pass a database (the path to the pickle) and a pattern.
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
12 The pattern is in the form of
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
13
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
14 <URL pattern>#<xpath pattern> -> URL
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
15
7
872f98a484d2 note about audiences
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
16 The URL pattern is a
0
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
17 `python regular expression <ttp://docs.python.org/library/re.html>`_
7
872f98a484d2 note about audiences
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
18 to match against the request's PATH_INFO.
0
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
19
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
20 The xpath pattern is where you want to place the comments on the
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
21 page. See http://www.w3schools.com/XPath/ for more about xpath
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
22 expressions.
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
23
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
24 The URL is a
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
25 `python string template <http://docs.python.org/library/string.html>`_
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
26 that is substituted for groups in the URL regular expression and
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
27 element attributes in the found nodes. The element attributes are
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
28 referenced by name (``${id}``, ``${class}``, etc) and the groups are
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
29 referenced by number (``${1}``, ...).
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
30
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
31
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
32 Example
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
33 -------
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
34
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
35 A reference implementation is illustrated in the commentator.ini
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
36 file. This uses the pattern:
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
37
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
38 ``commentator.pattern = (.*)#.//div[@id='comment_on_this'] -> ${1}``
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
39
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
40 What this pattern says is
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
41
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
42 * comment on every PATH_INFO ``(.*)``
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
43 * append the rendered content template to ``div[@id='comment_on_this']``
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
44 * reference the PATH_INFO as the canonical URL ``${1}``
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
45
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
46 To comment on every HTML page at the end of the body, you would use
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
47
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
48 ``commentator.pattern = (.*)#.//body -> ${1}``
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
49
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
50 A more complex example is in the ``.ini`` file, commented out, for use with
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
51 `bitsyblog <http://k0s.org/hg/bitsyblog>`_ :
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
52
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
53 ``commentator.pattern = /blog/.*#.//div[@class='blog-entry'] -> /blog/${id}``
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
54
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
55 This pattern says:
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
56
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
57 * comment on all paths under blog
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
58 * put the comments at the end of each ``div[@class='blog-entry']``
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
59 * get the URI from the ``div``'s id, not from the ``PATH_INFO``
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
60
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
61
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
62 TODO
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
63 ----
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
64
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
65 This is very alpha. I'd be happy to work more on this if anyone wants
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
66 it. A few outstanding issues:
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
67
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
68 * fix weird lxml issue where you have to put .// for elements
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
69 * allow commenting on multiple resources (multiple patterns per instance)
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
70 * locking pickle files
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
71 * fix couch....not sure what's wrong
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
72 * allow use of CSS classes, not just xpath
7
872f98a484d2 note about audiences
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
73 * tests!
872f98a484d2 note about audiences
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
74
872f98a484d2 note about audiences
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
75 Types of comments:
872f98a484d2 note about audiences
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
76
872f98a484d2 note about audiences
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
77 A generalize comment (stream) is a *discussion* content type. As
872f98a484d2 note about audiences
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
78 such, in general you could include the standard *((string)key, value)*
872f98a484d2 note about audiences
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
79 metadata with each comment.
872f98a484d2 note about audiences
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
80
872f98a484d2 note about audiences
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
81 More actionably, a single field, *audience*, is often sufficient.
872f98a484d2 note about audiences
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
82 While the general form is out-of-scope (for now) for commentator,
872f98a484d2 note about audiences
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
83 adding an audience would go some ways towards comment effectivity.
872f98a484d2 note about audiences
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
84
872f98a484d2 note about audiences
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
85 Examples of audiences:
872f98a484d2 note about audiences
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
86
872f98a484d2 note about audiences
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
87 * original author : especially useful for site comments
872f98a484d2 note about audiences
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
88 * discussion : everyone participating
872f98a484d2 note about audiences
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
89
0
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
90
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
91 --
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
92
1c95a3fa76c1 initial commit of commentator
k0s <k0scist@gmail.com>
parents:
diff changeset
93 http://k0s.org