Open sjw82 opened 5 years ago
@sjw82 The schema documentation is important, and you can even do it inside the schema file itself, using Relax NG comment syntax. Comments in Relax NG start with a hash mark and continue until the end of the line. There are no multi-line comments, so if you have a multi-line comment, you have to put a hash mark at the beginning of each line. Here’s a sample one-line comment:
# midpass refers to the passage number associated with the specific paragraph within the midrash
midpass = element midpass {text}
I usually write long one-line comments above the line of code they refer to; if the comment is short, I write it at the end of the line line:
midpass = element midpass {text} # passage number
Some of your content models can be simplified to make them more legible. For example, where you write:
ref = element ref {(rabbi|bibverse|item|character)* & content*}
I think what you want is:
ref = element ref { rabbi?, bibverse?, item? character?, content }
Similarly, where you write:
function = element function {(definition|allegory|allegory)* & content*}
definition = attribute definition {text}
allegory = attribute allegory {text}
it would be better to replace the first line with:
function = element function { definition?, allegory?, content }
The issue with both of the preceding cases is that attributes cannot be repeated on an element, so writing allegory
twice in the second content model is misleading, as it putting an asterisk after the attributes in both, since the asterisk allows repetition. The revisions make the attributes optional but not repeatable, which I think is what you want. (If you do want to allow multiple allegories on a function or multiple items on a ref, you can't do it by repeating an attribute, since <function allegory="x" allegory="y">
is not well formed. We can talk about alternatives if that is what you’re trying to do.)
I also removed the asterisk from content
because that’s already defined as a mixed-content repeatable or-group, so it always has all of the optionality and repetition it can have. The extra asterisk seems not to do any harm because it doesn’t contribute meaning one way or the other, but because its presence is misleading, it’s better to remove it.
If you’d like to take a crack at tightening up the schema and then push the update to GitHub, I’ll be happy to take another look. You seem to have the basic functionality you want, at least to get started on validating your markup, and this sort of clean-up is a common stage in the process. in other words, what you have above is a big step forward.
@djbpitt Thank you for the feedback! I've updated the schema if you wouldn't mind giving it another look. In the case that an attribute is required, would it look better to write it { att1?, att2?, att3?, content }
or { (att1 | att2 | att3)?, content}
?
@sjw82 I'll take a closer look later this weekend, but to answer your immediate question, the two expressions mean different things, and the one you want is the first one:
{ att1?, att2?, att3?, content }
means that any, none, or all of those attributes may be present, followed by content. Because attributes are informationally unordered (that is <p att1="x" att2="y">
is informationally identical to <p att2="y" att1="x">
, you can specify attributes in your content model in any order. The comma connector means “in this specific order” with elements, but because attributes are inherently unordered in the XML data model, the connector has a different meaning with attributes than it does with elements.
`( ( att1 | att2 | att3 )?, content }
means that you can have zero attributes or only one of the three specified attributes, but not more than one. That's because the question mark after the parentheses applies to the entire parenthesized expression. That is, it says that you can perform the action of choosing among the attributes zero times or one time.