Subject: [xml2rfc] use of sourcecode type

From: Paul Kyzivat <[email-masked]>
Date: Tue, 21 Jul 2020 10:36:49 -0400

I have a question about specification of type in sourcecode elements:

In RFC4566bis there are many examples that have fragments of SDP. But 
they aren't compliant to SDP syntax, since it requires that many things 
be present - that are intentionally omitted from these examples.

Is it valid to tag these with type="SDP"?

(In sip we had a similar problem. There is a mime-type message/sip, but 
we sometimes also return fragments of sip in error messages. We ended up 
defining a separate message/sipfrag mime-type for this.)

	Thanks,
	Paul

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 21 Jul 2020 17:10:18 +0200

A similar problem is giving examples that are intentionally bad in order to demonstrate a kind of error.

I typically tag them with a type that is derived from the one I would give for real code, e.g., “CDDLx” for a bad CDDL example.  I think it would be good to agree on some way to indicate this.

A related problem is that often several code blocks combine to one valid instance of CDDL, for example see Figure 1, 2, 3 in RFC 8428.  There is no way to say that Figure 1 and 2 combine into a valid instance, and so do Figure 1 and 3, but not any other combination.

And, by the way, those type tags are conventionally lower-cased, but this is not made very explicit; you have to infer that from the list in Section 2.48.4 of RFC 7991 or the RFC editor’s updated copy of that list:

https://www.rfc-editor.org/materials/sourcecode-types.txt

(Ha, this doesn’t even have “cddl” in it; I’m not sure how this is updated and whether there shouldn’t really be an IANA registry for these.)

Grüße, Carsten

> On 2020-07-21, at 16:36, Paul Kyzivat <[email-masked]> wrote:
> 
> In RFC4566bis there are many examples that have fragments of SDP. But they aren't compliant to SDP syntax, since it requires that many things be present - that are intentionally omitted from these examples.
> 
> (In sip we had a similar problem. There is a mime-type message/sip, but we sometimes also return fragments of sip in error messages. We ended up defining a separate message/sipfrag mime-type for this.)
> 
> 	Thanks,
> 	Paul
> 
> _______________________________________________
> xml2rfc mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/xml2rfc

---

From: Paul Kyzivat <[email-masked]>
Date: Tue, 21 Jul 2020 11:48:13 -0400

> A similar problem is giving examples that are intentionally bad in order to demonstrate a kind of error.

Good point.

> I typically tag them with a type that is derived from the one I would give for real code, e.g., “CDDLx” for a bad CDDL example.  I think it would be good to agree on some way to indicate this.

I agree that we should have some agreed upon way to do this.

Perhaps a "+xyz" suffix, with some agreed up xyz values.

> A related problem is that often several code blocks combine to one valid instance of CDDL, for example see Figure 1, 2, 3 in RFC 8428.  There is no way to say that Figure 1 and 2 combine into a val…

I'm also interested in this. I believe an obvious solution to this is 
via the "name" attribute. All the ones with the same name should be 
gathered together.

A problem I have with both name and type is that they are invisible in 
the human readable formats. They provide semantic information that may 
be of interest to a reader. Perhaps they could be available in html via 
a popup?

> (Ha, this doesn’t even have “cddl” in it; I’m not sure how this is updated and whether there shouldn’t really be an IANA registry for these.)

For these to be useful for any sort of automated processing I think they 
should be standardized. I agree with an IANA registry.

If we wanted to allow unstandardized usage there could be X- prefixes, 
but we have banned those many other places.

	Thanks,
	Paul

---

From: Henrik Levkowetz <[email-masked]>
Date: Tue, 21 Jul 2020 18:15:08 +0200

> via the "name" attribute. All the ones with the same name should be 

Yes.  That's already mentioned in RFC7991: 

  https://tools.ietf.org/html/rfc7991#section-2.48.2

and also in the documentation for the current xml2rfc release:

  https://xml2rfc.tools.ietf.org/xml2rfc-doc.html#name-name-attribute-4

Regards,

	Henrik

> rfc-interest mailing list
> [email-masked]
> https://www.rfc-editor.org/mailman/listinfo/rfc-interest
>

---

From: Paul Kyzivat <[email-masked]>
Date: Sat, 25 Jul 2020 13:07:47 -0400

