zsh-workers
 help / color / mirror / code / Atom feed
* [PATCH 1/4] docs: Clean up some subsection references.
@ 2021-09-26  8:43 Daniel Shahaf
  2021-09-26  8:43 ` [PATCH 2/4] docs: Add texinode()s, so the next commit can link directly to a subsection Daniel Shahaf
                   ` (2 more replies)
  0 siblings, 3 replies; 9+ messages in thread
From: Daniel Shahaf @ 2021-09-26  8:43 UTC (permalink / raw)
  To: zsh-workers

---
 Doc/Zsh/calsys.yo      | 2 +-
 Doc/Zsh/contrib.yo     | 6 +++---
 Doc/Zsh/expn.yo        | 2 +-
 Doc/Zsh/intro.yo       | 2 +-
 Doc/Zsh/jobs.yo        | 2 +-
 Doc/Zsh/mod_newuser.yo | 2 +-
 Doc/Zsh/options.yo     | 4 ++--
 Doc/Zsh/params.yo      | 2 +-
 Doc/Zsh/roadmap.yo     | 2 +-
 Doc/Zsh/zle.yo         | 2 +-
 10 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/Doc/Zsh/calsys.yo b/Doc/Zsh/calsys.yo
index c20c87e61..a8fd876a5 100644
--- a/Doc/Zsh/calsys.yo
+++ b/Doc/Zsh/calsys.yo
@@ -478,7 +478,7 @@ item(tt(calendar_add) [ tt(-BL) ] var(event) ...)(
 Adds a single event to the calendar in the appropriate location.
 The event can contain multiple lines, as described in
 ifnzman(noderef(Calendar File and Date Formats))\
-ifzman(the section Calendar File Format above).
+ifzman(the section `Calendar File Format' above).
 Using this function ensures that the calendar file is sorted in date
 and time order.  It also makes special arrangements for locking
 the file while it is altered.  The old calendar is left in a file
diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo
index 94059eff6..0781c7eb3 100644
--- a/Doc/Zsh/contrib.yo
+++ b/Doc/Zsh/contrib.yo
@@ -2341,7 +2341,7 @@ directly.
 )
 tindex(bracketed-paste-magic)
 item(tt(bracketed-paste-magic))(
-The tt(bracketed-paste) widget (see ifzman(subsection Miscellaneous in
+The tt(bracketed-paste) widget (see ifzman(the subsection `Miscellaneous' in
 zmanref(zshzle))ifnzman(noderef(Miscellaneous) in noderef(Zle Widgets)))
 inserts pasted text literally into the editor buffer rather than interpret
 it as keystrokes.  This disables some common usages where the self-insert
