[sc34wg3] CTM draft dtd. 2007-09-09 - Templates

[Steve Pepper]

* Lars Marius Garshol
| 
| What we have here is a group of requirements which are mutually
| incompatible, as follows:

[remainder of the posting below]

Lars Marius' analysis is (as usual) incisive and spot on, but I think we
need to go further and ask the question, is this just a difference of
opinion, or does it reflect something deeper? I think it reflects something
deeper.

We are all looking for elegance, but of different kinds.

Lars H. and Robert (in particular) are looking for an overall design
elegance that primarily reflects the needs of the programmer. Dmitry and I
(among others) are looking for a presentational elegance that primarily
reflects the needs of the end user. That is not to say that any of us wish
to ignore the needs of the other constituency; it's a question of what we
should prioritize.

To my mind, and I think also most users who are not also programmers, (1) is
far tidier, more readable, more visually appealing and less confusing than a
syntax in which the colons are sometimes there (names and occurrences) and
sometimes not (associations expressed through templates):

(1)
   *e41 isa: entry
     - title: "About Dublin Core in Topic Maps"
     date: 2007-08-07
     subject:  Subject-centric_computing
     subject:  Dublin_Core
     creator:  Steve_Pepper
     contributor:  Dmitry_Bogachev
     description: "Topic Maps and Dublin Core need each other..."

These are important qualities that should not be underestimated, and I think
they are critical to the adoption of CTM. A casual reader of (1) will have
absolutely no problem understanding what is intended, and will not be thrown
off by what to her will seem like gratuitous anomalies, cf. (2):

(2)
   *e41 isa entry
     - title: "About Dublin Core in Topic Maps"
     date: 2007-08-07
     subject   Subject-centric_computing
     subject   Dublin_Core
     creator   Steve_Pepper
     contributor   Dmitry_Bogachev
     description: "Topic Maps and Dublin Core need each other..."

Lars H argues that the reader will not be able to fully understand (1)
without referring back through the rest of the topic map. Actually the same
thing applies to (2), except that the user in this case receives a signal
(no colon) that a template has been used. The casual user is then expected
to know that she has to refer back to the template in order to interpret the
fragment.

Even assuming our user had the necessary sophistication, this little piece
of extra information is not, to my mind, sufficiently useful as to warrant
what *looks like* an inconsistent syntax.

(Actually, the truth is that no-one can know exactly what a fragment "means"
out of context and without having performed CTM parsing. If you want to be
absolutely sure what the result will be, you have to deserialize the whole
CTM document into the TMDM.)

The price we pay is reduced elegance of design, as a programmer would see
it, and that is a price I think we should be willing to pay, for the sake of
end users.

If people really think this is a problem, my conclusion is rather we have
made templates *too powerful*. Perhaps we shouldn't have allowed more or
less any *any* fragment of CTM to be included in a template. Perhaps we
should instead restrict them to just what unsophisticated users (and TMCL)
really needs.

Steve

| 
| #1: Syntax should have a uniform look
|      (ie: occurrences & templates should look the same)
| 
| #2: The meaning of a single expression like "foo: bar" should not
|      change throughout the file
|      (ie: template definitions should not change the meaning of this
|      expression)
| 
| #3: It should be possible to define templates anywhere in a file
| 
| It's possible to have any two of these, but not all three. So, it
| boils down to a question of which requirement is the least important
| to people. I guess we could do a quick poll or something.
| 
| Steve suggested an alternative solution: require template identifiers
| and topic identifiers to be distinct. In this case you'd have to
| check every declared template to see if there is a topic with that
| identifier and if so report and error, and conversely also check for
| conflicts with every new topic. This does add complexity to
| implementations.
| 
| There is the potential for trouble with %include, but given that %
| include will only work where identifiers are carefully managed across
| files anyway, I think we can ignore that problem.
| 
| In addition, we have another requirement, introduced by Lars Heuer:
| 
| #4: Mistyped template names should cause an error
| 
| This one conflicts directly with #1, so anyone who wants this
| basically ditches #1, so that they can have #2 and #3.
| 
| As far as I am able to tell, this leaves us with the following options:
| 
|   - #1 and #3: basically the post-Montreal syntax
|   - #1, #2, #3 and errors on shared identifiers: current draft
|     + new rule
|   - #2, #3, #4: back to distinguishing templates & occurrences
|   - #1, #2: means templates must be defined at top of file
|     not clear if this is compatible with new %include semantics
| 
| Personally, I don't like the "errors on shared identifiers" solution
| very much, and I don't think #1 is important. (I let it pass in
| Montreal, not realizing that this was a side-effect.) So basically, I
| prefer the #2-#4 solution.
| 
| As far as I can tell, Steve favours #1-#3 plus errors.
| 
| Lars, I think, favours #2-#4, like me.