'r' history parameter documentation fix

'r' history parameter documentation fix

[Jesse Weinstein]

In the Modifier's section of the docs, defining the 'r' history
modifier, "Remove a filename extension of the form `.XXX', leaving the
root name." appears to be subtly wrong.

At least in 4.3.10.Debian, (foo=blah.flac; echo ${foo:r}) gives blah, 
although it should't, according to the manual, as .flac isn't of the
form .XXX .  

I think the doc should be changed to "Remove a filename extension
leaving the root name."

Jesse Weinstein

Re: 'r' history parameter documentation fix

[Bart Schaefer]

On Jul 22, 11:37pm, Jesse Weinstein wrote:
}
} In the Modifier's section of the docs, defining the 'r' history
} modifier, "Remove a filename extension of the form `.XXX', leaving the
} root name." appears to be subtly wrong.
} 
} At least in 4.3.10.Debian, (foo=blah.flac; echo ${foo:r}) gives blah, 
} although it should't, according to the manual, as .flac isn't of the
} form .XXX .  
}  
} I think the doc should be changed to "Remove a filename extension
} leaving the root name."

That'd be at least as wrong (except maybe less subtly) because it
doesn't define "extension" at all.

I guess the question is whether anyone is really confused by what the
doc currently says?

Re: 'r' history parameter documentation fix

[Štěpán Němec]

On Monday, 25.07.2011, Bart Schaefer wrote: 

> On Jul 22, 11:37pm, Jesse Weinstein wrote:
> }
> } In the Modifier's section of the docs, defining the 'r' history
> } modifier, "Remove a filename extension of the form `.XXX', leaving the
> } root name." appears to be subtly wrong.
> } 
> } At least in 4.3.10.Debian, (foo=blah.flac; echo ${foo:r}) gives blah, 
> } although it should't, according to the manual, as .flac isn't of the
> } form .XXX .  
> }  
> } I think the doc should be changed to "Remove a filename extension
> } leaving the root name."
>
> That'd be at least as wrong (except maybe less subtly) because it
> doesn't define "extension" at all.
>
> I guess the question is whether anyone is really confused by what the
> doc currently says?

FWIW, I do think leaving out the "of the form `.XXX'" is better (and
avoids possible confusion, although I didn't suffer from it myself). The
manual doesn't explain what a file is or many other taken-for-granted
terms either (and -- to avoid possible confusion ;-) -- I'm not
suggesting it should).

-- 
Štěpán

Re: 'r' history parameter documentation fix

[Peter Stephenson]

This is what it actually does.

