More than once it happened that users asked questions on IRC and we
replied that they should use command *:rtfm* as described in the fine
manual. And these users to reply: "it is not in the manual".

This series aims at preventing such grotesque events while also adding
the undocumented commands/options.

Robin Jarry (8):
  contrib: add script to check man pages consistency
  docs: add [ui].client-threads-delay setting
  docs: add :recover command
  docs: add :toggle-key-passthrough command
  docs: add :help and :new-account commands
  docs: add :connect and :disconnect commands
  docs: add :fold and :unfold commands
  docs: add msglist_thread_folded style object

 GNUmakefile              |  1 +
 contrib/check-docs       | 59 ++++++++++++++++++++++++++++++++++++++++
 doc/aerc-config.5.scd    |  7 +++++
 doc/aerc-stylesets.7.scd |  3 ++
 doc/aerc.1.scd           | 38 ++++++++++++++++++++++++++
 5 files changed, 108 insertions(+)
 create mode 100755 contrib/check-docs

-- 
2.41.0

Add a new shell script to check that all commands are documented in man
pages and that the man pages do not contain non-existent commands. Also
check that all explicitly parsed options with ini reflection are
documented as well. It is not possible to check if the man pages do
reference non-existent options since some of the options are parsed
lazily in workers and some of them are also declared with placeholders
(e.g. *column-<name>*).

Run the script in the lint target.

Signed-off-by: Robin Jarry <robin@jarry.cc>
---
 GNUmakefile        |  1 +
 contrib/check-docs | 59 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 60 insertions(+)
 create mode 100755 contrib/check-docs

diff --git a/GNUmakefile b/GNUmakefile
index 7704fcdb37f7..95556bcf3bb3 100644
--- a/GNUmakefile
+++ b/GNUmakefile
@@ -53,6 +53,7 @@ linters.so: contrib/linters.go
 lint: linters.so
 	@contrib/check-whitespace `git ls-files ':!:filters/vectors'` && \
 		echo white space ok.
+	@contrib/check-docs && echo docs ok.
 	@$(GO) run mvdan.cc/gofumpt@$(gofumpt_tag) -d . | grep ^ \
 		&& echo The above files need to be formatted, please run make fmt && exit 1 \
 		|| echo all files formatted.
diff --git a/contrib/check-docs b/contrib/check-docs
new file mode 100755
index 000000000000..b92ca3c0bf1d
--- /dev/null
+++ b/contrib/check-docs
@@ -0,0 +1,59 @@
+#!/bin/sh
+
+tmp=$(mktemp)
+trap "rm -f $tmp" EXIT
+
+global_fail=0
+
+cmd_scd_sed='s/^\*:([a-z][a-z-]*)\*.*/\1/p'
+cmd_go_sed='/^func ([[:alnum:]]\+) Aliases() \[\]string {$/{n; s/", "/ /g; s/.*return \[\]string{"\(.*\)"}/\1/p}'
+
+fail=0
+sed -nre "$cmd_scd_sed" doc/*.scd > "$tmp"
+for f in $(find commands -type f -name '*.go'); do
+	for cmd in $(sed -ne "$cmd_go_sed" "$f"); do
+		if ! grep -qFx "$cmd" "$tmp"; then
+			grep -HnF --color "\"$cmd\"" "$f"
+			fail=$((fail+1))
+		fi
+	done
+done
+
+if [ "$fail" -gt 0 ]; then
+	echo "error: $fail command(s) not documented in man pages" >&2
+	global_fail=1
+fi
+
+fail=0
+sed -ne "$cmd_go_sed" $(find commands -type f -name '*.go') | tr ' ' '\n' > "$tmp"
+for f in doc/*.scd; do
+	for cmd in $(sed -nre "$cmd_scd_sed" "$f"); do
+		if ! grep -qFx "$cmd" "$tmp"; then
+			grep -Hn --color "^\\*:$cmd\\*" "$f"
+			fail=$((fail+1))
+		fi
+	done
+done
+
+if [ "$fail" -gt 0 ]; then
+	echo "error: $fail non-existent command(s) documented in man pages" >&2
+	global_fail=1
+fi
+
+fail=0
+sed -nre 's/^\*([a-z][a-z-]*)\* = .*/\1/p' doc/*.scd > "$tmp"
+for f in $(find config -type f -name '*.go'); do
+	for opt in $(sed -nre 's/.*`ini:"([a-z][a-z-]*)".*/\1/p' $f); do
+		if ! grep -qFx "$opt" "$tmp"; then
+			grep -HnF --color "\"$opt\"" "$f"
+			fail=$((fail+1))
+		fi
+	done
+done
+
+if [ "$fail" -gt 0 ]; then
+	echo "error: $fail option(s) not documented in man pages" >&2
+	global_fail=1
+fi
+
+exit $global_fail
-- 
2.41.0

