Document lake output format and add/update ls docs

cmd/zed/ls/command.go

@@ -19,9 +19,13 @@ var Cmd = &charm.Spec{
 	Usage: "ls [options] [pool]",
 	Short: "list pools in a lake or branches in a pool",
 	Long: `
-"zed ls" shows a listing of a data pool's data objects as IDs.
-If a pool name or pool ID is given, then the pool's branches are listed
-along with the ID of their commit object, which points at the tip of each branch.
+"zed ls" lists pools in a lake or branches in a pool.
+
+By default, all pools in the lake are listed along with each pool's unique ID
+and pool key configuration.
+
+If a pool name or pool ID is given, then the pool's branches are listed along
+with the ID of their commit object, which points at the tip of each branch.
 `,
 	New: New,
 }

docs/commands/zed.md

@@ -340,6 +340,11 @@ for that sub-command.
 * `zed command sub-command -h` displays help for a sub-command of a
 sub-command and so forth.
 
+By default, commands that display lake metadata (e.g., [`log`](#log) or
+[`ls`](#ls)) use the human-readable [lake metadata output](zq.md#zed-lake-metadata-output)
+format.  However, the `-f` option can be used to specify any supported
+[output format](zq.md#output-formats).
+
 ### Auth
 ```
 zed auth login|logout|method|verify
@@ -570,6 +575,18 @@ API for automation.
 
 > Note that the branchlog meta-query source is not yet implemented.
 
+### Ls
+```
+zed ls [options] [pool]
+```
+The `ls` command lists pools in a lake or branches in a pool.
+
+By default, all pools in the lake are listed along with each pool's unique ID
+and [pool key](#pool-key) configuration.
+
+If a pool name or pool ID is given, then the pool's branches are listed along
+with the ID of their commit object, which points at the tip of each branch.
+
 ### Manage
 ```
 zed manage [options]

docs/commands/zq.md

@@ -181,6 +181,7 @@ typically omit quotes around field names.
 | `arrows`  | [Arrow IPC Stream Format](https://arrow.apache.org/docs/format/Columnar.html#ipc-streaming-format) |
 | `csv`     | [CSV RFC 4180](https://www.rfc-editor.org/rfc/rfc4180.html) |
 | `json`    | [JSON RFC 8259](https://www.rfc-editor.org/rfc/rfc8259.html) |
+| `lake`    | [Zed Lake Metadata Output](#zed-lake-metadata-output) |
 | `parquet` | [Apache Parquet](https://github.com/apache/parquet-format) |
 | `table`   | (described [below](#simplified-text-outputs)) |
 | `text`    | (described [below](#simplified-text-outputs)) |
@@ -429,6 +430,46 @@ one   1     -
 hello -     greeting
 ```
 
+### Zed Lake Metadata Output
+
+The `lake` format is used to pretty-print lake metadata, such as in
+[Zed command](zed.md) outputs.  Because it's `zed`'s default output format,
+it's rare to request it explicitly via `-f`.  However, since it's possible for
+`zed` to [generate output in any supported format](zed.md#zed-commands),
+the `lake` format is useful to reverse this.
+
+For example, imagine you'd executed a [meta-query](zed.md#meta-queries) via
+`zed query -Z "from :pools"` and saved the output in this file `pools.zson`.
+
+```mdtest-input pools.zson
+{
+    ts: 2024-07-19T19:28:22.893089Z,
+    name: "MyPool",
+    id: 0x132870564f00de22d252b3438c656691c87842c2 (=ksuid.KSUID),
+    layout: {
+        order: "desc" (=order.Which),
+        keys: [
+            [
+                "ts"
+            ] (=field.Path)
+        ] (=field.List)
+    } (=order.SortKey),
+    seek_stride: 65536,
+    threshold: 524288000
+} (=pools.Config)
+```
+
+Using `zq -f lake`, this can be rendered in the same pretty-printed form as it
+would have originally appeared in the output of `zed ls`, e.g.,
+
+```mdtest-command
+zq -f lake pools.zson
+```
+produces
+```mdtest-output
+MyPool 2jTi7n3sfiU7qTgPTAE1nwTUJ0M key ts order desc
+```
+
 ## Query Debugging
 
 If you are ever stumped about how the `zq` compiler is parsing your query,