[PATCH] Document _canonical_paths.

[PATCH] Document _canonical_paths.

[Daniel Shahaf]

This mostly copy-pastes and adds markup, however, the positional arguments
are now annotated optional, and a ')' was added.
---
 Completion/Unix/Type/_canonical_paths | 13 -------------
 Doc/Zsh/compsys.yo                    | 15 +++++++++++++++
 2 files changed, 15 insertions(+), 13 deletions(-)

diff --git a/Completion/Unix/Type/_canonical_paths b/Completion/Unix/Type/_canonical_paths
index e4a725b..7dc6b78 100644
--- a/Completion/Unix/Type/_canonical_paths
+++ b/Completion/Unix/Type/_canonical_paths
@@ -1,18 +1,5 @@
 #autoload
 
-# This completion function completes all paths given to it, and also tries to
-# offer completions which point to the same file as one of the paths given
-# (relative path when an absolute path is given, and vice versa; when ..'s are
-# present in the word to be completed, and some paths got from symlinks.
-
-# Usage: _canonical_paths [-A var] [-N] [-MJV12nfX] tag desc paths...
-
-# -A, if specified, takes the paths from the array variable specified. Paths can
-# also be specified on the command line as shown above. -N, if specified,
-# prevents canonicalizing the paths given before using them for completion, in
-# case they are already so. `tag' and `desc' arguments are well, obvious :) In
-# addition, the options -M, -J, -V, -1, -2, -n, -F, -X are passed to compadd.
-
 _canonical_paths_pwd() {
   # Get the canonical directory name by changing to it.
   integer chaselinks
diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index 41864f8..8c7ef0f 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -2978,6 +2978,21 @@ widgets to find out if the command line hasn't changed since the last
 time completion was tried.  Only then are the tt(_ignored),
 tt(_correct) and tt(_approximate) completers called.
 )
+findex(_canonical_paths)
+item(tt(_canonical_paths) [ tt(-A) var(var) ] [ tt(-N) ] [ tt(-MJV12nfX) ] var(tag) var(descr) [ var(paths) ... ])(
+This completion function completes all paths given to it, and also tries to
+offer completions which point to the same file as one of the paths given
+(relative path when an absolute path is given, and vice versa; when tt(..)'s
+are present in the word to be completed; and some paths got from symlinks).
+
+tt(-A), if specified, takes the paths from the array variable specified. Paths can
+also be specified on the command line as shown above.  tt(-N), if specified,
+prevents canonicalizing the paths given before using them for completion, in
+case they are already so. The options tt(-M), tt(-J), tt(-V), tt(-1), tt(-2),
+tt(-n), tt(-F), tt(-X) are passed to tt(compadd).
+
+See tt(_description) for a description of var(tag) and var(descr).
+)
 findex(_complete)
 item(tt(_complete))(
 This completer generates all possible completions in a context-sensitive

Re: [PATCH] Document _canonical_paths.

[Bart Schaefer]

On Aug 16, 10:48pm, Daniel Shahaf wrote:
}
} This mostly copy-pastes and adds markup, however, the positional arguments
} are now annotated optional, and a ')' was added.

I don't understand why you want to remove comments from the function files.

Re: [PATCH] Document _canonical_paths.

[Daniel Shahaf]

Bart Schaefer wrote on Tue, Aug 16, 2016 at 23:28:27 -0700:
> On Aug 16, 10:48pm, Daniel Shahaf wrote:
> }
> } This mostly copy-pastes and adds markup, however, the positional arguments
> } are now annotated optional, and a ')' was added.
> 
> I don't understand why you want to remove comments from the function files.

To avoid duplication.

https://en.wikipedia.org/wiki/Don%27t_repeat_yourself

Does the removal break some workflow?  

Re: [PATCH] Document _canonical_paths.

[Bart Schaefer]

On Aug 17,  4:31pm, Daniel Shahaf wrote:
}
} > I don't understand why you want to remove comments from the function files.
} 
} To avoid duplication.

I think of function files as source code.  You wouldn't remove comments
from the C source code just because there's a manual page, would you?

Also manual pages are installed separately in many cases (even the zsh
tarballs are split to separate the docs) and therefore sometimes the
doc isn't installed at all on a given machine.  It's not duplication
when one of the copies doesn't exist ...

Re: [PATCH] Document _canonical_paths.

[Daniel Shahaf]

Bart Schaefer wrote on Wed, Aug 17, 2016 at 09:53:30 -0700:
> On Aug 17,  4:31pm, Daniel Shahaf wrote:
> }
> } > I don't understand why you want to remove comments from the function files.
> } 
> } To avoid duplication.
> 
> I think of function files as source code.  You wouldn't remove comments
> from the C source code just because there's a manual page, would you?

I draw a distinction between docstrings that describe the API
contract of a function and comments that document portions of the
implementation.

I wouldn't remove comments.

However, I would remove one of two duplicate copies of a docstring.
(I'd keep the copy that's in the manual's source — in our case, yodl —
and drop the other one.)

> Also manual pages are installed separately in many cases (even the zsh
> tarballs are split to separate the docs) and therefore sometimes the
> doc isn't installed at all on a given machine.  It's not duplication
> when one of the copies doesn't exist ...

This argument cuts both ways: somebody might choose to install the man
pages and only a zcompile'd version of the autoloadable function.

If we really want the docstring to be present in both locations, I think
one of them should be autogenerated from the other.  In the meantime,
I've gone ahead and pushed the yodl part of the patch.

Cheers,

Daniel

Re: [PATCH] Document _canonical_paths.

[Bart Schaefer]

On Aug 18,  4:55pm, Daniel Shahaf wrote:
}
} If we really want the docstring to be present in both locations, I think
} one of them should be autogenerated from the other.

I think that would be an overengineered solution to what ought to be a
non-problem.  We definitely don't want the function files being modified
by the doc formatter, and the alternative -- requiring every function
file to contain a specially-formatted comment -- is both a barrier to
users who want to contribute functions, and likely to make any such
comments more difficult to read as simple text.

If the programmer of the function went to the trouble of including a
documentary comment, it's not the job of the documentation writer to
nullify that.  If you prefer not to contribute functions that have
such comments and to write yodl instead, good for you; and if you want
to write yodl for functions that others have contributed, then that's
even better; but I object to the removal of another programmer's
commentary unless a corresponding *programming* change has made it
inaccurate or obsolete.

Re: [PATCH] Document _canonical_paths.

[Daniel Shahaf]

Bart Schaefer wrote on Thu, Aug 18, 2016 at 18:09:28 -0700:
> If the programmer of the function went to the trouble of including a
> documentary comment, it's not the job of the documentation writer to
> nullify that.

39044 does not nullify Clint's work: the new manual text builds
on Clint's docstring and makes _canonical_paths more discoverable.

I concede that 39044 would have broken a workflow whereby one reads
a function's docstring by opening the file defining the function,
and I addressed the issue by committing an alternate patch that breaks
no workflow.

Let's move on.  The reason I got into _canonical_paths at all is that
I'm trying to improve _umount, see separate thread.

Cheers,

Daniel