Update the documentation for the reworked NO_AF_UNIX message (20be28b) - derivepassphrase.git

Update the documentation for the reworked NO_AF_UNIX message

Marco Ricci commited on 2025-08-22 07:06:08
Zeige 2 geänderte Dateien mit 85 Einfügungen und 8 Löschungen.

Reintroduce the `NO_AF_UNIX` message (with the new text) in the warnings
category. Document the companion warning message
`NO_ANNOYING_OS_NAMED_PIPES` as well as the replacement error message
`NO_AGENT_SUPPORT` as well. Finally, document the old `NO_AF_UNIX` error
message text as a discontinued diagnostic.

docs/reference/derivepassphrase-vault.1.md 0a32e54..54d5f24
share/man/man1/derivepassphrase-vault.1 c6dc7d9..6f9d667

docs/reference/derivepassphrase-vault.1.md

Zeige Datei @ 20be28b

@@ -358,15 +358,16 @@ The <b>derivepassphrase vault</b> utility exits 0 on success, and >0 if an error
 
     We require a running SSH agent, but cannot locate its communication channel, which is normally indicated by the `SSH_AUTH_SOCK` environment variable.
 
-<!-- Message-ID: ErrMsgTemplate.NO_AF_UNIX -->
-??? failure "`Cannot connect to an SSH agent because this Python version does not support UNIX domain sockets.`"
+<!-- Message-ID: ErrMsgTemplate.NO_AGENT_SUPPORT -->
+??? failure "`Cannot connect to an SSH agent because this Python version does not support communicating with it.`"
 
     This Python installation does not support the communication mechanism necessary to talk to SSH agents.
+    [Since v0.6: May be preceded by several warning messages indicating which communication mechanisms were tried.]
 
 <!-- Message-ID: ErrMsgTemplate.CANNOT_CONNECT_TO_AGENT -->
 ??? failure "`Cannot connect to the SSH agent: %s.`"
 
-    We cannot connect to the SSH agent indicated by the `SSH_AUTH_SOCK` environment variable.
+    We cannot connect to the SSH agent indicated by the respective address (e.g. a well-known address, or the `SSH_AUTH_SOCK` environment variable).
     Further details are contained in the variable part of the message.
 
 <!-- Message-ID: ErrMsgTemplate.AGENT_REFUSED_LIST_KEYS -->
@@ -494,6 +495,30 @@ The <b>derivepassphrase vault</b> utility exits 0 on success, and >0 if an error
     The <i>vault</i>(1) legacy editor interface is in use, which carries a high risk of accidentally losing or corrupting the old notes because a notes editing session cannot be aborted mid-editing.
     To guard against such accidental data loss, a backup copy of the old notes was saved to the <b>derivepassphrase</b> configuration directory.
 
+<!-- Message-ID: WarnMsgTemplate.NO_AF_UNIX -->
+??? warning "`Cannot connect to an SSH agent via UNIX domain sockets because this Python version does not support them.`"
+
+    [Since v0.6.]
+    We attempted to use UNIX domain sockets to communicate with an SSH agent, but this Python installation does not support them.
+    (Only appears together with the error message "Cannot connect to an SSH agent because this Python version does not support communicating with it.".
+    Other, similar messages about unsupported communication mechanisms may precede the error message.)
+
+<!-- Message-ID: WarnMsgTemplate.NO_ANNOYING_OS_NAMED_PIPES -->
+??? warning "`Cannot connect to an SSH agent via Windows named pipes because this Python version does not support them.`"
+
+    [Since v0.6.]
+    We attempted to use Windows named pipes to communicate with an SSH agent, but this Python installation does not support them.
+    (Only appears together with the error message "Cannot connect to an SSH agent because this Python version does not support communicating with it.".
+    Other, similar messages about unsupported communication mechanisms may precede the error message.)
+
+### Discontinued error, warning and info messages on standard error
+
+<!-- Message-ID (mark only): ErrMsgTemplate.NO_AF_UNIX -->
+??? error "`Cannot connect to an SSH agent because this Python version does not support UNIX domain sockets.`"
+
+    [Until v0.6.]
+    Superseded by both the more general error message "Cannot connect to an SSH agent because this Python version does not support communicating with it." and the warning message "Cannot connect to an SSH agent via UNIX domain sockets because this Python version does not support them.".
+
 ## COMPATIBILITY
 
 ### With other software

