Attachment 'Ref-2.7.py'
Download 1 # -*- coding: iso-8859-1 -*-
2 """
3 MoinMoin - Ref macro, Version 2.7, 24.06.2014
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 'ref=', 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) search key text with found reference in a popup text box on mouseover, (5) found reference text only and (6) 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) can be used to show reference text in context as a popup tip. This option can also be used for other information, such as definitions of words that might be unfamilar to the reading, with the definitiions stored in a dictionary page.
18
19 Option (5) 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.
20
21 Option (6) simply inserts the search key text into the page. If reference text is inserted by Option (5) 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.
22
23 These options can be selected for each instance (Argument 2, with or without 'cite=', set to bkt, bktfn, bktlk, fn, key, keyfn, keylk, tip or val).
24
25 Case of the inserted key text can be overridden for options (2), (3) and (5) (`Argument 4`, with or without ` case = `, set to ` lower, title ` or ` upper`).
26
27 If 0 or >1 match is found, or dictpage is not found, a warning is inserted into the page.
28
29 <<Ref()>>
30
31 Inserts '[citation needed]' to act as a reminder and/or placeholder.
32
33 <<Ref([ref=]"key"[,[cite=]bkt|bktfn|bktlk|fn|key|keyfn|keylk|tip|val)] \
34 [,[dict=]["^]dictpage["]] \
35 [,[case=]lower|title|upper])>>
36
37 Argument labels (ref=, cite=, dict= and case=) are optional. If unlabelled, aruguments must appear in oder. Labelled arguments can appear in any order, but only after any unlablled arguments. A value for ref is required, all others are optional.
38
39 ref="key": search key to be matched in dictpage(s), set in single or double quotes. Setting ref="" is equivalent to <<Ref()>> (see above).
40
41 cite=bkt: insert only the key (reference code with the year bracketed) into the page. No link or footnote is created.
42
43 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.
44
45 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.
46
47 cite=fn: insert a footnote into the page as a numerical link only with the found value (reference text) as the footnote.
48
49 cite=key: insert only the key (reference code) into the page. No link or footnote is created.
50
51 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.
52
53 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).
54
55 cite=tip: insert key (reference code) and provide found value (reference text) as a popup tip. Tips can also be turned on for all references (other than cite=val) on the page using #pragma ref-tips on.
56
57 cite=val: insert only the found value (reference text) into the page. No link or footnote is generated.
58
59 dictpage(s): dictionary page name. If starting with ^, it is processed as a regex of dictpages to search (case sensitive). If containing any spaces or non-alphanumeric characters, it must be as a quoted string.
60
61 case=lower|title|upper: convert displayed text to lower, upper or title case, respectively (not for cite=val).
62
63 #pragma ref-cite citetype: set the default cite type for the page.
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 #pragma ref-dict dictpage(s): dictionary to be used by default for that page, replacing the wiki-wide default of RefDict. If starting with ^ (not as a quoted string), it is processed as a regex of dictpages to search (case sensitive).
70
71 #pragma ref-ital off: stops 'et al' in key being converted to italics.
72
73 #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.
74
75 #pragma ref-super off: turns off superscripting of numerical forward link to the footnote.
76
77 #pragma ref-tips on: turns on popup tips for all citation tips other than cite=val.
78
79 #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.
80
81 @copyright: 2010 Ian Riley <ian@riley.asia>
82 @licence: GNU GPL, see COPYING for details.
83
84 History
85
86 Version 2.7 - 24.06.2014; a few minor fixes to improve compatibility with FormattedPage macrop.
87
88 Version 2.6 - 17.11.2012: added option to overide case of inserted text, changed to wikiutil to for parsing parameters, improved error messages including message when a dictpage is not found.
89
90 Version 2.5 - 20.10.2012: added option to display found text as popup tips.
91
92 Version 2.4 - 10.10.2012: forced all search strings to be escaped for regex specials, to allow for example the inclusion of a '?' in the date of the reference key.
93
94 Version 2.3.- 09.05.2011: minor bug fix
95
96 Version 2.2 - 12.01.2011: streamlined the unwrap function.
97
98 Version 2.1 - 27.12.2010: some html security improvements.
99
100 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.
101
102 Version 1.0 - 19.12.2010: initial version.
103
104 Developed from:
105
106 (1) MoinMoin - Include macro
107
108 @copyright: 2000-2004 Juergen Hermann <jh@web.de>,
109 2000-2001 Richard Jones <richard@bizarsoftware.com.au>
110 @license: GNU GPL, see COPYING for details.
111
112 (2) http://moinmo.in/FeatureRequests/IncludeMacroInline using code of Junyx 2008-03-24 20:36:25
113
114 """
115
116 Dependencies = ["time", "namespace", "pages"]
117
118 import re
119 from MoinMoin import wikiutil
120 from MoinMoin.Page import Page
121 from MoinMoin.parser.text_moin_wiki import Parser as WikiParser
122
123 # remove character bracketing 'wrapped', if it is in 'wrappers'
124 def unwrap(wrapped,wrappers):
125 if (wrapped[0] in wrappers) and wrapped.endswith(wrapped[0]):
126 wrapped = wrapped[1:-1]
127 return wrapped
128
129 _msg = u'<strong class="error">Ref(): %s</strong>'
130 _msg_bad_arg = _msg % (u'invalid arguments {%s}')
131 _msg_bad_pragma = _msg % (u'invalid #pragma {%s}')
132 _msg_no_dict = _msg % (u'dict={%s} not found')
133 _msg_recursion = _msg % (u'recursive use of {%s} forbidden')
134 _msg_match_none = _msg % (u'no match for key={%s} in dict={%s}')
135 _msg_match_many = _msg % (u'%s matches for key={%s} in dict={%s}')
136 _msg_bad_insert = _msg % (u'Single insertion point ^ in {#pragma %s %s} obligatory')
137 _msg_ref_needed = u'[citation needed]'
138
139 _kw_case = [None,'lower','title','upper']
140 _kw_cite = [None,'fn','keyfn','bktfn','keylk','bktlk','tip','key','val','bkt']
141
142 _df_cite = u'keyfn'
143 _df_dict = u'RefDict'
144
145 _out_fn = u'<<FootNote(%s)>>'
146 _out_keyfn = u'%s' + _out_fn
147 _out_year_bkt = u' (%s)'
148 _out_esc = u'{{{%s}}}'
149 _out_link_bkt = u'[%s]'
150 _out_tip = u'<span style="cursor: help; border-bottom: 1px dashed;" title="%s">%s</span>'
151
152 def execute(macro, args):
153 request = macro.request
154 _ = request.getText
155
156 def dec_page():
157 # decrease or remove pagelist marker
158 if this_page._macroRef_pagelist[inc_name] > 1:
159 this_page._macroRef_pagelist[inc_name] = this_page._macroRef_pagelist[inc_name] - 1
160 else:
161 del this_page._macroRef_pagelist[inc_name]
162
163 # return immediately if getting links for the current page
164 if request.mode_getpagelinks:
165 return ('')
166
167 # parse and check arguments
168 try:
169 args_parser = wikiutil.ParameterParser('%(ref)s%(cite)s%(dict)s%(case)s')
170 (count,args_dict) = args_parser.parse_parameters(args)
171 except:
172 return (_msg_bad_arg % ('cannot parse: ' + args))
173
174 # flag reference needed
175 text = args_dict['ref']
176 if (text == '') or (text == None):
177 return (_msg_ref_needed)
178
179 # get cite or apply page default
180 cite = args_dict['cite']
181 if not cite in _kw_cite:
182 return (_msg_bad_arg % ('invalid cite: ' + cite))
183 if cite == None:
184 cite = macro.request.getPragma('ref-cite')
185 if not cite in _kw_cite:
186 return (_msg_bad_pragma % ('invalid #pragma ref-cite: ' + cite))
187 if cite == None:
188 cite = _df_cite
189
190 # establish dictionary page to be searched
191 dict_name = args_dict['dict']
192 if dict_name == None:
193 dict_name = macro.request.getPragma('ref-dict')
194 if dict_name == None:
195 dict_name = _df_dict
196
197 # get case change or leave as is
198 case = args_dict['case']
199 if not case in _kw_case:
200 return (_msg_bad_arg % ('invalid case: ' + case))
201
202 # prepare page
203 result = []
204 result_pending = []
205 this_page = macro.formatter.page
206 if not hasattr(this_page, '_macroRef_pagelist'):
207 this_page._macroRef_pagelist = {}
208
209 # get list of dictionary pages to search
210 inc_name = wikiutil.AbsPageName(this_page.page_name, dict_name)
211 pagelist = [inc_name]
212 if inc_name.startswith("^"):
213 try:
214 inc_match = re.compile(inc_name)
215 except re.error:
216 pass # treat as plain page name
217 else:
218 # get user filtered readable page list
219 pagelist = request.rootpage.getPageList(filter = inc_match.match)
220
221 ref_key = ''
222 ref_match_count = 0
223 val_end = '\n'
224
225 # iterate over pages
226 for inc_name in pagelist:
227 if not request.user.may.read(inc_name):
228 continue
229 if inc_name in this_page._macroRef_pagelist:
230 dec_page()
231 return (_msg_recursion % (inc_name, ))
232
233 fmt = macro.formatter.__class__(request, is_included=True)
234 fmt._base_depth = macro.formatter._base_depth
235 inc_page = Page(request, inc_name, formatter=fmt)
236 if not inc_page.exists():
237 return (_msg_no_dict % (inc_name, ))
238 inc_page._macroRef_pagelist = this_page._macroRef_pagelist
239
240 # prepare for ref_key search
241 body = inc_page.get_raw_body() + '\n'
242 ref_pos = 0
243 end_pos = -1
244 ref_found = True
245
246 # need to reset ref_key within loop, as it might have been modified
247 ref_key = args_dict['ref']
248
249 # remove any WikiName escape character
250 ref_key = ref_key.replace("!","")
251
252 if ref_key:
253 #try:
254 # ref_match = re.compile(ref_key + ':: ', re.M).search(body)
255 #except re.error:
256 ref_match = re.compile(re.escape(ref_key + ':: '), re.M).search(body)
257 if ref_match:
258 ref_pos = ref_match.end()
259 else:
260 ref_found = False
261
262 if val_end:
263 #try:
264 # end_match = re.compile(val_end, re.M).search(body, ref_pos)
265 #except re.error:
266 end_match = re.compile(re.escape(val_end), re.M).search(body, ref_pos)
267 if end_match:
268 end_pos = end_match.start()
269 else:
270 ref_found = False
271
272 if ref_found:
273 inc_page.set_raw_body(body[ref_pos:end_pos], modified=True)
274 ref_match_count = ref_match_count + 1
275
276 #TODO: loop back over remainder of body to find duplicate keys to allow user to be warned.
277 # Perhaps is would be better to use WikiDict calls to get the match,
278 # but I think this can only find the first match, not duplicates.
279
280 # set or increment pagelist marker
281 this_page._macroRef_pagelist[inc_name] = this_page._macroRef_pagelist.get(inc_name, 0) + 1
282
283 # need to reset ref_key within loop, as it might have been modified
284 ref_key = args_dict['ref']
285
286 if case:
287 if case == 'upper': ref_key = ref_key.upper()
288 elif case == 'title': ref_key = ref_key.title()
289 elif case == 'lower': ref_key = ref_key.lower()
290
291 # make et al italic unless #pragma ref-ital off
292 if macro.request.getPragma('ref-ital') != 'off':
293 ref_key = ref_key.replace("et al","''et al''")
294
295 # bracket year (last 'word' of ref key) for cite=bktfn, bktlk or bkt
296 if cite in ['bktfn', 'bktlk', 'bkt']:
297 ref_key = ref_key.rstrip()
298 ref_len = len(ref_key)
299 year_pos = ref_key.rfind(' ')
300 year_bkt = _out_year_bkt
301 if macro.request.getPragma('ref-year-bkt') != None:
302 #TODO check if the escape call really needed or does getPragma handle the html risk
303 year_bkt = wikiutil.escape(macro.request.getPragma('ref-year-bkt'))
304 if year_bkt.count("^") != 1:
305 dec_page()
306 return (_msg_bad_insert % ('ref-year-bkt', year_bkt))
307 year_bkt = year_bkt.replace("_"," ").replace("^","%s",1)
308 year_bkt = unwrap(year_bkt,"\\\"'")
309 year_str = year_bkt % (ref_key[year_pos+1:ref_len])
310 ref_key = ref_key[0:year_pos] + year_str
311
312 if ref_found:
313 # insert the ref value into the page as a footnote only
314 if cite == 'fn':
315 result_pending = _out_fn % (inc_page.get_body())
316
317 # insert the ref key (modified) into the page followed by the ref value into the page as a footnote
318 elif cite in ['keyfn','bktfn','keylk','bktlk']:
319 result_pending = _out_keyfn % (ref_key, inc_page.get_body())
320
321 # do nothing now, but later insert ref key with ref value as tip
322 elif cite == 'tip':
323 result_pending = u''
324
325 # insert the ref key into the page only
326 elif cite in ['key', 'bkt']:
327 result_pending = ref_key
328
329 # insert the ref value into the page only
330 elif cite == 'val':
331 result_pending = inc_page.get_body()
332
333 if macro.request.getPragma('ref-debug', None) == 'wiki':
334 result_pending = _out_esc % (result_pending)
335
336 result_pending = wikiutil.renderText(request, WikiParser, result_pending).rstrip(' ')
337
338 # post formating of html citation and link
339 if cite in ['keylk','bktlk']:
340 ref_key = ref_key.replace("!","")
341 ref_key = ref_key.replace("''et al''","<em>et al</em>")
342 result_pending = (result_pending.replace("<sup>","")
343 .replace("</sup>","")
344 .replace(ref_key,"")
345 .replace("</a>","")
346 .rstrip(" 0123456789") + ref_key + "</a>")
347
348 if cite in ['fn','keyfn','bktfn']:
349 if macro.request.getPragma('ref-super') == 'off':
350 link_bkt = _out_link_bkt
351 if macro.request.getPragma('ref-link-bkt') != None:
352 #TODO check if the escape call really needed or does getPragma handle the html risk
353 link_bkt = wikiutil.escape(macro.request.getPragma('ref-link-bkt'))
354 if link_bkt.count("^") != 1:
355 dec_page()
356 return (_msg_bad_insert % ('ref-link-bkt', link_bkt, ))
357 link_bkt = (unwrap(link_bkt,"\\\"'").replace("_"," ")
358 .replace("^","%s",1))
359 t = tuple(result_pending.replace("<sup>","<>")
360 .replace("</a>","</a><>")
361 .replace("</sup>","")
362 .split("<>"))
363 result_pending = ('%s' + link_bkt + '%s') % (t[0],t[1],t[2])
364
365 # escape HTML including quotes
366 tip = wikiutil.escape(inc_page.get_body(), quote=True)
367
368 #convert to html then remove tags to remove wiki markup
369 tip = wikiutil.renderText(request, WikiParser, tip).rstrip(' ')
370 tip = re.sub('<[^>]*>', '', tip)
371
372 if cite == 'tip':
373 #markup ref_key
374 result_pending = wikiutil.renderText(request, WikiParser, ref_key).rstrip(' ')
375
376 if (cite == 'tip') or (cite != 'val' and macro.request.getPragma('ref-tips') == 'on'):
377
378 result_pending = _out_tip % (tip, result_pending)
379
380 if macro.request.getPragma('ref-debug', None) == 'html':
381 result_pending = _out_esc % (result_pending)
382 result_pending = wikiutil.renderText(request, WikiParser, result_pending).rstrip(' ')
383
384 result.append(result_pending)
385
386 # decrease or remove pagelist marker
387 dec_page()
388
389 # no match and last page in list, so insert warning message
390 # need to reset ref_key within loop, as it might have been modified
391 ref_key = args_dict['ref']
392 if ref_match_count == 0:
393 result.append(_msg_match_none % (ref_key, dict_name, ))
394 elif ref_match_count > 1:
395 result.append(_msg_match_many % (ref_match_count, ref_key, dict_name, ))
396
397 return ''.join(result)
You are not allowed to attach a file to this page.