example/slog-handler-guide: run make

This change is the result of running `make` to produce README.md from
guide.md. It appears that the last time `make` was run was
2024-09-06 for 4e46ff5. I confirmed that all diffs to README.md
were deliberately introduced to guide.md (in 398e112 and 40afcb7).

In addition, one change to README.md (32022ca) was backported to
guide.md.

Change-Id: I6a27b8d128630f7f7e5799ad963fd96fb33ac3df
Reviewed-on: https://go-review.googlesource.com/c/example/+/668075
Reviewed-by: Junyang Shao <[email protected]>
Reviewed-by: Jonathan Amsterdam <[email protected]>
LUCI-TryBot-Result: Go LUCI <[email protected]>
Auto-Submit: Jonathan Amsterdam <[email protected]>

Author: bitlux

slog-handler-guide/README.md

@@ -9,11 +9,11 @@ This document is maintained by Jonathan Amsterdam `[email protected]`.
 
 1. [Introduction](#introduction)
 1. [Loggers and their handlers](#loggers-and-their-handlers)
-1. [Implementing `Handler` methods](#implementing-`handler`-methods)
-	1. [The `Enabled` method](#the-`enabled`-method)
-	1. [The `Handle` method](#the-`handle`-method)
-	1. [The `WithAttrs` method](#the-`withattrs`-method)
-	1. [The `WithGroup` method](#the-`withgroup`-method)
+1. [Implementing `Handler` methods](#implementing-handler-methods)
+	1. [The `Enabled` method](#the-enabled-method)
+	1. [The `Handle` method](#the-handle-method)
+	1. [The `WithAttrs` method](#the-withattrs-method)
+	1. [The `WithGroup` method](#the-withgroup-method)
 	1. [Testing](#testing)
 1. [General considerations](#general-considerations)
 	1. [Copying records](#copying-records)
@@ -28,7 +28,7 @@ The standard library’s `log/slog` package has a two-part design.
 A "frontend," implemented by the `Logger` type,
 gathers structured log information like a message, level, and attributes,
 and passes them to a "backend," an implementation of the `Handler` interface.
-The package comes with two built-in handlers that usually should be adequate.
+The package comes with two built-in handlers that should usually be adequate.
 But you may need to write your own handler, and that is not always straightforward.
 This guide is here to help.
 
@@ -41,7 +41,7 @@ types work together.
 Each logger contains a handler. Certain `Logger` methods do some preliminary work,
 such as gathering key-value pairs into `Attr`s, and then call one or more
 `Handler` methods. These `Logger` methods are `With`, `WithGroup`,
-and the output methods.
+and the output methods like `Info`, `Error` and so on.
 
 An output method fulfills the main role of a logger: producing log output.
 Here is a call to an output method:
@@ -107,6 +107,11 @@ so it will sometimes produce invalid YAML.
 For example, it doesn't quote keys that have colons in them.
 We'll call it `IndentHandler` to forestall disappointment.
 
+A brief aside before we start: it is tempting to embed `slog.Handler` in your
+custom handler and implement only the methods that you need.
+Loggers and handlers are too tightly coupled for that to work. You should
+implement all four handler methods.
+
 We begin with the `IndentHandler` type
 and the `New` function that constructs it from an `io.Writer` and options:
 
@@ -439,7 +444,7 @@ Most of the fields of `IndentHandler` can be copied shallowly, but the slice of
 the same underlying array. If we used `append` instead of making an explicit
 copy, we would introduce that subtle aliasing bug.
 
-Using `withGroupOrAttrs`, the `With` methods are easy:
+The `With` methods are easy to write using `withGroupOrAttrs`:
 
 ```
 func (h *IndentHandler) WithGroup(name string) slog.Handler {
@@ -543,7 +548,7 @@ See [this bug report](https://go.dev/issue/61321) for more detail.
 
 ### With pre-formatting
 
-Our second implementation implements pre-formatting.
+Our second version of the `WithGroup` and `WithAttrs` methods provides pre-formatting.
 This implementation is more complicated than the previous one.
 Is the extra complexity worth it?
 That depends on your circumstances, but here is one circumstance where
@@ -600,7 +605,7 @@ We also need to track how many groups we've opened, which we can do
 with a simple counter, since an opened group's only effect is to change the
 indentation level.
 
-The `WithGroup` implementation is a lot like the previous one: just remember the
+This `WithGroup` is a lot like the previous one: it just remembers the
 new group, which is unopened initially.
 
 ```

slog-handler-guide/guide.md

@@ -54,7 +54,7 @@ original remains unchanged.
 All subsequent output from `logger` will include those attributes.
 A logger's `With` method calls its handler's `WithAttrs` method.
 
-The `WithGroup` method is used to avoid avoid key collisions in large programs
+The `WithGroup` method is used to avoid key collisions in large programs
 by establishing separate namespaces.
 This call creates a new `Logger` value with a group named "g":