[ID 20000522.002] Documentation for utime should be improved


This is a bug report for perl from steve.tolkin@fmr.com,
generated with the help of perlbug 1.26 running under perl 5.00503.


-----------------------------------------------------------------
[Please enter your report here]
The documentation for utime should be improved, as follows:

Please change the man page for the utime() function.
It should add something like: 
Certain file systems can only store the time 
with a granularity (precision) of 2 seconds.
Some systems known to have this limitation are the FAT file system
used in DOS and various Microsoft Windows file systems derived from it.
This is a limitation of the file system, not of utime.


Change perlfaq5 to have similar language, instead of the 
current wording "doesn't work correctly with Win95/NT" 
which is both vague and imappropriately scary.

There was some discussion of this in 
news//comp.lang.perl.moderated under the subject
Does utime work correctly on Windows NT perl?
and date beginning 2000-05-19


In addition please add the words "utime" and "touch" to the *question*
"How do I set a file's timestamp?" in perlfaq5.

The point is to allow the command "perldoc -q touch"
to find this question and answer.  
Perldoc -q only searches the text of the *question*.  

In general adding one or two words to the the question
that gives the answer is a usefull approach to other
FAQ questions too.
I spent a while searching for "touch" before I found 
utime by looking at the names of all the perl functions.

Ideally touch would also be added to the perlfunc man page, as a 
dummy entry, just to refer to utime.  A precedent for this
has been established by including the non-existent function
export.

Steven Tolkin
steve.tolkin@fmr.com
2000-05-22
[Please do not change anything below this line]
-----------------------------------------------------------------

---
Site configuration information for perl 5.00503:

Configured by informix at Thu May  6 15:58:47 EDT 1999.

Summary of my perl5 (5.0 patchlevel 5 subversion 3) configuration:
  Platform:
    osname=solaris, osvers=2.5.1, archname=sun4-solaris
    uname='sunos denmark 5.5.1 generic_103640-18 sun4u sparc sunw,ultra-2 '
    hint=recommended, useposix=true, d_sigaction=define
    usethreads=undef useperlio=undef d_sfio=undef
  Compiler:
    cc='cc', optimize='-O', gccversion=
    cppflags='-I/usr/local/include'
    ccflags ='-I/usr/local/include'
    stdchar='unsigned char', d_stdstdio=define, usevfork=false
    intsize=4, longsize=4, ptrsize=4, doublesize=8
    d_longlong=define, longlongsize=8, d_longdbl=define, longdblsize=16
    alignbytes=8, usemymalloc=y, prototype=define
  Linker and Libraries:
    ld='cc', ldflags =' -L/usr/local/lib'
    libpth=/usr/local/lib /lib /usr/lib /usr/ccs/lib
    libs=-lsocket -lnsl -ldl -lm -lc -lcrypt
    libc=/lib/libc.so, so=so, useshrplib=false, libperl=libperl.a
  Dynamic Linking:
    dlsrc=dl_dlopen.xs, dlext=so, d_dlsymun=undef, ccdlflags=' '
    cccdlflags='-KPIC', lddlflags='-G -L/usr/local/lib'

Locally applied patches:
    

---
@INC for perl 5.00503:
    /local/home/fnx/steve/lib
    /local/home/fnx/lib/sun4-solaris
    /local/home/fnx/lib
    /usr/local/lib/perl5/5.00503/sun4-solaris
    /usr/local/lib/perl5/5.00503
    /usr/local/lib/perl5/site_perl/5.005/sun4-solaris
    /usr/local/lib/perl5/site_perl/5.005
    .

---
Environment for perl 5.00503:
    HOME=/local/home/fnx
    LANG (unset)
    LANGUAGE (unset)
 
LD_LIBRARY_PATH=/apps/informix/informix/lib:/apps/informix/informix/lib/esql
    LOGDIR (unset)
 
