Contents

Appendices

Ref

Background and rationale

There have been several worthy macro/parser offerings to provide a citation/reference system for Moin. These mostly use BibTex formatting and parser (either internal or external). Although these have merit, I felt a system based on Moin dictionaries and the footnote macro would be possible, simpler and more consistent (even if somewhat constrained).

Rather than extract and parse reference database fields (such as BibTex), I felt it better to leave that task to the specialist programs like Zotero (GPLv3, http://www.zotero.org) or EndNote (proprietary). These can be used to collect, store and format references. Although these only have styles for various journals and publishing houses, it is a simple matter to get them to generate output in Moin dictionary format, with wiki markup as needed (Italics, bold, ...). It is unlikely that more than one formatting scheme would be desirable/required for a particular wiki, so the reference text could also be added directly to a dictionary page in the format required, which is easy to read and maintain. The latter approach might be best for a multi-contributor wiki pages (unless the team uses a shared bibliography provided by, say, Zotero groups).

Moin footnotes are very useful, but inclusion of the reference text as an argument to the macro disperses the data throughout a page. This makes maintenance difficult, reduces the readability of the raw text and if the citation needs to be repeated within or between pages, redundant instances of the data are needed (adding further to the maintenance problem). A solution is to use a variable and store the data in a separate place. However, current variable substitution options (viz. @key@, Include, GetText), either don't work as arguments for the footnote macro (it either does not process markup or has layout issues) or are not sufficiently flexible.

The Ref macro attempts to provide a simple way to use a key:value list to help in adding citations and references to Moin pages. The keys can be the same as a standard in-text citations (author(s) year) and/or nemonic codes (if only numbered citations are used). Some simple processing of the key is provided; Italicising 'et al', bracketing the year, and handling !WikiName escapes, as well as bracketed non-superscript links and full key text as links. If numbered footnote citations are not required, the macro can also be used to build a reference (or further reading) list at the end of the page.

To keep the markup as minimalist as possible, #pragma settings are used for setting preferences for the whole page. So citations can be included cleanly as <<Ref("key")>>. Setting citation type and dictionary argument in the macro call should only be required occasionally.

Of course, the Ref macro cannot serve every possible citation/reference scheme, but it does provide a simple, easily-maintained, consistent and workable option.

Description

A macro to cite references from a dictionary page (a key:: value listing).

Searches one or more dictionary pages to match key (Argument 1, with or without ref=, as 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.

The dictionary page is set to RefDict by default, or can be set for (a) the whole page by #pragma ref-dict, or (b) for individual calls by Argument 3.

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.

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).

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.

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.

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.

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.

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).

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).

If no or more than one match is found, or the specified dictionary is not found, a warning is inserted into the page.

Usage

<<Ref()>>

Inserts '[citation needed]' to act as a reminder and/or placeholder.

<<Ref([ref=]"key"[,...])>>

<<Ref([ref=]"key"[,[cite=]bkt|bktfn|bktlk|fn|key|keyfn|keylk|tip|val)] \
                 [,[dict=]["^]dictpage["]] \
                 [,[case=]lower|title|upper])>>

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.

ref="key": search key to be matched in dictpage(s), set in single or double quotes. Setting ref="" is equivalent to <<Ref()>> (see above).

cite=bkt: insert only the key (reference code with the year bracketed) into the page. No link or footnote is created.

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.

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.

cite=fn: insert a footnote into the page as a numerical link only with the found value (reference text) as the footnote.

cite=key: insert only the key (reference code) into the page. No link or footnote is created.

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.

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).

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. 

cite=val: insert only the found value (reference text) into the page.  No link or footnote is generated.

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.

case=lower|title|upper: convert displayed text to lower, upper or title case, respectively (not for cite=val).

#pragma ref-cite citetype: set the default cite type for the page.

#pragma ref-debug wiki: shows the wiki markup without processing it.

#pragma ref-debug html: shows the markup as html.

#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).

#pragma ref-ital off: stops 'et al' in key being converted to italics.

#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.