@@ -3190,7 +3190,7 @@ investigate the command word found.  The default is tt(whence -c).
 tindex(zcalc-auto-insert)
 item(tt(zcalc-auto-insert))(
 This function is useful together with the tt(zcalc) function described in
-ifzman(the section Mathematical Functions)\
+ifzman(the section `Mathematical Functions')\
 ifnzman(noderef(Mathematical Functions)).
 It should be bound to a key representing a binary operator such
 as `tt(PLUS())', `tt(-)', `tt(*)' or `tt(/)'.  When running in zcalc,
@@ -3664,7 +3664,7 @@ types even if they are executable.  As this example shows, the complete
 file name is matched against the pattern, regardless of how the file
 was passed to the handler.  The file is resolved to a full path using
 the tt(:P) modifier described in
-ifzman(the subsection Modifiers in zmanref(zshexpn))\
+ifzman(the subsection `Modifiers' in zmanref(zshexpn))\
 ifnzman(noderef(Modifiers));
 this means that symbolic links are resolved where possible, so that
 links into other file systems behave in the correct fashion.
diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo
index c218ded05..50f70c9af 100644
--- a/Doc/Zsh/expn.yo
+++ b/Doc/Zsh/expn.yo
@@ -1854,7 +1854,7 @@ has similar effects.
 
 To combine brace expansion with array expansion, see the
 tt(${^)var(spec)tt(}) form described
-ifzman(in the section Parameter Expansion)\
+ifzman(in the section `Parameter Expansion')\
 ifnzman(in noderef(Parameter Expansion))
 above.
 
diff --git a/Doc/Zsh/intro.yo b/Doc/Zsh/intro.yo
index 75d25ce27..474e537c2 100644
--- a/Doc/Zsh/intro.yo
+++ b/Doc/Zsh/intro.yo
@@ -45,7 +45,7 @@ zsh most closely resembles bf(ksh) but includes many enhancements.  It
 does not provide compatibility with POSIX or other shells in its
 default operating mode:  see
 ifnzman(the section noderef(Compatibility))\
-ifzman(the section Compatibility below).
+ifzman(the section `Compatibility' below).
 
 Zsh has command line editing, builtin spelling correction, programmable
 command completion, shell functions (with autoloading), a history
diff --git a/Doc/Zsh/jobs.yo b/Doc/Zsh/jobs.yo
index 331b91d8d..3ab0698ae 100644
--- a/Doc/Zsh/jobs.yo
+++ b/Doc/Zsh/jobs.yo
@@ -135,4 +135,4 @@ ifzman(the section PROCESS SUBSTITUTION in the zmanref(zshexpn) manual page)\
 ifnzman(noderef(Process Substitution)), and the handler processes for
 multios, see
 ifzman(the section MULTIOS in the zmanref(zshmisc) manual page)\
-ifnzman(the section Multios in noderef(Redirection)).
+ifnzman(the section em(Multios) in noderef(Redirection)).
diff --git a/Doc/Zsh/mod_newuser.yo b/Doc/Zsh/mod_newuser.yo
index 92a64a013..7937e43c3 100644
--- a/Doc/Zsh/mod_newuser.yo
+++ b/Doc/Zsh/mod_newuser.yo
@@ -44,4 +44,4 @@ even if the tt(zsh/newuser) module is disabled.  Note, however, that
 if the module is not installed the function will not be installed either.
 The function is documented in
 ifnzman(noderef(User Configuration Functions))\
-ifzman(the section User Configuration Functions in zmanref(zshcontrib)).
+ifzman(the section `User Configuration Functions' in zmanref(zshcontrib)).
diff --git a/Doc/Zsh/options.yo b/Doc/Zsh/options.yo
index 4a8b85e08..cf4600769 100644
--- a/Doc/Zsh/options.yo
+++ b/Doc/Zsh/options.yo
@@ -602,7 +602,7 @@ Substitutions using the tt(:s) and tt(:&) history modifiers are performed
 with pattern matching instead of string matching.  This occurs wherever
 history modifiers are valid, including glob qualifiers and parameters.
 See
-ifzman(the section Modifiers in zmanref(zshexpn))\
+ifzman(the section `Modifiers' in zmanref(zshexpn))\
 ifnzman(noderef(Modifiers)).
 )
 pindex(IGNORE_BRACES)
@@ -1483,7 +1483,7 @@ The check is omitted if the commands run from the previous command line
 included a `tt(jobs)' command, since it is assumed the user is aware that
 there are background or suspended jobs.  A `tt(jobs)' command run from one
 of the hook functions defined in
-ifnzman(the section Special Functions in noderef(Functions))\
+ifnzman(the section `Special Functions' in noderef(Functions))\
 ifzman(the section SPECIAL FUNCTIONS in zmanref(zshmisc))
 is not counted for this purpose.
 )
diff --git a/Doc/Zsh/params.yo b/Doc/Zsh/params.yo
index b514eb072..583755dc7 100644
--- a/Doc/Zsh/params.yo
+++ b/Doc/Zsh/params.yo
@@ -106,7 +106,7 @@ may be in any order.  Note that this syntax is strict: tt([) and tt(]=) must
 not be quoted, and var(key) may not consist of the unquoted string
 tt(]=), but is otherwise treated as a simple string.  The enhanced forms
 of subscript expression that may be used when directly subscripting a
-variable name, described in the section Array Subscripts below, are not
+variable name, described in the section `Array Subscripts' below, are not
 available.
 
 The syntaxes with and without the explicit key may be mixed.  An implicit
diff --git a/Doc/Zsh/roadmap.yo b/Doc/Zsh/roadmap.yo
index 3f9a122af..2db90889b 100644
--- a/Doc/Zsh/roadmap.yo
+++ b/Doc/Zsh/roadmap.yo
@@ -20,7 +20,7 @@ The function is designed to be self-explanatory.  You can run it by hand
 with `tt(autoload -Uz zsh-newuser-install; zsh-newuser-install -f)'.
 See also
 ifnzman(noderef(User Configuration Functions))\
-ifzman(the section User Configuration Functions in zmanref(zshcontrib)).
+ifzman(the section `User Configuration Functions' in zmanref(zshcontrib)).
 
 
 sect(Interactive Use)
diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo
index 6d517b81b..70dfec333 100644
--- a/Doc/Zsh/zle.yo
+++ b/Doc/Zsh/zle.yo
@@ -50,7 +50,7 @@ argument causes the next command entered to be repeated the specified
 number of times, unless otherwise noted below; this is implemented
 by the tt(digit-argument) widget. See also
 ifzman(the em(Arguments) subsection of the em(Widgets) section )\
-ifnzman(noderef(Arguments) )\
+ifnzman(noderef(Arguments))\
 for some other ways the numeric argument can be modified.
 
 startmenu()


^ permalink raw reply	[flat|nested] 9+ messages in thread

* [PATCH 2/4] docs: Add texinode()s, so the next commit can link directly to a subsection.
  2021-09-26  8:43 [PATCH 1/4] docs: Clean up some subsection references Daniel Shahaf
@ 2021-09-26  8:43 ` Daniel Shahaf
  2021-09-27 15:41   ` Bart Schaefer
  2021-09-26  8:43 ` [PATCH 3/4] docs: _wanted: Clarify the example and point to another one Daniel Shahaf
  2021-09-26  8:43 ` [PATCH 4/4] docs: Fix pointers to the `Widgets', `User-defined Widgets', and `Standard Widgets' sections Daniel Shahaf
  2 siblings, 1 reply; 9+ messages in thread
From: Daniel Shahaf @ 2021-09-26  8:43 UTC (permalink / raw)
  To: zsh-workers

---
Should I also add startmenu() or something?  The subsect()s appear in
the table of contents even without that, and I'm not sure what would be
expected under native info viewers.

Cheers,

Daniel

 Doc/Zsh/expn.yo | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo
index 50f70c9af..16e99269c 100644
--- a/Doc/Zsh/expn.yo
+++ b/Doc/Zsh/expn.yo
@@ -1889,6 +1889,7 @@ The tt(PUSHD_MINUS)
 option exchanges the effects of `tt(~PLUS())' and `tt(~-)' where they are
 followed by a number.
 
+texinode(Dynamic named directories)(Static named directories)()(Filename Expansion)
 subsect(Dynamic named directories)
 cindex(directories, named, dynamic)
 cindex(named directories, dynamic)
@@ -1982,6 +1983,7 @@ example(zsh_directory_name+LPAR()RPAR() {
   return 0
 })
 
+texinode(Static named directories)(`=' expansion)(Dynamic named directories)(Filename Expansion)
 subsect(Static named directories)
 cindex(directories, named, static)
 cindex(named directories, static)
@@ -2008,6 +2010,7 @@ i.e. either the directory name or the full path; the name is used
 if they are the same length.
 The parameters tt($PWD) and tt($OLDPWD) are never abbreviated in this fashion.
 
+texinode(`=' expansion)(Notes)(Static named directories)(Filename Expansion)
 subsect(`=' expansion)
 
 If a word begins with an unquoted `tt(=)'
@@ -2017,6 +2020,7 @@ name of a command.  If a command
 exists by that name, the word is replaced
 by the full pathname of the command.
 
+texinode(Notes)()(`=' expansion)(Filename Expansion)
 subsect(Notes)
 cindex(filename expansion, notes)
 Filename expansion is performed on the right hand side of a parameter


^ permalink raw reply	[flat|nested] 9+ messages in thread

* [PATCH 3/4] docs: _wanted: Clarify the example and point to another one.
  2021-09-26  8:43 [PATCH 1/4] docs: Clean up some subsection references Daniel Shahaf
  2021-09-26  8:43 ` [PATCH 2/4] docs: Add texinode()s, so the next commit can link directly to a subsection Daniel Shahaf
@ 2021-09-26  8:43 ` Daniel Shahaf
  2021-09-27 15:38   ` Bart Schaefer
  2021-09-26  8:43 ` [PATCH 4/4] docs: Fix pointers to the `Widgets', `User-defined Widgets', and `Standard Widgets' sections Daniel Shahaf
  2 siblings, 1 reply; 9+ messages in thread
From: Daniel Shahaf @ 2021-09-26  8:43 UTC (permalink / raw)
  To: zsh-workers

---
 Doc/Zsh/compsys.yo | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index 89b918d60..cc5cd7165 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -5295,7 +5295,11 @@ matches with the given description:
 
 example(local expl
 _wanted tag expl 'description' \ 
-    compadd matches...)
+    compadd -- var(match1) var(match2)...)
+
+See also the use of tt(_wanted) in the example function in
+ifzman(the subsection `Dynamic named directories' in zmanref(zshexpn))\
+ifnzman(noderef(Dynamic named directories)).
 
 Note that, as for tt(_requested), the var(command) must be able to
 accept options to be passed down to tt(compadd).


^ permalink raw reply	[flat|nested] 9+ messages in thread

* [PATCH 4/4] docs: Fix pointers to the `Widgets', `User-defined Widgets', and `Standard Widgets' sections.
  2021-09-26  8:43 [PATCH 1/4] docs: Clean up some subsection references Daniel Shahaf
  2021-09-26  8:43 ` [PATCH 2/4] docs: Add texinode()s, so the next commit can link directly to a subsection Daniel Shahaf
  2021-09-26  8:43 ` [PATCH 3/4] docs: _wanted: Clarify the example and point to another one Daniel Shahaf
@ 2021-09-26  8:43 ` Daniel Shahaf
  2 siblings, 0 replies; 9+ messages in thread
From: Daniel Shahaf @ 2021-09-26  8:43 UTC (permalink / raw)
  To: zsh-workers

The latter two didn't have their own texinode()s.  Various places, both
those sections' subsections and elsewhere in the manual, linked to the
first section rather than to the third.  For instance, zshcontrib(1)
pointed to "noderef(Miscellaneous) in noderef(Zle Widgets)", even though
the former (currently §18.6.6) is not under the latter (currently §18.4).

Add texinode()s and fix those pointers.
---
 Doc/Zsh/contrib.yo |  2 +-
 Doc/Zsh/zle.yo     | 22 +++++++++++++---------
 2 files changed, 14 insertions(+), 10 deletions(-)

diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo
index 0781c7eb3..6aca14f04 100644
--- a/Doc/Zsh/contrib.yo
+++ b/Doc/Zsh/contrib.yo
@@ -2342,7 +2342,7 @@ directly.
 tindex(bracketed-paste-magic)
 item(tt(bracketed-paste-magic))(
 The tt(bracketed-paste) widget (see ifzman(the subsection `Miscellaneous' in
-zmanref(zshzle))ifnzman(noderef(Miscellaneous) in noderef(Zle Widgets)))
+zmanref(zshzle))ifnzman(noderef(Miscellaneous) in noderef(Standard Widgets)))
 inserts pasted text literally into the editor buffer rather than interpret
 it as keystrokes.  This disables some common usages where the self-insert
 widget is replaced in order to accomplish some extra processing.  An
diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo
index 70dfec333..6948aa5ac 100644
--- a/Doc/Zsh/zle.yo
+++ b/Doc/Zsh/zle.yo
@@ -728,7 +728,7 @@ enditem()
 )
 enditem()
 
-texinode(Zle Widgets)(Character Highlighting)(Zle Builtins)(Zsh Line Editor)
+texinode(Zle Widgets)(User-Defined Widgets)(Zle Builtins)(Zsh Line Editor)
 sect(Widgets)
 cindex(widgets)
 All actions in the editor are performed by `widgets'.  A widget's job is
@@ -736,7 +736,9 @@ simply to perform some small action.  The ZLE commands that key sequences
 in keymaps are bound to are in fact widgets.  Widgets can be user-defined
 or built in.
 
-The standard widgets built into ZLE are listed in Standard Widgets below.
+The standard widgets built into ZLE are listed in
+ifzman(the section `Standard Widgets' below)\
+ifnzman(noderef(Standard Widgets)).
 Other built-in widgets can be defined by other modules (see
 ifzman(zmanref(zshmodules))\
 ifnzman(noderef(Zsh Modules))\
@@ -750,6 +752,7 @@ as shell functions.  When the widget is executed, the corresponding
 shell function is executed, and can perform editing (or other) actions.
 It is recommended that user-defined widgets should not have names
 starting with `tt(.)'.
+texinode(User-Defined Widgets)(Standard Widgets)(Zle Widgets)(Zsh Line Editor)
 sect(User-Defined Widgets)
 cindex(widgets, user-defined)
 User-defined widgets, being implemented as shell functions,
@@ -1206,6 +1209,7 @@ This can be used for detecting switches between the vi command
 )
 enditem()
 
+texinode(Standard Widgets)(Character Highlighting)(User-Defined Widgets)(Zsh Line Editor)
 sect(Standard Widgets)
 cindex(widgets, standard)
 The following is a list of all the standard widgets,
@@ -1231,7 +1235,7 @@ menu(Completion)
 menu(Miscellaneous)
 menu(Text Objects)
 endmenu()
-texinode(Movement)(History Control)()(Zle Widgets)
+texinode(Movement)(History Control)()(Standard Widgets)
 subsect(Movement)
 startitem()
 tindex(vi-backward-blank-word)
@@ -1378,7 +1382,7 @@ item(tt(up-line) (unbound) (unbound) (unbound))(
 Move up a line in the buffer.
 )
 enditem()
-texinode(History Control)(Modifying Text)(Movement)(Zle Widgets)
+texinode(History Control)(Modifying Text)(Movement)(Standard Widgets)
 subsect(History Control)
 startitem()
 tindex(beginning-of-buffer-or-history)
@@ -1726,7 +1730,7 @@ the numeric argument. Zero for both local and imported lines and nonzero for
 only local lines.
 )
 enditem()
-texinode(Modifying Text)(Arguments)(History Control)(Zle Widgets)
+texinode(Modifying Text)(Arguments)(History Control)(Standard Widgets)
 subsect(Modifying Text)
 startitem()
 tindex(vi-add-eol)
@@ -2052,7 +2056,7 @@ into the kill buffer.
 Arguably, this is what Y should do in vi, but it isn't what it actually does.
 )
 enditem()
-texinode(Arguments)(Completion)(Modifying Text)(Zle Widgets)
+texinode(Arguments)(Completion)(Modifying Text)(Standard Widgets)
 subsect(Arguments)
 startitem()
 tindex(digit-argument)
@@ -2100,7 +2104,7 @@ example(zle argument-base 16
 zle universal-argument)
 )
 enditem()
-texinode(Completion)(Miscellaneous)(Arguments)(Zle Widgets)
+texinode(Completion)(Miscellaneous)(Arguments)(Standard Widgets)
 subsect(Completion)
 startitem()
 tindex(accept-and-menu-complete)
@@ -2175,7 +2179,7 @@ When a previous completion displayed a list below the prompt, this
 widget can be used to move the prompt below the list.
 )
 enditem()
-texinode(Miscellaneous)(Text Objects)(Completion)(Zle Widgets)
+texinode(Miscellaneous)(Text Objects)(Completion)(Standard Widgets)
 subsect(Miscellaneous)
 startitem()
 tindex(accept-and-hold)
@@ -2573,7 +2577,7 @@ If the last command executed was a digit as part of an argument,
 continue the argument.  Otherwise, execute vi-beginning-of-line.
 )
 enditem()
-texinode(Text Objects)()(Miscellaneous)(Zle Widgets)
+texinode(Text Objects)()(Miscellaneous)(Standard Widgets)
 subsect(Text Objects)
 cindex(text objects)
 Text objects are commands that can be used to select a block of text


^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [PATCH 3/4] docs: _wanted: Clarify the example and point to another one.
  2021-09-26  8:43 ` [PATCH 3/4] docs: _wanted: Clarify the example and point to another one Daniel Shahaf
@ 2021-09-27 15:38   ` Bart Schaefer
  2021-09-27 15:55     ` Oliver Kiddle
  0 siblings, 1 reply; 9+ messages in thread
From: Bart Schaefer @ 2021-09-27 15:38 UTC (permalink / raw)
  To: Daniel Shahaf; +Cc: Zsh hackers list

On Sun, Sep 26, 2021 at 1:47 AM Daniel Shahaf <d.s@daniel.shahaf.name> wrote:
>
> -    compadd matches...)
> +    compadd -- var(match1) var(match2)...)

Hmm ... I'm uncertain about using var() inside example().  This is
going to render in "info" as

  compadd -- MATCH1 MATCH2...

On the other hand I guess this particular example was already using
ellipses, so it's hardly usable code anyway.


^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [PATCH 2/4] docs: Add texinode()s, so the next commit can link directly to a subsection.
  2021-09-26  8:43 ` [PATCH 2/4] docs: Add texinode()s, so the next commit can link directly to a subsection Daniel Shahaf
@ 2021-09-27 15:41   ` Bart Schaefer
  2021-10-12 14:53     ` Daniel Shahaf
  0 siblings, 1 reply; 9+ messages in thread
From: Bart Schaefer @ 2021-09-27 15:41 UTC (permalink / raw)
  To: Daniel Shahaf; +Cc: Zsh hackers list

Does this mean you would approve of applying workers/48937 ?


^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [PATCH 3/4] docs: _wanted: Clarify the example and point to another one.
  2021-09-27 15:38   ` Bart Schaefer
@ 2021-09-27 15:55     ` Oliver Kiddle
  2021-10-12 14:40       ` Daniel Shahaf
  0 siblings, 1 reply; 9+ messages in thread
From: Oliver Kiddle @ 2021-09-27 15:55 UTC (permalink / raw)
  To: Daniel Shahaf, Zsh hackers list

Bart Schaefer wrote:
> On Sun, Sep 26, 2021 at 1:47 AM Daniel Shahaf <d.s@daniel.shahaf.name> wrote:
> >
> > -    compadd matches...)
> > +    compadd -- var(match1) var(match2)...)
>
> Hmm ... I'm uncertain about using var() inside example().  This is
> going to render in "info" as

