Plan formatting¶
Audience: people who use caret and want to know why it works as it does.
caret rewraps every plan to 90 columns before you see it, so every plan reads the same whichever agent host sent it. Line numbers on the review page count lines of that formatted plan; Call the review tool from your own skill covers what the agent receives.
Why some lines run wider¶
caret does not count a link's URL toward the 90 columns. Nothing can break inside a URL, so counting it would only chop up the words around it. A line that carries a link can therefore run wider than 90 columns and scroll sideways on the review page.
The formatter caret uses¶
caret formats plans with rumdl, its
plan formatter. You do not install rumdl
yourself: caret downloads its own copy, pinned to v0.3.4, into
$XDG_STATE_HOME/caret/rumdl/ (~/.local/state/caret/rumdl/ by default) and checks its
checksum. Formatting behaves the same however you installed caret.
Note
caret never uses a rumdl on your PATH, so which version rewraps your plans does not
depend on what your machine has installed.
How that plays out:
- caret keeps its copy at the pinned version. It replaces an older copy left by a previous caret, or a file that won't run.
caret installdownloads it ahead of time. Your first plan then does not wait for the download. If that fails, the install still succeeds with a warning, and a later plan retries.- After a failed download, caret waits ten minutes before retrying. Retrying on
every plan would download several megabytes while caret creates your review, and
likely fail again. Plans sent in those ten minutes are shown unformatted. Fix the
cause (your connection, a rate limit) and caret tries again on the first plan after
the ten minutes, or run
caret installto retry now. - Formatting never loses a plan. If a plan can't be formatted (no formatter, offline, a platform with no rumdl build such as Windows, or formatting took longer than two seconds), caret keeps it unchanged and logs one warning.
To use a rumdl of your own instead of the download, set CARET_RUMDL_BIN (see
Environment variables). caret uses it only when
it reports the pinned version; otherwise caret downloads its own copy as usual.