Differences

This shows you the differences between two versions of the page.

--- wiki:refnotes_plugin [2023/02/18 06:44] – removed - external edit (Unknown date) 127.0.0.1
+++ wiki:refnotes_plugin [2023/02/18 06:44] (current) – ↷ Page moved from contributing:refnotes_plugin to wiki:refnotes_plugin suedunham
@@ Line 1: / Line 1: @@
+====== RefNotes plugin ======
+[[doku>plugin:refnotes|RefNotes plugin page]]
+This is the most recently-added plugin, and its uses are still being explored. The references dictionary upon which it relies has been implemented in the quickest, simplest way, but this may change.
+The conventions for its use are still being developed as well. There too, what is presented here is subject to change. The upshot is that this is how works in the ''works:'' section of the wiki are cited from the ''harn:'' and other "World" sections.
+===== Basic use =====
+The plugin is invoked with a syntax resembling that of standard DokuWiki footnotes. It looks something like this, taken from [[harn:kaldor:albernet|the page for Albernet Manor]] in Kaldor.
+<panel>
+"Loral is the second eldest of Clan Ebor. Loral has a younger brother at Iversen. His older brother Minal will likely soon succeed his sickly father as Bailiff of Albernet."[(:ref:abriel)]<sup>:p.14</sup>
+----
+~~REFNOTES ref~~
+</panel>
+The reference is made in this way.
+<code>
+"Loral is the second eldest of Clan Ebor. Loral has a younger brother at Iversen. His older brother Minal will likely soon succeed his sickly father as Bailiff of Albernet."[(:ref:abriel)]<sup>:p.14</sup>
+</code>
+Here we see a quotation from the work, [[works:harn:kaldor:nelafayn:abriel]] in the main body of the page. following it is the relevant reference to the ''works:'' page from the dictionary, '':ref:abriel'', enclosed in brackets and parentheses, ''%%[()]%%''. In the vast majority of cases, that reference name is simply '':ref:'' followed by the base page name—without any namespaces—of the ''works:'' page.
+Following that, since, in this usage, the plugin doesn't provide it, is a manual, superscripted page number following a colon, '':p.14''. The colon is there and there is no space after the period because reasons. A multi-page reference might look like ''%%:pp.14--5%%'', with the two hyphens resolving to a suitable en dash.
+Optionally, the location of the generated references can be defined with the ''%%~~REFNOTES ref~~%%'' command. By default, the plugin will put them at the bottom of the page, so this is often not necessary.
+<code>
+----
+~~REFNOTES ref~~
+</code>
+A more detailed discussion of what can be done with the syntax [[doku>plugin:refnotes:syntax|can be found here]].
+===== Style considerations =====
+Yeah, that's pretty clunky. It may change. Suggestions are welcome.
+This is the general idea, however. A quotation, or a paraphrase, or some other datum drawn from a source is written in the main body of a page in the ''harn:'' section of the wiki, and a citation is made to a page in the ''works:'' section with a footnote linking it. The model in mind is something like [[wiki>harn|Wikipedia]], or even a term paper from school.
+There is a more sophisticated way of using the plugin that does format page numbers, the Harvard engine. However, this requires that the references dictionary be redone. Doing so may yield other benefits (fingers crossed), but that has not yet been determined.
+However, even if that all works, we would still have to abuse the data to get something better-suited to our own needs. The citation style that results is geared toward the papers of academic writing. For HârnWiki, citations such as "(Crossby, N. Robin, 1985)" or "(Mould, Kerry, 2005)" would obfuscate more than they reveal.
+===== Other downstream effects =====
+Use of this plugin threatens to force the resolution of a thorny issue, that of [[composite_works]]. Many works are sold loose-leaf, and some comprise several separate articles, numbered individually. This allows people to organize their collections as they see fit, and thus Hârnic convention doesn't use a "p." in a page number at all. Rather, the citation above would be given as "Abriel 14", including the name of the article. This seems too long for superscript, however, and the name of the work is right there if one hovers the pointer over the reference.
+To date, the wiki's handling of composite works is still inconsistent. Referring to them with this plugin means that even more composite works ought to be divided into their constituent articles with separate pages for each. In this way, "Pilot" p. 1 can be cited more readily than //Pilot's Almanac// p., um, 7? 5? 1?
+Luckily, the several "World" sections of the wiki are slow-filling, so that resolution gets deferred. Hopefully, that will be done as the present editor's grand scheme to create a database from all the Hârn data and create all the pages in an automated fashion therefrom comes to fruition.
+===== References dictionary =====
+The [[:refnotes:works|References dictionary]] is currently the simplest implementation, a big, two-column table of reference names and text on one page. It was readily-enough generated by running a Python script ({{get_wiki_ref_db_from_pages.zip| zip download}}) on a local, offline copy of the wiki. The present editor does not recall if some additional, hand-done editing of it was still required or if that was solved programmatically, but there wasn't much needed.
+This is not a very clean process for a live wiki, however. Subsequent additions to the ''works:'' section then need corresponding edits to this table. This isn't hard, but it's another thing to remember.
+There are other ways of doing this. The most involved is maintaining a collection of pages for each reference that each contain a structured data element. This would (probably? maybe?) require one or the other of the [[doku>plugin:data|Structured Data plugin]] or [[doku>plugin:struct|Struct plugin]] be employed.
+This seems like even more work, but then we already have a namespace full of individual pages for each reference. It could be that the ''works:'' section itself could be made to serve this purpose as well as what it presently does. The advantage would be that it's much more natural to then include the necessary data while adding a new page. More work needs to be done to explore this possibility before anything more can be said.