search

w3c / rdf-semantics

https://w3c.github.io/rdf-semantics/
Other
6 stars 2 forks source link

Updates to exported terms #16

Closed gkellogg closed 1 year ago

gkellogg commented 1 year ago

Relevant to w3c/rdf-star-wg#37, I suggest we make the following changes to defined terms:

Make the following exported terms local (still referencable, but not exported to WebRef):

pfps commented 1 year ago

Is this an enhancement or is it just editorial?

gkellogg commented 1 year ago

I suppose that's a matter of opinion. You might know better how important advertising these terms is outside of the spec itself. It should not break any existing links into the specification, but for the first five terms flowing the link will take you to RDF Concepts rather than the location of the "definition" in RDF semantics. Alternatively, these could be made internal ("no-export") terms like the others, but there should probably be text added to reference the exported term from RDF Concepts.

My purpose was to note that we have terms defined in parallel or that we have terms we might not really want to export.

pfps commented 1 year ago

I think that most or all of these are just editorial changes.

Is there a document that describes what the arguments to dfn mean?

gkellogg commented 1 year ago

I can create a PR do handle this.

The ReSpec Wiki documents the attributes (for the most part), but there is a certain amount of experience and trial-and-error involved in figuring these out.

pfps commented 1 year ago

That would be useful. Can you create a PR for the local-only ones by themselves? They all seem to be purely editorial and non-controversial.

I think it would be a good idea to collapse the terminology in semantics to use only denotes and referent and to check what the situation in concepts is. As long as no anchors are lost this would be a non-controversial editorial change. I'll put together a PR for this. Then a final PR can do the first five changes.

gkellogg commented 1 year ago

That would be useful. Can you create a PR for the local-only ones by themselves? They all seem to be purely editorial and non-controversial.

I can split #17 between the "no-export" and the data-cite changes.

I think it would be a good idea to collapse the terminology in semantics to use only denotes and referent and to check what the situation in concepts is. As long as no anchors are lost this would be a non-controversial editorial change. I'll put together a PR for this. Then a final PR can do the first five changes.

If you add data-lt (or data-lt-local) to a definition, you can use that as the body of an anchor and it will automatically reference the single definition. For example, this is already the case for "simple interpretation" and "simply entail".

<dfn data-lt="simply entail">simple interpretation</dfn>

That could be done for denotes and refers to for example:

The words <dfn id="dfn-denote" data-cite="RDF12-CONCEPTS#dfn-denote" data-lt="denote|refers to" data-local-lt="denoted">denotes</dfn>
      and <a>refers to<a>

Although, in this case, they both reference denote in RDF Concepts. It does allow you to simply use <a>denote</a> and <a>refers to</a> in the body of the document.

pfps commented 1 year ago

No, leave #17 as is. I'll update my PR after #17 is merged in.

The problem with using both denotes and refers to is that people end up thinking that they are different, even with the disclaimer near the beginning. Using one term removes this problem. Also, refer is used in a non-technical sense in a few places in Semantics so it is a good idea to not use in a technical sense.

Of course, this is all just wording changes and thus editorial.

gkellogg commented 1 year ago

Note, to be particularly safe, it's possible that there are existing links into #dfn-refers-to, so a pattern I've used to preserve the entry point is to add <span id="dfn-refers-to"></span> near the definition ofdenote`. It's a pain to manage manually, but it makes sure that any inbound links for deprecated terms still go to the right place.