From 02ef8fa5ddb8111aa8752ffb8267e67c4e209649 Mon Sep 17 00:00:00 2001
From: Steve Traut <straut@google.com>
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 <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>
---
 _content/doc/tutorial/handle-errors.html | 29 +++++++++++++++--------------
 1 file changed, 15 insertions(+), 14 deletions(-)

(limited to '_content/doc/tutorial/handle-errors.html')

diff --git a/_content/doc/tutorial/handle-errors.html b/_content/doc/tutorial/handle-errors.html
index 4dfd4b13..76f7a4f3 100644
--- a/_content/doc/tutorial/handle-errors.html
+++ b/_content/doc/tutorial/handle-errors.html
@@ -11,7 +11,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>
@@ -55,14 +55,13 @@ func Hello(name string) <ins>(</ins>string<ins>, error)</ins> {
         Change the function so that it returns two values: a
         <code>string</code> and an <code>error</code>. Your caller will check
         the second value to see if an error occurred. (Any Go function can
-        <a href="https://golang.org/doc/effective_go.html#multiple-returns"
-          >return multiple values</a
-        >.)
+        return multiple values. For more, see 
+        <a href="/doc/effective_go.html#multiple-returns">Effective Go</a>.)
       </li>
       <li>
         Import the Go standard library <code>errors</code> package so you can
         use its
-        <a href="https://golang.org/pkg/errors/#example_New"
+        <a href="https://pkg.go.dev/errors/#example-New"
           ><code>errors.New</code> function</a
         >.
       </li>
@@ -106,7 +105,7 @@ func main() {
     log.SetFlags(0)</ins>
 
     // Request a greeting message.
-    message, err := greetings.Hello("")
+    <ins>message, err := greetings.Hello("")</ins>
     <ins>// If an error was returned, print it to the console and
     // exit the program.
     if err != nil {
@@ -126,7 +125,7 @@ func main() {
     <ul>
       <li>
         Configure the
-        <a href="https://golang.org/pkg/log/"><code>log</code> package</a> to
+        <a href="https://pkg.go.dev/log/"><code>log</code> package</a> to
         print the command name ("greetings: ") at the start of its log messages,
         without a time stamp or source file information.
       </li>
@@ -163,7 +162,7 @@ func main() {
     </p>
 
     <pre>
-$ go run hello.go
+$ go run .
 greetings: empty name
 exit status 1
 </pre
@@ -172,17 +171,19 @@ exit status 1
 </ol>
 
 <p>
-  That's essentially how error handling in Go works: Return an error as a value
-  so the caller can check for it. It's pretty simple. In the tutorial's
-  <a href="random-greeting.html">next topic</a>, you'll use a Go slice to return
-  a randomly-selected greeting.
+  That's common error handling in Go: Return an error as a value so the caller
+  can check for it.
+</p>
+
+<p>
+  Next, you'll use a Go slice to return a randomly-selected greeting.
 </p>
 
 <p class="Navigation">
-  <a class="Navigation-prev" href="call-module-code.html"
+  <a class="Navigation-prev" href="/doc/tutorial/call-module-code.html"
     >&lt; Call your code from another module</a
   >
-  <a class="Navigation-next" href="random-greeting.html"
+  <a class="Navigation-next" href="/doc/tutorial/random-greeting.html"
     >Return a random greeting &gt;</a
   >
 </p>
-- 
cgit v1.3