This long discussion may be helpful and lead to some clarification that 
will be useful in the long term. In the meantime I still need to decide 
what type I should be using for *fragments* of SDP. Should I just use 
"sdp", or take a flyer with something like "sdp+fragment"? I'm in 
AUTH48, so I can't dawdle here.

(In this usage the fragments aren't intended to combine into a 
meaningful whole - they are generally previews. There is one sourcecode 
element at the end that contains the complete SDP syntax.)

	Thanks,
	Paul

---

From: Henrik Levkowetz <[email-masked]>
Date: Sat, 25 Jul 2020 22:51:13 +0200

Hi Paul,

> AUTH48, so I can't dawdle here.

Given the documented intention that fragments with the same name="$filename"
attribute should be gathered together, I'd go with "sdp" if they would
for a complete whole if gathered together as one, and your suggested
"sdp+fragment" otherwise.  I don't see any obvious improvement over that.

> element at the end that contains the complete SDP syntax.)

Right.  So "sdp+fragment" then.

Best regards,

	Henrik

---

From: Carsten Bormann <[email-masked]>
Date: Sun, 26 Jul 2020 00:24:28 +0200

On 2020-07-25, at 19:07, Paul Kyzivat <[email-masked]> wrote:
> sdp+fragment

This makes me cringe slightly because it looks like a structured syntax suffix (RFC 6839), but it isn’t.

(Structured syntax suffixes add a superclass to a name, so senml+cbor is a form of senml but also is CBOR.  Fragment doesn’t strike me as a superclass here…)

I’d prefer something unloaded like “sdp,fragment” (or “sdp, fragment” — this is free text after all, but that may be too radical).

Grüße, Carsten

---

From: Paul Kyzivat <[email-masked]>
Date: Sat, 25 Jul 2020 23:35:28 -0400

> I’d prefer something unloaded like “sdp,fragment” (or “sdp, fragment” — this is free text after all, but that may be too radical).

This is why I'm asking.

Perhaps "sdp;fragment", borrowing from mime parameters

The point is that it is *not* sdp, but it is *related* to (derived from) 
sdp.

I could use "sdpfrag", aking it clear that it is a different type. 
(Following the precedent of message/sipfrag mime type.)

The advantage of "+fragment" or ";fragment" would be that the same 
modifier might be used with other types. It could be defined once.

	Thanks,
	Paul

---

From: Carsten Bormann <[email-masked]>
Date: Sun, 26 Jul 2020 05:47:36 +0200

On 2020-07-26, at 05:35, Paul Kyzivat <[email-masked]> wrote:
> sdp;fragment

Looks good to me.

(Note that these are not MIME media types, so we are not preempting media type parameters, which would be bad.)

Grüße, Carsten

---

From: Paul Kyzivat <[email-masked]>
Date: Sat, 25 Jul 2020 23:47:53 -0400

In parallel with my query on the type element, I also have a question on 
use of the name attribute:

It is described in rfc7991 as a filename. But there isn't much 
discussion of what syntax is permitted, or conventions.

I gather that it is intended to be flexible for different environments. 
So for purposes of this discussion lets restrict the scope to use in 
IETF drafts and RFCs.

Is it appropriate to use file extensions? IOW, is it a good idea to use 
an extension to identify the type of the content? (E.g., "syntax.abnf" 
and "example1.sdp".)

What about use of "/" to introduce directory structure?

I'm thinking of how this might relate to tooling and storage. It would 
be nice if it was possible to have URL paths that retrieve a particular 
named element of an RFC or draft.

	Thanks,
	Paul

---

From: Carsten Bormann <[email-masked]>
Date: Sun, 26 Jul 2020 06:05:35 +0200

> On 2020-07-26, at 05:47, Paul Kyzivat <[email-masked]> wrote:
> 
> In parallel with my query on the type element, I also have a question on use of the name attribute:
> 
> It is described in rfc7991 as a filename. But there isn't much discussion of what syntax is permitted, or conventions.
> 
> I gather that it is intended to be flexible for different environments. So for purposes of this discussion lets restrict the scope to use in IETF drafts and RFCs.
> 
> Is it appropriate to use file extensions? IOW, is it a good idea to use an extension to identify the type of the content? (E.g., "syntax.abnf" and "example1.sdp".)

