From 02ef8fa5ddb8111aa8752ffb8267e67c4e209649 Mon Sep 17 00:00:00 2001 From: Steve Traut Date: Mon, 1 Mar 2021 10:42:43 -0500 Subject: _content/doc: fix module and tutorial bugs and clean up flow For golang/go#44241 - Fix issues 2, 3, 8, 16, 17, 18 from golang/go#44241 Other changes in multiple topics: - In markdown, replace HTML anchor tags with {#anchor} tags. - In a few places, add content to clarify that module path must be a location from which the module can be downloaded. - Where it was missing, add example.com domain to example module paths. Hopefully, this will reinforce the idea that the module path should typically include a domain. Docs will use something that looks like a domain name for module path. - Add more cross-references from tutorial to references for packages and commands. - Rewrite a few links so that they include the topic title, rather than simply inline text. Left those links whose destinations are references -- the item's name seems to suggest that a reference is at the destination. - Remove domain name from golang.org doc links, leaving root directory. Such as /cmd/go/* or /doc/modules/* - Add path up to root for all links in the same domain. Some were linking by file name only. - Change standard library links from golang.org to pkg.go.dev. Changes in the module tutorial: - Add text to help clarify that there should be a hello and greetings directory as siblings in their directory hierarchy. Some users thought one should be subordinate to the other. - Where needed, reorder steps so that `go mod init` is run before code is added. This is intended to reinforce the importance of the module's presence. - In require/replace steps, have the user use `go mod edit` rather than editing the go.mod file in an editor. The tools are more likely to yield a functioning result. - Where possible/appropriate, change module directive link destinations from "Modules reference" to go.mod reference. - Change "run the code" steps so that they all use `go run .` rather than `go build` or `go run `. This removes the impedance of explanation and more commands, while moving the explanation of `go build` and `go install` to a separate topic where they share a clearer context. - Add a "Conclusion" topic with a few links. The tutorial ended rather abruptly before. - Minor edits to remove some redundant language. Change-Id: I93055035d73c362ba73edea458fc53bc45e66512 Reviewed-on: https://go-review.googlesource.com/c/website/+/297531 Trust: Steve Traut Run-TryBot: Steve Traut TryBot-Result: Go Bot Reviewed-by: Jay Conrod --- _content/doc/tutorial/getting-started.html | 48 +++++++++++++++++++----------- 1 file changed, 30 insertions(+), 18 deletions(-) (limited to '_content/doc/tutorial/getting-started.html') diff --git a/_content/doc/tutorial/getting-started.html b/_content/doc/tutorial/getting-started.html index fc05867f..eff1bb69 100644 --- a/_content/doc/tutorial/getting-started.html +++ b/_content/doc/tutorial/getting-started.html @@ -21,7 +21,7 @@

Prerequisites

@@ -90,26 +90,35 @@ cd hello
  • - Initialize a new module for tracking dependencies. + Enable dependency tracking for your code.

    - When your code imports packages from another module, a go.mod file lists - the specific modules and versions providing those packages. That file - stays with your code, including in your source code repository. + When your code imports packages contained in other modules, you manage + those dependencies through your code's own module. That module is defined + by a go.mod file that tracks the modules that provide those packages. That + go.mod file stays with your code, including in your source code + repository.

    - To create a go.mod file, run the - go mod init command, giving it the name of the module your code will be in (here, just use - "hello"): + To enable dependency tracking for your code by creating a go.mod file, run + the + go mod init command, + giving it the name of the module your code will be in. The name is the + module's module path. In most cases, this will be the repository + location where your source code will be kept, such as + github.com/mymodule. If you plan to publish your module + for others to use, the module path must be a location from + which Go tools can download your module. +

    + +

    For the purposes of this tutorial, just use + example.com/hello. 

    -$ go mod init hello
-go: creating new go.mod: module hello
+$ go mod init example.com/hello
+go: creating new go.mod: module example.com/hello
    • @@ -143,10 +152,10 @@ func main() {
  • Import the popular - fmt package, + fmt package, which contains functions for formatting text, including printing to the console. This package is one of the - standard library packages you got + standard library packages you got when you installed Go.
  • @@ -168,7 +177,7 @@ Hello, World!

    The - go run command is one of many go commands you'll use to get things done with @@ -252,7 +261,10 @@ func main() { Add new module requirements and sums.

    - Go will add the quote module as a requirement, as well as a go.sum file for use in authenticating the module. For more, see Module authentication using go.sum. + Go will add the quote module as a requirement, as well as a + go.sum file for use in authenticating the module. For more, see + Authenticating modules in the Go + Modules Reference. 

     $ go mod tidy
@@ -289,5 +301,5 @@ Don't communicate by sharing memory, share memory by communicating.
 
    
   With this quick introduction, you got Go installed and learned some of the
   basics. To write some more code with another tutorial, take a look at
-  Create a Go module.
+  Create a Go module.
 
    
-- 
cgit v1.3