docs patches for precmd hooks and $?, and vcs_info

[Daniel Shahaf <d.s@xxxxxxxxxxxxxxxxxx>]

Bart Schaefer wrote on Wed, Apr 14, 2021 at 07:00:32 -0700:
> On Wed, Apr 14, 2021 at 5:06 AM Daniel Shahaf <d.s@xxxxxxxxxxxxxxxxxx>
> wrote:
> 
> >
> > > +prompt_newuser_precmd() {
> > > +  local exitstatus=$?
> >
> > It's not documented that precmd hooks can rely on $? to be the exit code
> > of the last command.  That does work, though (because callhookfunc()
> > calls doshfunc(noreturnval=1)), and seems useful, and I guess we won't
> > want to change it, so shall we document it?
> 
> 
> It's intentional and as far as I recall has always been assumed, so ... yes.

Done.  Attached as 4/8.  Also did a few other things while I was in the
area, and things that I noticed while auditing for other instances of
the bugs fixed by the the former things.

Split to rather small pieces, but in exchange, the log messages are
informative.  (Also, I do review my own patches to the same standard as
others'.)

Cheers,

Daniel

From ef53ae6286714123845ce80b5b8c2d1c8b7ce37c Mon Sep 17 00:00:00 2001
From: Daniel Shahaf <d.s@xxxxxxxxxxxxxxxxxx>
Date: Wed, 14 Apr 2021 14:12:25 +0000
Subject: [PATCH 1/8] docs: Minor markup tweak

---
 Doc/Zsh/func.yo | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Doc/Zsh/func.yo b/Doc/Zsh/func.yo
index d500a78ae..0944380b9 100644
--- a/Doc/Zsh/func.yo
+++ b/Doc/Zsh/func.yo
@@ -212,7 +212,7 @@ example, if tt($chpwd_functions) is an array containing the values
 execute the functions `tt(chpwd)', `tt(mychpwd)' and
 `tt(chpwd_save_dirstack)', in that order.  Any function that does not exist
 is silently ignored.  A function found by this mechanism is referred to
-elsewhere as a `hook function'.  An error in any function causes subsequent
+elsewhere as a em(hook function).  An error in any function causes subsequent
 functions not to be run.  Note further that an error in a tt(precmd) hook
 causes an immediately following tt(periodic) function not to run (though
 it may run at the next opportunity).

From 4017180dcd861fed2e054de946d7612b13249dde Mon Sep 17 00:00:00 2001
From: Daniel Shahaf <d.s@xxxxxxxxxxxxxxxxxx>
Date: Wed, 14 Apr 2021 14:20:23 +0000
Subject: [PATCH 2/8] docs: Fix example rendering in the man page output

The texi output was unaffected.  However, in the man page on my system,
everything after the example() was underlined and not indented.
---
 Doc/Zsh/contrib.yo | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo
index 586ac06f5..55ea06f34 100644
--- a/Doc/Zsh/contrib.yo
+++ b/Doc/Zsh/contrib.yo
@@ -2028,7 +2028,9 @@ disabled.
 item(Declare cleanup)(
 If your function makes any other changes that should be undone when the
 theme is disabled, your setup function may call
+
 example(prompt_cleanup var(command))
+
 where var(command) should be suitably quoted.  If your theme is ever
 disabled or replaced by another, var(command) is executed with tt(eval).
 You may declare more than one such cleanup hook.

From 49f9bb8ebe2a5ad0fc463930c6c8cf76a8eac8f9 Mon Sep 17 00:00:00 2001
From: Daniel Shahaf <d.s@xxxxxxxxxxxxxxxxxx>
Date: Wed, 14 Apr 2021 14:23:58 +0000
Subject: [PATCH 3/8] docs: Fix rendering in the man page output

In the man page output, the text was underlined from the var()
to the end of the paragraph.

The texi output in affected.  For instance, the text `name' in TeX
is now slanted Roman (\slshape\rmfamily) rather than slanted teletype
(\slshape\ttfamily).
---
 Doc/Zsh/contrib.yo | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo
index 55ea06f34..5e91f9a8d 100644
--- a/Doc/Zsh/contrib.yo
+++ b/Doc/Zsh/contrib.yo
@@ -2036,13 +2036,13 @@ disabled or replaced by another, var(command) is executed with tt(eval).
 You may declare more than one such cleanup hook.
 )
 item(Define preview)(
-Define or autoload a function tt(prompt_var(name)_preview) to display
+Define or autoload a function tt(prompt_)var(name)tt(_preview) to display
 a simulated version of your prompt.  A simple default previewer is
 defined by tt(promptinit) for themes that do not define their own.
 This preview function is called by `tt(prompt -p)'.
 )
 item(Provide help)(
-Define or autoload a function tt(prompt_var(name)_help) to display
+Define or autoload a function tt(prompt_)var(name)tt(_help) to display
 documentation or help text for your theme.
 This help function is called by `tt(prompt -h)'.
 )

From 20a22e5a4d7cd881c88554f87e571e1607612b28 Mon Sep 17 00:00:00 2001
From: Daniel Shahaf <d.s@xxxxxxxxxxxxxxxxxx>
Date: Wed, 14 Apr 2021 14:27:10 +0000
Subject: [PATCH 4/8] docs: Document that hook functions may rely on $? (see
 workers/48570).

---
 Doc/Zsh/func.yo | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Doc/Zsh/func.yo b/Doc/Zsh/func.yo
index 0944380b9..7edad7f23 100644
--- a/Doc/Zsh/func.yo
+++ b/Doc/Zsh/func.yo
@@ -206,7 +206,8 @@ findex(hook functions)
 For the functions below, it is possible to define an array that has the
 same name as the function with `tt(_functions)' appended.  Any element in
 such an array is taken as the name of a function to execute; it is executed
-in the same context and with the same arguments as the basic function.  For
+in the same context and with the same arguments and same initial value of tt($?)
+as the basic function.  For
 example, if tt($chpwd_functions) is an array containing the values
 `tt(mychpwd)', `tt(chpwd_save_dirstack)', then the shell attempts to
 execute the functions `tt(chpwd)', `tt(mychpwd)' and

From 0057f30bf04f8d0f5e855846805ca261a3c6c4a7 Mon Sep 17 00:00:00 2001
From: Daniel Shahaf <d.s@xxxxxxxxxxxxxxxxxx>
Date: Wed, 14 Apr 2021 14:49:13 +0000
Subject: [PATCH 5/8] vcs_info docs: Recommend use of prompt expandos rather
 than terminal escape sequences.

---
 Doc/Zsh/contrib.yo | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo
index 5e91f9a8d..07bf4e054 100644
--- a/Doc/Zsh/contrib.yo
+++ b/Doc/Zsh/contrib.yo
@@ -1826,10 +1826,22 @@ example(zstyle ':vcs_info:bzr:*' use-simple true)
 If you do use tt(use-simple), please report if it does `the-right-thing[tm]'.
 
 Display the revision number in yellow for tt(bzr) and tt(svn):
+example(zstyle ':vcs_info:(svn|bzr):*' \ 
+       branchformat '%b%%F{yellow}:%r')
+
+The doubled percent sign is explained in
+ifzman(the bf(Oddities) section)ifnzman(noderef(vcs_info Oddities)).
+
+Alternatively, one can use the raw colour codes directly:
+
 example(zstyle ':vcs_info:(svn|bzr):*' \ 
        branchformat '%b%{'${fg[yellow]}'%}:%r')
 
-If you want colors, make sure you enclose the color codes in tt(%{)var(...)tt(%})
+Normally when a variable is interpolated into a format string, the variable
+needs to be tt(%)-escaped. In this example we skipped that because we assume
+the value of tt(${fg[yellow]}) doesn't contain any tt(%) signs.
+
+Make sure you enclose the color codes in tt(%{)var(...)tt(%})
 if you want to use the string provided by tt(vcs_info) in prompts.
 
 Here is how to print the VCS information as a command (not in a prompt):

From 53a5e2b920e16d398e7869aaeb7077ebad049b9f Mon Sep 17 00:00:00 2001
From: Daniel Shahaf <d.s@xxxxxxxxxxxxxxxxxx>
Date: Wed, 14 Apr 2021 14:50:34 +0000
Subject: [PATCH 6/8] vcs_info docs: Change user-context name in an example, to
 avoid confusion with the special-casing of the value `command' in
 vcs_info_lastmsg.

---
 Doc/Zsh/contrib.yo | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo
index 07bf4e054..ef992bdeb 100644
--- a/Doc/Zsh/contrib.yo
+++ b/Doc/Zsh/contrib.yo
@@ -1845,10 +1845,10 @@ Make sure you enclose the color codes in tt(%{)var(...)tt(%})
 if you want to use the string provided by tt(vcs_info) in prompts.
 
 Here is how to print the VCS information as a command (not in a prompt):
-example(alias vcsi='vcs_info command; vcs_info_lastmsg')
+example(alias vcsi='vcs_info interactive; vcs_info_lastmsg')
 
 This way, you can even define different formats for output via
-tt(vcs_info_lastmsg) in the 'tt(:vcs_info:*:command:*)' namespace.
+tt(vcs_info_lastmsg) in the 'tt(:vcs_info:*:interactive:*)' namespace.
 
 Now as promised, some code that uses hooks:
 say, you'd like to replace the string `svn' by `subversion' in

From 22b629e8a2cfe237ed6ec2fddfa8826d67ea6f93 Mon Sep 17 00:00:00 2001
From: Daniel Shahaf <d.s@xxxxxxxxxxxxxxxxxx>
Date: Wed, 14 Apr 2021 15:10:03 +0000
Subject: [PATCH 7/8] vcs_info docs: vcs_info_lastmsg: Correct an
 ambiguous/wrong description.

---
 Doc/Zsh/contrib.yo | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo
index ef992bdeb..5fe5601a7 100644
--- a/Doc/Zsh/contrib.yo
+++ b/Doc/Zsh/contrib.yo
@@ -1510,7 +1510,7 @@ below for details.
 )
 findex(vcs_info_lastmsg)
 item(tt(vcs_info_lastmsg))(
-Outputs the last tt(${vcs_info_msg_*_}) value.
+Outputs the current values of tt(${vcs_info_msg_*_}).
 Takes into account the value of the tt(use-prompt-escapes) style in
 tt(':vcs_info:formats:command:-all-'). It also only prints tt(max-exports)
 values.

From 41f058912791b55b18de5e71f3426c3af1a5be8c Mon Sep 17 00:00:00 2001
From: Daniel Shahaf <d.s@xxxxxxxxxxxxxxxxxx>
Date: Wed, 14 Apr 2021 15:11:01 +0000
Subject: [PATCH 8/8] vcs_info git: Use best practices in an example

The alias was vulnerable to SHORT_LOOPS syntax, not invokable from
scripts, etc..
---
 Doc/Zsh/contrib.yo | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo
index 5fe5601a7..3c4fdded0 100644
--- a/Doc/Zsh/contrib.yo
+++ b/Doc/Zsh/contrib.yo
@@ -1845,7 +1845,7 @@ Make sure you enclose the color codes in tt(%{)var(...)tt(%})
 if you want to use the string provided by tt(vcs_info) in prompts.
 
 Here is how to print the VCS information as a command (not in a prompt):
-example(alias vcsi='vcs_info interactive; vcs_info_lastmsg')
+example(vcsi+LPAR()+RPAR() { vcs_info interactive; vcs_info_lastmsg })
 
 This way, you can even define different formats for output via
 tt(vcs_info_lastmsg) in the 'tt(:vcs_info:*:interactive:*)' namespace.