share/man/man1/derivepassphrase-vault.1

Zeige Datei @ 20be28b

@@ -828,20 +828,20 @@ indicated by the
 .Ev SSH_AUTH_SOCK
 environment variable.
 .
-.\" Message-ID: ErrMsgTemplate.NO_AF_UNIX
-.It Cannot connect to an SSH agent because this Python version does not support UNIX domain sockets.
+.\" Message-ID: ErrMsgTemplate.NO_AGENT_SUPPORT
+.It "Cannot connect to an SSH agent" "because this Python version does not support" "communicating with it."
 This Python installation does not support the communication mechanism
 necessary to talk to
 .Tn SSH
 agents.
+.Bq "Since v0.6: May be preceded by several warning messages" "indicating which communication mechanisms were tried."
 .
 .\" Message-ID: ErrMsgTemplate.CANNOT_CONNECT_TO_AGENT
 .It Cannot connect to the SSH agent: %s.
 We cannot connect to the
 .Tn SSH
-agent indicated by the
-.Ev SSH_AUTH_SOCK
-environment variable.
+agent indicated by the respective address
+.Pq e.g. a well-known address, or the Ev SSH_AUTH_SOCK No environment variable.
 Further details are contained in the variable part of the message.
 .
 .\" Message-ID: ErrMsgTemplate.AGENT_REFUSED_LIST_KEYS
@@ -1025,6 +1025,58 @@ notes was saved to the
 .Nm derivepassphrase
 configuration directory.
 .
+.\" Message-ID: WarnMsgTemplate.NO_AF_UNIX
+.\" Message-ID (mark only): ErrMsgTemplate.NO_AF_UNIX
+.It Cannot connect to an SSH agent via UNIX domain sockets because this Python version does not support them.
+We attempted to use
+.Tn UNIX
+domain sockets to communicate with an
+.Tn SSH
+agent, but this Python installation does not support them.
+.Po
+Only appears together with the error message
+.Do
+Cannot connect to an SSH agent because this Python version does not support communicating with it.
+.Dc .
+Other, similar messages about unsupported communication mechanisms may
+precede the error message.
+.Pc
+.
+.\" Message-ID: WarnMsgTemplate.NO_ANNOYING_OS_NAMED_PIPES
+.It Cannot connect to an SSH agent via Windows named pipes because this Python version does not support them.
+We attempted to use
+.Tn Windows
+named pipes to communicate with an
+.Tn SSH
+agent, but this Python installation does not support them.
+.Po
+Only appears together with the error message
+.Do
+Cannot connect to an SSH agent because this Python version does not support communicating with it.
+.Dc .
+Other, similar messages about unsupported communication mechanisms may
+precede the error message.
+.Pc
+.
+.El
+.Pp
+.
+.Ss Discontinued error, warning and info messages on standard error
+.
+.Pq Li %s Ns No " indicates a variable part of the message."
+.
+.Bl -diag
+.
+.\" Message-ID (mark only): ErrMsgTemplate.NO_AF_UNIX
+.It Cannot connect to an SSH agent because this Python version does not support UNIX domain sockets.
+.Bo
+Until v0.6.
+.Bc
+Superseded by both the more general error message
+.Dq "Cannot connect to an SSH agent because this Python version" "does not support communicating with it."
+and the warning message
+.Dq "Cannot connect to an SSH agent using UNIX domain sockets" "because this Python version does not support them." .
+.
 .El
 .
 .Sh COMPATIBILITY