As long as it isn’t “malware.php” :-)
There is some redundancy with the type here, type=“sdp” name=“syntax.abnf” sounds wrong, but then you don’t have to make this mistake.

> What about use of "/" to introduce directory structure?

Yes, but:
— no . or ..
- a leading / would be interpreted as relative to the RFC, not relative to the local file system (i.e., it would be ignored, or signify something else than overwriting the local system).

> I'm thinking of how this might relate to tooling and storage. It would be nice if it was possible to have URL paths that retrieve a particular named element of an RFC or draft.

These look more like fragment identifiers to me.
(There is no problem with fragment identifiers that collect content from different places in the document.  There is also no problem with shipping a fragment identifier to a server for server-side fragment extraction as part of an API.)

Grüße, Carsten

---

From: Julian Reschke <[email-masked]>
Date: Sun, 26 Jul 2020 09:16:46 +0200

> element at the end that contains the complete SDP syntax.)

In any case, this should be tracked at
<https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/issues>.

Best regards, Julian

---

From: Henrik Levkowetz <[email-masked]>
Date: Sun, 26 Jul 2020 13:23:41 +0200

> syntax suffix (RFC 6839), but it isn’t.

I can see that, yes

> (Structured syntax suffixes add a superclass to a name, so senml+cbor
> is a form of senml but also is CBOR.  Fragment doesn’t strike me as a
> superclass here…)
> 
> I’d prefer something unloaded like “sdp,fragment” (or “sdp, fragment”
> — this is free text after all, but that may be too radical).

Since fragment is a qualifier a comma-separated sequence also could be
misconstrued -- what about "sdp(fragment)" ?

	Henrik

---

From: Henrik Levkowetz <[email-masked]>
Date: Sun, 26 Jul 2020 13:28:25 +0200

> On 2020-07-26, at 05:35, Paul Kyzivat <[email-masked]> wrote:

Ack; works for me

	Henrik

---

From: Paul Kyzivat <[email-masked]>
Date: Sun, 26 Jul 2020 14:49:03 -0400

> (There is no problem with fragment identifiers that collect content from different places in the document.  There is also no problem with shipping a fragment identifier to a server for server-side…

We have two things to coordinate here:
- naming pieces of the xml (the name attribute)
- referring to those named pieces (some conventions around URLs)

I'm not well informed on the idiosyncrasies of URL forms. I'm happy to 
defer to others on the best way. But it may be that the way the URLs 
should be formatted might constrain or suggest ways that the names 
should be structured.

So maybe it is worth talking about URL access to this stuff. My thinking 
is that the named contents of the RFC can be viewed as being contained 
in a directory associated with a particular document. Such a directory 
could actually be created at the time the xml form of the document is 
posted. Or it could be entirely virtual, being retrieved from the xml in 
realtime when a suitable URL is de-referenced. This is an implementation 
choice for the web site.

This would for instance allow referencing abnf defined in a draft 
directly for feeding into a verifier or compiler.

Allowing the names to be organized into subdirectories (with slashes in 
the names) seems unnecessary for any document I am familiar with. But I 
can imagine it might be helpful for a document that has *many* figures.

Or, perhaps the "type" of the sourcecode could be treated as a 
directory, with the "name" identifying individual elements within that. 
That would avoid the problems of using name extensions that might be 
inconsistent with the "type".

	Thanks,
	Paul

---

From: Paul Kyzivat <[email-masked]>
Date: Sun, 26 Jul 2020 14:50:58 -0400

On 7/26/20 3:16 AM, Julian Reschke wrote:
> In any case, 

In which case?

> this should be tracked at

Which "this"? the general issue, or my particular need in the short term?

	Thanks,
	Paul

---

From: Julian Reschke <[email-masked]>
Date: Sun, 26 Jul 2020 21:48:30 +0200

>>> element at the end that contains the complete SDP syntax.)

In this case, and in others where we discuss shortcomings of RFC 7991.
The replacement document is under development, and has an issue tracker.

> ...

Best regards, Julian

---

From: Paul Kyzivat <[email-masked]>
Date: Sun, 26 Jul 2020 16:36:10 -0400

Julian,

> <https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/issues>.

I posted a reply to an existing issue on the "name" attribute.

	Thanks,
	Paul