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 <shaojunyang@google.com>
Reviewed-by: Jonathan Amsterdam <jba@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Auto-Submit: Jonathan Amsterdam <jba@google.com>
diff --git a/slog-handler-guide/README.md b/slog-handler-guide/README.md
index 8ab958a..01027cc 100644
--- a/slog-handler-guide/README.md
+++ b/slog-handler-guide/README.md
@@ -9,11 +9,11 @@
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 @@
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 @@
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 @@
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 @@
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 @@
### 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 @@
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.
```
diff --git a/slog-handler-guide/guide.md b/slog-handler-guide/guide.md
index 4207e7a..f79f4e0 100644
--- a/slog-handler-guide/guide.md
+++ b/slog-handler-guide/guide.md
@@ -54,7 +54,7 @@
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":
