RE: [office-comment] Systematic faults in normative presentation of content models (ODF 1.2 CD01)

["Alex Brown" <alexb@griffinbrown.co.uk>]

Patrick hi

[I'm moving this to opendocument-users@lists.oasis-open.org, so as not
to fall foul of the house rules of office-comment]

> Sorry, I have been offline for several days due to illness.

I'm very sorry to hear that. I trust you are once again firing on all
cylinders.
 
> Alex Brown wrote:
> > Dear all,
> >
> > The presentation of elements (currently the monospaced text on a
> > peach-coloured background) within ODF 1.2 CD01 is a big step
backward
> > from previous versions, and needs to be revisited.
> >
> >
> If you had stopped to consider the content of the material in question
> you would have realized that it is in fact *is*
> 
> "part-normalized to eliminate opaque patterns and bring actual element
> and attribute declarations to the fore. Ideally each mentioned
> element/attribute name should then be hyperlinked to its corresponding
> description in the spec."

I don't believe I claimed the current presentation wasn't
part-normalized. What I was intending to convey was that *if* RELAX NG
compact is used, *it* needs to be part-normalized as it is opaque simply
to have verbatim slabs from the schema. Apologies if this was not clear.

My objections the current presentation is (a) that it is unreadable and
(b) that it is wrong.

(I should also say I very much support an attempt to move away from
having XML syntax slabs of RELAX NG, as previous drafts did. It was,
however, technically correct - which is a trumping benefit for now).

> I agree that the mandatory/optional nature of the models should be
> reflected in the auto-generated language and that plus the nature of
> auto-generated value lists for attributes with enumerated values is
> already underway.

By so doing, you are inventing a kind of prose schema language. 

Granted this kind of thing has been done before. Look for example what
the NLM folks did. They have "models" like (http://is.gd/lqC2):

------------------------------snip
The following, in order:

    * Object Identifier <object-id>, zero or more
    * Label (Of a Figure, Reference, Etc.) <label>, zero or one
    * Caption of a Figure, Table, Etc. <caption>, zero or one
    * Any combination of:
          o All the accessibility elements:
                + Alternate Title Text (For a Figure, Etc.) <alt-text>
                + Long Description <long-desc>
          o All the address linking elements:
                + Email Address <email>
                + External Link <ext-link>
                + Uniform Resource Indicator (URI) <uri>
    * Any combination of:
          o Quote, Displayed <disp-quote>
          o Speech <speech>
          o Statement, Formal <statement>
          o Verse Form for Poetry <verse-group>
          o Definition List <def-list>
          o List <list>
          o Chemical Structure (Display) <chem-struct>
          o Graphic <graphic>
          o Media Object <media>
          o Preformatted Text <preformat>
          o Table (XHTML table model) <table>
    * Any combination of:
          o Table Wrapper Footer <table-wrap-foot>
          o Attribution <attrib>
          o Copyright Statement <copyright-statement>
          o Permissions <permissions>
------------------------------snip

But that is much more readable than what we have in CD01.

You're not seriously going to contend that the presentation of, say,
text:p is acceptable, are you (pages 103-4)?
 
> Since the RELAX NG schema will be a normative part of the standard, I
> fail to see why we should include a form of it here. A "part-
> normalized"
> form is going to be as long as what you complain about here, assuming
> we
> insert the hyperlinked references.

It'll be shorter than what you've got now. The names themselves should
be links (i.e. the section number needn't be broken out alongside).

> Moreover, the standard would then
> fact the objection that it was *duplicating normative content.* An
> objection many would find persuasive. As it stands, we are simply
> providing relevant cross-references that aid in understanding a
> particular element or attribute.

A hyperlinked version of the schema as an appendix, maybe?

> Recall that there are issues with the structure of the schema that are
> directly related to its early editorial use and I would prefer to
avoid
> those in the future. Structures for schema authoring should facilitate
> that task and no other.

I don't think the TC should by shy about pulling the schema around
lexically - so long as it describes the models they want I see nothing
sacrosanct about its lexical form. In fact, in my opinion it could stand
to be made a lot more readable!

- Alex.