PATH=/local/home/fnx/steve/scripts/misc:/local/home/fnx/steve/scripts:/local
/home/sy71046/mybin:/local/home/fnx/scripts:/local/home/fnx/scripts/misc:/lo
cal/home/fnx/bin:/usr/openwin/bin:/usr/bin:/local/home/fnx/jdk1.1.7A/bin:/ap
ps/curamesg/2.1:.:/opt/UWpine/bin:/usr/local/bin:/usr/ucb:/usr/ccs/bin:/apps
/informix/informix/bin:/usr/sbin
    PERL5LIB=/local/home/fnx/steve/lib:/local/home/fnx/lib
    PERL_BADLANG (unset)
    SHELL=/bin/ksh
0
Richard
6/7/2000 1:56:49 PM
perl.perl5.porters 47777 articles. 1 followers. Follow

3 Replies
178 Views

Similar Articles

[PageSpeed] 18

> This is a bug report for perl from steve.tolkin@fmr.com,
> generated with the help of perlbug 1.26 running under perl 5.00503.

> Ideally touch would also be added to the perlfunc man page, as a 
> dummy entry, just to refer to utime.  A precedent for this
> has been established by including the non-existent function
> export.

Where?  I don't see any such thing.
0
sthoenna
6/8/2000 2:25:26 AM
On Wed, Jun 07, 2000 at 07:25:26PM -0700, Yitzchak Scott-Thoennes wrote:
> > This is a bug report for perl from steve.tolkin@fmr.com,
> > generated with the help of perlbug 1.26 running under perl 5.00503.
> 
> > Ideally touch would also be added to the perlfunc man page, as a 
> > dummy entry, just to refer to utime.  A precedent for this
> > has been established by including the non-existent function
> > export.
> 
> Where?  I don't see any such thing.

Steve may have meant import rather than export.


=item import

There is no builtin C<import> function.  It is just an ordinary
method (subroutine) defined (or inherited) by modules that wish to export
names to another module.  The C<use> function calls the C<import> method
for the package used.  See also L</use()>, L<perlmod>, and L<Exporter>.


I don't think that touch and import are similar cases, however.  import is
not a builtin, but it is part of the core.


Ronald
0
rjk
6/8/2000 2:36:43 AM
Dear Ronald,
	Yes, I meant import.  And yes, I can see why import is different
than touch.

My general objective in posting this (and a few others) to c.l.p.moderated
is to help perl users find what they are looking for in *documentation*
(including the man pages and the FAQ).

I went looking to a function that did the equivalent of Unix "touch".  I
could not find it by any kind of search.  I finally found it by accident.
That seems wrong, and fixable.  I probably would have eventually done
something like 
perldoc perlfunc | cgrep.pl touch

The entry for utime does mention touch, so if the man page was an plain old
book, with a human created index, this would likely be in the index.  I want
to understand how to solve this specific problem, and many others like it,
in a way that is compatible with "perldoc -f touch" finding it.

I want an entry such as "touch -- see utime".  The question is, where to put
such an entry.  

One part of the solution is to use the word touch, and utime, in the
*question* in the FAQ about changing a file's modification time.  Then
perldoc -q touch would find it,
under the question: "How do I set a file's timestamp in perl?"

We can always omit the string "in perl" from the questions, to save space.
So maybe the simplest solutiuon is to reword this to include a few more
keywords in
the question, e.g. "How do I set a file's timestamp? (touch, utime)"

A more comprehensive approach would be to add other questions that use the
other words a user might search on, and the refer to the original question,
e.g.
How can I use touch to change the date or time a file was modified?
    See the question: How do I set a file's timestamp?


It would be useful to extend the capability of perldoc to support multiple
arguments to -q (or a new option letter) meaning find all these strings in
the
question.

It would also be useful to add a new option meaning find all these strings
in the answer.  (Or similarly in the pod section for a function, etc.)


I will post to perlbug, as a doc "bug", once I have a concrete suggestion to
make as to how to fix the doc.  

Steve

