Attachment 'Ref-2.3.py'
Download 1 # -*- coding: iso-8859-1 -*-
2 """
3 MoinMoin - Ref macro, Version 2.3, 09.05.2011
4
5 A macro to cite references from a dictionary page (a ' key:: value' listing).
6
7 Searches one or more dictionary pages to match key (Argument 1, with or without 'key=', quoted string). Matches are included in the page as (1) bookmarks, (2) search key text followed by a footnote link, (3) search key text as the link to the footnote, (4) found reference text only and (5) search key text only.
8
9 The dictionary page is set the RefDict by default, or can be set for (a) the whole page by #pragma ref-dict, or (b) for individual calls by Argument 3.
10
11 For options (2) and (3), search key text will have 'et al' set to Italics (which can be switched off for the whole page by setting #pragma ref-ital off). Also, the year (last word of the key assumed to be a year) can be surrounded in brackets. By default these are just ' (year)' but can be set by #pragma ref-year-bkt to give, for example ', (^)' (where ^ indicates the insertion point for year), if the desired format in the in-text citation differs from the key text in the dictionary.
12
13 Exclamation marks (as WikiName escapes) can be included in the search key, they are removed for matching in dictpage(s) and restored for display under options (2) and (3).
14
15 Additionally superscripting of the numerical link in options (2) and (3) can be switched off and default square brackets are used to distinguish the link from the text. The bracketing can customised using #pragma ref-link-bkt as described above for bracketing the year.
16
17 Option (4) is used to create reference (or further reading) list at any point in the the page, without hyperlinks to or from the citation. Or, just to put the reference into the text perhaps in brackets.
18
19 Option (5) simply inserts the search key text into the page. If reference text is inserted by Option (4) on the same or separate page, inserting references into the text using this macro allows them to be found by searching for the macro. Additionally, if this citation type is set at the page level (by #pragma), it can be temporarily reset to make a footnote list on the page for proof reading purposes.
20
21 These options can be selected for each instance (Argument 2, with or without 'cite=', without quotes, 'fn' 'keyfn' 'bktfn', 'keylk', 'bktlk', 'key', 'val' or 'bkt').
22
23 If 0 or >1 match is found a warning is inserted into the page.
24
25 <<Ref()>>
26
27 Inserts '[citation needed]' to act as a reminder and/or placeholder.
28
29 <<Ref([ref=]"key"[,[cite=]fn|keyfn|bktfn|keylk|bktlk|val|key|bkt)[,[dict=]dictpage]])>>
30
31 Argument labels (ref=, cite= and dict=) are optional. The first argument must be ref. Cite and dict arguments are optional and can appear alone, or together in any order. Keywords for cite should not be used for dictpage names.
32
33 ref="key": search key to be matched in dictpage(s), set in single or double quotes. Setting ref="" is equivalent to <<Ref()>> (see above).
34
35 cite=fn: insert a footnote into the page as a numerical link only with the found value (reference text) as the footnote.
36
37 cite=keyfn: insert a footnote into the page as the search key (reference code) followed by a numerical link to the found value (reference text) as the footnote (default).
38
39 cite=bktfn: insert a footnote into the page as the search key (reference code with the year bracketed) followed by a numerical link to the found value (reference text) as a footnote.
40
41 cite=keylk: insert a footnote into the page as the search key (reference code) as the link to the found value (reference text) as the footnote.
42
43 cite=bktlk: insert a footnote into the page as the search key (reference code with the year bracketed) as the link to the found value (reference text) as a footnote.
44
45 cite=val: insert only the found value (reference text) into the page. No link or footnote is generated.
46
47 cite=key: insert only the key (reference code) into the page. No link or footnote is created.
48
49 cite=bkt: insert only the key (reference code with the year bracketed) into the page. No link or footnote is created.
50
51 dictpage(s): dictionary page name. If it starts with ^, a regex of dictpages to include (case sensitive).
52
53 #pragma ref-cite citetype: set the default cite type for the page.
54
55 #pragma ref-year-bkt string: string to bracket year when cite=bktfn, bktlk or bkt, replacing the default ' (^)'; where ^ indicates the insertion point of the year (only one ^ can appear in the string). Set in single or double quotes, or backslash pair.
56
57 #pragma ref-super off: turns of superscripting of numerical forward link to the footnote.
58
59 #pragma ref-link-bkt string: to distinguish the link when ref-super=off, sets string to bracket footnote forward link number for cite=fn, keyfn or bktfn, replacing the default '[^]'; where ^ indicates the insertion point of the link (only one ^ can appear in the string). Set in single or double quotes, or backslash pair.
60
61 #pragma ref-ital off: stops 'et al' in key being converted to italics.
62
63 #pragma ref-dict dictpage(s): dictionary to be used by default for that page, replacing the wiki-wide default of RefDict.
64
65 #pragma ref-debug wiki: shows the wiki markup without processing it.
66
67 #pragma ref-debug html: shows the markup as html.
68
69 @copyright: 2010 Ian Riley <ian.riley@adelaide.edu.au>
70 @licence: GNU GPL, see COPYING for details.
71
72 History
73
74 Version 2.3.- 09.05.2011: minor bug fix
75
76 Version 2.2 - 12.01.2011: streamlined the unwrap function.
77
78 Version 2.1 - 27.12.2010: some html security improvements.
79
80 Version 2.0 - 25.12.2010: dict specification optional (for cleaner markup), added key linking and display, added additional pragma to set cite type for the whole page (again for cleaner markup), to turn off superscripting and to add alternative demarkation of numbered links and to change year demarkation text. Macro call without arguments to raise a citation needed reminder.
81
82 Version 1.0 - 19.12.2010: initial version.
83
84 Developed from:
85
86 (1) MoinMoin - Include macro
87
88 @copyright: 2000-2004 Juergen Hermann <jh@web.de>,
89 2000-2001 Richard Jones <richard@bizarsoftware.com.au>
90 @license: GNU GPL, see COPYING for details.
91
92 (2) http://moinmo.in/FeatureRequests/IncludeMacroInline using code of Junyx 2008-03-24 20:36:25
93
94 """
95
96 Dependencies = ["time"]
97
98 import re
99 from MoinMoin import wikiutil
100 from MoinMoin.Page import Page
101 from MoinMoin.parser.text_moin_wiki import Parser as WikiParser
102
103 # renmove character bracketing 'wrapped' if it is in 'wrappers'
104 def unwrap(wrapped,wrappers):
105 if (wrapped[0] in wrappers) and wrapped.endswith(wrapped[0]):
106 wrapped = wrapped[1:-1]
107 return wrapped
108
109 _msg = u'<strong class="error">Ref(): %s</strong>'
110 _msg_bad_arg = _msg % (u'invalid arguments {%s}')
111 _msg_recursion = _msg % (u'recursive use of {%s} forbidden')
112 _msg_match_none = _msg % (u'no match for key={%s} in dict={%s}')
113 _msg_match_many = _msg % (u'%s matches for key={%s} in dict={%s}')
114 _msg_bad_insert = _msg % (u'Single insertion point ^ in {#pragma %s %s} obligatory')
115 _msg_ref_needed = u'[citation needed]'
116
117 _kw_cite = ['fn','keyfn','bktfn','keylk','bktlk','key','val','bkt']
118
119 _df_cite = u'keyfn'
120 _df_dict = u'RefDict'
121
122 _out_fn = u'<<FootNote(%s)>>'
123 _out_keyfn = u'%s' + _out_fn
124 _out_year_bkt = u' (%s)'
125 _out_esc = u'{{{%s}}}'
126 _out_link_bkt = u'[%s]'
127
128 _arg_ref = r'(\s*(ref=)?(?P<quote>[\'"])(?P<ref>.+)?(?P=quote))?'
129 _arg_cite = r'(,\s*(cite=)?(?P<cite>(fn|keyfn|bktfn|keylk|bktlk|key|val|bkt)))?'
130 _arg_dict = r'(,\s*(dict=)?(?P<dict>[^,.]+?))?'
131 _args_re_pattern = r'^%s((%s)?%s)?$' % (_arg_ref, _arg_cite, _arg_dict, )
132 _args_re_pattern2 = r'^%s((%s)?%s)?$' % (_arg_ref, _arg_dict, _arg_cite, )
133
134 def execute(macro, text, args_re=re.compile(_args_re_pattern)):
135 request = macro.request
136 _ = request.getText
137
138 def dec_page():
139 # decrease or remove pagelist marker
140 if this_page._macroRef_pagelist[inc_name] > 1:
141 this_page._macroRef_pagelist[inc_name] = this_page._macroRef_pagelist[inc_name] - 1
142 else:
143 del this_page._macroRef_pagelist[inc_name]
144
145 # return immediately if getting links for the current page
146 if request.mode_getpagelinks:
147 return ('')
148
149 # parse and check arguments
150 args = text and args_re.match(text)
151 if not args and text != '':
152 args_re = re.compile(_args_re_pattern2)
153 args = text and args_re.match(text)
154 if not args and text != '':
155 return (_msg_bad_arg % (text, ))
156
157 # flag reference needed
158 if text == '':
159 return (_msg_ref_needed)
160 elif args.group('ref') == None:
161 return (_msg_ref_needed)
162
163 # get cite or apply page default
164 cite = args.group('cite')
165 if cite == None:
166 cite = macro.request.getPragma('ref-cite')
167 if not (cite in _kw_cite):
168 cite = _df_cite
169
170 # prepare page
171 result = []
172 result_pending = []
173 this_page = macro.formatter.page
174 if not hasattr(this_page, '_macroRef_pagelist'):
175 this_page._macroRef_pagelist = {}
176
177 # establish dictionary page to be searched
178 dict_name = args.group('dict')
179 if dict_name == None:
180 dict_name = macro.request.getPragma('ref-dict')
181 if dict_name == None:
182 dict_name = _df_dict
183
184 # get list of dictionary pages to search
185 inc_name = wikiutil.AbsPageName(this_page.page_name, dict_name)
186 pagelist = [inc_name]
187 if inc_name.startswith("^"):
188 try:
189 inc_match = re.compile(inc_name)
190 except re.error:
191 pass # treat as plain page name
192 else:
193 # get user filtered readable page list
194 pagelist = request.rootpage.getPageList(filter = inc_match.match)
195
196 ref_key = ''
197 ref_match_count = 0
198 val_end = '\n'
199
200 # iterate over pages
201 for inc_name in pagelist:
202 if not request.user.may.read(inc_name):
203 continue
204 if inc_name in this_page._macroRef_pagelist:
205 dec_page()
206 return (_msg_recursion % (inc_name, ))
207
208 fmt = macro.formatter.__class__(request, is_included=True)
209 fmt._base_depth = macro.formatter._base_depth
210 inc_page = Page(request, inc_name, formatter=fmt)
211 if not inc_page.exists():
212 continue
213 inc_page._macroRef_pagelist = this_page._macroRef_pagelist
214
215 # prepare for ref_key search
216 body = inc_page.get_raw_body() + '\n'
217 ref_pos = 0
218 end_pos = -1
219 ref_found = True
220
221 # need to reset ref_key within loop, as it might have been modified
222 ref_key = args.group('ref')
223
224 # remove any WikiName escape character
225 ref_key = ref_key.replace("!","")
226
227 if ref_key:
228 try:
229 ref_match = re.compile(ref_key + ':: ', re.M).search(body)
230 except re.error:
231 ref_match = re.compile(re.escape(ref_key + ':: '), re.M).search(body)
232 if ref_match:
233 ref_pos = ref_match.end()
234 else:
235 ref_found = False
236
237 if val_end:
238 try:
239 end_match = re.compile(val_end, re.M).search(body, ref_pos)
240 except re.error:
241 end_match = re.compile(re.escape(val_end), re.M).search(body, ref_pos)
242 if end_match:
243 end_pos = end_match.start()
244 else:
245 ref_found = False
246
247 if ref_found:
248 inc_page.set_raw_body(body[ref_pos:end_pos], modified=True)
249 ref_match_count = ref_match_count + 1
250
251 #TODO: loop back over remainder of body to find duplicate keys to allow user to be warned.
252 # Perhaps is would be better to use WikiDict calls to get the match,
253 # but I think this can only find the first match, not duplicates.
254
255 # set or increment pagelist marker
256 this_page._macroRef_pagelist[inc_name] = this_page._macroRef_pagelist.get(inc_name, 0) + 1
257
258 # need to reset ref_key within loop, as it might have been modified
259 ref_key = args.group('ref')
260
261 # make et al italic unless #pragma ref-ital off
262 if macro.request.getPragma('ref-ital') != 'off':
263 ref_key = ref_key.replace("et al","''et al''")
264
265 # bracket year (last 'word' of ref key) for cite=bktfn, bktlk or bkt
266 if cite in ['bktfn', 'bktlk', 'bkt']:
267 ref_key = ref_key.rstrip()
268 ref_len = len(ref_key)
269 year_pos = ref_key.rfind(' ')
270 year_bkt = _out_year_bkt
271 if macro.request.getPragma('ref-year-bkt') != None:
272 #TODO check if the escape call really needed or does getPragma handle the html risk
273 year_bkt = wikiutil.escape(macro.request.getPragma('ref-year-bkt'))
274 if year_bkt.count("^") != 1:
275 dec_page()
276 return (_msg_bad_insert % ('ref-year-bkt', year_bkt))
277 year_bkt = year_bkt.replace("_"," ").replace("^","%s",1)
278 year_bkt = unwrap(year_bkt,"\\\"'")
279 year_str = year_bkt % (ref_key[year_pos+1:ref_len])
280 ref_key = ref_key[0:year_pos] + year_str
281
282 if ref_found:
283 # insert the ref value into the page as a footnote only
284 if cite == 'fn':
285 result_pending = _out_fn % (inc_page.get_body())
286
287 # insert the ref key (modified) into the page followed by the ref value into the page as a footnote
288 elif cite in ['keyfn','bktfn','keylk','bktlk']:
289 result_pending = _out_keyfn % (ref_key, inc_page.get_body())
290
291 # insert the ref key into the page only
292 elif cite in ['key', 'bkt']:
293 result_pending = ref_key
294
295 # insert the ref value into the page only
296 elif cite == 'val':
297 result_pending = inc_page.get_body()
298
299
300 if macro.request.getPragma('ref-debug') == 'wiki':
301 result_pending = _out_esc % (result_pending)
302
303 result_pending = wikiutil.renderText(request, WikiParser, result_pending).rstrip(' ')
304
305 # post formating of html citation and link
306 if cite in ('keylk','bktlk'):
307 ref_key = ref_key.replace("!","")
308 ref_key = ref_key.replace("''et al''","<em>et al</em>")
309 result_pending = (result_pending.replace("<sup>","")
310 .replace("</sup>","")
311 .replace(ref_key,"")
312 .replace("</a>","")
313 .rstrip(" 0123456789") + ref_key + "</a>")
314
315 if cite in ('fn','keyfn','bktfn'):
316 if macro.request.getPragma('ref-super') == 'off':
317 link_bkt = _out_link_bkt
318 if macro.request.getPragma('ref-link-bkt') != None:
319 #TODO check if the escape call really needed or does getPragma handle the html risk
320 link_bkt = wikiutil.escape(macro.request.getPragma('ref-link-bkt'))
321 if link_bkt.count("^") != 1:
322 dec_page()
323 return (_msg_bad_insert % ('ref-link-bkt', link_bkt, ))
324 link_bkt = (unwrap(link_bkt,"\\\"'").replace("_"," ")
325 .replace("^","%s",1))
326 t = tuple(result_pending.replace("<sup>","<>")
327 .replace("</a>","</a><>")
328 .replace("</sup>","")
329 .split("<>"))
330 result_pending = ('%s' + link_bkt + '%s') % (t[0],t[1],t[2])
331
332 if macro.request.getPragma('ref-debug') == 'html':
333 result_pending = _out_esc % (result_pending)
334 result_pending = wikiutil.renderText(request, WikiParser, result_pending).rstrip(' ')
335
336 result.append(result_pending)
337
338 # decrease or remove pagelist marker
339 dec_page()
340
341 # no match and last page in list, so insert warning message
342 # need to reset ref_key within loop, as it might have been modified
343 ref_key = args.group('ref')
344 if ref_match_count == 0:
345 result.append(_msg_match_none % (ref_key, dict_name, ))
346 elif ref_match_count > 1:
347 result.append(_msg_match_many % (ref_match_count, ref_key, dict_name, ))
348
349 return ''.join(result)
You are not allowed to attach a file to this page.