feat: add "Using the playground" section + Reference skeleton
Restructure the docs into five top-level sections, splitting the application you drive from the database language you build with. - New "Using the playground" section: command-line options; the assistive editor (completion, highlighting, [ERR]/[WRN] indicator, hints, in-line editing); the output pane (scrolling); projects (save/load/new/rebuild); undo/redo & history; export & import; clipboard; getting help. Grounded in the in-app help/usage and ADR-0003/0022/0027. - Reference: seed the remaining topic pages (Columns, Relationships, Indexes, Constraints, Inserting & editing data, Querying & inspecting) with real syntax synopses; worked examples to follow. - Surface the assistive editor on the landing page and in Getting started; restore cross-links now that targets exist. Plan + STYLE updated to the five-section structure. 24 pages, build green, links resolve, content clean; planned features carry "planned" callouts.
This commit is contained in:
claude@clouddev1
@@ -0,0 +1,44 @@
|
||||
---
|
||||
title: Command-line options
|
||||
description: How to start the playground, open a project, and the flags you can pass.
|
||||
sidebar:
|
||||
order: 1
|
||||
---
|
||||
|
||||
Start the playground with no arguments and it opens a fresh, automatically
|
||||
named temporary project so you can begin straight away:
|
||||
|
||||
```sh
|
||||
rdbms-playground
|
||||
```
|
||||
|
||||
To open an existing project, give its path:
|
||||
|
||||
```sh
|
||||
rdbms-playground path/to/project
|
||||
```
|
||||
|
||||
## Options
|
||||
|
||||
| Option | Effect |
|
||||
|---|---|
|
||||
| `--resume` | Reopen the most recently used project. Errors if there is none; cannot be combined with a project path. |
|
||||
| `--data-dir <PATH>` | Use `PATH` as the data root instead of the OS-standard location for this run. |
|
||||
| `--mode <simple\|advanced>` | Start in this input mode, overriding the project's stored mode (precedence: `--mode` > stored > simple). |
|
||||
| `--theme <light\|dark>` | Force a theme instead of auto-detecting from the terminal. |
|
||||
| `--no-undo` | Disable the undo machinery for this run — no snapshot is taken before each change (see [Undo, redo & history](/using-the-playground/undo-and-history/)). |
|
||||
| `--log-file <PATH>` | Write diagnostic logging to `PATH`. |
|
||||
| `-h`, `--help` | Print the usage banner and exit. |
|
||||
|
||||
## Examples
|
||||
|
||||
```sh
|
||||
# Reopen wherever you left off, in advanced mode
|
||||
rdbms-playground --resume --mode advanced
|
||||
|
||||
# Keep a course's projects in one folder
|
||||
rdbms-playground --data-dir ~/db-course
|
||||
```
|
||||
|
||||
Where projects are stored, and what a project contains, is covered in
|
||||
[Projects and storage](/concepts/projects-and-storage/).
|
||||
@@ -0,0 +1,22 @@
|
||||
---
|
||||
title: Copy to clipboard
|
||||
description: Copy the output panel to your system clipboard.
|
||||
sidebar:
|
||||
order: 7
|
||||
---
|
||||
|
||||
Copy what's in the output pane to your system clipboard — handy for pasting a
|
||||
result or an error into a question or a note.
|
||||
|
||||
```rdbms
|
||||
copy
|
||||
```
|
||||
Copy the whole output pane. (`copy all` does the same.)
|
||||
|
||||
```rdbms
|
||||
copy last
|
||||
```
|
||||
Copy just the most recent command's output.
|
||||
|
||||
The text is copied exactly as shown in the pane. Copying works over SSH as
|
||||
well as locally.
|
||||
@@ -0,0 +1,42 @@
|
||||
---
|
||||
title: Export & import
|
||||
description: Package a project to share it, and unpack one you've received.
|
||||
sidebar:
|
||||
order: 6
|
||||
---
|
||||
|
||||
## Export
|
||||
|
||||
```rdbms
|
||||
export
|
||||
```
|
||||
|
||||
Packages the project as a single zip. The zip contains the readable files
|
||||
(`project.yaml` and `data/`) but **not** the working database (the recipient
|
||||
rebuilds it on open) or your private `history.log`. Pass a path to choose
|
||||
where it goes:
|
||||
|
||||
```rdbms
|
||||
export path/to/exercise.zip
|
||||
```
|
||||
|
||||
## Import
|
||||
|
||||
```rdbms
|
||||
import path/to/exercise.zip
|
||||
```
|
||||
|
||||
Unpacks a zip into a new project and switches to it; the database is rebuilt
|
||||
from the readable files. Add `as <name>` to choose the target name:
|
||||
|
||||
```rdbms
|
||||
import path/to/exercise.zip as my-copy
|
||||
```
|
||||
|
||||
## Sharing recipes
|
||||
|
||||
Because a project is plain text plus CSV, sharing it is easy:
|
||||
|
||||
- **Git** — each project includes a `.gitignore` that excludes the working
|
||||
database, so a project commits cleanly and diffs sensibly.
|
||||
- **Email / file transfer** — send the exported zip; the recipient imports it.
|
||||
@@ -0,0 +1,33 @@
|
||||
---
|
||||
title: Getting help
|
||||
description: Built-in help — a command list, per-command detail, and the type reference.
|
||||
sidebar:
|
||||
order: 8
|
||||
---
|
||||
|
||||
The playground has help built in, so you rarely need to leave it.
|
||||
|
||||
```rdbms
|
||||
help
|
||||
```
|
||||
Lists the supported commands, with the grammar reference and the type list.
|
||||
|
||||
```rdbms
|
||||
help insert
|
||||
```
|
||||
`help <command>` shows detail for one command (every command sharing that
|
||||
entry word). Try `help create`, `help add`, `help show`, and so on.
|
||||
|
||||
```rdbms
|
||||
help types
|
||||
```
|
||||
Shows the type reference on its own.
|
||||
|
||||
Outside the app, run `rdbms-playground --help` for the
|
||||
[command-line options](/using-the-playground/command-line-options/).
|
||||
|
||||
:::note[Planned]
|
||||
A `hint` command for contextual help on the current input or the last error
|
||||
is planned and not yet available — but the input already shows hints as you
|
||||
type (see [The assistive editor](/using-the-playground/the-assistive-editor/)).
|
||||
:::
|
||||
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: Projects — save, load, new, rebuild
|
||||
description: The app-level commands for managing projects.
|
||||
sidebar:
|
||||
order: 4
|
||||
---
|
||||
|
||||
A project is where your work lives. The playground saves it continuously as
|
||||
you go (see [Projects and storage](/concepts/projects-and-storage/) for the
|
||||
model), so these commands are about *switching* and *managing* projects, not
|
||||
a manual "save your changes" step.
|
||||
|
||||
```rdbms
|
||||
save
|
||||
```
|
||||
Give the current temporary project a permanent name. (On a project that is
|
||||
already named, `save` reports that it is already auto-saved — use `save as`.)
|
||||
|
||||
```rdbms
|
||||
save as
|
||||
```
|
||||
Copy the current project to a new name or location and switch to it.
|
||||
|
||||
```rdbms
|
||||
new
|
||||
```
|
||||
Close the current project and start a fresh temporary one.
|
||||
|
||||
```rdbms
|
||||
load
|
||||
```
|
||||
Open the project picker — a list of your projects, newest first, with
|
||||
`[TEMP]` markers; you can also browse to a path.
|
||||
|
||||
```rdbms
|
||||
rebuild
|
||||
```
|
||||
Rebuild the working database from the readable files (`project.yaml` +
|
||||
`data/`), after a confirmation. Useful if the database is ever missing or out
|
||||
of date.
|
||||
@@ -0,0 +1,54 @@
|
||||
---
|
||||
title: The assistive editor
|
||||
description: The input field helps as you type — completion, highlighting, a validity indicator, and hints.
|
||||
sidebar:
|
||||
order: 2
|
||||
---
|
||||
|
||||
You type commands into the input field at the bottom of the screen, and it
|
||||
helps you as you go. None of this gets in your way — it is all advisory.
|
||||
|
||||
## Completion
|
||||
|
||||
Press <kbd>Tab</kbd> to complete what you are typing. Completion knows about
|
||||
the commands, the keywords for the current position, your **table, column,
|
||||
index, and relationship names**, and — in advanced mode — common SQL
|
||||
function names. It is the fastest way to discover what is available without
|
||||
leaving the keyboard.
|
||||
|
||||
## Syntax highlighting
|
||||
|
||||
As you type, the input is coloured live: keywords, identifiers, column
|
||||
**types**, and SQL function names each get their own colour, so a command's
|
||||
shape is visible before you run it.
|
||||
|
||||
## The validity indicator
|
||||
|
||||
A small marker appears at the right-hand edge of the input line and tells
|
||||
you, *before you submit*, whether the command would run:
|
||||
|
||||
- **`[ERR]`** — the command will fail as written (for example, an unknown
|
||||
table or column, or a value that doesn't match a column's type).
|
||||
- **`[WRN]`** — the command will run, but something looks suspect (for
|
||||
example, comparing a number column with a text pattern).
|
||||
|
||||
It is purely advisory — it never blocks you from submitting.
|
||||
|
||||
## Hints
|
||||
|
||||
A hint line below the input offers contextual guidance — the next token that
|
||||
would fit, the type expected at the current position, and help with the most
|
||||
recent error. When the input is empty it reminds you that <kbd>Tab</kbd>
|
||||
lists options and `help` lists commands.
|
||||
|
||||
## Editing the line
|
||||
|
||||
Move and edit within the line with the usual keys: <kbd>←</kbd>/<kbd>→</kbd>
|
||||
by character, <kbd>Home</kbd>/<kbd>End</kbd> to the ends, and
|
||||
<kbd>Delete</kbd>/<kbd>Backspace</kbd> to remove characters. Your
|
||||
project-scoped command history is available with <kbd>↑</kbd>/<kbd>↓</kbd>.
|
||||
|
||||
:::note[Planned]
|
||||
Multi-line entry and extra readline-style shortcuts (Ctrl-A/E/W/K/U) are
|
||||
planned and not yet available.
|
||||
:::
|
||||
@@ -0,0 +1,22 @@
|
||||
---
|
||||
title: The output pane
|
||||
description: Where results appear, and how to scroll back through them.
|
||||
sidebar:
|
||||
order: 3
|
||||
---
|
||||
|
||||
Results appear in the output pane: the structure of a table after you change
|
||||
it, the rows from `show data` and after writes (as aligned, box-drawn
|
||||
tables), query plans, and command outcomes marked with a ✓ or ✗.
|
||||
|
||||
## Scrolling
|
||||
|
||||
Use <kbd>PageUp</kbd> and <kbd>PageDown</kbd> to scroll back through earlier
|
||||
output. New output snaps the view back to the most recent entry, so you never
|
||||
lose your place when you run something.
|
||||
|
||||
:::note[Planned]
|
||||
A fuller session journal — a scrollable, richly rendered log of the whole
|
||||
session that you can save as Markdown — and multiple result tabs are planned
|
||||
and not yet available.
|
||||
:::
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
title: Undo, redo & history
|
||||
description: Step back from any change, and replay a recorded session.
|
||||
sidebar:
|
||||
order: 5
|
||||
---
|
||||
|
||||
Every change you make is safe to undo — the playground snapshots the whole
|
||||
project before each one.
|
||||
|
||||
## Undo and redo
|
||||
|
||||
```rdbms
|
||||
undo
|
||||
```
|
||||
|
||||
```rdbms
|
||||
redo
|
||||
```
|
||||
|
||||
Each asks you to confirm, naming the exact command being undone or
|
||||
re-applied. Redo is available until you make a new change. (How snapshots
|
||||
work is explained in [Concepts](/concepts/projects-and-storage/).)
|
||||
|
||||
Starting with `--no-undo` turns this off for the session — no snapshot is
|
||||
taken before each change, and `undo`/`redo` report that undo is off.
|
||||
|
||||
## History and replay
|
||||
|
||||
Every command you run is recorded, in order, in the project's `history.log`.
|
||||
You can re-run a saved sequence of commands from a file:
|
||||
|
||||
```rdbms
|
||||
replay path/to/commands
|
||||
```
|
||||
|
||||
Replay runs each non-blank, non-`#`-comment line, stopping at the first error
|
||||
(relative paths resolve under the project directory). It re-applies the
|
||||
schema- and data-changing commands and skips app-level ones.
|
||||
Reference in New Issue
Block a user