Differences

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

--- nsv:nsv_page_format [2026/07/20 04:42] – appledog
+++ nsv:nsv_page_format [2026/07/20 12:04] (current) – external edit 127.0.0.1
@@ Line 1: / Line 1: @@
 = NSV Page Format
+* Working copy of [[nsv:nsv_page_format]]. Keep the two in step: this is the
+  contract between the wiki and the reader, and it is what a future database
+  import will be written against.
 == Page Titles
 Each page begins with the page name and the license. This is ignored by the reader, but is of course used to index the page.
@@ Line 8: / Line 12: @@
 </code>
-Next let's discuss the data used to construct the main reader formatting:
+== Page names
+Page ids are **lowercase** and filed **by section**, not in one flat namespace:
+<code>
+nsv:<section>:<book>_<chapter>      ex. nsv:torah:genesis_1
+</code>
+Sections follow the Tanakh division: ''torah'', ''neviim'', ''treiasar'', ''ketuvim'', with the New Testament under ''gospel''. The wiki also carries ''apocrypha'', ''apostolic'', ''christian'', ''christian_other'', ''christianb'' and ''ntapocrypha'', which the reader's canon does not yet include.
+**Psalms is filed singular** -- ''psalm_23'', titled "Psalm 23". Because of this the reader cannot rebuild a chapter's title from the book name; it takes the title from the page's own ''=='' heading. Get that heading wrong and the reader shows an empty chapter.
+== The reading section
 <code>
 == Genesis 1
@@ Line 19: / Line 33: @@
 === The First Day
 And God said, "Let there be light," and there was light.
+</code>
-And God saw that the light was good, therefore God divided[c] between the light and between[d] the darkness.
+Three heading levels are in play inside a chapter:
-And God called the light "day", and the darkness he called "night". And there was morning and there was evening: day one[e].
+^ level ^ meaning ^
-</code>
+| ''== Genesis 1''       | the chapter |
+| ''=== The First Day''  | a section within the chapter |
+| ''==== ...''           | a subsection -- a lesser form of the section heading |
-The above is an example; what you will notice is:
+Both section and subsection headings render, the subsection a step below its section. Use ''===='' where a passage subdivides a section rather than starting a new one; do not use it merely because a section feels minor. (The day headings in Genesis 1 were written as ''===='' and were really sections, so they were moved up.)
-* Chapter headings are second level (ex. == Genesis 1)
-* Section headings are third level (ex. == The First Day)
-* Each new line that begins with a verse number is the start of that verse in the chapter. Currently, each line appears separated by the others; this means in this protocol there is no formatting. The verses are taken and interpreted by the reader.
-'interpreted by the reader' means paragraphs are currently decided by headings, ex. '=== The First Day' starts a new paragraph, and a blank heading (ex. "=== ") is invisible, but starts a new paragraph.
+* Each new line beginning with a verse number starts that verse. There is no formatting in the verse text itself; the reader interprets it.
+'interpreted by the reader' means paragraphs are decided by headings: ''=== The First Day'' starts a new paragraph, and a **blank heading** (''==='' or ''===='' alone) is invisible but still starts one. Both levels behave the same way.
 Other formatting rules:
