docs: Improve command formatting (#644)

why: Standardize shell code blocks to follow documentation guidelines
what:
- Use `console` language tag with `$ ` prefix for shell commands
- One command per code block for copyability
- Split long pipx install command with `\` line continuations
- Add Shell Command Formatting rules to AGENTS.md

Author: tony

AGENTS.md

@@ -436,7 +436,7 @@ EOF
 
 When writing documentation (README, CHANGES, docs/), follow these rules for code blocks:
 
-**One command per code block.** This makes commands individually copyable.
+**One command per code block.** This makes commands individually copyable. For sequential commands, either use separate code blocks or chain them with `&&` or `;` and `\` continuations (keeping it one logical command).
 
 **Put explanations outside the code block**, not as comments inside.
 
@@ -464,6 +464,42 @@ $ uv run pytest
 $ uv run pytest --cov
 ```
 
+### Shell Command Formatting
+
+These rules apply to shell commands in documentation (README, CHANGES, docs/), **not** to Python doctests.
+
+**Use `console` language tag with `$ ` prefix.** This distinguishes interactive commands from scripts and enables prompt-aware copy in many terminals.
+
+Good:
+
+```console
+$ uv run pytest
+```
+
+Bad:
+
+```bash
+uv run pytest
+```
+
+**Split long commands with `\` for readability.** Each flag or flag+value pair gets its own continuation line, indented. Positional parameters go on the final line.
+
+Good:
+
+```console
+$ pipx install \
+    --suffix=@next \
+    --pip-args '\--pre' \
+    --force \
+    'libtmux'
+```
+
+Bad:
+
+```console
+$ pipx install --suffix=@next --pip-args '\--pre' --force 'libtmux'
+```
+
 ## Debugging Tips
 
 When stuck in debugging loops:

CHANGES

@@ -12,7 +12,11 @@ $ pip install --user --upgrade --pre libtmux
 [pipx](https://pypa.github.io/pipx/docs/):
 
 ```console
-$ pipx install --suffix=@next 'libtmux' --pip-args '\--pre' --force
+$ pipx install \
+    --suffix=@next \
+    --pip-args '\--pre' \
+    --force \
+    'libtmux'
 // Usage: libtmux@next [command]
 ```
 

README.md

@@ -41,27 +41,30 @@ Maintenance-only backports (no new fixes):
 
 Stable release:
 
-```bash
-pip install libtmux
+```console
+$ pip install libtmux
 ```
 
 With pipx:
 
-```bash
-pipx install libtmux
+```console
+$ pipx install libtmux
 ```
 
 With uv / uvx:
 
-```bash
-uv add libtmux
-uvx --from "libtmux" python
+```console
+$ uv add libtmux
+```
+
+```console
+$ uvx --from "libtmux" python
 ```
 
 From the main branch (bleeding edge):
 
-```bash
-pip install 'git+https://github.com/tmux-python/libtmux.git'
+```console
+$ pip install 'git+https://github.com/tmux-python/libtmux.git'
 ```
 
 Tip: libtmux is pre-1.0. Pin a range in projects to avoid surprises:
@@ -94,6 +97,9 @@ Use [ptpython], [ipython], etc. for a nice REPL with autocompletions:
 
 ```console
 $ pip install --user ptpython
+```
+
+```console
 $ ptpython
 ```
 

docs/developing.md

@@ -73,8 +73,7 @@ $ make start
 ### Manual documentation (the hard way)
 
 ```console
-$ cd docs/
-$ make html
+$ cd docs/ && make html
 ```
 
 to build.
@@ -86,8 +85,16 @@ $ make serve
 to start http server.
 
 Helpers:
+
+Build docs:
+
 ```console
 $ make build_docs
+```
+
+Serve docs:
+
+```console
 $ make serve_docs
 ```
 
@@ -278,10 +285,19 @@ building, and publishing. Therefore there is no setup.py or requirements files.
 Update `__version__` in `__about__.py` and `pyproject.toml`:
 
 ```console
-git commit -m 'build(libtmux): Tag v0.1.1'
-git tag v0.1.1
-git push
-git push --tags
+$ git commit -m 'build(libtmux): Tag v0.1.1'
+```
+
+```console
+$ git tag v0.1.1
+```
+
+```console
+$ git push
+```
+
+```console
+$ git push --tags
 ```
 
 [twine]: https://twine.readthedocs.io/

docs/quickstart.md

@@ -44,10 +44,15 @@ the 4th beta release of `1.10.0` before general availability.
 - [pipx]\:
 
   ```console
-  $ pipx install --suffix=@next 'libtmux' --pip-args '\--pre' --force
-  // Usage: libtmux@next [command]
+  $ pipx install \
+      --suffix=@next \
+      --pip-args '\--pre' \
+      --force \
+      'libtmux'
   ```
 
+  Usage: `libtmux@next [command]`
+
 - [uv tool install][uv-tools]\:
 
   ```console
@@ -77,7 +82,10 @@ via trunk (can break easily):
 - [pipx]\:
 
   ```console
-  $ pipx install --suffix=@master 'libtmux @ git+https://github.com/tmux-python/libtmux.git@master' --force
+  $ pipx install \
+      --suffix=@master \
+      --force \
+      'libtmux @ git+https://github.com/tmux-python/libtmux.git@master'
   ```
 
 - [uv]\: