From 46e00888aea9bd398d590cef79b58be05878b079 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Arturo=20Filast=C3=B2?= <arturo@openobservatory.org>
Date: Mon, 11 Oct 2021 17:48:45 +0200
Subject: [PATCH] Edits to the measurex tutorial (#534)

---
 internal/tutorial/measurex/chapter03/README.md |  8 ++++----
 internal/tutorial/measurex/chapter03/main.go   |  8 ++++----
 internal/tutorial/measurex/chapter04/README.md |  8 ++++----
 internal/tutorial/measurex/chapter04/main.go   |  8 ++++----
 internal/tutorial/measurex/chapter05/README.md | 12 ++++++------
 internal/tutorial/measurex/chapter05/main.go   | 12 ++++++------
 internal/tutorial/measurex/chapter06/README.md | 10 +++++-----
 internal/tutorial/measurex/chapter06/main.go   | 10 +++++-----
 internal/tutorial/measurex/chapter08/README.md |  6 +++---
 internal/tutorial/measurex/chapter08/main.go   |  6 +++---
 internal/tutorial/measurex/chapter11/README.md |  6 +++---
 internal/tutorial/measurex/chapter11/main.go   |  6 +++---
 internal/tutorial/measurex/chapter14/README.md |  8 ++++----
 internal/tutorial/measurex/chapter14/main.go   |  8 ++++----
 14 files changed, 58 insertions(+), 58 deletions(-)

diff --git a/internal/tutorial/measurex/chapter03/README.md b/internal/tutorial/measurex/chapter03/README.md
index 1c7e4f3..fc08816 100644
--- a/internal/tutorial/measurex/chapter03/README.md
+++ b/internal/tutorial/measurex/chapter03/README.md
@@ -30,7 +30,7 @@ import (
 )
 
 func main() {
-	query := flag.String("query", "example.com", "domain to resolver")
+	query := flag.String("query", "example.com", "domain to resolve")
 	address := flag.String("address", "8.8.4.4:53", "DNS-over-UDP server address")
 	timeout := flag.Duration("timeout", 60*time.Second, "timeout to use")
 	flag.Parse()
@@ -429,9 +429,9 @@ Here's the corresponding JSON:
 }
 ```
 
-We see that we do fail with a timeout (I have marked some of them
+We see that we fail with a timeout (I have marked some of them
 with comments inside the JSON). We see the timeout at three different
-level of abstractions (from lower to higher abstraction): at the socket layer,
+levels of abstractions (from lower to higher abstraction): at the socket layer,
 during the DNS round trip, during the DNS lookup.
 
 What we also see is that `t`'s value is ~5s when the `read` event
@@ -562,6 +562,6 @@ Here's the answer I get:
 
 ## Conclusion
 
-We have seen how we sending DNS queries over UDP, measure the
+We have seen how to send DNS queries over UDP, measure the
 results, and what happens on common error conditions.
 
diff --git a/internal/tutorial/measurex/chapter03/main.go b/internal/tutorial/measurex/chapter03/main.go
index 8d000c4..1cce740 100644
--- a/internal/tutorial/measurex/chapter03/main.go
+++ b/internal/tutorial/measurex/chapter03/main.go
@@ -31,7 +31,7 @@ import (
 )
 
 func main() {
-	query := flag.String("query", "example.com", "domain to resolver")
+	query := flag.String("query", "example.com", "domain to resolve")
 	address := flag.String("address", "8.8.4.4:53", "DNS-over-UDP server address")
 	timeout := flag.Duration("timeout", 60*time.Second, "timeout to use")
 	flag.Parse()
@@ -430,9 +430,9 @@ func main() {
 // }
 // ```
 //
-// We see that we do fail with a timeout (I have marked some of them
+// We see that we fail with a timeout (I have marked some of them
 // with comments inside the JSON). We see the timeout at three different
-// level of abstractions (from lower to higher abstraction): at the socket layer,
+// levels of abstractions (from lower to higher abstraction): at the socket layer,
 // during the DNS round trip, during the DNS lookup.
 //
 // What we also see is that `t`'s value is ~5s when the `read` event
@@ -563,7 +563,7 @@ func main() {
 //
 // ## Conclusion
 //
-// We have seen how we sending DNS queries over UDP, measure the
+// We have seen how to send DNS queries over UDP, measure the
 // results, and what happens on common error conditions.
 //
 // -=-=- StopHere -=-=-
diff --git a/internal/tutorial/measurex/chapter04/README.md b/internal/tutorial/measurex/chapter04/README.md
index 970d860..25989de 100644
--- a/internal/tutorial/measurex/chapter04/README.md
+++ b/internal/tutorial/measurex/chapter04/README.md
@@ -192,8 +192,8 @@ https://github.com/ooni/spec/tree/master/data-formats.
 ### Suggested follow-up experiments
 
 Try to run experiments in the following scenarios, and
-check the output JSON to familiarize with what changes in
-different error conditions.
+check the output JSON to familiarize yourself with what
+changes in different error conditions.
 
 1. measurement that causes timeout
 
@@ -217,7 +217,7 @@ Here are the commands I used for each proposed exercise:
 
 4. go run -race ./internal/tutorial/measurex/chapter04 -address 104.154.89.105:443 -sni expire.badssl.com
 
-To emulate the two last scenario, if you're on Linux, a
+To emulate the last two scenarios, if you're on Linux, a
 possibility is building Jafar with this command:
 
 ```
@@ -243,5 +243,5 @@ Likewise, you can obtain a timeout using the
 ## Conclusion
 
 We have seen how to measure TLS handshakes. We have seen how
-this flow produces different output on different error conditions.
+this flow produces a different output on different error conditions.
 
diff --git a/internal/tutorial/measurex/chapter04/main.go b/internal/tutorial/measurex/chapter04/main.go
index 3ca7bfc..1c7d387 100644
--- a/internal/tutorial/measurex/chapter04/main.go
+++ b/internal/tutorial/measurex/chapter04/main.go
@@ -193,8 +193,8 @@ func main() {
 // ### Suggested follow-up experiments
 //
 // Try to run experiments in the following scenarios, and
-// check the output JSON to familiarize with what changes in
-// different error conditions.
+// check the output JSON to familiarize yourself with what 
+// changes in different error conditions.
 //
 // 1. measurement that causes timeout
 //
@@ -218,7 +218,7 @@ func main() {
 //
 // 4. go run -race ./internal/tutorial/measurex/chapter04 -address 104.154.89.105:443 -sni expire.badssl.com
 //
-// To emulate the two last scenario, if you're on Linux, a
+// To emulate the last two scenarios, if you're on Linux, a
 // possibility is building Jafar with this command:
 //
 // ```
@@ -244,6 +244,6 @@ func main() {
 // ## Conclusion
 //
 // We have seen how to measure TLS handshakes. We have seen how
-// this flow produces different output on different error conditions.
+// this flow produces a different output on different error conditions.
 //
 // -=-=- StopHere -=-=-
diff --git a/internal/tutorial/measurex/chapter05/README.md b/internal/tutorial/measurex/chapter05/README.md
index 9898dfc..6ab8a89 100644
--- a/internal/tutorial/measurex/chapter05/README.md
+++ b/internal/tutorial/measurex/chapter05/README.md
@@ -10,7 +10,7 @@ For this reason, we will not see a connect event, but we
 will only see a "QUIC handshake event".
 
 Having said that, let us now move on and see the code of
-the simple program that shows this functionality.
+the simple program that uses this functionality.
 
 (This file is auto-generated. Do not edit it directly! To apply
 changes you need to modify `./internal/tutorial/measure/chapter05/main.go`.)
@@ -63,7 +63,7 @@ The same remarks mentioned in the previous chapter regarding
 the arguments for the TLS config also apply here. We need
 to specify the SNI (`ServerName`), the ALPN (`NextProtos`),
 and the CA pool we want to use. Here, again, we're using
-the CA pool from cURL that we bundle with ooniprobe.
+the CA pool from cURL that we bundle with OONI Probe.
 
 As we did in the previous chapters, here's the usual three
 lines of code for printing the resulting measurement.
@@ -224,7 +224,7 @@ Produces this JSON:
   ],
 
   // This section describes the QUIC handshake and it has
-  // basically the same fields of the TLS handshake.
+  // basically the same fields as the TLS handshake.
   "quic_handshake": [
     {
       "cipher_suite": "TLS_CHACHA20_POLY1305_SHA256",
@@ -260,9 +260,9 @@ Produces this JSON:
 }
 ```
 
-Here are some suggestions on other experiments to run:
+Here are some suggestions for other experiments to run:
 
-1. obtain a timeout by connecting on a port that is not
+1. obtain a timeout by connecting to a port that is not
 actually listening for QUIC;
 
 2. obtain a certificate validation error by forcing
@@ -271,7 +271,7 @@ a different SNI;
 3. use a different ALPN (by changing the code), and see
 how the error and the oddity are handled. Can we do
 anything about this by changing `./internal/netxlite/errorx`
-to better support for this specific error condition?
+to better support this specific error condition?
 
 ## Conclusion
 
diff --git a/internal/tutorial/measurex/chapter05/main.go b/internal/tutorial/measurex/chapter05/main.go
index 8d92d6b..5e6962a 100644
--- a/internal/tutorial/measurex/chapter05/main.go
+++ b/internal/tutorial/measurex/chapter05/main.go
@@ -11,7 +11,7 @@
 // will only see a "QUIC handshake event".
 //
 // Having said that, let us now move on and see the code of
-// the simple program that shows this functionality.
+// the simple program that uses this functionality.
 //
 // (This file is auto-generated. Do not edit it directly! To apply
 // changes you need to modify `./internal/tutorial/measure/chapter05/main.go`.)
@@ -64,7 +64,7 @@ func main() {
 	// the arguments for the TLS config also apply here. We need
 	// to specify the SNI (`ServerName`), the ALPN (`NextProtos`),
 	// and the CA pool we want to use. Here, again, we're using
-	// the CA pool from cURL that we bundle with ooniprobe.
+	// the CA pool from cURL that we bundle with OONI Probe.
 	//
 	// As we did in the previous chapters, here's the usual three
 	// lines of code for printing the resulting measurement.
@@ -225,7 +225,7 @@ func main() {
 //   ],
 //
 //   // This section describes the QUIC handshake and it has
-//   // basically the same fields of the TLS handshake.
+//   // basically the same fields as the TLS handshake.
 //   "quic_handshake": [
 //     {
 //       "cipher_suite": "TLS_CHACHA20_POLY1305_SHA256",
@@ -261,9 +261,9 @@ func main() {
 // }
 // ```
 //
-// Here are some suggestions on other experiments to run:
+// Here are some suggestions for other experiments to run:
 //
-// 1. obtain a timeout by connecting on a port that is not
+// 1. obtain a timeout by connecting to a port that is not
 // actually listening for QUIC;
 //
 // 2. obtain a certificate validation error by forcing
@@ -272,7 +272,7 @@ func main() {
 // 3. use a different ALPN (by changing the code), and see
 // how the error and the oddity are handled. Can we do
 // anything about this by changing `./internal/netxlite/errorx`
-// to better support for this specific error condition?
+// to better support this specific error condition?
 //
 // ## Conclusion
 //
diff --git a/internal/tutorial/measurex/chapter06/README.md b/internal/tutorial/measurex/chapter06/README.md
index f37b8cc..ba83f1d 100644
--- a/internal/tutorial/measurex/chapter06/README.md
+++ b/internal/tutorial/measurex/chapter06/README.md
@@ -1,15 +1,15 @@
 
 # Chapter VI: Getting a webpage from an HTTP/HTTPS/HTTP3 endpoint.
 
-This chapter describes measuring getting a webpage from an
+This chapter describes measuring the retrieval of a webpage from an
 HTTPS endpoint. We have seen how to TCP connect, we have
 seen how to TLS handshake, now it's time to see how we can
-combine these operations with fetching a webpage from a
-given TCP endpoint speaking HTTP and TLS. (As well as to
-provide you with information on how to otherwise fetch
+combine these operations with that of fetching a webpage from a
+given TCP endpoint speaking HTTP and TLS. (As well as
+providing you with information on how to otherwise fetch
 from HTTP and HTTP/3 endpoints.)
 
-The program we're going to write, `main.go`, will show a
+The program we're going to write, `main.go`, will use a
 high-level operation to perform this measurement in a
 single API call. The code implementing this API call will
 combine the operations we have seen in previous chapter
diff --git a/internal/tutorial/measurex/chapter06/main.go b/internal/tutorial/measurex/chapter06/main.go
index 42ff264..8b19074 100644
--- a/internal/tutorial/measurex/chapter06/main.go
+++ b/internal/tutorial/measurex/chapter06/main.go
@@ -2,15 +2,15 @@
 //
 // # Chapter VI: Getting a webpage from an HTTP/HTTPS/HTTP3 endpoint.
 //
-// This chapter describes measuring getting a webpage from an
+// This chapter describes measuring the retrieval of a webpage from an
 // HTTPS endpoint. We have seen how to TCP connect, we have
 // seen how to TLS handshake, now it's time to see how we can
-// combine these operations with fetching a webpage from a
-// given TCP endpoint speaking HTTP and TLS. (As well as to
-// provide you with information on how to otherwise fetch
+// combine these operations with that of fetching a webpage from a
+// given TCP endpoint speaking HTTP and TLS. (As well as
+// providing you with information on how to otherwise fetch
 // from HTTP and HTTP/3 endpoints.)
 //
-// The program we're going to write, `main.go`, will show a
+// The program we're going to write, `main.go`, will use a
 // high-level operation to perform this measurement in a
 // single API call. The code implementing this API call will
 // combine the operations we have seen in previous chapter
diff --git a/internal/tutorial/measurex/chapter08/README.md b/internal/tutorial/measurex/chapter08/README.md
index 5baba85..69dc24a 100644
--- a/internal/tutorial/measurex/chapter08/README.md
+++ b/internal/tutorial/measurex/chapter08/README.md
@@ -58,7 +58,7 @@ func main() {
 ```
 ### Call LookupHTTPSSvc
 
-Here we perform the `LookupHostUDP` we performed in the
+Here we perform the `LookupHostUDP` we used in the
 previous chapter and then we call `LookupHTTPSvcUDP`.
 
 ```Go
@@ -67,7 +67,7 @@ previous chapter and then we call `LookupHTTPSvcUDP`.
 ```
 
 The `LookupHTTPSSvcUDP` function has the same signature
-of `LookupHostUDP` _but_ it behaves differently. Rather than
+as `LookupHostUDP` _but_ it behaves differently. Rather than
 querying for `A` and `AAAA`, it performs an `HTTPS` DNS
 lookup. This query returns:
 
@@ -80,7 +80,7 @@ lookup. This query returns:
 ### Build an []HTTPEndpoint and run serial measurements
 
 Here we call `AllHTTPEndpointsForURL` like we did in the
-previous chapter. However, note that we pass to it the
+previous chapter. However, note that we pass it the
 whole content of `m.DNS`, which now contains not only the
 A/AAAA lookups results but also the HTTPS lookup results.
 
diff --git a/internal/tutorial/measurex/chapter08/main.go b/internal/tutorial/measurex/chapter08/main.go
index eb1c6cd..8aac27e 100644
--- a/internal/tutorial/measurex/chapter08/main.go
+++ b/internal/tutorial/measurex/chapter08/main.go
@@ -59,7 +59,7 @@ func main() {
 	// ```
 	// ### Call LookupHTTPSSvc
 	//
-	// Here we perform the `LookupHostUDP` we performed in the
+	// Here we perform the `LookupHostUDP` we used in the
 	// previous chapter and then we call `LookupHTTPSvcUDP`.
 	//
 	// ```Go
@@ -68,7 +68,7 @@ func main() {
 	// ```
 	//
 	// The `LookupHTTPSSvcUDP` function has the same signature
-	// of `LookupHostUDP` _but_ it behaves differently. Rather than
+	// as `LookupHostUDP` _but_ it behaves differently. Rather than
 	// querying for `A` and `AAAA`, it performs an `HTTPS` DNS
 	// lookup. This query returns:
 	//
@@ -81,7 +81,7 @@ func main() {
 	// ### Build an []HTTPEndpoint and run serial measurements
 	//
 	// Here we call `AllHTTPEndpointsForURL` like we did in the
-	// previous chapter. However, note that we pass to it the
+	// previous chapter. However, note that we pass it the
 	// whole content of `m.DNS`, which now contains not only the
 	// A/AAAA lookups results but also the HTTPS lookup results.
 	//
diff --git a/internal/tutorial/measurex/chapter11/README.md b/internal/tutorial/measurex/chapter11/README.md
index 482e7dd..700fad7 100644
--- a/internal/tutorial/measurex/chapter11/README.md
+++ b/internal/tutorial/measurex/chapter11/README.md
@@ -15,9 +15,9 @@ changes you need to modify `./internal/tutorial/measurex/chapter11/main.go`.)
 ## main.go
 
 The beginning of the program is much simpler. We have removed
-out custom measurement type. We are now going to use the
+our custom measurement type. We are now going to use the
 `URLMeasurement` type (`go doc ./internal/measurex.URLMeasurement`),
-which as the same fields of `measurement` in chapter10 _plus_
+which has the same fields of `measurement` in chapter10 _plus_
 some extra fields that we'll examine in a later chapter.
 
 ```Go
@@ -77,7 +77,7 @@ The arguments are:
 The return value is either an `URLMeasurement`
 or an error. The error happens, for example, if
 the input URL scheme is not "http" or "https" (which
-we handled by panicking in chapter11).
+we handled by panicking in chapter07).
 
 Now, rather than panicking inside `MeasureURL`, we
 return the error to the caller and we `panic`
diff --git a/internal/tutorial/measurex/chapter11/main.go b/internal/tutorial/measurex/chapter11/main.go
index 6f37a17..6e36f26 100644
--- a/internal/tutorial/measurex/chapter11/main.go
+++ b/internal/tutorial/measurex/chapter11/main.go
@@ -16,9 +16,9 @@
 // ## main.go
 //
 // The beginning of the program is much simpler. We have removed
-// out custom measurement type. We are now going to use the
+// our custom measurement type. We are now going to use the
 // `URLMeasurement` type (`go doc ./internal/measurex.URLMeasurement`),
-// which as the same fields of `measurement` in chapter10 _plus_
+// which has the same fields of `measurement` in chapter10 _plus_
 // some extra fields that we'll examine in a later chapter.
 //
 // ```Go
@@ -78,7 +78,7 @@ func main() {
 	// The return value is either an `URLMeasurement`
 	// or an error. The error happens, for example, if
 	// the input URL scheme is not "http" or "https" (which
-	// we handled by panicking in chapter11).
+	// we handled by panicking in chapter07).
 	//
 	// Now, rather than panicking inside `MeasureURL`, we
 	// return the error to the caller and we `panic`
diff --git a/internal/tutorial/measurex/chapter14/README.md b/internal/tutorial/measurex/chapter14/README.md
index 348a4d4..b15de3c 100644
--- a/internal/tutorial/measurex/chapter14/README.md
+++ b/internal/tutorial/measurex/chapter14/README.md
@@ -67,7 +67,7 @@ func webConnectivity(ctx context.Context, URL string) (*measurement, error) {
 ```
 
 We start by parsing the input URL. If we cannot parse it, of
-course this is an hard error and we cannot continue.
+course this is a hard error and we cannot continue.
 
 ```Go
 	parsedURL, err := url.Parse(URL)
@@ -100,7 +100,7 @@ the input URL's domain using the system resolver.
 
 ```
 
-This is code we have already seen in previous chapter.
+This is code we have already seen in the previous chapters.
 
 
 ### 2. Building a list of endpoints
@@ -149,7 +149,7 @@ now focus on the last point:
 ### 5. HTTP measurement
 
 We need to manually build a `MeasurementDB`. This is a
-"database" where networking code will store events.
+"database" where the networking code will store events.
 
 ```Go
 
@@ -190,7 +190,7 @@ the round trip. Reading a snapshot of the response
 body is not implemented by this function but rather
 is a property of the "tracing" HTTP transport we
 created above (this type of transport is the one we
-have been internally using in all the examples
+have been using internally in all the examples
 presented so far.)
 
 ```Go
diff --git a/internal/tutorial/measurex/chapter14/main.go b/internal/tutorial/measurex/chapter14/main.go
index 0c07301..4acfc39 100644
--- a/internal/tutorial/measurex/chapter14/main.go
+++ b/internal/tutorial/measurex/chapter14/main.go
@@ -68,7 +68,7 @@ func webConnectivity(ctx context.Context, URL string) (*measurement, error) {
 	// ```
 	//
 	// We start by parsing the input URL. If we cannot parse it, of
-	// course this is an hard error and we cannot continue.
+	// course this is a hard error and we cannot continue.
 	//
 	// ```Go
 	parsedURL, err := url.Parse(URL)
@@ -101,7 +101,7 @@ func webConnectivity(ctx context.Context, URL string) (*measurement, error) {
 
 	// ```
 	//
-	// This is code we have already seen in previous chapter.
+	// This is code we have already seen in the previous chapters.
 	//
 	//
 	// ### 2. Building a list of endpoints
@@ -150,7 +150,7 @@ func webConnectivity(ctx context.Context, URL string) (*measurement, error) {
 	// ### 5. HTTP measurement
 	//
 	// We need to manually build a `MeasurementDB`. This is a
-	// "database" where networking code will store events.
+	// "database" where the networking code will store events.
 	//
 	// ```Go
 
@@ -191,7 +191,7 @@ func webConnectivity(ctx context.Context, URL string) (*measurement, error) {
 	// body is not implemented by this function but rather
 	// is a property of the "tracing" HTTP transport we
 	// created above (this type of transport is the one we
-	// have been internally using in all the examples
+	// have been using internally in all the examples
 	// presented so far.)
 	//
 	// ```Go