docs: shorten help and migration texts to gh-like brevity

Long texts no longer restate the flag list, the instance selection
of tea help environment, the config keys with descriptions or the
team argument rules shown under ARGUMENTS; webhook events come from
services.WebhookEvents; the migration guide refers to tea help
formatting for the terminal layout.

Signed-off-by: bircni <bircni@icloud.com>

docs/migration-1.0.md

@@ -295,29 +295,13 @@ names; `--jq` / `-q` filters the result and implies `--json`. Commands that
 produce no resource, such as deletes, reject `--json` with a usage error instead
 of printing nothing. See `tea help formatting`.
 
-Lists follow gh. On a terminal they print a "Showing 30 of 112 open issues in
+When stdout is not a terminal, lists print tab-separated values without header,
-alice/project" line, an uppercase header row and columns fitted to the terminal
+color or links, with times in RFC 3339 UTC, and a `--page` hint goes to stderr;
-width, with times relative ("about 3 hours ago"), states colored and the first
+prefer `--json` in scripts. Commands that change resources report each change on
-column linked to the web page (`tea config set hyperlinks never` turns the links
+stderr only on a terminal. Create commands print the URL of the new resource on
-off). An empty list prints a message on stderr and exits 0. When stdout is not a
+stdout, so `url=$(tea issue create …)` works; other changes print nothing when
-terminal, lists print tab-separated values without header, color or links, with
+piped. Bodies are rendered as Markdown only on a terminal (`tea config set
-times in RFC 3339 UTC and stable columns, so `cut -f1` works; a `--page` hint
+markdown raw` turns this off). See `tea help formatting` for the terminal layout.
-goes to stderr when more results follow. Still prefer `--json` in scripts: the
-columns may change. Tabs and line breaks in list cells become spaces, and
-control characters such as escape sequences are dropped from all human output,
-bodies included.
-
-Commands that change resources report each change on stderr, such as
-`✓ Closed issue alice/project#5 (Fix login)` or `! … is already closed`, only
-when stdout is a terminal. Create commands print the URL of the new resource
-on stdout, so `url=$(tea issue create …)` works; other changes print nothing
-when piped. With `--json` they print the changed resource instead.
-
-Issue, pull request, release and comment bodies are rendered as Markdown on a
-terminal and printed as written when piped; `tea config set markdown raw` always
-prints them as written. Long output on a terminal goes through a pager
-(`TEA_PAGER`, the `pager` preference or `PAGER`). Each command starts the pager
-at most once.
 
 ## Exit codes
 

internal/app/action_runs.go

