proposal: go/doc: ITU-T URL support

[JesseCoretta]

Proposal Details

When authoring documentation meant for display via x/pkgsite, support should be added to recognize and support ITU-T recommendation URLs in the same manner RFC XXXX is currently supported.

For instance:

Where the raw text RFC 1234 would automatically link to https://www.rfc-editor.org/rfc/rfc1234.html upon page generation, x/pkgsite should link E.123, X.411, X.501 and other "alpha series" (A-Z) documents to the appropriate https://www.itu.int/... resource.

It is true that placing a link (verbatim) in doc text is possible, but is undesirable for obvious reasons.

I do recall Go maintainers claiming godocs/pkgsite is not meant to be a "rich markdown system". While I agree, I would argue that ITU-T Recommendations are just as relevant/critical as RFCs, therefore they should qualify for the same consideration.

Thank you

[fzipp]

Why don't you link them with the link feature? https://go.dev/doc/comment#links

[JesseCoretta]

@fzipp Oh that is fine in practice for most URLs, but my impression was that ITU-T (and, I suppose out of necessity, ITU-R) documents are so central to technology in general, that it made them seem like valid candidates for the same kind of built-in link support that RFCs currently enjoy in godoc/pkgsit mark down.

[fzipp]

The RFC special case support has existed since the inception of go/doc, well before the addition of general link support. Had general link support been available earlier, it's unlikely that the special case support would have been introduced.

[JesseCoretta]

@fzipp Fair enough. I tend to cite X.NNN documents heavily which is why I asked.

[rsc]

I think only pkgsite has the RFC special case. go/doc does not. If anything I think we should move toward removing the x/pkgsite special case and other deviations from go/doc.

[JesseCoretta]

There is also an issue with inconsistent link support. I wouldn't necessarily say this "strengthens" my case, but I'm going to cite it here for the purposes of tracking:

The "links" solution mentioned by @fzipp has always worked nicely for paragraphs and instance comments, e.g.:

Package blarg implements [Linked Resource] ...

... or ...

/*
ImplementationType implements Section X.Y of [Linked Resource].
*/
type ImplementationType struct {
   ...
   ...
}

But where it does not work is on line-ending or terminating comments, such as those found on iota constants, struct fields, etc:

/*
ImplementationType implements Section X.Y of [Linked Resource].
*/
type ImplementationType struct {
   Field1   type    // Section X.Y.A of [Linked Resource]   -- Link fails, raw text only
   Field2   type    // Section X.Y.B of [Linked Resource]   -- Link fails, raw text only
   Field3   type    // Section X.Y.C of [Linked Resource]   -- Link fails, raw text only
}

The reason I am bringing this up is because the so-called "built-in" RFC link support DOES work for the aforementioned line-ending comments.

In other words:

/*
ImplementationType implements Section X.Y of [Linked Resource].
*/
type ImplementationType struct {
   Field1   type    // Section X.Y.A of [Linked Resource]   -- Link fails, raw text only
   Field2   type    // Section X.Y.B of [Linked Resource]   -- Link fails, raw text only
   Field3   type    // Section X.Y.C of [Linked Resource]   -- Link fails, raw text only
   Field4   type    // Section A.B.C of RFC NNNN            -- Link is valid hypertext
}