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

go/doc: heading with "go.mod" not detected as a heading #26938

Closed
myitcv opened this issue Aug 12, 2018 · 4 comments
Closed

go/doc: heading with "go.mod" not detected as a heading #26938

myitcv opened this issue Aug 12, 2018 · 4 comments

Comments

@myitcv
Copy link
Member

myitcv commented Aug 12, 2018

Please answer these questions before submitting your issue. Thanks!

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

go version devel +5c11480631 Fri Aug 10 20:02:31 2018 +0000 linux/amd64

Does this issue reproduce with the latest release?

N/a - testing with tip.

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

GOARCH="amd64"
GOBIN=""
GOCACHE="/home/myitcv/.cache/go-build"
GOEXE=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GOOS="linux"
GOPATH="/home/myitcv/gostuff"
GOPROXY=""
GORACE=""
GOROOT="/home/myitcv/gos"
GOTMPDIR=""
GOTOOLDIR="/home/myitcv/gos/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-build705478527=/tmp/go-build -gno-record-gcc-switches"

What did you do?

go install golang.org/x/tools/cmd/godoc && godoc -http :8080

then visit:

http://localhost:8080/cmd/go/#hdr-Module_downloading_and_verification

Scroll down slightly to see that "Edit go.mod from tools or scripts" has not been formatted as a heading as it needs to be.

What did you expect to see?

"Edit go.mod from tools or scripts" formatted as a heading, so that I can see the section but also link to it (which is how I came across this).

What did you see instead?

screen shot 2018-08-11 at 13 46 25

This is ultimately because headings are currently not allowed to contain a period (.):

if strings.ContainsAny(line, ".;:!?+*/=[]{}_^°&§~%#@<\">\\") {

Feels like simply allowing a . is probably too much of a change that could easily trigger changes in the way existing docs are currently rendered. But maybe it's ok to special case a filename, e.g. go.mod, where there is an alpha-numeric either side. Else reject.

Given how significant go.mod and go.sum are in the context of modules, would be a shame to have to come up with alternative headings if we don't want to allow .?

/cc @rsc @griesemer

@myitcv
Copy link
Member Author

myitcv commented Aug 12, 2018

I note the semi-related #17564

@ianlancetaylor
Copy link
Contributor

I think that for 1.11 we should just fix the doc string, rather than trying to mess with godoc. Sending a CL.

@gopherbot
Copy link

Change https://golang.org/cl/129695 mentions this issue: cmd/go: don't use period in godoc heading line

@gopherbot
Copy link

Change https://golang.org/cl/129677 mentions this issue: go/doc: allow interior dot in heading, as in "go.mod"

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

No branches or pull requests

3 participants