#pragma ref-tips on: turns on popup tips for all citation tips other than cite=val.

#pragma ref-super off: turns of superscripting of numerical forward link to the footnote.

#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.

Download & Release Notes

Download	Release Version	Moin Version	Release Notes
Ref-2.7.py	2.7	1.9.2

Examples

Example 1

Example 1a

Example 2

Example 2a

Example 3

Example 4

Example dictionary

The dictionary used for these examples was:

Literature references

 Croll and Mathews 1977:: Croll NA, Mathews BE (1977) ''Biology of Nematodes''. (Wiley: NY, USA) 201 pp.

 MacNish and Neate 1996:: !MacNish GC, Neate SM (1996) Rhizoctonia bare patch of cereals: an Australian perspective. ''Plant Disease'' '''80''', 965-971.

 Sijmons et al. 1994:: Sijmons PC, Atkinson HJ, Wyss U (1994) Parasitic strategies of root nematodes and associated host cell responses. ''Annual Review of Phytopathology'' '''32''', 235-259.

Term definitions and other tests

 bacterium:: single-celled, prokaryotic organism

 escape me:: <strong class="error">escape me</strong>

 nematode:: microscopic roundworm

 remove wiki markup:: ''italic'' '''bold''' !EscapedWikiName

 RileyLink:: test link to RileyLink page

If only numerical footnote links are needed, nemonic codes like CM77, MM86 and Sal94 could be used as keys.

History

Version 2.7 - 24.06.2014; a few minor fixes to improve compatibility with FormattedPage macrop.

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.

Version 2.5 - 20.20.2012: added option to display found text as popup tips.

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.

Version 2.3.- 09.05.2011: minor bug fix.

Version 2.2 - 12.01.2011: streamlined the unwrap function.

Version 2.1 - 27.12.2010: some html security improvements.

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.

Version 1.0 - 19.12.2010: initial version.

Developed from:

MoinMoin - Include macro
http://moinmo.in/FeatureRequests/IncludeMacroInline using code of Junyx 2008-03-24 20:36:25

This is my first go at Python and Moin macro programming, so perhaps not as well designed as possible, and building from the Include macro might not be as good as doing it from scratch. All suggestions and improvements welcome.

Copyright

License

GNU GPL, see COPYING for details.

Known issues and limitations

Trailing line break in preview.
Does not detect or warn of duplicates within a single dictionary page. Ref() uses the first match. For dictionary integrity, duplicates must be eliminated/avoided by the creator/maintainer of the dictionary. The parser dictate.py is useful for maintaining dictionaries.
Dictionary keys need to be unique and so alphabetic suffixes are usually added to remove ambiguity (e.g. when, say, Jones et al. 2010a, 2010b and 2010c are different papers). However, sometimes one paper will be cited on a page without citing all those that precede it, thereby creating an inconsistency in the footnote list. It is not an issue if numeric-only citation is used (provided the suffix is not added after the year in the value text). For author-year citations, a solution needs to be found. A separate dictionary page or subpage for each citing page would work, but reintroduces duplication and maintenance issues.
The footnote macro only gives references numbered in citation order. So if an alphabetical list (with hyperlinks) is desired, it is conceivable to cite all reference in alphabetical order before using them in the text, hiding them in {{{#!wiki comment ... }}}. This is somewhat untidy, but the main problem is that an additional back reference to the hidden citation follows each footnote. A sort option for the footnote macro would be a better solution.
Changed #pragma values do not take effect in preview; this only happens after a page save.
The #pragma ref-debug options should perhaps go, or be left undocumented/commented-out. Perhaps, I will do this after some more testing and incorporating advice from others.
Calls to <<Ref(...)>> in captions provided to the figures.py parser are processed before the rest of the page, so the numbering of the footnotes will not be in the order of appearance on the page. Using cite options keylk and bktln avoids the problem for text but not the reference listing. So I need to find a way to sort the reference listing by key and present it as an un-numberlist. Also, backlinks might be best cycled for each item rather than the whole list.

Hits: 489