Clarify the semantics of CDComment

[jbs1]

migrated from Trac, where originally posted by clange on 8-Sep-2008 2:44pm

The semantics of CDComment is unclear, or at least not semantic-web-friendly. Let me cite from the 2.0 spec:

The content of this element should be text that does not convey
any crucial information concerning the current Content Dictionary.

In many cases it does convey crucial information, namely licensing. But maybe we want a special element for that (cf. #18).

It can be used in the Content Dictionary header to report the 
author of the Content Dictionary and to log change information.

Special fields for the author have been proposed already (cf. #12, #38).

Still, there may be information that just doesn't fit into whatever extended metadata scheme -- information that the author still considers "comment"-like. If we follow #39, I'd propose reusing rdfs:comment and declaring CDComment as syntactic sugar.

In the body of the Content Dictionary, it can be used to attach 
extra remarks to certain symbols.

Fine. It does make sense to have multiple "comment" metadata fields in a CD, which are separate from each other. But not mixed with CDDefinitions! That looks to me like a relic from the plain text age, which I consider incompatible with well-defined XML markup and the semantic web. For attaching comments to symbols, we do have CDComment as a child of CDDefinition, and in the line of #40 we might want to allow CDComment on more fine-grained levels as well. But what semantics does

<CD>
  <CDDefinition/>
  <CDComment/>
  <CDDefinition/>
</CD>

have? Is the comment a comment about the preceding symbol? Then it should be a child of that CDDefinition! Same for the following symbol. Otherwise, the relation between the comment and the thing that it comments wouldn't be clear to an automated data processor. If it is a comment about the CD, then it could as well be placed in the CD header, preceding any CDDefinitions.

[jbs1]

migrated from Trac, where originally posted by clange on 16-May-2014 12:51am

Still a valid concern IMHO.

[jbs1]

migrated from Trac, where originally posted by lars_h on 17-May-2014 1:51pm

A perfectly sensible use of CDComment as sibling of CDDefinition that I have seen in some places is as container for a section heading and (possibly) some introductory text following this. Cf. http://www.openmath.org/cd/polyd.xhtml The current rendering does not convey that intent, but it is pretty clear in the .ocd source, and resonates well with the whole Literate Programming paradigm.

[jbs1]

migrated from Trac, where originally posted by clange on 2-Jun-2014 11:13am

Replying to [comment:2 lars_h]:

A perfectly sensible use of CDComment as sibling of CDDefinition that I have seen in some places is as container for a section heading and (possibly) some introductory text following this. Cf. http://www.openmath.org/cd/polyd.xhtml The current rendering does not convey that intent, but it is pretty clear in the .ocd source, and resonates well with the whole Literate Programming paradigm.
Thanks for pointing out! Sectioning is indeed another situation in which CDComment is being used. This makes it even less clear to generally tell what semantic element (CD, CDDefinition, etc.) a CDComment belongs to. So how about specifying the following?

• CDComments as children of CD apply to the CD as a whole
• CDComments as children of CDDefinition apply to that symbol
• For any other situation (e.g. a section that comprises more than one symbol but not the CD as a whole), we introduce a CDSection element, whose CDComment children apply to that section.

[kohlhase]

moved to OpenMath/OMSTD#37