This setting was not documented. Make it so.

Fixes: 54a0a377e030 ("threads: debounce client-side thread building")
Signed-off-by: Robin Jarry <robin@jarry.cc>
---
 doc/aerc-config.5.scd | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/doc/aerc-config.5.scd b/doc/aerc-config.5.scd
index b7a3a9b65d7d..ecfa7666fbd3 100644
--- a/doc/aerc-config.5.scd
+++ b/doc/aerc-config.5.scd
@@ -394,6 +394,13 @@ These options are configured in the *[ui]* section of _aerc.conf_.
 
 	Default: _false_
 
+*client-threads-delay* = _<duration>_
+	Delay of inactivity after which the client threads are rebuilt. Setting
+	this to _0s_ may introduce a noticeable lag when scrolling through the
+	message list.
+
+	Default: _50ms_
+
 ## CONTEXTUAL UI CONFIGURATION
 
 The UI configuration can be specialized for accounts, specific mail
-- 
2.41.0

This command was not documented. Make it so.

Fixes: cdec23323c64 ("recover: recover emails from tempdir after a crash")
Signed-off-by: Robin Jarry <robin@jarry.cc>
---
 doc/aerc.1.scd | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/doc/aerc.1.scd b/doc/aerc.1.scd
index 660056352adb..dd09ad1bc5a3 100644
--- a/doc/aerc.1.scd
+++ b/doc/aerc.1.scd
@@ -365,6 +365,17 @@ message list, the message in the message viewer, etc).
 
 	_<body>_: The initial message body.
 
+*:recover* [*-f*] [*-e*|*-E*] _<file>_
+	Resume composing a message that was not sent nor postponed. The file may
+	not contain header data unless *[compose].edit-headers* was enabled when
+	originally composing the aborted message.
+
+	*-f*: Delete the _<file>_ after opening the composer.
+
+	*-e*: Forces *[compose].edit-headers* = _true_ for this message only.
+
+	*-E*: Forces *[compose].edit-headers* = _false_ for this message only.
+
 *:filter* [_<options>_] _<terms>_...
 	Similar to *:search*, but filters the displayed messages to only the search
 	results. The search syntax is dependent on the underlying backend.
-- 
2.41.0

This command was not documented. Make it so.

Fixes: 74366d895d5c ("viewer: add key passthrough mode")
Signed-off-by: Robin Jarry <robin@jarry.cc>
---
 doc/aerc.1.scd | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/doc/aerc.1.scd b/doc/aerc.1.scd
index dd09ad1bc5a3..488541142569 100644
--- a/doc/aerc.1.scd
+++ b/doc/aerc.1.scd
@@ -579,6 +579,10 @@ message list, the message in the message viewer, etc).
 *:toggle-headers*
 	Toggles the visibility of the message headers.
 
+*:toggle-key-passthrough*
+	Enter or exit the *[view::passthrough]* key bindings context. See
+	*aerc-binds*(5) for more details.
+
 ## MESSAGE COMPOSE COMMANDS
 
 *:abort*
-- 
2.41.0

These commands were not documented. Make them so.

Signed-off-by: Robin Jarry <robin@jarry.cc>
---
 doc/aerc.1.scd | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/doc/aerc.1.scd b/doc/aerc.1.scd
index 488541142569..1e7ef8cf0dfc 100644
--- a/doc/aerc.1.scd
+++ b/doc/aerc.1.scd
@@ -77,6 +77,17 @@ forwards.
 
 These commands work in any context.
 
+*:help* _<topic>_
+	Display one of aerc's man pages in the embedded terminal.
+
+*:help* *keys*
+	Display the active key bindings in the current context.
+
+*:new-account* [*-t*]
+	Start the new account wizard.
+
+	*-t*: Create a temporary account. Do not modify _accounts.conf_.
+
 *:cd* _<directory>_
 	Changes aerc's current working directory.
 
-- 
2.41.0

These commands were not documented. Make them so.

Fixes: e41ed82cf3db ("imap: add manual {dis,}connect support")
Signed-off-by: Robin Jarry <robin@jarry.cc>
---
 doc/aerc.1.scd | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/doc/aerc.1.scd b/doc/aerc.1.scd
index 1e7ef8cf0dfc..fc94de05e167 100644
--- a/doc/aerc.1.scd
+++ b/doc/aerc.1.scd
@@ -340,6 +340,11 @@ message list, the message in the message viewer, etc).
 
 ## MESSAGE LIST COMMANDS
 