...	...	@@ -358,15 +358,16 @@ The <b>derivepassphrase vault</b> utility exits 0 on success, and >0 if an error
358	358
359	359	We require a running SSH agent, but cannot locate its communication channel, which is normally indicated by the `SSH_AUTH_SOCK` environment variable.
360	360
361		-<!-- Message-ID: ErrMsgTemplate.NO_AF_UNIX -->
362		-??? failure "`Cannot connect to an SSH agent because this Python version does not support UNIX domain sockets.`"
	361	+<!-- Message-ID: ErrMsgTemplate.NO_AGENT_SUPPORT -->
	362	+??? failure "`Cannot connect to an SSH agent because this Python version does not support communicating with it.`"
363	363
364	364	This Python installation does not support the communication mechanism necessary to talk to SSH agents.
	365	+ [Since v0.6: May be preceded by several warning messages indicating which communication mechanisms were tried.]
365	366
366	367	<!-- Message-ID: ErrMsgTemplate.CANNOT_CONNECT_TO_AGENT -->
367	368	??? failure "`Cannot connect to the SSH agent: %s.`"
368	369
369		- We cannot connect to the SSH agent indicated by the `SSH_AUTH_SOCK` environment variable.
	370	+ We cannot connect to the SSH agent indicated by the respective address (e.g. a well-known address, or the `SSH_AUTH_SOCK` environment variable).
370	371	Further details are contained in the variable part of the message.
371	372
372	373	<!-- Message-ID: ErrMsgTemplate.AGENT_REFUSED_LIST_KEYS -->
...	...	@@ -494,6 +495,30 @@ The <b>derivepassphrase vault</b> utility exits 0 on success, and >0 if an error
494	495	The <i>vault</i>(1) legacy editor interface is in use, which carries a high risk of accidentally losing or corrupting the old notes because a notes editing session cannot be aborted mid-editing.
495	496	To guard against such accidental data loss, a backup copy of the old notes was saved to the <b>derivepassphrase</b> configuration directory.
496	497
	498	+<!-- Message-ID: WarnMsgTemplate.NO_AF_UNIX -->
	499	+??? warning "`Cannot connect to an SSH agent via UNIX domain sockets because this Python version does not support them.`"
	500	+
	501	+ [Since v0.6.]
	502	+ We attempted to use UNIX domain sockets to communicate with an SSH agent, but this Python installation does not support them.
	503	+ (Only appears together with the error message "Cannot connect to an SSH agent because this Python version does not support communicating with it.".
	504	+ Other, similar messages about unsupported communication mechanisms may precede the error message.)
	505	+
	506	+<!-- Message-ID: WarnMsgTemplate.NO_ANNOYING_OS_NAMED_PIPES -->
	507	+??? warning "`Cannot connect to an SSH agent via Windows named pipes because this Python version does not support them.`"
	508	+
	509	+ [Since v0.6.]
	510	+ We attempted to use Windows named pipes to communicate with an SSH agent, but this Python installation does not support them.
	511	+ (Only appears together with the error message "Cannot connect to an SSH agent because this Python version does not support communicating with it.".
	512	+ Other, similar messages about unsupported communication mechanisms may precede the error message.)
	513	+
	514	+### Discontinued error, warning and info messages on standard error
	515	+
	516	+<!-- Message-ID (mark only): ErrMsgTemplate.NO_AF_UNIX -->
	517	+??? error "`Cannot connect to an SSH agent because this Python version does not support UNIX domain sockets.`"
	518	+
	519	+ [Until v0.6.]
	520	+ Superseded by both the more general error message "Cannot connect to an SSH agent because this Python version does not support communicating with it." and the warning message "Cannot connect to an SSH agent via UNIX domain sockets because this Python version does not support them.".
	521	+
497	522	## COMPATIBILITY
498	523
499	524	### With other software

