go/doc: reconsider comment rewrites of '' to ”

[kortschak]

In ae3d890 as part of addressing #51082, a change was made to go/doc that rewrite all '' to ”. This makes semantic changes to comments where ' is used as a prime and '' is used as double prime, common in mathematical code.

This was raised in #51082 (comment) but essentially disregarded. A work around was suggested,

as a workaround, you could replace those with U+2032 PRIME and U+2033 DOUBLE PRIME. That is, f' → f′ and f'' → f″. (Those may look the same depending on your font.)

However on investigation with relevant fonts (the font here and the font used by pkg.go.dev) at 100%, U+2033 DOUBLE PRIME is barely distinguishable from U+2032 PRIME and worse, also barely distinguishable from other commonly used marks in the same position such as '*' (Comparison: f′ f″ f* ).

The change has made it harder to read these comments, harder to write them in a way that doesn't get mutated and easier for incorrectly formatted comments to be committed (f'' getting mutated to f” which is essentially indistinguishable from f″ at normal font sizes).

[mvdan]

f'' getting mutated to f” which is essentially indistinguishable from f″ at normal font sizes

I had to put my glasses on to see the difference at my regular zoom level, so I think you're right :) And this is on a 25" monitor, let alone a tiny phone screen.

[seankhliao]

cc @rsc

[zikaeroh]

Another example is when docs refer to the empty string, specifically JS where strings aren't necessarily double quoted, leading to undesirable doc replacements (and apparently, inserting quotes at the start/end of paragraphs that are not quotes?) as in: evanw/esbuild@296870e

[ALTree]

An example from #56380 (unable to write '' in a comment, closed as a dup of this one):

Since Go 1.19 (commit ae3d890) '' is unconditionally transformed to “ or ”. This means my comment:

// lexMultilineRawString consumes a raw string. Nothing can be escaped in such
// a string. It assumes that the beginning ''' has already been consumed and
// ignored.

Now becomes:

// lexMultilineRawString consumes a raw string. Nothing can be escaped in such
// a string. It assumes that the beginning ”' has already been consumed and
// ignored.

There are some other cases, especially when parsing things, where one might reasonably want to type '' inside a regular (non-codeblock) comment.

Looking at go/doc/comment/parse.go, there is no way to escape this behaviour, and I don't really see an obvious non-ugly way to write that comment.

[evanw]

I recently encountered a particularly annoying case of this behavior. I wanted to write this:

quoteChar should be either '"' or '\''

But no matter what I do, it keeps being turned into this:

quoteChar should be either '"' or '\”

This replacement makes no sense, and is not helpful at all. Really hoping this behavior can be reverted.