Formatting Notes, Commentary and Cross-References

This is just a little brainstorm to figure out now how I am going to format notes, commentary, and cross-references. The problem goes something like this. It’s easy to mark notes in a section by verse, but difficult to mark notes in a section by a particular word. If I use double braces ((like this)), which is DokuWiki’s default footnoting mechanism, the text could get very messy. One idea I had was to preface all footnotes such as ((5a Hebrew: lamos)), and then have an ‘a’ on the word in the text. But, they are footnotes, so they would show a number as well. Then I thought if I just keep them in a separate section with ‘5a’ as the heading, I could have a manually superscripted ‘a’ on the word. Then the layout script could interpret the line 5a in the comments section as belonging to that particular word in the text. This is probably the easiest solution, unfortunately DokuWiki does not seem to have an out-of-paragraph footnoting mechanism.

The RefNotes plugin

Although I am lax to rely on a plugin, the RefNotes plugin has been recently updated (looks active) and seems to be able to do what I want: Keep notes in a separate section, and even have different kinds of notes. I will investigate this further and if it allows me to have numbers and letters as well, or i, ii, etc. then I can have these represent certain kinds of notes such as Cross-Reference, Commentary, Translation Notes, Rashi, and so forth. In any case, manually tagging words with superscript, which will then be searched for in named sections (ex. == Cross-Reference) will be a default, or fallback functionality.

With this development the process forward for representing the Bible both on Dokuwiki, and also in a custom reader via a simple PHP script, looks relatively complete. So why do I have “writer’s block” over this? Maybe just a habit from not knowing what to do next. I’ll try sitting down and writing a basic PHP layout reader tonight. If it is promising we may suddenly have a decent reader, complete with collapsible inline commentary, or in a column, plus possibly sticky notes on the bottom of the page (bootstrap), pagination, and so many more exciting things!

Also, as an aside, please check out our “gofundme” page if you would like to support this project. The fact is this is an absolutely massive undertaking and I won’t be able to complete the entire Bible at this rate for more than 20 or 30 years. I want to do this right, and in a reasonable time. If you would like to support this project please visit us at NSV Bible Project ( You can help change the world, too!

Update on RefNotes

So I’ve been looking at the RefNotes plugin, and it auto-numbers (using various styles) the notes on the page. Versus manual superscripting, this is a better alternative. I’ve been able to use the lowercase latin style to successfully create a custom “note” namespace which pretty much looks like the letter note system in the ASV (and many other bibles). When exported to xhtmlbody it produces superscripted links which link to and are named ex. name="refnotes:note:1:ref1" — this of course being exactly what I was looking for on the DokuWiki end, more or less. Manual superscripting takes 11 characters and must be maintained manually; this takes four characters plus namespace name and a colon and identifier, so is technically more characters, but I feel it’s a better system from an editor’s point of view, and even just for human readability there is easy to read information in those characters compared to an endless sea of meaningless <sub></sub> tags.

You can also configure the notes to appear by namespace, allowing you to organize the notes into columns. They can be configured to appear in various text styles as well. Overall this is probably what I am looking for. We will use RefNotes to mark up the entire document.

However, it seems that the only real need for this is to do the actual notes on a per-word basis. The verse notes are things like cross reference and commentary which is not really intended to be in the reader’s mind during reading. All the same, having this automatically managed with lowercase letters is better than DokuWiki’s normal footnoting system, so we will move towards incorporating this for the notes system, and will layout other sections (like cross-reference) using the reader script. I mean, we’re going to layout notes with the script too, but in terms of “print version” having the footnotes layout like normal bible notes with lowercase letters seems convenient enough for now.

Why Not Just Use Creole ^^superscripting^^?

It’s possible to use creole as a markup system even with DokuWiki fallback; “5 Something^^a^^ like this^^b^^.”

Then, we could create an automatic link to comment section [5a] and [5b]. The problem is, that DokuWiki doesn’t create the link automatically. Do we care? Maybe. The PHP layout/reader could create the link. So typing ^^5a^^ versus [(note:a)]  is not going to damage the text so much. It would be trivial to autoconvert from one format to another for print later, if need be Plus there is, of course, export_xhtmlbody).

Overall it seems the RefNotes plugin is just good enough that it might as well be used despite some of the inevitable quirks using a foreign plugin will introduce.

After all, in the end there is no real interest in tagging Rashi (or commentary much) to a word or verse, versus a sectioned display; so there it is; RefNotes for notes, and commentary (even cross-reference) in it’s own section.

Using cites in commentary

The big problem with the RefNotes Plugin is that you can’t put cites inside a note. So if a note is being used for commentary the cites system doesn’t work. The solution, to put commentary in it’s own area (verse by verse) is limiting. If then, we must use something like [5a] and manually process it for the reader, leaving it to look ugly in Dokuwiki (or use ^^5a^^) then it won’t be a “blue link” in Dokuwiki. That kind of sucks. It would look good everywhere except DokuWiki.

But you know, why bother with all this. We can easily create a Dokuwiki plugin based on RefNotes (or a custom one) or modify footnoting to work how we want; to have [(5a)] for example, or whatever, link to a section and have formatting be done on a section by section basis. After all the point is coming up with a custom reader anyways. Dokuwiki is just for editing. And, refnotes is very convenient — for notes. The other sections appear in their own place anyways.

But I think all of this is problematic and too difficult. It just doesn’t seem to be an interesting solution.

Now here’s a solution!

The answer came to me. Mark each comment as a section (4th or 5th order is ok, as long as it doesn’t cloud the table of contents). This is fine on Dokuwiki; we will have it display differently in the reader script. Then just do a link to the section i.e. [[#1a]]. You can even superscript it. Yes, it requires manual setup, but considering the simplicity of it all, I think this is the solution I will use. It creates links to ids which have nothing to do with the section name, but that is irreverent to a reader script, and DokuWiki seems to skip around that anyways. Whew, that was a lot of brainstorming but I think we found a good answer in the end!

Leave a Reply

Your email address will not be published.