Also, note that listing no matches at all with compadd is still a
completely valid compadd command. This can be useful because you might
generate the list of candidate matches from a command and pass the list
straight to compadd without first checking whether any were generated.

Doesn't this updated usage imply that there must be at least one?

Oliver


^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [PATCH 3/4] docs: _wanted: Clarify the example and point to another one.
  2021-09-27 15:55     ` Oliver Kiddle
@ 2021-10-12 14:40       ` Daniel Shahaf
  0 siblings, 0 replies; 9+ messages in thread
From: Daniel Shahaf @ 2021-10-12 14:40 UTC (permalink / raw)
  To: Zsh hackers list

Oliver Kiddle wrote on Mon, Sep 27, 2021 at 17:55:03 +0200:
> Bart Schaefer wrote:
> > On Sun, Sep 26, 2021 at 1:47 AM Daniel Shahaf <d.s@daniel.shahaf.name> wrote:
> > >
> > > -    compadd matches...)
> > > +    compadd -- var(match1) var(match2)...)
> >
> > Hmm ... I'm uncertain about using var() inside example().  This is
> > going to render in "info" as

There's plenty of precedent:

% ag -G yo 'example\(.*var\('
Doc/Zsh/builtins.yo:227:example(emulate zsh -c 'autoload -Uz var(func)')
Doc/Zsh/mod_system.yo:76:example(tt(exec {)var(fd)tt(}<&-)
Doc/Zsh/expn.yo:474:example(tt(paste <LPAR()cut -f1) var(file1)tt(RPAR() <LPAR()cut -f3) var(file2)tt(RPAR() |
Doc/Zsh/expn.yo:514:example(tt(paste <LPAR()cut -f1) var(file1)tt(RPAR() <LPAR()cut -f3) var(file2)tt(RPAR()) ifzman(\ 
Doc/Zsh/expn.yo:529:example(tt(paste <LPAR()cut -f1) var(file1)tt(RPAR() <LPAR()cut -f3) var(file2)tt(RPAR()) tt(> >LPAR())var(process)tt(RPAR()))
Doc/Zsh/expn.yo:534:example(tt({ paste <LPAR()cut -f1) var(file1)tt(RPAR() <LPAR()cut -f3) var(file2)tt(RPAR() }) tt(> >LPAR())var(process)tt(RPAR()))
Doc/Zsh/contrib.yo:350:example(tt(zle )var(widgetname)tt( -Nw -f "nolast" -- "$@"))
Doc/Zsh/contrib.yo:957:example(:vcs_info:var(vcs-string):var(user-context):var(repo-root-name))
Doc/Zsh/contrib.yo:1560:example(:vcs_info:var(vcs-string)PLUS()var(hook-name):var(user-context):var(repo-root-name))
Doc/Zsh/contrib.yo:2054:example(prompt_cleanup var(command))
Doc/Zsh/contrib.yo:2084:example(autoload var(function)
Doc/Zsh/contrib.yo:4641:ifnzman(example(var(program) tt(-)tt(-) var(oldname) var(newname)))
Doc/Zsh/contrib.yo:4680:example(zstyle+ ':foo:bar' var(style1) var(value1) \ 
% 

(This is just a line-based grep: there may be additional uses of var()
in multi-line example()s.)

Furthermore, semantically, var() is the correct macro to use here: the
argument «matches» (before this patch) does not literally mean to add
the string «matches» as a completion; it is a placeholder for actual
matches.  If info doesn't render that sanely, ideally we'll teach
ztexi.yo to do that.

How about changing that line to say «compadd foo bar...» instead?

> Also, note that listing no matches at all with compadd is still a
> completely valid compadd command.

Sure.

Incidentally, why does «_f() { compadd; }» followed by «f <TAB>» not
print the message set by «zstyle ':completion:*:warnings' format "No
matches"»?

> This can be useful because you might
> generate the list of candidate matches from a command and pass the list
> straight to compadd without first checking whether any were generated.
> 
> Doesn't this updated usage imply that there must be at least one?

I don't see how.  This isn't the synopsis at the top of «compadd»'s
docs (the usage summary); it's simply an example of how one might invoke
«compadd», whose own docs specify all possible ways to invoke it.

Sorry for my long turn-around on this.

Daniel


^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [PATCH 2/4] docs: Add texinode()s, so the next commit can link directly to a subsection.
  2021-09-27 15:41   ` Bart Schaefer
@ 2021-10-12 14:53     ` Daniel Shahaf
  0 siblings, 0 replies; 9+ messages in thread
From: Daniel Shahaf @ 2021-10-12 14:53 UTC (permalink / raw)
  To: Zsh hackers list

Bart Schaefer wrote on Mon, Sep 27, 2021 at 08:41:07 -0700:
> Does this mean you would approve of applying workers/48937 ?

In that case, and going by your descriptions of Marlon's patches'
effects, I'd +1 promoting the child nodes of «Utilities» one level up,
per workers/48982.  That's an alternative to workers/48937.

I suppose "Other Functions" should be renamed and then its child
"Descriptions" renamed "Functions".

Cheers,

Daniel

P.S.  workers/48937 is https://www.zsh.org/mla/workers/2021/msg01163.html.
The X-Seq redirector doesn't currently resolve that X-Seq properly, as
it's missing from the underlying «numlist» file.


^ permalink raw reply	[flat|nested] 9+ messages in thread

end of thread, other threads:[~2021-10-12 14:53 UTC | newest]

Thread overview: 9+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-09-26  8:43 [PATCH 1/4] docs: Clean up some subsection references Daniel Shahaf
2021-09-26  8:43 ` [PATCH 2/4] docs: Add texinode()s, so the next commit can link directly to a subsection Daniel Shahaf
2021-09-27 15:41   ` Bart Schaefer
2021-10-12 14:53     ` Daniel Shahaf
2021-09-26  8:43 ` [PATCH 3/4] docs: _wanted: Clarify the example and point to another one Daniel Shahaf
2021-09-27 15:38   ` Bart Schaefer
2021-09-27 15:55     ` Oliver Kiddle
2021-10-12 14:40       ` Daniel Shahaf
2021-09-26  8:43 ` [PATCH 4/4] docs: Fix pointers to the `Widgets', `User-defined Widgets', and `Standard Widgets' sections Daniel Shahaf

Code repositories for project(s) associated with this public inbox

	https://git.vuxu.org/mirror/zsh/

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).