ZedAI Spec Finalize Issues
From zedwiki
Compendium of comments from James...
Introduction
1.3 Design Goals
"Processability" is truly ugly. I will try to come up with a more felicitous wording of this.
Matt: section rewritten + metadata section added. for review.
1.4 Overview
"RDF metadata is an integral means of expressing metadata about documents and the elements they contain ...." I see two redundancies there, but maybe I just don't understand the terminology here: "RDF metadata" is a "means of expressing metadata"? And not just metadata, but "metadata about documents"?
Matt: I think I've parsed this part. RDF metadata is not the only means of expressing metadata, but it is an integral one to the framework. There are perfectly valid means of expressing metadata about elements and documents without going near RDF if you want to go that route. It's not a redundancy but a statement of a fact that needs more elaboration.
---
I think that the paragraph describing Resource Directories needs further elaboration. It currently says that schemas alone are not helpful (really?), then has what appears to be a nonsequitur about publicly publishing a profile. Maybe a sentence or two on why schemas alone won't work and what the RD does to remedy this?
There is nothing mentioned in this section about the processing agent part of the spec.
Matt: I don’t know when we want to review the overview. It was filler text until we worked out the structure of the document, so needs a full rewrite at some point. I’m not sure if that’s even how we want to structure it.
Markus: Right, and once James have read the sections after Modules (where the new proposed section structure appears) and if James has no revision proposal re the structure, then the overview section can finally be written for real. (Barring final terminology but even so). Either of you can sign up for this one; I'll refrain from volunteering here. ;)
1.4.2. Z39.86-2005
Matt: Unclear to me what "functional expansion" is going on. Can the relation and expansion be elaborated? Do we need to reference Part B in this section at all, or can we drop the first sentence entirely and only discuss the relation of this spec to the preceding version?
Abstract Document Model
"This section is normative" Really? Subsection 2.1 ("Introduction") doesn't look very normative to me. I'd move the normative/informative tagging down a level.
Matt: Applies to more than just this section. I'm not sure we have a consistent policy. But like with Online, I hate adding these modifiers so more than happy to let you and Markus review them and determine how best to apply.
Matt: removed all normative and made document normative except where otherwise labelled
2.3.2.2 et al.
"Implementation". The current wording used in all implementation sections is "Elements contributed to this layer ..." Would it be inaccurate to use the simpler and clearer "Elements in this layer ..."?
Matt: I don’t think that’s accurate, as there is nothing in a layer by default (excepting default members). If we take out the contribution it reads like the layers are fixed (or so it seems to me).
Matt: leaving as is
2.3.3 Block layer
Sidebars aren't mentioned anywhere in the descriptions of layers. Do they belong here? They're so common and so problematic, I think they're worth mentioning explicitly.
Matt: Here or in a primer? I can't see how to work it in without launching into an aside (sorry, couldn't help that one).
Matt: not implementing at this point
2.3.3.1 Description (of block layer)
Does the use of white space to set off content (either vertically or horizontally) have anything to do with the block-ness of that content? That's intuitive based on the long-standing practice of HTML, which is why I mention it and wonder whether it would be worthwhile to put here.
Markus: I though we had something in there to that effect? vertical/horizontal?
Matt: we have: "Block content likewise differs from Phrase content in that it establishes a connection between content ordered and divided vertically on a rendered page." Phrase has similar establishing its horizontal nature. Rewording? Something else?
2.3.3.2 Implementation (of block layer)
"They must not allow structural headings" I would suggest rewording this for clarity to "They must not allow structural headings within their content models," but I defer to you guys on this one.
Also, I have to say that something seems wrong to me about the reference to structural headings here. If structural headings are strictly for the use of Section members, why not define them up there? Again, I defer to you guys on this.
Matt: Do we need these structural/non-structural rules at all? If the section layer is the only layer that defines structural elements, an <h> attached to a section-layer element is by default structural and an <h> attached to a block-layer element by default isn't. That only leaves the "bridgeheady" headings. Or is this rule to absolutely stop people from trying to treat block elements as though they're structural?
2.3.4.1 Description (of phrase layer)
"... [it] operates at a grammatical level." Really? What about numbers and math and stuff like that? "grammatical" seems too limiting to me, but I have no substitute that I can recommend. I'm suspicious that "phrase" is really just stuff that's inbetween block-level stuff and text stuff. You might call it "inline", but that would be old-fashioned.
Markus: I wouldn't oppose to a renaming, but noting the problem with inline as our Phrase is not fully identical to HTML inline: HTML inline roughly equals our Phrase + our Text layers.
As a non-native speaker, I admittedly find "phrase" a bit unintuitive, think it came from (don't tell anyone) HTML5 which has the notion of "phrasing content" (they dont use "inline" either, much or at all).
Matt: For the first, what if we state it more generally as: "Phrase content differs from Text content in that defines constructs smaller in scope than Block content but that are still semantically significant." Inline-y but not too inline-y?
As for switching the name of the layer, there would be a case to be made if only because html5 phrasal content doesn't encompass the same breadth as what we're defining in our phrase layer. I'm equally stumped for a better name, though. Are we perhaps being too academic in parsing apart the meaning of a phrase? Are people going to "get it" as soon as they figure out the split of inline? (which I believe we briefly detail in the ADM intro) So long as it's clear what content goes in the layer, I'm not too worried about grammarians attacking me in the street.
Matt: not changing at this point. can be reviewed later
Modules
3.1 Introduction
I think this needs more information to give a comprehensive view of modules. I sketched out yet another nested box diagram showing that a module consists of an abstract definition and a bunch of components, and the components include a bunch of traits. But I'm not sure that a diagram is really needed here. It would just be good to get that map described in the intro.
I'd restructure the whole section like this:
3.1 Introduction (describes everything that is to follow)
3.2 Abstract definitions
3.3 Components
3.4 Traits (subsections on the various traits) [or this could be a subsection of 3.3?]
3.5 Expression (formerly "Composition")
3.6 Activation (moved down from 3.1 to here)
3.7 Core Module Pool
The intro would then follow the same outline to give an overview of the topic.
However, the rest of my comments follow the structure as it currently stands.
Matt: the current order is a bit hard to follow. I'd definitely keep traits under components, as they don't relate to modules. One of the other questions I had here is why 3.3 in the original (Composition) only has a single subsection left. Assuming that would come out under this reorder to expression?
3.1.1 Activation
The definition of activation here does not match the one in the Definitions section, but it ought to. This is something to double-check throughout the spec.
Matt: fixed the reference to the adm layers to the classes in the first sentence. A pointer from the definition to this section would probably also be helpful, as the definition is a bit light on detail. What do you see that needs tighter binding, though? Or does that solve it?
3.2 Abstract definitions
I don't care for this term. To me, it's just the "module description", or "module documentation", or even "module definition". I don't see anything particularly "abstract" about it.
3.2.1.2 Traits
I deleted the word "metadata" here, since I think this will be confusing and is redundant ("information about" is the same thing as "metadata").
There is a list of six traits given here -- can there be others? If so, how are they defined? If not, we can simplify the specification language by addressing these six directly. If these are the only six, then I'd drop the term "trait", which is so generic as to be meaningless, and instead say that a component must have a semantic definition, a default usage context, a default content model, a default attribute model, and indications of whether it is variable and/or mandatory. Then you can address each of those things.
Boris: I was worried about this list too. If a Component includes things like a datatype, pattern, or set of values, then a requirement that every Component have a content model as a trait is seemingly unmeetable - datatypes and such don't have content models, do they? Could we just say something more along the lines of "The Component Definition contains the following information..."
3.2.1.2.2 Initial usage context
Can we say "default" instead of "initial"? I think that's clearer. It took me awhile to figure out that "usage context" meant what content models the component may appear within. Can we use the term "content model" here somewhere to make that clearer?
Markus: "Usage context" is not ideal, agreed. Are you suggesting that we keep it but clarify that it means the content model (or class) in which a component is allowed (or required)?
James: Yes, that's what I had in mind. Although if we can think of a better term than "usage context", that would be good, too.
---
An example would be really helpful here, I think, as it would be really for all these traits. We are pretty liberal with examples in other parts of the spec, but not here.
3.2.1.2.4: Initial attribute model
"... that constitute its initial set of allowed attributes". I started to delete "allowed" (for clarity), but then wasn't sure if that changed the meaning.
Matt: It might have a purpose if there were a corresponding set of attributes that are expressly forbidden to attach, but do we make restrictions like that anywhere? So far as I know the ADM is the only source of restrictions, and it only relates to elements and what child elements they can contain.
3.2.1.2.5: Alterability
What about "variability" rather than "alterability" (which didn't sound like a legitimate word to me, although Webster's online has it).
Matt: Every time I see variability it sounds like we don't know what state it's in at any given moment. Alterability is closer to what the trait is expressing, but not super-nice either. Altering creates a customization (as per the formal def.), so maybe this should be "customizability", "configurability" or some such? The only down side of that is we could wind up talking about how the customizability traits determines if you can customize a component to make a customization (which just grates on the eyes and ears).
The third paragraph here starts "The initial context model ...": should that be "initial usage context"?
Last sentence: "The abstract definition for the component must explicityy express any restrictions to this rule." Which rule? I assumed it meant the rule that you can alter a component to conflict with its semantic definition, but how can that rule be "restricted"?
Matt: Probably confusing as it's not implemented yet. The rule is that all components are alterable, as stated in the sentence that precedes this one, unless expressed through the abstract definition. How exactly that happens Markus can address.
3.2.1.2.6: Optionality
Another word that I thought was made up, but which Webster's online provides. I tried to come up with something better but couldn't.
Matt: I don't expect this one will cause much confusion, although it's gone through a couple of name iterations already. With w3c on the first page of results, I'd take it as a good sign it at least has industry traction: http://www.google.ca/search?&q=optionality+xml
---
The last sentence here is a mess: "Optionality is an implied trait for all components; the abstract definition for the component must explicitly state if it is fixed and not excludable." I think that what is meant is that "by default, all components are optional; if it is mandatory this must be explicitly stated in the module's abstract definition." But I'm not sure about that.
Matt: sounds the same but simplified. fixed.
3.3 Composition and 3.3.1 Schemas
Is "composition" the right word here? That implies bringing multiple things together, and I don't think that modules are "composed" in this way. And the only thing defined in this part of the spec is what schema languages you can use, which is something different than composition rules. I'd suggest getting rid of the subheading 3.3.1 (it's redundant) and calling this "Expression" or "Formal expression", or something like that.
Matt: agree. it used to have more subsections detailing all the steps to compose, but they've been moved out or removed. removing the same comment i had above about its continued need for one subsection and merging.
3.4 Core Module Pool
"... a collection of pre-defined modules ..." Could you say "defined as part of this specification"? That's clearer to me.
Matt: Are they technically part of the specification anymore? I thought that was part of why we removed their definitions from the main spec.
Markus: no, they are part of the spec for sure, just outlined in order to be versioned independently.
3.4.1 & 3.4.2
are marked as "normative", but so is all of section 3. Again, a finer categorization of normative/informative is in order for this section.
Profiles
4.1 Introduction [Profiles]
Yes, I'd use the term markup models here.
This is another introduction that could be filled in a bit. It would be good for it to give a very rough idea of how a profile happens -- markup model made up by composing modules -- from CMP, other module collections, newly-written modules, driver, etc. -- and features, plus metadata, etc. Profile documented fully via resource directory, etc. Give a roadmap here for the rest of the section.
4.2.2 Profile Markup Model Definition
The third bullet point ("If the profile supports one or several features ..." is unclear to me. What are the "activated normative schema fragments"?
Features
5.1 Introduction [Features]
The second paragraph is unclear to me. How about this:
Features have much in common with profiles: each feature defines a markup model and has a unique URI associated with it which serves as its identifier, and which resolves to a unique resource directory. However, features are more specialized and narrower in scope: they are not indended to be used as complete markup languages on their own. In the Z39.86-AI framework, features can be thought of as optional "add-ons" to profiles.
[I didn't make that change because I wasn't sure if it altered the intended meaning]
5.2.2 Feature Markup Model Definition
The rules about including attribute sets on all elements appear here, but not in the corresponding Profile section (4.2.2). Is that an oversight?
Documents
6.1 Introduction
"A Z39.86-AI document may comprise more than just the XML file(s) ..." This makes no sense to me. In the container section of the spec, the term "Z39.86-AI file set" is used, which is more appropriate. We need a clear definition of this, probably in the #6.5 Container section (see my comments there). Once that's done, then this introduction will need to be tweaked to match.
6.3 Referencing Profiles and Features
The example here is inline and not identified as informative or normative. The example #6.4.4 Document-level metadata example is a separate sub-sub-section. The example #6.4.5.1 Inline Metadata example is a sub-sub-sub-section. We need a consistent example structure. I personally would recommend using the style of the Primer: Use the docbook example element with caption, etc., and include "(informative)" in the caption. I think that looks nicer and avoids structural bloat.
Markus: I agree
6.4 Metadata
6.4.1 Introduction
I would suggest removing the "instead of" clauses in the bullet list. Why explain what we're not doing? It is much clearer to state the positive only.
6.4.4 Document-level metadata example
See my comment in #6.3 Referencing Profiles and Features regarding styling here.
Also, I would suggest that the example include a URI for a remote resource for completeness.
6.4.5.1 Inline Metadata example
See my comment in #6.3 Referencing Profiles and Features regarding styling here.
6.5 Container
This section seems very weak to me. There is no definition of what has to be included in the package file: every image referenced by the document? Everything referenced by a URI? What about http:// URIs? etc. I could not find this addressed in the OCF spec, but I might have missed it.
Also, should this section be promoted? In that it has an informative introduction followed by normative prose, it seems to follow the pattern for a section, not a subsection.
Finally, this section could probably use some examples, possibly as part of #6.5.2 Format.
6.5.1 Introduction
The term "Z39.86 file set" is used here to refer to what goes into the container, but it is not defined anywhere. It is also used interchangeably with "document" both here and in #6.1 Introduction, which is not good.
6.5.2 Format
"Valid Z39.86-AI container files must only ever include the container.xml file ..." This is unclear to me. This reads as if the only thing in a ZAI container file is container.xml, which is obviously not correct. Do you mean that the contents of the META-INF directory must consist of the container.xml and nothing else?
Resource Directories
RDF vocabularies
8.2 Predefined vocabularies
I dislike the term "predefined" here (defined before what?). I'd suggest "Vocabularies defined by this specification" to be clearer. If we go for that, then section 8.1 would need a tweak, too, since "predefined" appears there.
Also, is this section really informative?
Markus: no problem with removing predefined (it was meant to mean: "shipped with the spec, not need to define them post hoc"). As for informativeness, the plan was to be informative yes, the only thing normative would be the catalog URIs which are in the appendix. While this section says things like "use of the vocab is required", that is just a reflection of reqs posed elsewhere, not a new req. What we could do though is to scrap the catalogs appendix and move those three sections to their respective home in the main body of the spec (so the vocab URIs would be normatively defined here, and this section would become normative).
Processing Agents
9.4 Processing of vocabulary terms
There are no requirements to understand the core semantics vocabulary? Is that wise?
Markus: I have pondered this too. This section is basically a very roundtripping way of saying "you dont need to support this, apart from the reqd terms used in head". This reflects our original intent however; that role should be an optional layer that you only need understand if you really need to, that the element set is fully functional in itself for basic behaviors. This requires further thought.
