Attachment 'Ref-2.2.py'
Download 1 # -*- coding: iso-8859-1 -*-
2 """
3 MoinMoin - Ref macro, Version 2.2, 12.01.2010
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' or 'val').
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)[,[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.2 - 12.01.2011: streamlined the unwrap function.
75
76 Version 2.1 - 27.12.2010: some html security improvements.
77
78 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.
79
80 Version 1.0 - 19.12.2010: initial version.
81
82 Developed from:
83
84 (1) MoinMoin - Include macro
85
86 @copyright: 2000-2004 Juergen Hermann <jh@web.de>,
87 2000-2001 Richard Jones <richard@bizarsoftware.com.au>
88 @license: GNU GPL, see COPYING for details.
89
90 (2) http://moinmo.in/FeatureRequests/IncludeMacroInline using code of Junyx 2008-03-24 20:36:25
91
92 """
93
94 Dependencies = ["time"]
95
96 import re
97 from MoinMoin import wikiutil
98 from MoinMoin.Page import Page
99 from MoinMoin.parser.text_moin_wiki import Parser as WikiParser
100
101 # renmove character bracketing 'wrapped' if it is in 'wrappers'
102 def unwrap(wrapped,wrappers):
103 if (wrapped[0] in wrappers) and wrapped.endswith(wrapped[0]):
104 wrapped = wrapped[1:-1]
105 return wrapped
106
107 _msg = u'<strong class="error">Ref(): %s</strong>'
108 _msg_bad_arg = _msg % (u'invalid arguments {%s}')
109 _msg_recursion = _msg % (u'recursive use of {%s} forbidden')
110 _msg_match_none = _msg % (u'no match for key={%s} in dict={%s}')
111 _msg_match_many = _msg % (u'%s matches for key={%s} in dict={%s}')
112 _msg_bad_insert = _msg % (u'Single insertion point ^ in {#pragma %s %s} obligatory')
113 _msg_ref_needed = u'[citation needed]'
114
115 _kw_cite = ['fn','keyfn','bktfn','keylk','bktlk','key','bkt','val']
116
117 _df_cite = u'keyfn'
118 _df_dict = u'RefDict'
119
120 _out_fn = u'<<FootNote(%s)>>'
121 _out_keyfn = u'%s' + _out_fn
122 _out_year_bkt = u' (%s)'
123 _out_esc = u'{{{%s}}}'
124 _out_link_bkt = u'[%s]'
125
126 _arg_ref = r'(\s*(ref=)?(?P<quote>[\'"])(?P<ref>.+)?(?P=quote))?'
127 _arg_cite = r'(,\s*(cite=)?(?P<cite>(fn|keyfn|bktfn|keylk|bktlk|key|val)))?'
128 _arg_dict = r'(,\s*(dict=)?(?P<dict>[^,.]+?))?'
129 _args_re_pattern = r'^%s((%s)?%s)?$' % (_arg_ref, _arg_cite, _arg_dict, )
130 _args_re_pattern2 = r'^%s((%s)?%s)?$' % (_arg_ref, _arg_dict, _arg_cite, )
131
132 def execute(macro, text, args_re=re.compile(_args_re_pattern)):
133 request = macro.request
134 _ = request.getText
135
136 def dec_page():
137 # decrease or remove pagelist marker
138 if this_page._macroRef_pagelist[inc_name] > 1:
139 this_page._macroRef_pagelist[inc_name] = this_page._macroRef_pagelist[inc_name] - 1
140 else:
141 del this_page._macroRef_pagelist[inc_name]
142
143 # return immediately if getting links for the current page
144 if request.mode_getpagelinks:
145 return ('')
146
147 # parse and check arguments
148 args = text and args_re.match(text)
149 if not args and text != '':
150 args_re = re.compile(_args_re_pattern2)
151 args = text and args_re.match(text)
152 if not args and text != '':
153 return (_msg_bad_arg % (text, ))
154
155 # flag reference needed
156 if text == '':
157 return (_msg_ref_needed)
158 elif args.group('ref') == None:
159 return (_msg_ref_needed)
160
161 # get cite or apply page default
162 cite = args.group('cite')
163 if cite == None:
164 cite = macro.request.getPragma('ref-cite')
165 if not (cite in _kw_cite):
166 cite = _df_cite
167
168 # prepare page
169 result = []
170 result_pending = []
171 this_page = macro.formatter.page
172 if not hasattr(this_page, '_macroRef_pagelist'):
173 this_page._macroRef_pagelist = {}
174
175 # establish dictionary page to be searched
176 dict_name = args.group('dict')
177 if dict_name == None:
178 dict_name = macro.request.getPragma('ref-dict')
179 if dict_name == None:
180 dict_name = _df_dict
181
182 # get list of dictionary pages to search
183 inc_name = wikiutil.AbsPageName(this_page.page_name, dict_name)
184 pagelist = [inc_name]
185 if inc_name.startswith("^"):
186 try:
187 inc_match = re.compile(inc_name)
188 except re.error:
189 pass # treat as plain page name
190 else:
191 # get user filtered readable page list
192 pagelist = request.rootpage.getPageList(filter = inc_match.match)
193
194 ref_key = ''
195 ref_match_count = 0
196 val_end = '\n'
197
198 # iterate over pages
199 for inc_name in pagelist:
200 if not request.user.may.read(inc_name):
201 continue
202 if inc_name in this_page._macroRef_pagelist:
203 dec_page()
204 return (_msg_recursion % (inc_name, ))
205
206 fmt = macro.formatter.__class__(request, is_included=True)
207 fmt._base_depth = macro.formatter._base_depth
208 inc_page = Page(request, inc_name, formatter=fmt)
209 if not inc_page.exists():
210 continue
211 inc_page._macroRef_pagelist = this_page._macroRef_pagelist
212
213 # prepare for ref_key search
214 body = inc_page.get_raw_body() + '\n'
215 ref_pos = 0
216 end_pos = -1
217 ref_found = True
218
219 # need to reset ref_key within loop, as it might have been modified
220 ref_key = args.group('ref')
221
222 # remove any WikiName escape character
223 ref_key = ref_key.replace("!","")
224
225 if ref_key:
226 try:
227 ref_match = re.compile(ref_key + ':: ', re.M).search(body)
228 except re.error:
229 ref_match = re.compile(re.escape(ref_key + ':: '), re.M).search(body)
230 if ref_match:
231 ref_pos = ref_match.end()
232 else:
233 ref_found = False
234
235 if val_end:
236 try:
237 end_match = re.compile(val_end, re.M).search(body, ref_pos)
238 except re.error:
239 end_match = re.compile(re.escape(val_end), re.M).search(body, ref_pos)
240 if end_match:
241 end_pos = end_match.start()
242 else:
243 ref_found = False
244
245 if ref_found:
246 inc_page.set_raw_body(body[ref_pos:end_pos], modified=True)
247 ref_match_count = ref_match_count + 1
248
249 #TODO: loop back over remainder of body to find duplicate keys to allow user to be warned.
250 # Perhaps is would be better to use WikiDict calls to get the match,
251 # but I think this can only find the first match, not duplicates.
252
253 # set or increment pagelist marker
254 this_page._macroRef_pagelist[inc_name] = this_page._macroRef_pagelist.get(inc_name, 0) + 1
255
256 # need to reset ref_key within loop, as it might have been modified
257 ref_key = args.group('ref')
258
259 # make et al italic unless #pragma ref-ital off
260 if macro.request.getPragma('ref-ital') != 'off':
261 ref_key = ref_key.replace("et al","''et al''")
262
263 # bracket year (last 'word' of ref key) for cite=bktfn, bktlk or bkt
264 if cite in ['bktfn', 'bktlk', 'bkt']:
265 ref_key = ref_key.rstrip()
266 ref_len = len(ref_key)
267 year_pos = ref_key.rfind(' ')
268 year_bkt = _out_year_bkt
269 if macro.request.getPragma('ref-year-bkt') != None:
270 #TODO check if the escape call really needed or does getPragma handle the html risk
271 year_bkt = wikiutil.escape(macro.request.getPragma('ref-year-bkt'))
272 if year_bkt.count("^") != 1:
273 dec_page()
274 return (_msg_bad_insert % ('ref-year-bkt', year_bkt))
275 year_bkt = year_bkt.replace("_"," ").replace("^","%s",1)
276 year_bkt = unwrap(year_bkt,"\\\"'")
277 year_str = year_bkt % (ref_key[year_pos+1:ref_len])
278 ref_key = ref_key[0:year_pos] + year_str
279
280 if ref_found:
281 # insert the ref value into the page as a footnote only
282 if cite == 'fn':
283 result_pending = _out_fn % (inc_page.get_body())
284
285 # insert the ref key (modified) into the page followed by the ref value into the page as a footnote
286 elif cite in ['keyfn','bktfn','keylk','bktlk']:
287 result_pending = _out_keyfn % (ref_key, inc_page.get_body())
288
289 # insert the ref key into the page only
290 elif cite in ['key', 'bkt']:
291 result_pending = ref_key
292
293 # insert the ref value into the page only
294 elif cite == 'val':
295 result_pending = inc_page.get_body()
296
297
298 if macro.request.getPragma('ref-debug') == 'wiki':
299 result_pending = _out_esc % (result_pending)
300
301 result_pending = wikiutil.renderText(request, WikiParser, result_pending).rstrip(' ')
302
303 # post formating of html citation and link
304 if cite in ('keylk','bktlk'):
305 ref_key = ref_key.replace("!","")
306 ref_key = ref_key.replace("''et al''","<em>et al</em>")
307 result_pending = (result_pending.replace("<sup>","")
308 .replace("</sup>","")
309 .replace(ref_key,"")
310 .replace("</a>","")
311 .rstrip(" 0123456789") + ref_key + "</a>")
312
313 if cite in ('fn','keyfn','bktfn'):
314 if macro.request.getPragma('ref-super') == 'off':
315 link_bkt = _out_link_bkt
316 if macro.request.getPragma('ref-link-bkt') != None:
317 #TODO check if the escape call really needed or does getPragma handle the html risk
318 link_bkt = wikiutil.escape(macro.request.getPragma('ref-link-bkt'))
319 if link_bkt.count("^") != 1:
320 dec_page()
321 return (_msg_bad_insert % ('ref-link-bkt', link_bkt, ))
322 link_bkt = (unwrap(link_bkt,"\\\"'").replace("_"," ")
323 .replace("^","%s",1))
324 t = tuple(result_pending.replace("<sup>","<>")
325 .replace("</a>","</a><>")
326 .replace("</sup>","")
327 .split("<>"))
328 result_pending = ('%s' + link_bkt + '%s') % (t[0],t[1],t[2])
329
330 if macro.request.getPragma('ref-debug') == 'html':
331 result_pending = _out_esc % (result_pending)
332 result_pending = wikiutil.renderText(request, WikiParser, result_pending).rstrip(' ')
333
334 result.append(result_pending)
335
336 # decrease or remove pagelist marker
337 dec_page()
338
339 # no match and last page in list, so insert warning message
340 # need to reset ref_key within loop, as it might have been modified
341 ref_key = args.group('ref')
342 if ref_match_count == 0:
343 result.append(_msg_match_none % (ref_key, dict_name, ))
344 elif ref_match_count > 1:
345 result.append(_msg_match_many % (ref_match_count, ref_key, dict_name, ))
346
347 return ''.join(result)
You are not allowed to attach a file to this page.