...	...	@@ -828,20 +828,20 @@ indicated by the
828	828	.Ev SSH_AUTH_SOCK
829	829	environment variable.
830	830	.
831		-.\" Message-ID: ErrMsgTemplate.NO_AF_UNIX
832		-.It Cannot connect to an SSH agent because this Python version does not support UNIX domain sockets.
	831	+.\" Message-ID: ErrMsgTemplate.NO_AGENT_SUPPORT
	832	+.It "Cannot connect to an SSH agent" "because this Python version does not support" "communicating with it."
833	833	This Python installation does not support the communication mechanism
834	834	necessary to talk to
835	835	.Tn SSH
836	836	agents.
	837	+.Bq "Since v0.6: May be preceded by several warning messages" "indicating which communication mechanisms were tried."
837	838	.
838	839	.\" Message-ID: ErrMsgTemplate.CANNOT_CONNECT_TO_AGENT
839	840	.It Cannot connect to the SSH agent: %s.
840	841	We cannot connect to the
841	842	.Tn SSH
842		-agent indicated by the
843		-.Ev SSH_AUTH_SOCK
844		-environment variable.
	843	+agent indicated by the respective address
	844	+.Pq e.g. a well-known address, or the Ev SSH_AUTH_SOCK No environment variable.
845	845	Further details are contained in the variable part of the message.
846	846	.
847	847	.\" Message-ID: ErrMsgTemplate.AGENT_REFUSED_LIST_KEYS
...	...	@@ -1025,6 +1025,58 @@ notes was saved to the
1025	1025	.Nm derivepassphrase
1026	1026	configuration directory.
1027	1027	.
	1028	+.\" Message-ID: WarnMsgTemplate.NO_AF_UNIX
	1029	+.\" Message-ID (mark only): ErrMsgTemplate.NO_AF_UNIX
	1030	+.It Cannot connect to an SSH agent via UNIX domain sockets because this Python version does not support them.
	1031	+We attempted to use
	1032	+.Tn UNIX
	1033	+domain sockets to communicate with an
	1034	+.Tn SSH
	1035	+agent, but this Python installation does not support them.
	1036	+.Po
	1037	+Only appears together with the error message
	1038	+.Do
	1039	+Cannot connect to an SSH agent because this Python version does not support communicating with it.
	1040	+.Dc .
	1041	+Other, similar messages about unsupported communication mechanisms may
	1042	+precede the error message.
	1043	+.Pc
	1044	+.
	1045	+.\" Message-ID: WarnMsgTemplate.NO_ANNOYING_OS_NAMED_PIPES
	1046	+.It Cannot connect to an SSH agent via Windows named pipes because this Python version does not support them.
	1047	+We attempted to use
	1048	+.Tn Windows
	1049	+named pipes to communicate with an
	1050	+.Tn SSH
	1051	+agent, but this Python installation does not support them.
	1052	+.Po
	1053	+Only appears together with the error message
	1054	+.Do
	1055	+Cannot connect to an SSH agent because this Python version does not support communicating with it.
	1056	+.Dc .
	1057	+Other, similar messages about unsupported communication mechanisms may
	1058	+precede the error message.
	1059	+.Pc
	1060	+.
	1061	+.El
	1062	+.Pp
	1063	+.
	1064	+.Ss Discontinued error, warning and info messages on standard error
	1065	+.
	1066	+.Pq Li %s Ns No " indicates a variable part of the message."
	1067	+.
	1068	+.Bl -diag
	1069	+.
	1070	+.\" Message-ID (mark only): ErrMsgTemplate.NO_AF_UNIX
	1071	+.It Cannot connect to an SSH agent because this Python version does not support UNIX domain sockets.
	1072	+.Bo
	1073	+Until v0.6.
	1074	+.Bc
	1075	+Superseded by both the more general error message
	1076	+.Dq "Cannot connect to an SSH agent because this Python version" "does not support communicating with it."
	1077	+and the warning message
	1078	+.Dq "Cannot connect to an SSH agent using UNIX domain sockets" "because this Python version does not support them." .
	1079	+.
1028	1080	.El
1029	1081	.
1030	1082	.Sh COMPATIBILITY
1031	1083