~rjarry/aerc-devel

aerc: Avoid undocumented stuff v1 APPLIED

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
#1059564 alpine-edge.yml success
#1059565 openbsd.yml success



          
          
          
          
Next



          
          
          
          
Next
aerc/patches: SUCCESS in 4m49s

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

[0]: https://lists.sr.ht/~rjarry/aerc-devel/patches/44855
[1]: mailto: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
Bence Ferdinandy, Sep 19, 2023 at 22:04:
Next
Export patchset (mbox)
How do I use this?

Copy & paste the following snippet into your terminal to import this patchset into git:

curl -s https://lists.sr.ht/~rjarry/aerc-devel/patches/44855/mbox | git am -3
Learn more about email & git

[PATCH aerc 1/8] contrib: add script to check man pages consistency Export this patch

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

[PATCH aerc 2/8] docs: add [ui].client-threads-delay setting Export this patch

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

[PATCH aerc 3/8] docs: add :recover command Export this patch

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

[PATCH aerc 4/8] docs: add :toggle-key-passthrough command Export this patch

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

[PATCH aerc 5/8] docs: add :help and :new-account commands Export this patch

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

[PATCH aerc 6/8] docs: add :connect and :disconnect commands Export this patch

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

[PATCH aerc 7/8] docs: add :fold and :unfold commands Export this patch

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

[PATCH aerc 8/8] docs: add msglist_thread_folded style object Export this patch

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]: mailto: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