docs(help): rewrite every command's help text in STE100 - #190
Merged
Merged
Conversation
Plan for finishing #165: rewrite every command's help text in STE100, one commit per command, with quality gates, then a code review.
The configuration precedence becomes a table of setting, flag, and variable. Every generated page changes, since each one lists the root's persistent flags.
PAGE now says a page_id can come from a pages: entry too, which pageref has accepted since #139.
The NAME column no longer says a published image is stored under its encoded source path; since _plans/029 the name is the base name. PAGE now mentions a pages: entry.
PAGE now mentions a pages: entry. The --name flag's usage says what the name becomes.
The list of what check reports gains the empty title and the project file, which it already checked. The page_status note no longer says a space decides the statuses; Confluence decides per page and per account (#168).
PAGE now mentions a pages: entry.
Two corrections: --space and a frontmatter space: that disagree are refused, not resolved by precedence (resolveSpace); and preflight converts every file before reserve (#127), so stubs are reserved before any file is published, not before any is converted.
The patch labels are relative to the root only when a markfluence.yaml exists; otherwise they are the path as typed (reportPath). The note on lossy round trips no longer cites the L5 and L6 statuses, which plan 048 removes.
Adds two things export already did and the help never said: it writes a markfluence.yaml into --dest for a multi-page export, and it suffixes colliding sibling slugs with -<id>. --file says it cannot be used with --depth. PAGE now mentions a pages: entry.
Adds a pointer to search for a text search, which a reader who expects a substring match needs.
The two status fields become a small table. PAGE now mentions a pages: entry.
What happens to editor-authored content becomes a two-item list. PAGE now mentions a pages: entry.
Prose only.
Keeps the words TestHelpMentionsWhatSearchCannotFind needs: Archived, folders, and find.
The two sources of page statuses become a list.
Three corrections: Confluence decides the permitted statuses per page and per account, not per space (#168); the command that lists them is page-info, not info; and both local checks need a markfluence.yaml, since there is no action log without one. Also says an absent title keeps the live one.
Prose only.
Drops the note about reimplementing Confluence's permission rules; the request count carries the point.
Checked against the code: - user-info: the rewrite broke the sentence after its list - --debug prints retry decisions, not each request (client.send logs only a failure that was eligible for a retry) - --json: a fatal error goes to stderr as an error object, not stdout - create: an interrupted run leaves ids written back only without --no-persist - update: the body skip and --dry-run also cover page status, and a status change still bumps the version - diff: with --json, stdout is one JSON document, not a patch - export: PAGE can be a folder id; rewrap a line past 80 columns - attachment-download: a recorded path comes from any published or uploaded file, and a missing one means a manual upload or an older publish, matching attachment-list - search: --cql refuses --type only when you set it; --space says an unknown key is an error, as find's does - user-find: a shorter Short, so its row fits the root command list; every --dry-run usage now names its own command
Markdown is a proper noun. Capitalized in Go comments, the documentation (CLAUDE.md, README, SECURITY.md, docs/, docs/confluence/), and the user-facing strings: the root command's Short, pageref's error, the schema's descriptions, the goreleaser cask description, and the bug report template's label. Left lowercase where it is a literal token: --format markdown and the schema's format enum, the output-is-valid-markdown label, YAML keys in the issue template, and filenames. Test fixtures, _plans/, and the generated Casks/ are unchanged; docs/commands/ is regenerated.
This fixes the warning about not setting this if you're using a personal token. It's fine either way.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #165.
An ASD-STE100 (Simplified Technical English) pass over the help text of every command:
Short,Long,Example, and every flag's usage string. #187 did the README, CONTRIBUTING, anddocs/, so this finishes the prose pass #165 asked for.The plan is
_plans/049_help-text-ste100.md, the first commit here. Each command has its own commit, in this order: the root command, which regenerates every page indocs/commands/because each page lists the root's flags, then the 17 subcommands alphabetically. Each commit passed these gates:TestSubcommandsDocumentThemselvesandTestHelpMentionsWhatSearchCannotFindpass.make checkpasses, withdocs/commands/regenerated.Corrections that came out of the review for users, beyond the rewording:
create: a--spacethat disagrees with the frontmatter is refused, not resolved by precedence. Preflight converts every file before reserve (create: a document defect can leave a stub page behind #127).update: Confluence decides the permitted statuses per page and per account, not per space (Add a page_status frontmatter field for the lozenge next to the page title #168). The command that lists them ispage-info, notinfo. Both local checks need amarkfluence.yaml, since there is no action log without one.attachment-list: a published image is stored under its base name, not an encoded path.check: it also reports an emptytitleand an unloadablemarkfluence.yaml. Thepage_statusnote matches Add a page_status frontmatter field for the lozenge next to the page title #168.diff: patch labels are relative to the root only when amarkfluence.yamlexists.export: it says that a multi-page export writes amarkfluence.yaml, and that colliding sibling slugs get-<id>.PAGEargument now says apage_idcan come from apages:entry.The last commit fixes what a code review of the whole branch found: a broken sentence in
user-info,--debugand--jsonpromising more than they do,update's dry-run leaving out page status,diffunder--json, and consistency between commands.