~rjarry/aerc-devel

This thread contains a patchset. You're looking at the original emails, but you may wish to use the patch review UI. Review patch
12 3

[PATCH aerc 0/8] Avoid undocumented stuff

Details
Message ID
<20230918230724.383519-11-robin@jarry.cc>
DKIM signature
missing
Download raw message
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

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

Details
Message ID
<20230918230724.383519-12-robin@jarry.cc>
In-Reply-To
<20230918230724.383519-11-robin@jarry.cc> (view parent)
DKIM signature
missing
Download raw message
Patch: +60 -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

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

Details
Message ID
<20230918230724.383519-13-robin@jarry.cc>
In-Reply-To
<20230918230724.383519-11-robin@jarry.cc> (view parent)
DKIM signature
missing
Download raw message
Patch: +7 -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

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

Details
Message ID
<20230918230724.383519-14-robin@jarry.cc>
In-Reply-To
<20230918230724.383519-11-robin@jarry.cc> (view parent)
DKIM signature
missing
Download raw message
Patch: +11 -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

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

Details
Message ID
<20230918230724.383519-15-robin@jarry.cc>
In-Reply-To
<20230918230724.383519-11-robin@jarry.cc> (view parent)
DKIM signature
missing
Download raw message
Patch: +4 -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

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

Details
Message ID
<20230918230724.383519-16-robin@jarry.cc>
In-Reply-To
<20230918230724.383519-11-robin@jarry.cc> (view parent)
DKIM signature
missing
Download raw message
Patch: +11 -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

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

Details
Message ID
<20230918230724.383519-17-robin@jarry.cc>
In-Reply-To
<20230918230724.383519-11-robin@jarry.cc> (view parent)
DKIM signature
missing
Download raw message
Patch: +5 -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

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

Details
Message ID
<20230918230724.383519-18-robin@jarry.cc>
In-Reply-To
<20230918230724.383519-11-robin@jarry.cc> (view parent)
DKIM signature
missing
Download raw message
Patch: +7 -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

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

Details
Message ID
<20230918230724.383519-19-robin@jarry.cc>
In-Reply-To
<20230918230724.383519-11-robin@jarry.cc> (view parent)
DKIM signature
missing
Download raw message
Patch: +3 -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] build success

builds.sr.ht <builds@sr.ht>
Details
Message ID
<CVMFD4K1J1Y8.3D9NWW6BM93WL@cirno2>
In-Reply-To
<20230918230724.383519-19-robin@jarry.cc> (view parent)
DKIM signature
missing
Download raw message
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

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

Details
Message ID
<CVN5SP52DY38.32M03FHSBO0O3@ferdinandy.com>
In-Reply-To
<20230918230724.383519-12-robin@jarry.cc> (view parent)
DKIM signature
missing
Download raw message
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

Re: [PATCH aerc 8/8] docs: add msglist_thread_folded style object

Details
Message ID
<CVN5W4S00Y9N.10IDPTV1ZOSTA@ferdinandy.com>
In-Reply-To
<20230918230724.383519-19-robin@jarry.cc> (view parent)
DKIM signature
missing
Download raw message
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

Re: [PATCH aerc 8/8] docs: add msglist_thread_folded style object

Details
Message ID
<CVN7EXEF0GOX.1CA29AFW2DFX7@ringo>
In-Reply-To
<CVN5W4S00Y9N.10IDPTV1ZOSTA@ferdinandy.com> (view parent)
DKIM signature
missing
Download raw message
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!
Reply to thread Export thread (mbox)