@@ -28,10 +28,7 @@ func (a *application) runCommand() *cobra.Command {
 	group := &cobra.Command{
 		Use:   "run",
 		Short: "View and manage Actions workflow runs",
-		Long: `List, view and watch the runs of a repository's Actions workflows, read their logs, download
+		Long:  "Work with the runs of a repository's Actions workflows. Start a run with tea workflow run.",
-their artifacts, and cancel, rerun or delete them.
-
-Start a run with tea workflow run.`,
 	}
 	group.AddCommand(a.runListCommand(), a.runViewCommand(), a.runWatchCommand(), a.runCancelCommand(), a.runRerunCommand(), a.runDeleteCommand(),
 		a.runJobsCommand(), a.runLogsCommand(), a.runDownloadCommand(), a.artifactCommand())

internal/app/actions.go

@@ -27,9 +27,7 @@ func (a *application) workflowCommand() *cobra.Command {
 	group := &cobra.Command{
 		Use:   "workflow",
 		Short: "View, run, enable and disable Actions workflows",
-		Long: `View the Actions workflows of a repository, dispatch them, and enable or disable them.
+		Long:  "Work with the Actions workflows of a repository. Inspect their runs with tea run.",
-
-List and inspect the runs of workflows with tea run.`,
 	}
 	group.AddCommand(a.workflowListCommand(), a.workflowViewCommand(), a.workflowRunCommand(), a.workflowStateCommand(true), a.workflowStateCommand(false))
 	return group

internal/app/auth.go

@@ -103,7 +103,8 @@ func (a *application) authCommand() *cobra.Command {
 tea keeps the accounts of each instance in hosts.yml and their tokens in the system
 keyring, or in a private file when you choose so. One account per instance is active;
 --user or TEA_USER selects another for a single command. GITEA_TOKEN, together with
-GITEA_INSTANCE_URL or TEA_HOST, replaces the stored credentials of its instance.`}
+GITEA_INSTANCE_URL or TEA_HOST, replaces the stored credentials of its instance. See
+tea help environment for how commands select the instance.`}
 	group.AddCommand(a.loginCommand(), a.logoutCommand(), a.authStatusCommand(), a.authSwitchCommand(), a.authRefreshCommand(), a.authTokenCommand(), a.setupGitCommand(), a.gitCredentialCommand())
 	return group
 }
@@ -124,17 +125,8 @@ func (a *application) loginCommand() *cobra.Command {
 	login := &cobra.Command{
 		Use: "login", Short: "Log in to a Gitea instance", Args: argsExact(0),
 		Annotations: map[string]string{"tea.text": "login does not return a resource", "tea.confirm": "true"},
-		Long: `Log in to a Gitea instance.
+		Long: `Log in to a Gitea instance. On a terminal without a method flag, tea asks for the instance,
-
+how to log in, where to keep the token and whether git should use tea for the instance.
-On a terminal without a method flag, tea asks for the instance, how to log in, where to
-keep the token and whether git should use tea for the instance. Otherwise choose one
-method:
-
-  --with-token             read an access token from stdin, or ask for it on a terminal
-  --oauth, --web           authorize tea in a web browser
-  --ssh-key FILE           sign requests with an SSH private key
-  --ssh-agent-key FP       sign requests with the key of fingerprint FP in ssh-agent
-  --ssh-agent-principal P  sign requests with the ssh-agent certificate of principal P
 
 Create a token on the instance under Settings > Applications. Logging in to an account
 that tea already has replaces its stored credential after a confirmation (or with --yes).`,
@@ -427,11 +419,8 @@ func (a *application) authStatusCommand() *cobra.Command {
 	status := &cobra.Command{
 		Use: "status", Short: "Show the accounts tea can use", Args: argsExact(0),
 		Long: `Show the accounts tea can use on each instance, the active one, and how they
-authenticate. --verify asks each instance whether the credentials still work.
+authenticate. Fails with exit code 4 when there is no account, or when a credential is
-
+missing or rejected.`,
-A GITEA_TOKEN in the environment shows under its instance, where it replaces the stored
-accounts. tea auth status fails with exit code 4 when there is no account, or when a
-credential is missing or rejected.`,
 		Example: `$ tea auth status
 # Check the credentials against their instances
 $ tea auth status --verify
@@ -637,8 +626,7 @@ func (a *application) authSwitchCommand() *cobra.Command {
 		Annotations: textOutput("switching accounts does not return a resource"), ValidArgsFunction: a.completeAccounts,
 		Long: `Switch the active account of an instance, which commands use unless --user or TEA_USER
 selects another. With two accounts, tea auth switch toggles between them; with more, it
-asks which one on a terminal. The instance is the one of the current repository, else
+asks which one on a terminal.`,
---host, TEA_HOST, default_host or the only instance.`,
 		Example: "$ tea auth switch\n$ tea auth switch bob\n$ tea auth switch bob --host gitea.com",
 		RunE: func(cmd *cobra.Command, args []string) error {
 			t, err := a.instanceTarget(cmd.Context())
@@ -718,11 +706,7 @@ func (a *application) logoutCommand() *cobra.Command {
 		Annotations: map[string]string{"tea.text": "logout does not return a resource", "tea.confirm": "true"},
 		Long: `Log out of an account: tea forgets the account and deletes its stored credential. Git's
 other credential helpers are asked to forget what they stored for the account on the
-instance, such as a copy of its token that a keychain kept after a push.
+instance, such as a copy of its token that a keychain kept after a push.`,
-
-Without an account argument or --user, tea logs out of the active account of the
-current repository's instance, else of --host, TEA_HOST, default_host or the only
-instance.`,
 		Example: "$ tea auth logout\n$ tea auth logout bob --host gitea.com\n# Without confirmation\n$ tea auth logout alice --yes",
 		RunE: func(cmd *cobra.Command, args []string) error {
 			if len(args) == 1 {

internal/app/config.go

@@ -175,28 +175,12 @@ Preferences live in config.yml and instance settings in hosts.yml, in the config
 directory ($TEA_CONFIG_DIR, or tea under the XDG config directory); tea config path prints
 both files. Environment variables that override settings are listed in tea help environment.
 
-Preferences (tea config set <key> <value>):
+Preferences: default_host, git_protocol, editor, prompt (enabled or disabled), pager,
-  default_host  instance used when no --host, environment variable or repository selects one
+browser (never disables opening), color, hyperlinks and markdown (auto or raw), remote and
-  git_protocol  https or ssh, for clone and checkout remotes
+aliases (see tea alias).
-  editor        command that edits bodies
+Instance settings (--host <url>): user, ssh_host, insecure, git_protocol, oauth_client_id.
-  prompt        enabled or disabled
+Account settings (--host <url> --user <name>): ssh_key, ssh_agent,
-  pager         command that pages long output
+ssh_certificate_principal, ssh_key_fingerprint.`}
-  browser       command that opens web pages; never disables opening
-  color         auto, always or never
-  hyperlinks    auto, always or never: link the first column of lists to its web page
-  markdown      auto or raw: render markdown bodies on a terminal, or print them as written
-  remote        Git remote that selects the repository
-  aliases       command shortcuts; manage them with tea alias
-
-Instance settings (tea config set --host <url> <key> <value>):
-  user             active account; change it with tea auth switch
-  ssh_host         SSH host[:port] when it differs from the web host
-  insecure         true skips TLS certificate verification
-  git_protocol     https or ssh, overriding the preference for this instance
-  oauth_client_id  OAuth application used by tea auth login --oauth
-
-Account settings (tea config set --host <url> --user <name> <key> <value>):
-  ssh_key, ssh_agent, ssh_certificate_principal, ssh_key_fingerprint`}
 	group.AddCommand(&cobra.Command{
 		Use: "path", Short: "Print the paths of the settings files", Args: argsExact(0),
 		Annotations: map[string]string{"tea.text": "config path prints text", "tea.offline": "true"},

internal/app/notifications.go

@@ -26,11 +26,8 @@ type notificationScope struct {
 }
 
 func (a *application) notificationCommand() *cobra.Command {
-	group := &cobra.Command{Use: "notification", Short: "Read and triage your notifications", Long: `Read and triage the notifications of your account.
+	group := &cobra.Command{Use: "notification", Short: "Read and triage your notifications", Long: `Read and triage the notifications of your account, across your whole inbox unless -R or
-
+--this-repo selects a repository. IDs identify notification threads, not issue numbers.`}
-Commands act on your whole inbox. -R OWNER/REPO limits them to one repository, and
---this-repo to the repository of the current directory. The IDs that tea notification
-list shows identify notification threads; they are not issue numbers.`}
 	var mine, thisRepo bool
 	group.PersistentFlags().BoolVar(&mine, "mine", false, "Read your whole inbox (the default)")
 	_ = group.PersistentFlags().MarkHidden("mine")

internal/app/pull_review.go

@@ -146,12 +146,7 @@ $ tea pr review 13
 
 # Start a pending review with inline comments, then submit it
 $ tea pr review 13 --pending --comments-file inline.json
-$ tea pr review submit 13 --approve
+$ tea pr review submit 13 --approve`
-
-# See who reviewed, then reply to and resolve an inline comment
-$ tea pr review list 13
-$ tea pr review reply 13 36 -b "Done"
-$ tea pr review resolve 36`
 
 func (a *application) pullReviewCommand() *cobra.Command {
 	review := a.reviewCreateCommand("review [<number> | <url> | <branch>]", "Review a pull request or manage its reviews")

internal/app/teams.go

@@ -91,9 +91,7 @@ func (a *application) completeTeamThen(next func(ctx context.Context, t target,
 
 func (a *application) teamCommand() *cobra.Command {
 	group := &cobra.Command{Use: "team", Short: "Manage organization teams and access", Long: `Manage the teams of an organization: what they may do in its repositories, who belongs to
-them, and which repositories they can reach.
+them, and which repositories they can reach.`}
-
-` + teamArguments}
 	group.AddCommand(a.teamListCommand(), a.teamViewCommand(), a.teamCreateCommand(), a.teamEditCommand(), a.teamDeleteCommand(), a.teamMemberCommand(), a.teamRepoCommand())
 	return group
 }
@@ -485,9 +483,7 @@ func joinNames(names []string) string {
 
 func (a *application) teamMemberCommand() *cobra.Command {
 	group := &cobra.Command{Use: "member", Short: "Manage team members", Long: `List, add and remove the members of a team. Adding a user to a team of an organization
-also makes them a member of the organization.
+also makes them a member of the organization.`}
-
-` + teamArguments}
 	var limit, page int
 	list := &cobra.Command{
 		Use: "list <team>", Short: "List team members", Args: argsExact(1), ValidArgsFunction: a.completeTeams(),
@@ -585,9 +581,7 @@ func teamRepository(team services.Team, raw string) (string, error) {
 
 func (a *application) teamRepoCommand() *cobra.Command {
 	group := &cobra.Command{Use: "repo", Short: "Manage team repository access", Long: `List the repositories a team can reach, and grant or revoke its access to repositories of
-its organization. Repositories are named alone, such as service, or as ORG/NAME.
+its organization. Repositories are named alone, such as service, or as ORG/NAME.`}
-
-` + teamArguments}
 	var limit, page int
 	list := &cobra.Command{
 		Use: "list <team>", Short: "List team repositories", Args: argsExact(1), ValidArgsFunction: a.completeTeams(),

internal/app/webhooks.go

@@ -260,11 +260,8 @@ $ tea webhook edit 3 --events push,release --authorization-header-file header.tx
 		command.Args = usageArgs(cobra.MaximumNArgs(1))
 		command.Long = `Create a webhook that delivers events to a URL, by default as JSON for push events.
 
-Events: create, delete, fork, push, issues (every issue event), issues_only, issue_assign,
+Events: ` + strings.Join(services.WebhookEvents, ", ") + `; issues and pull_request
-issue_label, issue_milestone, issue_comment, pull_request (every pull request event),
+include every issue or pull request event.
-pull_request_only, pull_request_assign, pull_request_label, pull_request_milestone,
-pull_request_comment, pull_request_review, pull_request_sync, pull_request_review_request, wiki,
-repository, release, package, status, workflow_run, workflow_job.
 
 Types: ` + strings.Join(services.WebhookTypes, ", ") + `. Slack webhooks need
 --config channel=#name; other types take their settings through --config too.`