search

rtcweb-wg / jsep

33 stars 32 forks source link

60) [rfced] Please let us know if any changes are needed for the #930

Closed juberti closed 4 years ago

juberti commented 4 years ago

60) [rfced] Please let us know if any changes are needed for the following:

  1. The following terms were used inconsistently in this document. We chose to use the latter forms. Please let us know any objections.

    • a m= / an "m=" (per published RFCs and per author feedback for other documents in this cluster
    • q= value / "q=" value (We also changed 'x= and y= values' to "x=" and "y=" values')
    • a RTP / an RTP
    • to true / to "true" (per the rest of the cluster)
    • to false / to "false" (per the rest of the cluster)
    • bundle-tag / BUNDLE-tag (per other documents in this cluster)
    • offer-answer exchange / offer/answer exchange
    • clockrate / clock rate (per RFCs 3389 and 7160)
    • other than IDENTICAL and TRANSPORT / other than IDENTICAL or TRANSPORT

  2. The following terms appear to be used inconsistently in this document. Please let us know which form is preferred.

    • createOffer API / createOffer() API (We see "createAnswer() API" but not "createAnswer API"; however, we also see "getCapabilities API" and "W3C RTCPeerConnection API." In RFC 8826 (draft-ietf-rtcweb-security), we see "XMLHttpRequest() API.")

    • setLocalDescription API / setLocalDescription() API / setRemoteDescription() API (We also see "whether setLocalDescription or setRemoteDescription is called" and "before setRemoteDescription() is called")

    • mid identifiers / MID identifiers Because RFC 8843 (draft-ietf-mmusic-sdp-bundle-negotiation) and RFC 8852 (draft-ietf-avtext-rid) define "MID" as "Media Identification," would it be appropriate to use "mid values" (or "MID values"*) and "MIDs" instead of "mid identifiers" and "MID identifiers"?

    • We see inconsistent capitalization in this cluster of documents; a separate question regarding which form to use will be sent separately.

    • "RID identifiers" and "rid-identifier": RFC 8851 (draft-ietf-mmusic-rid) defines "RID" as "restriction identifier." Should "RID identifiers" and "rid-identifier" be "rid-ids" and "rid-id" per RFC 8851 (draft-ietf-mmusic-rid), to avoid "identifier identifier(s)"?

    • the stable state (1 instance) / the "stable" state (3 instances) (Also, should 'the previous stable state' be 'a previous stable state' (per Section 5.7) or 'the previous "stable" state'?)

    • sess-id / (Section 5.2.1, second bullet item)

    • set to zero / set to 0 (May we use the latter, because of '"dummy" port value of 9' in Sections 5.2.1 and 5.3.1?)

    • dummy value / "dummy" value

    • fmt value / "fmt" value

    • mid value / "mid" value

    • tls-id value / "a=tls-id" value

    • "IceRestart" option / IceRestart option

    • dissociate (Section 5.10) / disassociate (Sections 3.4.1 and 5.7) Example: "A rollback disassociates any RtpTransceivers that were associated with m= sections by the application of the rolled-back session description (see Section 5.10 and Section 5.9)."

  3. Are "canTrickleIceCandidates" (Section 4.1.15) and "canTrickle property" (Section 5.10) distinct terms? If so, should this distinction be clarified in the text?

juberti commented 4 years ago

  1. [rfced] Please let us know if any changes are needed for the following:

  2. The following terms were used inconsistently in this document. We chose to use the latter forms. Please let us know any objections.

    • a m= / an "m=" (per published RFCs and per author feedback for other documents in this cluster
    • q= value / "q=" value (We also changed 'x= and y= values' to "x=" and "y=" values')
    • a RTP / an RTP
    • to true / to "true" (per the rest of the cluster)
    • to false / to "false" (per the rest of the cluster)
    • bundle-tag / BUNDLE-tag (per other documents in this cluster)
    • offer-answer exchange / offer/answer exchange
    • clockrate / clock rate (per RFCs 3389 and 7160)
    • other than IDENTICAL and TRANSPORT / other than IDENTICAL or TRANSPORT

I don't love the use of "true" and "false", since the meaning is subtly different than the non-quoted forms, but I suppose it's OK if other documents have gone the same way. Could you point us at an example to confirm?

The rest seem fine.

  1. The following terms appear to be used inconsistently in this document. Please let us know which form is preferred.

    • createOffer API / createOffer() API (We see "createAnswer() API" but not "createAnswer API"; however, we also see "getCapabilities API" and "W3C RTCPeerConnection API." In RFC 8826 (draft-ietf-rtcweb-security), we see "XMLHttpRequest() API.")
    • setLocalDescription API / setLocalDescription() API / setRemoteDescription() API (We also see "whether setLocalDescription or setRemoteDescription is called" and "before setRemoteDescription() is called")

There seems to be a pretty clear preponderance for the non-parenthetical form, so let's keep that. W3C also does not use ().

  • mid identifiers / MID identifiers Because RFC 8843 (draft-ietf-mmusic-sdp-bundle-negotiation) and RFC 8852 (draft-ietf-avtext-rid) define "MID" as "Media Identification," would it be appropriate to use "mid values" (or "MID values"*) and "MIDs" instead of "mid identifiers" and "MID identifiers"?

RFC 5888 defines it as Media Stream Identification, and later uses "Mid Value", but I agree we should probably go with MID/mid values.

  • "RID identifiers" and "rid-identifier": RFC 8851 (draft-ietf-mmusic-rid) defines "RID" as "restriction identifier." Should "RID identifiers" and "rid-identifier" be "rid-ids" and "rid-id" per RFC 8851 (draft-ietf-mmusic-rid), to avoid "identifier identifier(s)"?

Should we also do RID values? "rid-ids" seems like it is still a case of "identifier identifiers".

  • the stable state (1 instance) / the "stable" state (3 instances) (Also, should 'the previous stable state' be 'a previous stable state' (per Section 5.7) or 'the previous "stable" state'?)

The quoted form is preferred, including the case of "previous stable state".

  • sess-id / (Section 5.2.1, second bullet item)

LGTM

  • set to zero / set to 0 (May we use the latter, because of '"dummy" port value of 9' in Sections 5.2.1 and 5.3.1?)

What's the IETF style guide say on this sort of thing? 'zero' looks more natural to me, and matches RFC 3264's usage of 'zero'.

  • dummy value / "dummy" value

Another style question - other RFCs seem to only quote "dummy" when introducing the term.

  • fmt value / "fmt" value

Would we also do media, port, and proto? This one needs more discusison.

  • mid value / "mid" value

MID is not quoted in other RFCs ,I believe.

  • tls-id value / "a=tls-id" value

The source RFC seems to prefer "tls-id" when discussing values.

  • "IceRestart" option / IceRestart option

LGTM

  • dissociate (Section 5.10) / disassociate (Sections 3.4.1 and 5.7) Example: "A rollback disassociates any RtpTransceivers that were associated with m= sections by the application of the rolled-back session description (see Section 5.10 and Section 5.9)."

LGTM

  1. Are "canTrickleIceCandidates" (Section 4.1.15) and "canTrickle property" (Section 5.10) distinct terms? If so, should this distinction be clarified in the text?

no, they should all be canTrickleIceCandidates.

juberti commented 4 years ago

@ajeanmahoney input needed

ajeanmahoney commented 4 years ago

(Breaking this issue and the comments up into smaller chunks) --

60.1) Regarding the use of "true" and "false" - W3C's API documentation formats Boolean true/false values with (e.g., https://w3c.github.io/webrtc-pc/#dom-rtcofferoptions-icerestart), which we could use here (it would put the terms in quotes in the txt output).

FWIW, in the other Cluster 238 documents, "true"/"false" (formatted in quotes) are used for the setting of an XML attribute (RFC8846, RFC8847) and an SDP attribute (RFC8864).

ajeanmahoney commented 4 years ago

60.2) We'll remove the parens (camelCase is sufficient formatting).

ajeanmahoney commented 4 years ago

60.2) Regarding RIDs -- A restriction identifier ("a=rid" attribute) contains a rid-id, which identifies a unique RTP payload configuration, and one or more "a=rid" restrictions (the term this is used 8851), which are semicolon-separated, parameter-value pairs. With that in mind --

Section 5.2.1, current:

  • If the RtpTransceiver has a sendrecv or sendonly direction, and the application has specified RID values or has specified more than one encoding in the RtpSenders's parameters, an "a=rid" line for each encoding specified. The "a=rid" line is specified in [RFC8851], and its direction MUST be "send". If the application has chosen a RID value, it MUST be used as the rid-identifier; otherwise, a RID value MUST be generated by the implementation. RID values MUST be generated in a fashion that does not leak user information, e.g., randomly or using a per-PeerConnection counter (see guidance at the end of [RFC8852], Section 3.3), and SHOULD be 3 bytes or less, to allow them to efficiently fit into the RTP header extensions defined in [RFC8852], Section 3.3. If no encodings have been specified, or only one encoding is specified but without a RID value, then no "a=rid" lines are generated.

  • If the RtpTransceiver has a sendrecv or sendonly direction and more than one "a=rid" line has been generated, an "a=simulcast" line, with direction "send", as defined in [RFC8853], Section 5.1. The list of RIDs MUST include all of the RID identifiers used in the "a=rid" lines for this "m=" section.

Section 5.2.1, perhaps:

  • If the RtpTransceiver has a sendrecv or sendonly direction, and the application has specified "a=rid" restrictions or has specified more than one encoding in the RtpSenders's parameters, an "a=rid" line for each encoding specified. The "a=rid" line is specified in [RFC8851], and its direction MUST be "send". If the application has chosen a rid-id, it MUST be used as the rid-id; otherwise, a rid-id MUST be generated by the implementation. A rid-id MUST be generated in a fashion that does not leak user information, e.g., randomly or using a per-PeerConnection counter (see guidance at the end of [RFC8852], Section 3.3), and SHOULD be 3 bytes or less, to allow it to efficiently fit into the RTP header extensions defined in [RFC8852], Section 3.3. If no encodings have been specified, or only one encoding is specified but without an "a=rid" restriction, then no "a=rid" lines are generated.

  • If the RtpTransceiver has a sendrecv or sendonly direction and more than one "a=rid" line has been generated, an "a=simulcast" line, with direction "send", as defined in [RFC8853], Section 5.1. The list of "a=rid" restrictions MUST include all of the restrictions used in the "a=rid" lines for this "m=" section.

Section 5.8.3, current:

All RID values referenced in an "a=simulcast" line MUST exist as "a=rid" lines.

Section 5.8.3, perhaps:

All "a=rid" restrictions referenced in an "a=simulcast" line MUST
exist as "a=rid" lines.

Section 5.11, current:

Any RTP header extensions that were negotiated should be included in the outgoing RTP streams, using the extension mapping from the remote description; if the RID header extension has been negotiated and RID values are specified, include the RID header extension in the outgoing RTP streams, as indicated in [RFC8851], Section 4.

Section 5.11, perhaps:

Any RTP header extensions that were negotiated should be included in the outgoing RTP streams, using the extension mapping from the remote description; if the "a=rid" extension has been negotiated and "a=rid" restrictions are specified, include the "a=rid" attribute in the outgoing RTP streams, as indicated in [RFC8851], Section 4.

ajeanmahoney commented 4 years ago

I think that this collection of issues needs to be broken out into separate issues. Shall I go ahead and do that?

juberti commented 4 years ago

Yes, I was going to suggest the same thing. Thanks.

juberti commented 4 years ago

Since this issue has been split out into separate issues, should we close this issue? @ajeanmahoney

ajeanmahoney commented 4 years ago

Yes, this issue can be closed because it's been broken down into sub-issues, thanks!