doc for locate-file - unclear, typos

doc for locate-file - unclear, typos

[Drew Adams]

First, the doc string:
 
 ...
 If SUFFIXES is non-nil, it should be a list of suffixes to append to
 file name when searching.  If SUFFIXES is nil, it is equivalent to '("").
 Use '("/") to disable PATH search, but still try the suffixes in SUFFIXES.
 ...
 
The use and meaning of '("/") is unclear. Is it used for SUFFIXES? In
that case, the last part of the sentence is unclear. Is it used for
PATH? In that case, it is not in the right place (and it's not clear
why that would disable PATH search, instead of just searching under
"/").
 
The Elisp manual, on the other hand, says that an absolute FILENAME
disables PATH ("PATH has no effect"). The manual says nothing about
'("/"), and the doc string says nothing about the use of an absolute
FILENAME.
 
The Elisp manual also has some typos: It has several cross refs that
are followed by periods, all within parentheses in the middle of
sentences. And one of these is split over two lines, with the period
following the newline. This is what it looks like in Info:
 
     Typical values of SUFFIXES are
     `exec-suffixes' (*note exec-suffixes.),
     `load-suffixes', `load-file-rep-suffixes' and the return value of
     the function `get-load-suffixes' (*note Load Suffixes).
 
     Typical values for PATH are `exec-path' (*note exec-path
     .) when looking for executable programs or
     `load-path' (*note load-path.) when looking for
     Lisp files.
 
Each of these references is poorly formatted: "(*noteexec-suffixes.)",
"(*note exec-path
.)", and "(*note load-path.)".  There should be no periods.
 
Note that each "see xxxxxxx." is really "see xxxxxxx:YYYYY YYYYY.", but
that's how it gets formatted in Info. That is, if I copy and paste the
Info text, this is what I get:
 
     Typical values of SUFFIXES are
     `exec-suffixes' (*note exec-suffixes: Subprocess Creation.),
     `load-suffixes', `load-file-rep-suffixes' and the return value of
     the function `get-load-suffixes' (*note Load Suffixes::).
 
     Typical values for PATH are `exec-path' (*note exec-path:
     Subprocess Creation.) when looking for executable programs or
     `load-path' (*note load-path: Library Search.) when looking for
     Lisp files.
 

In GNU Emacs 22.1.1 (i386-mingw-nt5.1.2600)
 of 2007-06-02 on RELEASE
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4) --cflags -Ic:/gnuwin32/include'
 

Re: doc for locate-file - unclear, typos

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Fri, 8 Feb 2008 21:47:52 -0800
> 
> The Elisp manual also has some typos: It has several cross refs that
> are followed by periods, all within parentheses in the middle of
> sentences.

These are not typos: an xref in parens (a.k.a. pxref) is followed by a
period in Info if the source Texinfo specified a second argument for
that pxref.

> And one of these is split over two lines, with the period following
> the newline.

That's because Emacs tries to remove part of the pxref when it
displays it.  It's a (mis)feature, not a bug.

Thanks for reporting this, nonetheless.

RE: doc for locate-file - unclear, typos

[Drew Adams]

> > The Elisp manual also has some typos: It has several cross refs that
> > are followed by periods, all within parentheses in the middle of
> > sentences.
> 
> These are not typos: an xref in parens (a.k.a. pxref) is followed by a
> period in Info if the source Texinfo specified a second argument for
> that pxref.
> 
> > And one of these is split over two lines, with the period following
> > the newline.
> 
> That's because Emacs tries to remove part of the pxref when it
> displays it.  It's a (mis)feature, not a bug.
> 
> Thanks for reporting this, nonetheless.

I was afraid this might be the case. Too bad. Looks worse than if the entire
source text were present, IMO. But no biggee.

Re: doc for locate-file - unclear, typos

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <bug-gnu-emacs@gnu.org>
> Date: Sat, 9 Feb 2008 07:55:07 -0800
> 
> > > The Elisp manual also has some typos: It has several cross refs that
> > > are followed by periods, all within parentheses in the middle of
> > > sentences.
> > 
> > These are not typos: an xref in parens (a.k.a. pxref) is followed by a
> > period in Info if the source Texinfo specified a second argument for
> > that pxref.
> > 
> > > And one of these is split over two lines, with the period following
> > > the newline.
> > 
> > That's because Emacs tries to remove part of the pxref when it
> > displays it.  It's a (mis)feature, not a bug.
> > 
> > Thanks for reporting this, nonetheless.
> 
> I was afraid this might be the case. Too bad. Looks worse than if the entire
> source text were present, IMO.

You can have what you want by customizing Info-hide-note-references.
Alternatively, try customizing Info-refill-paragraphs.

RE: doc for locate-file - unclear, typos

[Drew Adams]

> > I was afraid this might be the case. Too bad. Looks worse 
> > than if the entire
> > source text were present, IMO.
> 
> You can have what you want by customizing Info-hide-note-references.
> Alternatively, try customizing Info-refill-paragraphs. 

Thanks for the info, but my report wasn't for me; it was to improve Emacs.
For my own use, I don't really care.