> -----Original Message-----
> From: Ronald J Kimball [mailto:rjk@linguist.dartmouth.edu]
> Sent: Wednesday, June 07, 2000 10:37 PM
> To: Yitzchak Scott-Thoennes
> Cc: perl5-porters@perl.org; steve.tolkin@fmr.com
> Subject: Re: [ID 20000522.002] Documentation for utime should be
> improved
> 
> 
> On Wed, Jun 07, 2000 at 07:25:26PM -0700, Yitzchak 
> Scott-Thoennes wrote:
> > > This is a bug report for perl from steve.tolkin@fmr.com,
> > > generated with the help of perlbug 1.26 running under 
> perl 5.00503.
> > 
> > > Ideally touch would also be added to the perlfunc man page, as a 
> > > dummy entry, just to refer to utime.  A precedent for this
> > > has been established by including the non-existent function
> > > export.
> > 
> > Where?  I don't see any such thing.
> 
> Steve may have meant import rather than export.
> 
> 
> =item import
> 
> There is no builtin C<import> function.  It is just an ordinary
> method (subroutine) defined (or inherited) by modules that 
> wish to export
> names to another module.  The C<use> function calls the 
> C<import> method
> for the package used.  See also L</use()>, L<perlmod>, and 
> L<Exporter>.
> 
> 
> I don't think that touch and import are similar cases, 
> however.  import is
> not a builtin, but it is part of the core.
> 
> 
> Ronald
> 
0
Steve
6/8/2000 1:40:18 PM
Reply:

Similar Artilces:

[ID 19991001.002] $^W documentation
This is a bug report for perl from root@brutos.mchh3.oen.siemens.de, generated with the help of perlbug 1.26 running under perl 5.00503. ----------------------------------------------------------------- [Please enter your report here] This is more a hint than a bug, and possibly it's already known - sorry then. The report concerns the documentation of $^W. Currently, it implies that $^W=0 disables -w, in other words, that $^W and -w are synonyms. But this is not completely true because of the two phases precompilation and runtime - a $^W assignment outside BEGIN scopes doe...

[ID 19991117.002] a bug in perl5 under Linux
I find this problem when I use perl5 compiled under Linux. % perl -v This is perl, version 5.005_03 built for i386-linux % perl print 8473018401 % 524288 , "\n" 524287 The correct answer should be 33. Guoheng Wei _.-. Sr. Component Design Eng. '( ^{_} ( Intel Corp. `~\`-----'\ 512-314-0053 )_)---)_) >I find this problem when I use perl5 compiled under Linux. >% perl -v >This is perl, version 5.005_03 built for i386-linux >% perl >print 8473018401 ...

[ID 20000908.002] perlipc documentation bug.
--------------FA9A6CC6103CC5B938D66EC3 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Hi, I test the examples in perlipc.pod with client server and found a bug in multi-threaded version. Here are perl-V.res and perlipc.pod.patch attached files. Best regards. --------------FA9A6CC6103CC5B938D66EC3 Content-Type: text/plain; charset=us-ascii; name="perl-V.res" Content-Transfer-Encoding: 7bit Content-Disposition: inline; filename="perl-V.res" Summary of my perl5 (5.0 patchlevel 5 subversion 3) configuration: Platform: ...

[ID 19990709.002] [DOCUMENTATION PATCH] perldiag
fixing old bugs.... http://bugs.perl.org/admin/perlbug.cgi?req=tid&tid=19990709.002 for rationale. -R [against perl-current] --- perldiag.pod.1 Thu Jul 27 09:43:43 2000 +++ perldiag.pod Thu Jul 27 09:47:46 2000 @@ -261,9 +261,9 @@ (S malloc) An internal routine called free() on something that had never been malloc()ed in the first place. Mandatory, but can be disabled by -setting environment variable C<PERL_BADFREE> to 1. +setting environment variable C<PERL_BADFREE> to 0. -This message can be quite often seen with DB_File on systems ...