Index: Doc/Zsh/expn.yo
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/Zsh/expn.yo,v
retrieving revision 1.136
diff -p -u -r1.136 expn.yo
--- Doc/Zsh/expn.yo	19 May 2011 16:24:38 -0000	1.136
+++ Doc/Zsh/expn.yo	25 Jul 2011 10:14:27 -0000
@@ -259,8 +259,9 @@ item(tt(Q))(
 Remove one level of quotes from the substituted words.
 )
 item(tt(r))(
-Remove a filename extension of the form `tt(.)var(xxx)', leaving
-the root name.
+Remove a filename extension, i.e. a `tt(.)' followed by any number of
+characters (including zero) that are not `tt(.)', leaving the root
+name.
 )
 item(tt(s/)var(l)tt(/)var(r)[tt(/)])(
 Substitute var(r) for var(l) as described below.

-- 
Peter Stephenson <pws@csr.com>            Software Engineer
Tel: +44 (0)1223 692070                   Cambridge Silicon Radio Limited
Churchill House, Cambridge Business Park, Cowley Road, Cambridge, CB4 0WZ, UK


Member of the CSR plc group of companies. CSR plc registered in England and Wales, registered number 4187346, registered office Churchill House, Cambridge Business Park, Cowley Road, Cambridge, CB4 0WZ, United Kingdom
More information can be found at www.csr.com. Follow CSR on Twitter at http://twitter.com/CSR_PLC and read our blog at www.csr.com/blog

Re: 'r' history parameter documentation fix

[Štěpán Němec]

On Monday, 25.07.2011, Peter Stephenson wrote: 

> -Remove a filename extension of the form `tt(.)var(xxx)', leaving
> -the root name.
> +Remove a filename extension, i.e. a `tt(.)' followed by any number of
> +characters (including zero) that are not `tt(.)', leaving the root
> +name.

If you want to go that route, you need to say "the last `tt(.)'".

-- 
Štěpán

Re: 'r' history parameter documentation fix

[Peter Stephenson]

On Mon, 25 Jul 2011 13:45:28 +0200
Štěpán Němec <stepnem@gmail.com> wrote:
> On Monday, 25.07.2011, Peter Stephenson wrote: 
> 
> > -Remove a filename extension of the form `tt(.)var(xxx)', leaving
> > -the root name.
> > +Remove a filename extension, i.e. a `tt(.)' followed by any number of
> > +characters (including zero) that are not `tt(.)', leaving the root
> > +name.
> 
> If you want to go that route, you need to say "the last `tt(.)'".

That would imply that it wasn't clear that the string of characters that
were not "." had to extend to the end of the string, as I'd intended, so
I need to fix that.  I also need to say "not `tt(.)' or `tt(/)'".


Remove a filename extension leaving the root name.  Strings with no
filename extension are not altered.  For this purpose, a filename
extension is a `tt(.)' followed by any number characters (including
zero) that are neither `tt(.)' nor `tt(/)' and that continue to the end
of the string.  For example, the extension of
`tt(foo.orig.c)' is `tt(.c)', and `tt(dir.c/foo)' has no extension.


-- 
Peter Stephenson <pws@csr.com>            Software Engineer
Tel: +44 (0)1223 692070                   Cambridge Silicon Radio Limited
Churchill House, Cambridge Business Park, Cowley Road, Cambridge, CB4 0WZ, UK


Member of the CSR plc group of companies. CSR plc registered in England and Wales, registered number 4187346, registered office Churchill House, Cambridge Business Park, Cowley Road, Cambridge, CB4 0WZ, United Kingdom
More information can be found at www.csr.com. Follow CSR on Twitter at http://twitter.com/CSR_PLC and read our blog at www.csr.com/blog

Re: 'r' history parameter documentation fix

[Štěpán Němec]

Peter Stephenson wrote: 

> Remove a filename extension leaving the root name.  Strings with no
> filename extension are not altered.  For this purpose, a filename
> extension is a `tt(.)' followed by any number characters (including
                                               ^
                                               of
> zero) that are neither `tt(.)' nor `tt(/)' and that continue to the end
> of the string.  For example, the extension of
> `tt(foo.orig.c)' is `tt(.c)', and `tt(dir.c/foo)' has no extension.

Quite clear to me. (Except that I'd still prefer just leaving the
explanation out than opening this can of worms -- for instance, although
it might seem far-fetched, the "for this purpose" thing made me wonder
"Hm, is this supposed to imply that Zsh also might have other notions of
file extensions in other contexts?" And you know, I don't really want to
know the answer. Everybody knows what a file extension is, right?)

-- 
Štěpán

Re: 'r' history parameter documentation fix

[Peter Stephenson]

On Mon, 25 Jul 2011 14:27:24 +0200
Štěpán Němec <stepnem@gmail.com> wrote:
> > Remove a filename extension leaving the root name.  Strings with no
> > filename extension are not altered.  For this purpose, a filename
> > extension is a `tt(.)' followed by any number characters (including
>                                                ^
>                                                of
> > zero) that are neither `tt(.)' nor `tt(/)' and that continue to the end
> > of the string.  For example, the extension of
> > `tt(foo.orig.c)' is `tt(.c)', and `tt(dir.c/foo)' has no extension.
> 
> Quite clear to me. (Except that I'd still prefer just leaving the
> explanation out than opening this can of worms -- for instance, although
> it might seem far-fetched, the "for this purpose" thing made me wonder
> "Hm, is this supposed to imply that Zsh also might have other notions of
> file extensions in other contexts?"

I'll remove "for this purpose".

> Everybody knows what a file extension is, right?)

I think it's worth being explicit.  For example, it's probably obvious
to a geek that alongfilename.withalongbitontheend has a file extension,
but a casual shell user might say "surely that's too long to be an
extension?  aren't they limited to three characters, or something?",
or they might not realise "manpage.3" had an extension ("surely they've
got to be alphabetic, or something"?) and it's not necessarily clear
whether "foo." has an extension "." or no extension.  Etcetera.

-- 
Peter Stephenson <pws@csr.com>            Software Engineer
Tel: +44 (0)1223 692070                   Cambridge Silicon Radio Limited
Churchill House, Cambridge Business Park, Cowley Road, Cambridge, CB4 0WZ, UK


Member of the CSR plc group of companies. CSR plc registered in England and Wales, registered number 4187346, registered office Churchill House, Cambridge Business Park, Cowley Road, Cambridge, CB4 0WZ, United Kingdom
More information can be found at www.csr.com. Follow CSR on Twitter at http://twitter.com/CSR_PLC and read our blog at www.csr.com/blog

Re: 'r' history parameter documentation fix

[Manuel Presnitz]

Am Montag 25 Juli 2011 14:40 schrieb Peter Stephenson:

> and it's not necessarily clear whether "foo." has an
> extension "." or no extension.

That's really not clear, at least to me. But after the
actual documentation ("a filename extension is a `tt(.)'
followed by (...)") it has the extension "."

And this is exactly what the :r modifier does:
# test=foo. && print +$test:r+
+foo+


But then IMHO there's another subtle error in the ":e"
modifiers doc a few lines above:
"e    Remove all but the extension."

# test=foo. && print +$test:e+
++

Perhaps it should read "e   Leaves only the extension
but without the separating dot."



---Manuel.
-- 
NEU: FreePhone - 0ct/min Handyspartarif mit Geld-zurück-Garantie!		
Jetzt informieren: http://www.gmx.net/de/go/freephone

Re: 'r' history parameter documentation fix

[Štěpán Němec]

Peter Stephenson wrote:

> On Mon, 25 Jul 2011 14:27:24 +0200
> Štěpán Němec <stepnem@gmail.com> wrote:

>> the "for this purpose" thing made me wonder "Hm, is this supposed to
>> imply that Zsh also might have other notions of file extensions in
>> other contexts?"
>
> I'll remove "for this purpose".

Thanks. :-)

>> Everybody knows what a file extension is, right?)
>
> I think it's worth being explicit.  For example, it's probably obvious
> to a geek that alongfilename.withalongbitontheend has a file extension,
> but a casual shell user might say "surely that's too long to be an
> extension?  aren't they limited to three characters, or something?",
> or they might not realise "manpage.3" had an extension ("surely they've
> got to be alphabetic, or something"?) and it's not necessarily clear
> whether "foo." has an extension "." or no extension.  Etcetera.

Fair enough, I guess.

-- 
Štěpán

Re: 'r' history parameter documentation fix

[Benjamin R. Haskell]

[-- Attachment #1: Type: TEXT/PLAIN, Size: 1365 bytes --]

On Mon, 25 Jul 2011, Peter Stephenson wrote:

> On Mon, 25 Jul 2011 14:27:24 +0200 Štěpán Němec wrote:
>>> Remove a filename extension leaving the root name.  Strings with no 
>>> filename extension are not altered.  For this purpose, a filename 
>>> extension is a `tt(.)' followed by any number characters (including
>>                                                ^
>>                                                of

[Just making this addition more obvious.  I didn't notice it in my 
mailer, and pws didn't respond to it inline.]


>>> zero) that are neither `tt(.)' nor `tt(/)' and that continue to the 
>>> end of the string.  For example, the extension of `tt(foo.orig.c)' 
>>> is `tt(.c)', and `tt(dir.c/foo)' has no extension.
>>
>> Quite clear to me. (Except that I'd still prefer just leaving the 
>> explanation out than opening this can of worms -- for instance, 
>> although it might seem far-fetched, the "for this purpose" thing made 
>> me wonder "Hm, is this supposed to imply that Zsh also might have 
>> other notions of file extensions in other contexts?"
>
> I'll remove "for this purpose".

Seems important.  Or maybe it could be changed to 'Remove a tt(.) 
followed by a filename extension'?

:e is described in the same section as "Remove all but the extension", 
which by the definition above would include the dot.

-- 
Best,
Ben

Re: 'r' history parameter documentation fix

[Peter Stephenson]

On Mon, 25 Jul 2011 09:41:30 -0400
"Benjamin R. Haskell" <zsh@benizi.com> wrote:
> :e is described in the same section as "Remove all but the extension",
> which by the definition above would include the dot.

Right, as Manuel also pointed out.  This could say "remove all but the
part of the file extension following the `.'" and refer to :r.  That
seems to be unambiguous, given that :r defines it to include the ".".

(Or we could of course say that :r removed the "." and the file
extension, but that seems to make the description more waffly.)

-- 
Peter Stephenson <pws@csr.com>            Software Engineer
Tel: +44 (0)1223 692070                   Cambridge Silicon Radio Limited
Churchill House, Cambridge Business Park, Cowley Road, Cambridge, CB4 0WZ, UK



Member of the CSR plc group of companies. CSR plc registered in England and Wales, registered number 4187346, registered office Churchill House, Cambridge Business Park, Cowley Road, Cambridge, CB4 0WZ, United Kingdom
More information can be found at www.csr.com. Follow CSR on Twitter at http://twitter.com/CSR_PLC and read our blog at www.csr.com/blog

Re: 'r' history parameter documentation fix

[Jesse Weinstein]

A more exact suggestion:

On Mon, 2011-07-25 at 01:34 -0700, Bart Schaefer wrote:
> On Jul 22, 11:37pm, Jesse Weinstein wrote:
> }
> } In the Modifier's section of the docs, defining the 'r' history
> } modifier, "Remove a filename extension of the form `.XXX', leaving the
> } root name." appears to be subtly wrong.
> } 
> } At least in 4.3.10.Debian, (foo=blah.flac; echo ${foo:r}) gives blah, 
> } although it should't, according to the manual, as .flac isn't of the
> } form .XXX .  
> }  
> } I think the doc should be changed to "Remove a filename extension
> } leaving the root name."
> 
> That'd be at least as wrong (except maybe less subtly) because it
> doesn't define "extension" at all.
It would be less wrong, because rather than defining extension wrongly, 
it leaves it up to the expectations of the reader, which in many cases
may be correct.

However, you convinced me to look up how the 'r' modifier is handled in
the code, so we can be strictly correct.  It's implemented by a call to
hist.c:remtext() which simply trims off the last dot in the filename,
and whatever characters follow it, i.e. ${variable%%.[^.]#} (with
EXTENDED_GLOB set).

So we could rephrase the documentation as:

"Remove a filename extension (the rightmost period and everything
following it) leaving the root name."

> I guess the question is whether anyone is really confused by what the
> doc currently says?
Currently, the doc implies behavior that differs from what the shell
does.  This is a (minor) problem whether anyone is "really confused" or
not.

Jesse