x/website: various mistakes in documentation on modules

[fzipp]

I read the new documentation on modules (which is great, btw) and took notes of mistakes I encountered.

https://golang.org/doc/modules/gomod-ref

1. Contradiction: The description for 'replacement-path' says:

   "[...] If this is a module path, you must specify a _replacement-version_ value. [...]"
   But the following example shows the replacement of a module path without a replacement version value:
   "replace example.com/othermodule => example.com/myfork/othermodule"

2. Section 'exclude', description of 'module-version":

   "If this version number is omitted, all versions of the module are replaced with the content on the right side of the arrow."

   But an 'exclude' directive doesn't have an arrow. This sentence seems to be copy&pasted from the 'replace' directive and wrong.

3. Contradiction:

   "These directives are ignored in modules that depend on the current module."
   vs. later
   "These directives are ignored in modules that are dependencies of the current module."
   Which one is it?

4. Formatting: In the first example one line is not correctly indented.

5. Formatting: "_replacement-version_", "_replacement-path_". The underscores are probably not intended, but unsupported Markdown syntax.

https://golang.org/doc/tutorial/create-module

6. "This tutorial's sequence includes six brief topics [...]"

   Followed by a numbered list of seven topics. s/six/seven/

https://golang.org/doc/tutorial/call-module-code

7. Broken link: "Here, the replace directive [...]"

8. Broken tutorial: "In the hello directory, run go build to make Go locate the module and add it as a dependency to the go.mod file."

   Starting with Go 1.16 'go build' doesn't add dependencies anymore, which breaks this tutorial (similar to x/website: Getting Started tutorial doesn't work with Go 1.16 #43672).

https://golang.org/doc/tutorial/getting-started

9. Outdated description: "3. On the Doc tab, under Index, [...]"

   The former Doc tab is a menu item named 'Documentation' on the left side now.

https://golang.org/doc/modules/managing-dependencies

10. Broken link: "See package discovery."

11. Typo: "One you've discovered" s/One/Once/

https://golang.org/doc/modules/version-numbers

12. Typo: "For more, see Managingdependencies." (missing space)

https://golang.org/doc/modules/publishing

13. Typo: "6. [...] with 1nformation about [...]"

    s/1nformation/information/

14. Broken links: "go get command" (twice)

    here: "[ ... ] and run the go get command [...]",
    and here: "They can run the go get command [...]

https://golang.org/doc/modules/major-version

15. Invalid syntax:

    "Old import statement: import example.com/mymodule/package1
    New import statement: import example.com/mymodule/v2/package1"

    Package paths must be in quotes.

General

16. The anchors on most pages under doc/modules have temporary names: #tmp_0, #tmp_1, etc.

[fzipp]

17. Adding to this point:

Starting with Go 1.16 'go build' doesn't add dependencies anymore, which breaks this tutorial.

Step 4 on https://golang.org/doc/tutorial/call-module-code tells the user to run go mod init hello:

$ go mod init hello
go: creating new go.mod: module hello

But the actual output starting with Go 1.16 is:

$ go mod init hello
go: creating new go.mod: module hello
go: to add module requirements and sums:
	go mod tidy

The tutorial should tell the user to ignore the go mod tidy message, since it will go on to set up a replace directive for example.com/greetings to a local directory.

[fzipp]

18. Another tutorial that needs to be updated for the Go 1.16 changes:

https://golang.org/doc/code.html

When you run commands like go install, go build, or go run, the go command will automatically download the remote module and record its version in your go.mod file:

$ go install example.com/user/hello
go: finding module for package github.com/google/go-cmp/cmp
go: downloading github.com/google/go-cmp v0.4.0
go: found github.com/google/go-cmp/cmp in github.com/google/go-cmp v0.4.0

go install no longer automatically downloads modules. The actual output is:

$ go install example.com/user/hello
hello.go:7:2: no required module provides package github.com/google/go-cmp/cmp; to add it:
	go get github.com/google/go-cmp/cmp

[fzipp]

The minor issues (typos, broken links, formatting) are addressed by CL 293229

[gopherbot]

Change https://golang.org/cl/293229 mentions this issue: _content/doc: fix typos, broken links, and text formatting

[dmitshur]

Thank you for reporting this and sending a CL.

CC @stevetraut.

[stevetraut]

Thanks so much for these fixes, @fzipp! I'll take a look at the CL.

[fzipp]

@stevetraut
Thanks. I have numbered the points now. The CL only fixes the simpler points (1, 4, 5, 6, 7, 9, 10, 11, 12, 13, 14, 15).

Points 2, 3, 8, 16, 17, 18 are still open, and some of them are more important, because they break the tutorial experience, but I think they should be addressed by you, because in some cases I don't know what the right answer or best practice is.

[stevetraut]

Thanks, @fzipp. I'll take a look.