_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 <filename>`. 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 <straut@google.com>
Run-TryBot: Steve Traut <straut@google.com>
TryBot-Result: Go Bot <gobot@golang.org>
Reviewed-by: Jay Conrod <jayconrod@google.com>

1 files changed, 114 insertions, 110 deletions

diff --git a/_content/doc/tutorial/call-module-code.html b/_content/doc/tutorial/call-module-code.html
index 3c3602b8..bce43d72 100644
--- a/_content/doc/tutorial/call-module-code.html
+++ b/_content/doc/tutorial/call-module-code.html
@@ -4,7 +4,7 @@
 }-->
 
 <p>
-  In the <a href="create-module.html">previous section</a>, you created a
+  In the <a href="/doc/tutorial/create-module.html">previous section</a>, you created a
   <code>greetings</code> module. In this section, you'll write code to make
   calls to the <code>Hello</code> function in the module you just wrote. You'll
   write code you can execute as an application, and which calls code in the
@@ -13,7 +13,7 @@
 
 <aside class="Note">
   <strong>Note:</strong> This topic is part of a multi-part tutorial that begins
-  with <a href="create-module.html">Create a Go module</a>.
+  with <a href="/doc/tutorial/create-module.html">Create a Go module</a>.
 </aside>
 
 <ol>
@@ -22,8 +22,16 @@
     is where you'll write your caller.
 
     <p>
-      For example, if your current directory in the command prompt is the
-      greetings directory, you could use the following commands:
+      After you create this directory, you should have both a hello and a
+      greetings directory at the same level in the hierarchy, like so:
+    </p>
+      <pre>&lt;home&gt;/
+ |-- greetings/
+ |-- hello/</pre>
+
+    <p>
+      For example, if your command prompt is in the greetings directory, you
+      could use the following commands:
     </p>
 
     <pre>
@@ -35,7 +43,28 @@ cd hello
   </li>
 
   <li>
-    In your text editor (in the hello directory), create a file in which to
+    Enable dependency tracking for the code you're about to write.
+
+    <p>
+      To enable dependency tracking for your code, run the
+      <a
+        href="/ref/mod#go-mod-init"
+        ><code>go mod init</code> command</a>, giving it the name of the module
+        your code will be in.</p>
+
+    <p>
+        For the purposes of this tutorial, use <code>example.com/hello</code>
+        for the module path.
+    </p>
+
+    <pre>
+$ go mod init example.com/hello
+go: creating new go.mod: module example.com/hello
+</pre>
+  </li>
+
+  <li>
+    In your text editor, in the hello directory, create a file in which to
     write your code and call it hello.go.
   </li>
 
@@ -61,8 +90,7 @@ func main() {
     message := greetings.Hello("Gladys")
     fmt.Println(message)
 }
-</pre
-    >
+</pre>
 
     <p>
       In this code, you:
@@ -71,16 +99,16 @@ func main() {
     <ul>
       <li>
         Declare a <code>main</code> package. In Go, code executed as an
-        application must go in a <code>main</code> package.
+        application must be in a <code>main</code> package.
       </li>
       <li>
         Import two packages: <code>example.com/greetings</code> and
-        <code>fmt</code>. This gives your code access to functions in those
-        packages. Importing <code>example.com/greetings</code> (the package
-        contained in the module you created earlier) gives you access to the
-        <code>Hello</code> function. You also import <code>fmt</code>, with
-        functions for handling input and output text (such as printing text to
-        the console).
+        the <a href="https://pkg.go.dev/fmt/"><code>fmt</code> package</a>. This
+        gives your code access to functions in those packages. Importing
+        <code>example.com/greetings</code> (the package contained in the module
+        you created earlier) gives you access to the <code>Hello</code>
+        function. You also import <code>fmt</code>, with functions for handling
+        input and output text (such as printing text to the console).
       </li>
       <li>
         Get a greeting by calling the <code>greetings</code> package’s
@@ -90,148 +118,124 @@ func main() {
   </li>
 
   <li>
-    Create a new module for this hello package.
+    Edit the <code>example.com/hello</code> module to use your local
+    <code>example.com/greetings</code> module.
 
     <p>
-      From the command line at the hello directory, run the
-      <code>go mod init</code> command, giving it the name of the module your
-      code will be in (here, just use "hello").
-    </p>
-
-    <pre>
-$ go mod init hello
-go: creating new go.mod: module hello
-</pre
-    >
-  </li>
-
-  <li>
-    Edit the <code>hello</code> module to use the unpublished greetings module.
-
-    <p>
-      For production use, you’d publish your modules on a server, either inside
-      your company or on the internet, and the Go command will download them
-      from there. For now, you need to adapt the caller's module so it can find
-      the greetings code on your local file system.
+      For production use, you’d publish the <code>example.com/greetings</code>
+      module from its repository (with a module path that reflected its published
+      location), where Go tools could find it to download it.
+      For now, because you haven't published the module yet, you need to adapt
+      the <code>example.com/hello</code> module so it can find the
+      <code>example.com/greetings</code> code on your local file system.
     </p>
 
     <p>
-      To do that, make a small change to <code>hello</code> module’s go.mod
-      file.
+      To do that, use the
+      <a href="/ref/mod#go-mod-edit"><code>go
+      mod edit</code> command</a> to edit the <code>example.com/hello</code>
+      module to redirect Go tools from its module path (where the module isn't)
+      to the local directory (where it is).
     </p>
 
     <ol>
       <li>
-        In the hello directory, open the go.mod file, change it so that it looks
-        like the following, and save the file.
+        From the command prompt in the hello directory, run the following
+        command:
+
+    <pre>
+$ go mod edit -replace=example.com/greetings=../greetings
+</pre>
+
+    <p>
+      The command specifies that <code>example.com/greetings</code> should be
+      replaced with <code>../greetings</code> for the purpose of locating the
+      dependency. After you run the command, the go.mod file in the hello
+      directory should include a <a href="/doc/modules/gomod-ref#replace">
+        <code>replace</code> directive</a>:
+    </p>
 
         <pre>
-module hello
+module example.com/hello
 
-go 1.14
+go 1.16
 
 <ins>replace example.com/greetings => ../greetings</ins>
 </pre>
-
-        <p>
-          Here, the
-          <a href="/ref/mod#go-mod-file-replace">
-            <code>replace</code> directive
-          </a>
-          tells Go to replace the module path (the URL
-          <code>example.com/greetings</code>) with a path you specify. In this
-          case, that's a greetings directory next to the hello directory.
-        </p>
       </li>
 
       <li>
-        In the hello directory, run <code>go build</code> to make Go locate the
-        module and add it as a dependency to the go.mod file.
+        From the command prompt in the hello directory, run the
+        <a href="/ref/mod#go-mod-tidy">
+        <code>go mod tidy</code> command</a> to synchronize the
+        <code>example.com/hello</code> module's dependencies, adding those
+        required by the code, but not yet tracked in the module.
 
-        <pre>
-$ go build
+        <pre>$ go mod tidy
 go: found example.com/greetings in example.com/greetings v0.0.0-00010101000000-000000000000
-</pre
-        >
-      </li>
-
-      <li>
-        Look at go.mod again to see the changes made by <code>go build</code>,
-        including the <code>require</code> directive Go added.
+</pre>
+        <p>
+         After the command completes, the <code>example.com/hello</code>
+         module's go.mod file should look like this:
+        </p>
 
-        <pre>
-module hello
+        <pre>module example.com/hello
 
-go 1.14
+go 1.16
 
 replace example.com/greetings => ../greetings
 
-<ins>require example.com/greetings v0.0.0-00010101000000-000000000000</ins>
-</pre>
+<ins>require example.com/greetings v0.0.0-00010101000000-000000000000</ins></pre>
 
         <p>
-          To build the module, Go found the local code in the ../greetings
-          directory, then added a
-          <a href="/ref/mod#go-mod-file-require">
-            <code>require</code> directive
-          </a>
-          to specify that <code>hello</code> is dependent on (requires)
-          <code>example.com/greetings</code>. You created this dependency when
-          you imported the <code>greetings</code> package (contained in the
-          greetings module) in hello.go. The <code>replace</code> directive
-          tells Go where to find the <code>greetings</code> module, because it
-          isn't published yet.
+          The command found the local code in the greetings directory, then
+          added a <a href="/doc/modules/gomod-ref#require"><code>require</code>
+          directive</a> to specify that <code>example.com/hello</code>
+          requires <code>example.com/greetings</code>. You created this
+          dependency when you imported the <code>greetings</code> package in
+          hello.go.
+        </p>
+        <p>
+          The number following the module path is a <em>pseudo-version number</em>
+          -- a generated number used in place of a semantic version number (which
+          the module doesn't have yet).
         </p>
-
         <p>
-          To reference a published module, a go.mod file would omit the
-          <code>replace</code> directive and use a
-          <code>require</code> directive with a tagged version number at the
-          end.
+          To reference a <em>published</em> module, a go.mod file would
+          typically omit the <code>replace</code> directive and use a
+          <code>require</code> directive with a tagged version number at the end.
         </p>
 
         <pre>require example.com/greetings v1.1.0</pre>
+
+        <p>For more on version numbers, see
+          <a href="/doc/modules/version-numbers">Module version numbering</a>.</p>
       </li>
     </ol>
-  </li>
-
   <li>
-    In the <code>hello</code> directory, run the <code>hello</code> executable
-    (created by <code>go build</code>) to confirm that the code works.
-    <ul>
-      <li>
-        On Linux or Mac:
+    At the command prompt in the <code>hello</code> directory, run your code to
+    confirm that it works.
 
-        <pre>
-$ ./hello
-Hi, Gladys. Welcome!
-</pre
-        >
-      </li>
-
-      <li>
-        On Windows:
-
-        <pre>
-$ hello.exe
+    <pre>
+$ go run .
 Hi, Gladys. Welcome!
-</pre
-        >
-      </li>
-    </ul>
+</pre>
   </li>
 </ol>
 
 <p>
-  Congrats! You've written two functioning modules. In the tutorial's
-  <a href="handle-errors.html">next topic</a>, you'll add some error handling.
+  Congrats! You've written two functioning modules.
+</p>
+
+<p>
+  In the next topic, you'll add some error handling.
 </p>
 
 <p class="Navigation">
-  <a class="Navigation-prev" href="create-module.html"
+  <a class="Navigation-prev" href="/doc/tutorial/create-module.html"
     >&lt; Create a Go module</a
   >
-  <a class="Navigation-next" href="handle-errors.html"
+  <a class="Navigation-next" href="/doc/tutorial/handle-errors.html"
     >Return and handle an error &gt;</a
   >
 </p>