-* Notes and subscripts are not shown unless they are written-in. For example, "4 And God saw that the light was good, therefore God divided[c] between the light and between[d] the darkness." -- c and d are shown as subscripts in the appropriate location. They don't have to link to anything right now, just display as they do now, and we will modify it later.
+* Notes and subscripts are not shown unless written in. In "God divided[c] between the light and between[d] the darkness", ''c'' and ''d'' appear as superscripts where they sit. They need not link anywhere yet.
+* ''//text//'' renders as italics in verse text.
+== Apparatus sections
+After the reading section come the apparatus sections, each a second-level heading:
+<code>
+== Notes
+== Cross Reference
+== Commentary
+== Rashi
+</code>
+**Order matters.** The reader shows them in the order the page gives them, not in a fixed order of its own. Notes and cross-references appear in the reader's right-hand column; commentary and Rashi below the text.
+**Spelling matters.** Write ''== Cross Reference'' -- singular, one space, no hyphen. ''Cross-Reference'' was written on two pages and its content was silently dropped for years.
+**Empty sections are skipped.** A heading with nothing under it renders nothing, so there is no need to write the skeleton out in advance. ''== Concordance'' currently appears on 535 pages with no content on any of them.
+=== Two kinds of content
+Within an apparatus section, content is one of two kinds, and a section may hold both.
+**Verse-keyed** entries open with a marker naming the verse:
+<code>
+== Notes
+[1] BERESHEIT -- 7225 also means "choice" as well as "first" ...
+[2] a wind from God -- In Hebrew, 'Ruach Ha-Kodesh' ...
+[6f] 'a firmament' is h.7549 ...
+</code>
+The marker may carry a letter (''[6f]'', ''[30h]''). The letter identifies **which footnote marker in the verse** the entry belongs to, matching the ''[f]'' in the verse text. It is not a verse number: ''6f'' is a key in its own right.
+Entries are shown in the order the page gives them -- the reader does not sort them -- so write them in verse order.
+**Book-level** material is introduced by a third-level heading and belongs to the work rather than to any verse:
+<code>
+== Commentary
+=== Goals of the Commentary Section
+The goal of the commentary section is twofold ...
+</code>
+A heading that **opens with a verse marker** is a verse-keyed entry written as a heading, not book-level material. The words after the marker are the lemma being commented on:
+<code>
+=== [2] "and on the seventh day God ended..."
+</code>
+Loose prose before any heading or marker is treated as book-level and is intentional.
+== Cross references
+Currently free text, one line per verse marker:
+<code>
+[2] Isaiah 45:7
+[2a] Genesis 8:1, Deuteronomy 4:15-18
+[26] Leviticus 11:44-45, Leviticus 19:2, 1 Peter 1:16
+</code>
+Shorthand in use, which a human resolves from context and software cannot:
+* ''18:19'' -- chapter:verse in the **same book**
+* ''v.20'' -- verse in the **same chapter**
+* ''4:15-18'' -- a verse range
+About 30% of citations are written in full. **Prefer the full form** -- book, chapter, verse -- on anything new. Full citations are what will let the reader show a passage's inbound references, which the wiki cannot do at all.
+== Section introductions
+Each division has a prose page the reader shows when a division is chosen without a book:
+<code>
+nsv:<section>:start        ex. nsv:neviim:start
+</code>
+Torah is the exception: it has no ''start'' page and uses ''nsv:torah:Torah''.
+These pages are ordinary prose. The reader understands headings, nested lists, ''[[links]]'', ''**bold**'', ''//italics//'' and horizontal rules. Links to a chapter (''nsv:neviim:Joshua'') resolve into the reader; anything with no counterpart renders as plain text rather than a dead link.
+== NSV constructs
+Provided by the ''nsv'' wiki plugin, so they render on the wiki and in the reader alike. They name what a passage **is**, not how it should look -- which is why they survive a move to a database, where an "indent" would not.
+^ tag ^ meaning ^
+| ''<poetry>…</poetry>'' | Hebrew parallelism. Line breaks are kept, so a paired line may be written indented. |
+| ''<citation>…</citation>'' | Scripture quoted within scripture -- the Old Testament cited in the New. Not for ordinary speech, which quotation marks already handle. |
+| ''<letter>…</letter>'' | An inset document. |
+| ''<decree>…</decree>'' | A proclamation; the formal sibling of a letter. |
+| ''<p>''                | Starts a paragraph here. **No closing tag** -- a paragraph ends where the next one or the next heading begins. ''</p>'' is accepted and ignored. |
+| ''<selah>''            | The liturgical marker. Renders as //Selah//, set aside from the text. |
+| ''<br>''               | A line break. Same as DokuWiki's ''\\''; both work. |
+''<p>'' may sit immediately before a verse number, which is the usual way to write it:
+<code>
+And God called the dry land "earth" ...
+<p>11 And God said, Let the earth bring forth green herbs ...
+And the earth brought forth green herbs ...
+</code>
+The wrapping constructs are **pure markup**: it does not matter where you put them. They may open before a verse number, after it, inside a verse, or span several verses -- the reader lifts them out and wraps the verses they cover.
+<code>
+<poetry>1 The LORD is my shepherd;
+  I shall not want.
+He maketh me to lie down in green pastures.</poetry>
+</code>
+A construct left unclosed is closed at the end of the chapter rather than swallowing the notes below it.
+The wrapping tags may also enclose whole verses or sit inside one:
+<code>
+== Psalm 23
+<poetry>The LORD is my shepherd;
+  I shall not want.</poetry>
+</code>
+**Verses may share a line.** ''3 And God said ... 4 And God saw ... 5 And God called ...'' is read as three verses, so a paragraph can be written as a paragraph rather than one verse per line. A number is only treated as a verse marker when it is the **next** verse in sequence -- which is what keeps "Noah was 500 years old" from being read as verse 500.
+Three implementations share this grammar: the wiki plugin (''wiki-plugin/nsv/''), the reader (''nsv_blocks()'' in ''php/nsvlib.php'') and this document. Change one, change all three.
+== Inline HTML
+A small set of inline tags is permitted anywhere text appears:
+  ''<b>'' ''<strong>'' ''<i>'' ''<em>'' ''<u>'' ''<s>'' ''<sup>'' ''<sub>'' ''<small>'' ''<mark>''
+Everything else is shown as text rather than interpreted -- attributes included. ''<b onclick="...">'' is **not** bold, it is the literal characters, so no page can carry a script or a link out of the wiki into the reader.
+DokuWiki's own ''<html>...</html>'' wrapper is **ignored**: the tags inside are read as above and the wrapper itself disappears. 738 chapters carry it around imported Rashi, where the only markup inside is ''<b>'' for lemmas. Do not add new ones -- write the tags directly.
+Note DokuWiki's ''htmlok'' setting is **off**, so the wiki escapes raw HTML even where the reader renders it. Enabling it would allow scripts from anyone who can edit; the allowlist above gives the formatting without the risk.
+== Tags that belong to other plugins
+The Blockquote plugin is installed and claims these. **Do not use them for NSV
+constructs** -- it will handle them, not us, and no warning is given:
+  ''<blockquote>''  ''<q>''  ''<quote>''  ''<QUOTE>''  ''<cite>''
+''<blockquote>'' and ''<cite>'' are genuinely useful and work as that plugin
+intends. ''<q>'', ''<quote>'' and ''<QUOTE>'' are its inline-quotation tags; they
+are not used on this wiki, but they cannot be turned off without disabling the
+whole plugin, so they stay claimed. That is why the NSV construct for quoted
+scripture is **not** called ''<quote>''.
+Before adding any new NSV tag, check nothing else claims it. A collision is
+silent: the other plugin simply renders it and the NSV meaning is lost.
+== Not supported
+The reader ignores anything not listed above -- tables, images, embedded HTML, plugins. It will not error, but the content will not appear.
+== Why this matters
+This format is the contract between the wiki and the reader. Every discrepancy found so far cost content silently rather than loudly:
+* ''Cross-Reference'' spelt with a hyphen -- content dropped
+* Commentary written as prose where the reader expected verse-keyed entries -- whole sections rendered as nothing
+* ''===='' subheadings -- parsed and then discarded across 889 pages
+* A blank ''==='' heading with no trailing space -- paragraph break lost
+If the text later moves into a database, this document is the specification the import will be written against. Anything not described here is at risk of being lost in that move.
-(other formatting rules described below)