[ID 19991022.002] documentation in another format?
Dear sir/madam: I'm trying to learn perl and would like to print out the documentation on your site. However, due to the many <hr> tags, I tried printing the version changes page <http://www.perl.com/pub/doc/manual/html/pod/perldelta.html> and that gave me 89 pages! Isn't there the documentation in txt format, without <hr> tags, or in pdf, etc? thanks marcelo __________________________________________________ Do You Yahoo!? Bid and sell for free at http://auctions.yahoo.com Message from the perl bug squashing team at 'perlbug@perl.org'...

[ID 20000504.002] values() documentation needs updating
--Message-Boundary-9140 Content-type: text/plain; charset=US-ASCII Content-description: Mail message body Content-transfer-encoding: 7BIT Content-disposition: inline To: perlbug@perl.com Subject: values() documentation needs updating Reply-To: dougw@safeguard.net This is a bug report for perl from dougw@safeguard.net, generated with the help of perlbug 1.28 running under perl v5.6.0. ----------------------------------------------------------------- 'perldoc -f values' still says that it gives a copy of values, but it now gives access to the hash's actual valu...

[ID 20000125.002] Problem in documentation of Fcntl constants
The Perl documentation of Fcntl at http://www.perl.com/pub/doc/manual/html/pod/perlfunc/flock.html says: "If LOCK_NB is added to LOCK_SH or LOCK_EX then flock() will return immediately rather than blocking waiting for the lock (check the return status to see if you got it)." After a discussion in the perl.misc newsgroup, everyone agreed that the operation should be a logical OR, not an ADD. I'm submitting this as a documentation bug, in hopes that this is the appropriate channel to get the document changed. In conjunction with the bug in the definition of the consta...

