doc: start sketching out the DNS tutorial (#59)

This commit starts writing some content inside of the DNS tutorial,
trying to introduce topics incrementally.

README.md

@@ -94,32 +94,31 @@ using the pure-Go DNS lookup engine (`netgo`).
 
 ```sh
 # Resolve a domain name
-$ rbmk dig +short=ip example.com
+rbmk dig +short=ip example.com
 93.184.215.14
 
 # Make an HTTP request
-$ rbmk curl https://example.com/
-...
+rbmk curl https://example.com/
 
 # Combine dig and curl for step-by-step measurement
-$ IP=$(rbmk dig +short=ip example.com | rbmk head -n 1)
-$ rbmk curl --resolve example.com:443:$IP https://example.com/
+addr=$(rbmk dig +short=ip example.com | rbmk head -n 1)
+rbmk curl --resolve example.com:443:$addr https://example.com/
 
 # Collect measurement data in flat JSONL format
-$ rbmk dig --logs dns.jsonl example.com
-$ rbmk curl --logs http.jsonl https://example.com/
+rbmk dig --logs dns.jsonl example.com
+rbmk curl --logs http.jsonl https://example.com/
 ```
 
 For a quick introduction with more examples, run:
 
 ```sh
-$ rbmk intro
+rbmk intro
 ```
 
 For comprehensive usage documentation, run:
 
 ```sh
-$ rbmk tutorial
+rbmk tutorial
 ```
 
 ## Commands

pkg/cli/intro/README.md

@@ -14,7 +14,7 @@ these to perform step-by-step measurements.
 Get IP address for a domain
 
 ```
-$ rbmk dig +short=ip example.com
+$ rbmk dig +short=ip example.com | rbmk head -n1
 93.184.215.14
 ```
 
@@ -34,13 +34,24 @@ Fetch webpage using a specific IP address:
 $ rbmk curl --resolve example.com:443:93.184.215.14 https://example.com/
 ```
 
+Note that `rbmk curl` ignores the port passed to `--resolve` and uses
+the given address for all ports of the given domain.
+
 ### Combining Commands
 
 Separate DNS and HTTP measurements:
 
+```bash
+addr=$(rbmk dig +short=ip example.com | rbmk head -n1)
+rbmk curl --resolve example.com:443:$addr https://example.com/
 ```
-$ IP=$(rbmk dig +short=ip example.com | rbmk head -n1)
-$ rbmk curl --resolve example.com:443:$IP https://example.com/
+
+Or, to measure all the available IP addresses:
+
+```bash
+for addr in $(rbmk dig +short=ip example.com); do
+    rbmk curl --resolve example.com:443:$addr https://example.com/
+done
 ```
 
 ### Collecting Structured Logs
@@ -52,6 +63,8 @@ $ rbmk dig --logs dns.jsonl example.com
 $ rbmk curl --logs http.jsonl https://example.com/
 ```
 
+Use `--logs -` to emit the logs to the standard output.
+
 ## Benefits
 
 This modular approach helps isolate different aspects of network measurements

pkg/cli/tutorial/basics.md

@@ -68,14 +68,24 @@ Same as above, but also checking for TLS reachability:
 $ rbmk nc --alpn h2 --alpn http/1.1 -zvc example.com 443
 ```
 
+Run `rbmk nc --help` for additional help.
+
 
 ## Combining Commands
 
 Commands can be combined to perform detailed measurements:
 
+```bash
+addr=$(rbmk dig +short=ip example.com | rbmk head -n1)
+rbmk curl --resolve "example.com:443:$addr" https://example.com/
 ```
-$ ip=$(rbmk dig +short=ip example.com | rbmk head -n1)
-$ rbmk curl --resolve "example.com:443:$ip" https://example.com/
+
+And:
+
+```bash
+for addr in $(rbmk dig +short=ip example.com); do
+    rbmk curl --resolve example.com:443:$addr https://example.com/
+done
 ```
 
 Combining measurements allows to isolate network operations and
@@ -89,9 +99,12 @@ addresses for a domain name are reachable and working as intended.
 
 Use `--logs` to collect detailed measurement data:
 
-```
-$ rbmk dig --logs dns.jsonl example.com
-$ rbmk curl --logs http.jsonl https://example.com/
+```sh
+# Saves structured logs to the dns.jsonl file
+rbmk dig --logs dns.jsonl example.com
+
+# Saves structured logs to the http.jsonl file
+rbmk curl --logs http.jsonl https://example.com/
 ```
 
 The measurement data consists of a sequence of lines in JSON format
@@ -113,4 +126,4 @@ Using `--logs -` causes the command to emit logs to the standard output.
 
 - Run `rbmk curl --logs - https://example.com/ | jq` to see the structured logs.
 
-- Use `rbmk COMMAND --help` for detailed command documentation.
+- Use `rbmk COMMAND --help` for detailed documentation on a `COMMAND`.