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

Jump to bottom

go/doc: doc package converts smart quotes in preformatted blocks #29730

Closed
segevfiner opened this issue Jan 14, 2019 · 7 comments
Closed

go/doc: doc package converts smart quotes in preformatted blocks #29730

segevfiner opened this issue Jan 14, 2019 · 7 comments
Labels
FrozenDueToAge NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. Suggested Issues that may be good for new contributors looking for work to do.
Milestone
Go1.13

Comments

@segevfiner
Copy link
Contributor

segevfiner commented Jan 14, 2019 •
edited

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

$ go version
go version devel +7cbfa55b5d Sat Jan 12 00:27:48 2019 +0000 linux/amd64

Does this issue reproduce with the latest release?

Git master.

What operating system and processor architecture are you using (go env)?

go env Output
$ go env
GOARCH="amd64"
GOBIN=""
GOCACHE="<snip>/.cache/go-build"
GOEXE=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GOOS="linux"
GOPATH="<snip>/go"
GOPROXY=""
GORACE=""
GOROOT="<snip>/prj/go"
GOTMPDIR=""
GOTOOLDIR="<snip>/prj/go/pkg/tool/linux_amd64"
GCCGO="gccgo"
CC="gcc"
CXX="g++"
CGO_ENABLED="1"
GOMOD=""
CGO_CFLAGS="-g -O2"
CGO_CPPFLAGS=""
CGO_CXXFLAGS="-g -O2"
CGO_FFLAGS="-g -O2"
CGO_LDFLAGS="-g -O2"
PKG_CONFIG="pkg-config"
GOGCCFLAGS="-fPIC -m64 -pthread -fmessage-length=0 -fdebug-prefix-map=/tmp/go-build019133103=/tmp/go-build -gno-record-gcc-switches"

What did you do?

  1. Save as smartquotes.go
package godoctest

// Bar does ``stuff''
//
//     Bar(`` + '')
func Bar(s string) {

}
  1. Run go doc Bar in that package directory.

What did you expect to see?

➜ ~/prj/go/bin/go doc Bar
func Bar(s string)
    Bar does “stuff”

    Bar(`` + '')

What did you see instead?

➜ ~/prj/go/bin/go doc Bar
func Bar(s string)
    Bar does “stuff”

    Bar(“ + ”)

The preformatted block has smart quotes converted.

Analysis

Smart quotes are converted here:

go/src/go/doc/comment.go

Line 448 in 4e8aaf6

line = convertQuotes(line)

But it's explicitly not done in HTML output here:

go/src/go/doc/comment.go

Line 332 in 4e8aaf6

emphasize(w, line, nil, false)

By the final false argument. So it probably shouldn't be done for the text format too.
@agnivade
Copy link
Contributor

/cc @robpike @griesemer

@agnivade agnivade added the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label Jan 16, 2019
@robpike
Copy link
Contributor

robpike commented Jan 16, 2019

It's go/doc. @griesemer?

@robpike robpike changed the title cmd/doc: Converts smart quotes in preformatted blocks go/doc: doc package converts smart quotes in preformatted blocks Jan 16, 2019
@griesemer
Copy link
Contributor

I haven't investigated in detail but probably happens in go/doc/comment.go somewhere. This sounds like a good starter problem for somebody to fix.

@griesemer griesemer added the Suggested Issues that may be good for new contributors looking for work to do. label Jan 17, 2019
@griesemer griesemer added this to the Go1.13 milestone Jan 17, 2019
@agnivade
Copy link
Contributor

agnivade commented Jan 17, 2019 •
edited

I made the convertQuotes change, which converts these special quotes to unicode quotes. But we were never checking for preformatted blocks.

For 1.11, it will be -

func Bar(s string)
    Bar does ``stuff''

    Bar(`` + '')

For 1.12, it will be -

func Bar(s string)
    Bar does “stuff”

    Bar(” + ”)

@griesemer - Are you fine with ignoring these conversions in preformatted blocks ? We will then need to add the logic to check for preformatted blocks.

@griesemer
Copy link
Contributor

@agnivade It makes sense to leave preformatted blocks alone, but I don't have the full picture in my head at the moment. Probably worthwhile making sure we have a plan that doesn't require this changing back and forth in each release.

@segevfiner
Copy link
Contributor Author

Note that the code already doesn't convert quotes in the HTML output.

@gopherbot
Copy link

Change https://golang.org/cl/162922 mentions this issue: go/doc: skip escaping comments in pre-formatted blocks

@gokcehan gokcehan mentioned this issue Mar 21, 2019
Closed
@golang golang locked and limited conversation to collaborators Feb 26, 2020
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
FrozenDueToAge NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. Suggested Issues that may be good for new contributors looking for work to do.
Projects
None yet
Milestone
Go1.13
Development

No branches or pull requests
5 participants
@agnivade @robpike @griesemer @gopherbot @segevfiner