[ID 20000111.002] pod2html (Html.pm)
This is a bug report for perl from Wolfgang.Laun@alcatel.at, generated with the help of perlbug 1.26 running under perl 5.00503. ----------------------------------------------------------------- [Please enter your report here] (Note: I'm aware of the ongoing work concerning Brad Appleton's Pod::Parser and Nick Ing-Simmon's podtohtml. Still, IMHO, the core Perl distribution should have a tool for converting pod to HTML, and podtohtml requires not only the POD::Parser family, but also Font-AFM, HTML-Format, HTML-Parser, HTML-Tree, MIME-Base64, PodToHTML and URI. So...

[ID 20010702.002] perldata documents dubious hash slice
This is a bug report for perl from nick@talking.bollo.cx, generated with the help of perlbug 1.33 running under perl v5.7.1. ----------------------------------------------------------------- [Please enter your report here] perldata.pod gives this as one of its examples of a hash slice: foreach (@hash{keys %hash}) { s/^\s+//; # trim leading whitespace s/\s+$//; # trim trailing whitespace s/(\w+)/\u\L$1/g; # "titlecase" words } Surely this isn't a good example, as (I think - what am I missing?) foreach (values %hash) { ... } ...

[ID 20020313.002] [PATCH][docs]Typeglobs: add documentation
This is a bug report for perl from "Anton Tagunov" <tagunov@motor.ru> generated with the help of perlbug 1.33 running under perl v5.7.3. ----------------------------------------------------------------- Hello, developers! Very few time has passed since I started learning Perl and the docs have helped me well to get up to speed with a new language so far. :-) But there was one subject that remained completely mysterious to me: the Typeglobs. I was completely stuck at understanding them utill sthoenna@efn.org (Yitzchak Scott-Thoennes) (bs"d) and Mark-Jason...

[ID 19991116.002] perl5.005_02: my_setenv() and Term::ReadLine::Gnu
Hi! I've had a problem with perl5.005_02 and Term::ReadLine::Gnu dumping core on a solaris 5.5.1 box. A little bit of debugging revealed that readline-4.0 calls putenv(3) for LINES and COLUMNS during initialization. If these vars weren't present in the environment the call to putenv() changes the value of char **environ. my_setenv() tests this value to decide wether to copy the environment. In my case it didn't copy and thus dumped core on Safefree() as result of an assignment to $ENV{PATH}. Patch appended. Kind regards, Joerg -- Gaertner Datensysteme ...

[ID 19991113.002] Fwd: Problem while installing perl5 on HPUX 10.2
--0-1804289383-942492322=:4000 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Hi folks, Resending, since there was no response .. i'd really appreciate ur help. thanks achal Note: forwarded message attached. ===== __________________________________________________ Do You Yahoo!? Bid and sell for free at http://auctions.yahoo.com --0-1804289383-942492322=:4000 Content-Type: message/rfc822 X-Apparently-To: achalt@yahoo.com via web1206.mail.yahoo.com Return-Path: <dbi-users-bounce@isc.org> X-Track: 1: 40 Received: from ib.rc.vix.com ...

[ID 20020326.002] coredump perl5.7.3 with GD modules on OpenBSD
This is a bug report for perl from alian@cpan.org, generated with the help of perlbug 1.33 running under perl v5.7.3. ----------------------------------------------------------------- First module I found that give coredump. Here list of successful build: http://testers.cpan.org/search?distname=all_distributions&macids=176 I've test GD1.29 => Last version same problem I've test with gcc-3.0.4 and gcc-2.95.3 same problem bash-2.05$ pwd /usr/local/workplace/perl/GD-1.29 bash-2.05$ make test PERL_DL_NONLAZY=1 /usr/bin/perl -Iblib/arch -Iblib/lib -e 'use Test...

Re: [ID 19991116.002] perl5.005_02: my_setenv() and Term::ReadLine::Gnu
Nick Ing-Simmons <nik@tiuk.ti.com> wrote > Thus as far as I can see unless we keep a hash of "things we malloc'ed" > and check for match we should not free() anything in environ. Exactly. And therefore, since we don't want memory leaks, we must keep a hash. What would happen about changes to %ENV from XS code? Or would the magic just "do the right thing"? Mike Guy On Fri, 19 Nov 1999, M.J.T. Guy wrote: > Nick Ing-Simmons <nik@tiuk.ti.com> wrote > > Thus as far as I can see unless we keep a hash of "things we...

Web resources about - [ID 20000522.002] Documentation for utime should be improved - perl.perl5.porters

GNU Free Documentation License - Wikipedia
La GNU Free Documentation License ( GNU FDL ) è una licenza di copyleft per contenuti liberi , creata dalla Free Software Foundation per il progetto ...

Facebook Tweaks Documentation For Developers
Facebook continued its focus on developers with its release Thursday of improved documentation for FQL and the software-development kits for ...

Documentation for building software with Facebook - APIs, SDKs and Services
Learn how to integrate with Facebook's APIs and developer tools to drive growth and engagement to your app, website or content.

Facebook shares new documentation for local currency pricing, sets migration for Q3
Facebook today provided updates regarding its transition from Credits to local currency pricing. The company offered new documentation for game ...

Emergent Documentation: One way that Agile is very different from Waterfall.
(from a 2012 email) One of the questions I always get around the use of Agile is, how do you do the documentation? Many people are very uncomfortable ...

BIMx Pro - Building Information Model eXplorer for complete project documentations on the App Store on ...
Get BIMx Pro - Building Information Model eXplorer for complete project documentations on the App Store. See screenshots and ratings, and read ...

Documentation in Software Development
There is currently a trend to produce “just enough” documentation in software development. We should however not forgot that what we might estimate ...

The Documentation Dilemma
Back when 37signals was consulting, we gradually weaned ourselves off of documentation. It’s normal practice in the design world to produce lots ...

Apple publishes OS X Mavericks and iOS 7 Core Technologies Overview documentation
A new developer document posted to Apple’s website today details the technologies that power OS X Mavericks. The 36-page document includes information ...

Facebook Releases ThreatExchange API Documentation
... information about malware and other security threats, and the social network announced Friday that the application-programming-interface documentation ...

Resources last updated: 11/20/2015 10:43:21 PM