+*:disconnect*++
+*:connect*
+	Disconnect or reconnect the current account. This only applies to
+	certain email sources.
+
 *:clear* [*-s*]
 	Clears the current search or filter criteria.
 
-- 
2.41.0

These commands were not documented. Make them so.

Fixes: 94b1c778dbe6 ("commands: add :fold and :unfold for thread folding")
Signed-off-by: Robin Jarry <robin@jarry.cc>
---
 doc/aerc.1.scd | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/doc/aerc.1.scd b/doc/aerc.1.scd
index fc94de05e167..8515370a89ee 100644
--- a/doc/aerc.1.scd
+++ b/doc/aerc.1.scd
@@ -496,6 +496,13 @@ message list, the message in the message viewer, etc).
 *:toggle-threads*
 	Toggles between message threading and the normal message list.
 
+*:fold*++
+*:unfold*
+	Collapse or un-collapse the thread children of the selected message.
+	Folded threads can be identified by _{{.Thread\*}}_ template attributes
+	in *[ui].index-columns*. See *aerc-config*(5) and *aerc-templates*(7)
+	for more details.
+
 *:view* [*-p*]++
 *:view-message* [*-p*]
 	Opens the message viewer to display the selected message. If the peek
-- 
2.41.0

This style object was not documented. Make it so.

Fixes: 995dfc15a806 ("styles: add style for folded threads")
Signed-off-by: Robin Jarry <robin@jarry.cc>
---
 doc/aerc-stylesets.7.scd | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/doc/aerc-stylesets.7.scd b/doc/aerc-stylesets.7.scd
index 698ad6716abf..8083888b14b4 100644
--- a/doc/aerc-stylesets.7.scd
+++ b/doc/aerc-stylesets.7.scd
@@ -113,6 +113,8 @@ styling.
 :  The message list gutter.
 |  *msglist_pill*
 :  The message list pill.
+|  *msglist_thread_folded*
+:  Visible messages that have folded thread children.
 |  *dirlist_default*
 :  The default style for directories in the directory list.
 |  *dirlist_unread*
@@ -281,6 +283,7 @@ The order that *msglist_\** styles are applied in is, from first to last:
 . *msglist_flagged*
 . *msglist_deleted*
 . *msglist_result*
+. *msglist_thread_folded*
 . *msglist_marked*
 
 So, the marked style will override all other msglist styles.
-- 
2.41.0

aerc/patches: SUCCESS in 4m49s

[Avoid undocumented stuff][0] from [Robin Jarry][1]

[0]: https://lists.sr.ht/~rjarry/aerc-devel/patches/44855
[1]: robin@jarry.cc

✓ #1059565 SUCCESS aerc/patches/openbsd.yml     https://builds.sr.ht/~rjarry/job/1059565
✓ #1059564 SUCCESS aerc/patches/alpine-edge.yml https://builds.sr.ht/~rjarry/job/1059564

On Tue Sep 19, 2023 at 01:07, Robin Jarry wrote:
> Add a new shell script to check that all commands are documented in man
> pages and that the man pages do not contain non-existent commands. Also
> check that all explicitly parsed options with ini reflection are
> documented as well. It is not possible to check if the man pages do
> reference non-existent options since some of the options are parsed
> lazily in workers and some of them are also declared with placeholders
> (e.g. *column-<name>*).
>
> Run the script in the lint target.
>
> Signed-off-by: Robin Jarry <robin@jarry.cc>
> ---
Tested-by: Bence Ferdinandy <bence@ferdinandy.com>


--
+36305425054
bence.ferdinandy.com

On Tue Sep 19, 2023 at 01:07, Robin Jarry wrote:
> This style object was not documented. Make it so.
>
> Fixes: 995dfc15a806 ("styles: add style for folded threads")
> Signed-off-by: Robin Jarry <robin@jarry.cc>
> ---

I was thinking about the order of the commands in the global parts in the man
page, seems not totally but somewhat random, but that does not concern this
patch. Otherwise for all the doc patches:

Acked-by: Bence Ferdinandy <bence@ferdinandy.com>


--
+36305425054
bence.ferdinandy.com

Bence Ferdinandy, Sep 19, 2023 at 22:04:
>
> On Tue Sep 19, 2023 at 01:07, Robin Jarry wrote:
> > This style object was not documented. Make it so.
> >
> > Fixes: 995dfc15a806 ("styles: add style for folded threads")
> > Signed-off-by: Robin Jarry <robin@jarry.cc>
> > ---
>
> I was thinking about the order of the commands in the global parts in the man
> page, seems not totally but somewhat random, but that does not concern this
> patch. Otherwise for all the doc patches:
>
> Acked-by: Bence Ferdinandy <bence@ferdinandy.com>

Applied. Thanks!