doc: document when each command appeared (#53)

While there, tweak the documentation here and there, add clarifications
and examples.

internal/rootcmd/README.md

@@ -35,9 +35,21 @@ to facilitate network exploration and measurements.
 
 * `intro` - Shows a brief introduction with usage examples.
 * `tutorial` - Provides comprehensive usage documentation.
+* `version` - Prints the version of the `rbmk` utility to the stdout.
 
 ## Getting Started
 
 New to RBMK? Try `rbmk intro` to get started!
 
 Run `rbmk COMMAND --help` for more information about `COMMAND`.
+
+## License
+
+```
+SPDX-License-Identifier: GPL-3.0-or-later
+```
+
+## Reporting Bugs
+
+Please, use the [rbmk-project/issues](https://github.com/rbmk-project/issues)
+repository to report bugs or suggest improvements.

pkg/cli/cat/README.md

@@ -16,8 +16,14 @@ Concatenate files and print on the standard output.
 The following invocation concatenates the content of the
 `file1.txt` and `file2.txt` files to the stdout:
 
-    $ rbmk cat file.txt
+```
+$ rbmk cat file1.txt file2.txt
+```
 
 ## Exit Status
 
 This command exits with `0` on success and `1` on failure.
+
+## History
+
+The `rbmk cat` command was introduced in RBMK v0.2.0.

pkg/cli/curl/README.md

@@ -20,10 +20,10 @@ Print this help message.
 
 ### `--logs FILE`
 
-Writes structured logs to the given FILE. If FILE already exists, we
-append to it. If FILE does not exist, we create it. If FILE is a single
+Writes structured logs to the given `FILE`. If `FILE` already exists, we
+append to it. If `FILE` does not exist, we create it. If `FILE` is a single
 dash (`-`), we write to the stdout. If you specify `--logs` multiple
-times, we write to the last FILE specified.
+times, we write to the last `FILE` specified.
 
 ### `--max-time DURATION`
 
@@ -41,46 +41,56 @@ continuing due to this flag.
 
 ### `-o, --output FILE`
 
-Write the response body to FILE instead of using the stdout.
+Write the response body to `FILE` instead of using the stdout.
 
 ### `--resolve HOST:PORT:ADDR`
 
-Use ADDR instead of DNS resolution for HOST:PORT.
+Use `ADDR` instead of DNS resolution for `HOST:PORT`.
 
-Implementation note: we ignore the port and replace the HOST with
-ADDR for every port number. Additionally, when using this flag, the
-DNS lookup fails with "no such host" if the URL host is not HOST.
+Implementation note: we ignore the `PORT` and replace the `HOST` with
+`ADDR` for every port number. Additionally, when using this flag, the
+DNS lookup fails with "no such host" if the URL host is not `HOST`.
 
 ### `-v, --verbose`
 
 Make the operation more talkative.
 
 ### `-X, --request METHOD`
 
-Use the given request METHOD instead of GET.
+Use the given request `METHOD` instead of GET.
 
 ## Examples
 
 The following invocation prints the response body
 of the `https://example.com/` website URL:
 
-    $ rbmk curl https://example.com/
+```
+$ rbmk curl https://example.com/
+```
 
 To also print request and response headers, use `-v`:
 
-    $ rbmk curl -v https://example.com/
+```
+$ rbmk curl -v https://example.com/
+```
 
 To save structured logs to `logfile.jsonl` use `--logs`:
 
-    $ rbmk curl --logs logfile.jsonl https://example.com/
+```
+$ rbmk curl --logs logfile.jsonl https://example.com/
+```
 
 To save the response body to `output.txt` use `-o`:
 
-    $ rbmk curl -o output.txt https://example.com/
+```
+$ rbmk curl -o output.txt https://example.com/
+```
 
 To use a previously resolved IP address, use `--resolve`:
 
-    $ rbmk curl --resolve example.com:443:93.184.215.14 https://example.com/
+```
+$ rbmk curl --resolve example.com:443:93.184.215.14 https://example.com/
+```
 
 ## Exit Status
 
@@ -91,3 +101,7 @@ Returns `0` on success. Returns `1` on:
 - File operation errors (cannot open/close files).
 
 - Measurement failures (unless `--measure` is specified).
+
+## History
+
+The `rbmk curl` command was introduced in RBMK v0.1.0.

pkg/cli/dig/README.md

@@ -61,10 +61,10 @@ Print this help message.
 
 ### `--logs FILE`
 
-Writes structured logs to the given FILE. If FILE already exists, we
-append to it. If FILE does not exist, we create it. If FILE is a single
+Writes structured logs to the given `FILE`. If `FILE` already exists, we
+append to it. If `FILE` does not exist, we create it. If `FILE` is a single
 dash (`-`), we write to the stdout. If you specify `--logs` multiple
-times, we write to the last FILE specified.
+times, we write to the last `FILE` specified.
 
 ### `--measure`
 
@@ -179,3 +179,7 @@ Returns `0` on success. Returns `1` on:
 - File operation errors (cannot open/close files).
 
 - Measurement failures (unless `--measure` is specified).
+
+## History
+
+The `rbmk dig` command was introduced in RBMK v0.1.0.

pkg/cli/intro/README.md

@@ -64,3 +64,7 @@ and makes it easier to understand where issues occur.
 * Run `rbmk curl --help` for detailed HTTP measurement options
 
 * Try `rbmk tutorial` for a comprehensive guide
+
+## History
+
+The `rbmk intro` command was introduced in RBMK v0.1.0.

pkg/cli/ipuniq/README.md

@@ -53,11 +53,11 @@ Print this help message.
 
 ### `-p, --port PORT`
 
-Format output as HOST:PORT endpoints, adding [] brackets for IPv6
+Format output as `ADDRESS:PORT` endpoints, adding [] brackets for IPv6
 addresses as needed. This flag can be specified multiple times
 to generate endpoints for multiple ports (e.g., `-p 80 -p 443 -p 22`
 generates HTTP, HTTPS, and SSH endpoints). When no ports are
-specified, we output IP addresses without ports. Each PORT must
+specified, we output IP addresses without ports. Each `PORT` must
 be a valid port number (0-65535).
 
 ### `-r, --random`
@@ -138,3 +138,5 @@ This command exits with `0` on success and `1` on failure.
 
 Before RBMK v0.4.0, this command always randomly shuffled the
 addresses. Afterwards, one must use `--random` explicitly.
+
+This command was introduced in RBMK v0.2.0.

pkg/cli/mkdir/README.md

@@ -7,7 +7,7 @@
 rbmk mkdir [-p] DIRECTORY...
 ```
 
-Create the DIRECTORY(ies), if they do not already exist. We use the
+Create the `DIRECTORY`(ies), if they do not already exist. We use the
 `0755` file mode to create new directories.
 
 ## Flags
@@ -37,3 +37,7 @@ $ rbmk mkdir -p a/long/path/of/dirs
 ## Exit Status
 
 This command exits with `0` on success and `1` on failure.
+
+## History
+
+The `rbmk mkdir` command was introduced in RBMK v0.2.0.

pkg/cli/mv/README.md

@@ -8,8 +8,8 @@ rbmk mv [-f] SOURCE... DESTINATION
 
 ## Description
 
-Move (rename) SOURCE to DESTINATION. When moving multiple SOURCE files,
-the DESTINATION must be an existing directory.
+Move (rename) `SOURCE` to `DESTINATION`. When moving multiple `SOURCE` files,
+the `DESTINATION` must be an existing directory.
 
 ## Flags
 
@@ -34,3 +34,7 @@ $ rbmk mv file1.txt file2.txt target_directory/
 ## Exit Status
 
 This command exits with `0` on success and `1` on failure.
+
+## History
+
+The `rbmk mv` command was introduced in RBMK v0.3.0.

pkg/cli/nc/README.md

@@ -24,7 +24,9 @@ it is recommended to specify an IP address directly.
 Specify ALPN protocol(s) for TLS connections. Can be specified
 multiple times to support protocol negotiation. For example:
 
-    --alpn h2 --alpn http/1.1
+```
+--alpn h2 --alpn http/1.1
+```
 
 Must be used alongside the `--tls` flag.
 
@@ -38,10 +40,10 @@ Print this help message.
 
 ### `--logs FILE`
 
-Writes structured logs to the given FILE. If FILE already exists, we
-append to it. If FILE does not exist, we create it. If FILE is a single
+Writes structured logs to the given `FILE`. If `FILE` already exists, we
+append to it. If `FILE` does not exist, we create it. If `FILE` is a single
 dash (`-`), we write to the stdout. If you specify `--logs` multiple
-times, we write to the last FILE specified.
+times, we write to the last `FILE` specified.
 
 ### `--measure`
 
@@ -56,7 +58,9 @@ continuing due to this flag.
 Specify the server name for the SNI extension in the TLS
 handshake. For example:
 
-    --sni www.example.com
+```
+--sni www.example.com
+```
 
 Must be used alongside the `--tls` flag.
 
@@ -110,3 +114,7 @@ $ rbmk nc --logs conn.jsonl example.com 80
 ## Exit Status
 
 The nc utility exits with `0` on success and `1` on error.
+
+## History
+
+The `rbmk nc` command was introduced in RBMK v0.6.0.

pkg/cli/pipe/README.md

@@ -11,7 +11,7 @@ rbmk pipe COMMAND [args...]
 
 Create and use named pipes for inter-process communication within
 measurement scripts. Uses Unix domain sockets on both Unix systems
-and modern Windows (10.0.17063+).
+and modern Windows systems (10.0.17063+).
 
 ## Commands
 
@@ -69,3 +69,7 @@ Returns `0` on success. Returns `1` on:
 - Connection timeouts
 
 - I/O errors
+
+## History
+
+The `rbmk pipe` command was introduced in RBMK v0.4.0.

pkg/cli/pipe/read.md

@@ -9,9 +9,9 @@ rbmk pipe read --writers N PIPE
 
 ## Description
 
-Read from a named pipe in the current directory. Accepts exactly N writers
+Read from a named pipe in the current directory. Accepts exactly `N` writers
 and multiplexes their output to stdout line by line. The command terminates
-after all N writers have disconnected. If `N` is not specified
+after all `N` writers have disconnected. If `N` is not specified
 or is zero, this command will `exit 1` and print an error.
 
 Each line from each writer is written atomically to stdout to prevent garbled
@@ -43,15 +43,15 @@ done
 
 ## Notes
 
-- Blocks until exactly N writers have connected and completed
+- Blocks until exactly `N` writers have connected and completed
 
 - Each writer's output is handled line by line
 
 - Lines from different writers may be interleaved
 
 - Writers may disconnect early
 
-- No new connections are accepted after N writers
+- No new connections are accepted after `N` writers
 
 ## Exit Status
 
@@ -62,3 +62,7 @@ Returns `0` on success. Returns `1` on:
 - Connection errors
 
 - I/O errors
+
+## History
+
+The `rbmk pipe read` command was introduced in RBMK v0.4.0.

pkg/cli/pipe/write.md

@@ -37,3 +37,7 @@ Returns `0` on success. Returns `1` on:
 - Connection timeout
 
 - I/O errors
+
+## History
+
+The `rbmk pipe write` command was introduced in RBMK v0.4.0.

pkg/cli/rm/README.md

@@ -42,3 +42,7 @@ $ rbmk rm -rf directory
 ## Exit Status
 
 This command exits with `0` on success and `1` on failure.
+
+## History
+
+The `rbmk rm` command was introduced in RBMK v0.2.0.

pkg/cli/sh/README.md

@@ -96,4 +96,4 @@ Since v0.7.0. `rbmk` is an internal shell command, `rbmk sh` is not capable
 of executing external commands, and `$RBMK_EXE` is set to `rbmk`, thus
 supporting previously existing scripts without modification.
 
-The `rbmk sh` command appeared in RBMK v0.2.0.
+The `rbmk sh` command was introduced in RBMK v0.2.0.

pkg/cli/stun/README.md

@@ -9,14 +9,14 @@ rbmk stun [flags] ENDPOINT
 
 ## Description
 
-Send a STUN Binding Request to the given ENDPOINT and print the reflexive
+Send a STUN Binding Request to the given `ENDPOINT` and print the reflexive
 transport address (public IP address and port) to standard output.
 
 ## Arguments
 
 ### `ENDPOINT`
 
-The ENDPOINT argument should be in the form HOST:PORT. For example:
+The ENDPOINT argument should be in the form `HOST:PORT`. For example:
 
 - `stun.l.google.com:19302`
 
@@ -35,8 +35,8 @@ Print this help message.
 
 ### `--logs FILE`
 
-Writes structured logs to the given FILE. If FILE already exists, we
-append to it. If FILE does not exist, we create it. If FILE is a single
+Writes structured logs to the given `FILE`. If `FILE` already exists, we
+append to it. If `FILE` does not exist, we create it. If `FILE` is a single
 dash (`-`), we write to the stdout.
 
 ### `--max-time DURATION`
@@ -77,3 +77,7 @@ Returns `0` on success. Returns `1` on:
 - File operation errors (cannot open/close files).
 
 - Measurement failures (unless `--measure` is specified).
+
+## History
+
+The `rbmk stun` command was introduced in RBMK v0.3.0.

pkg/cli/tar/README.md

@@ -9,7 +9,7 @@ rbmk tar -czf ARCHIVE FILE|DIR...
 
 ## Description
 
-Create a tar ARCHIVE containing the specified FILEs and DIRs. We
+Create a tar `ARCHIVE` containing the specified `FILE`s and `DIR`s. We
 only support archiving regular files and directories.
 
 ## Flags
@@ -20,7 +20,7 @@ Create a new archive.
 
 ### `-f, --file NAME`
 
-Set the archive file name.
+Set the archive file name and path.
 
 ### `-h, --help`
 
@@ -42,3 +42,7 @@ $ rbmk tar -czf results.tar.gz ./measurements
 ## Exit Status
 
 This command exits with `0` on success and `1` on failure.
+
+## History
+
+The `rbmk tar` command was introduced in RBMK v0.2.0.