Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

x/website: Usage of unicode double quotes in code blocks of the documentation #54300

Closed
piroux opened this issue Aug 5, 2022 · 2 comments
Closed
Labels
Documentation NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. website

Comments

@piroux
Copy link

piroux commented Aug 5, 2022

What version of Go are you using (go version)?

Go 1.19

Does this issue reproduce with the latest release?

Yes

What did you do?

Read the current Go documentation website, for instance the Links section on the new Comments page

What did you expect to see?

Usage of the simple back quote character: `

What did you see instead?

Usage of double quote characters: and

Context

I think that for a language that boasts itself to be very precise about Unicode, it should be very precise as what kind of backquotes / double-quotes it does render in its code-blocks example for the comment documentation, hence this issue.
I am not sure if that is a problem yet, maybe only a discussion.

Here is what the page says about rendering quotes:

A pair of consecutive backticks (` U+0060) is interpreted as a Unicode left quote (“ U+201C), and a pair of consecutive single quotes (' U+0027) is interpreted as a unicode right quote (” U+201D).

Specific example

In the comment.md file, source for the Comment documentation page:

  • text-side: “[Text]: URL”
  • code-block: “[JSON and Go].”
@gopherbot gopherbot added this to the Unreleased milestone Aug 5, 2022
@piroux piroux changed the title x/website: Usage of unicode double quotes in code blocks the documentation x/website: Usage of unicode double quotes in code blocks of the documentation Aug 5, 2022
@thanm thanm added the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label Aug 8, 2022
@thanm
Copy link
Contributor

thanm commented Aug 8, 2022

@rsc

@jamalc jamalc modified the milestones: Unreleased, website/unplanned Aug 29, 2022
@weakish
Copy link

weakish commented Sep 16, 2022

Usage of double quote characters: “ and ”

are NOT part of the Go comment syntax specification

As you have quoted, according to /doc/comment,
a pair of consecutive backticks (U+0060) will be interpreted as a Unicode left quote (“ U+201C),
and a pair of consecutive single quotes (U+0027) as a Unicode right quote (” U+201D).
But it does not forbid to input the Unicode left and right quotes directly.

What did you expect to see?

Usage of the simple back quote character: `

The go doc comment page said nothing about using backticks to mark the opening and closing of an inline code span,
although there does exist this type of usage in the doc comment sample:

it may embed the `Status` in the normal response to indicate the

But this sample is used to show a common mistake "not indenting a wrapped indented line of a list or code block".
Thus I guess this sample are cited from some existing go doc comment,
where the original author used backticks for inline code spans.
This may not imply that Go endorses this usage.

@piroux piroux closed this as not planned Won't fix, can't repro, duplicate, stale Oct 6, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. website
Projects
None yet
Development

No branches or pull requests

5 participants