tplate@blackmesacapital.com
2005-Jun-15 19:25 UTC
[Rd] (PR#7943) documentation enhancement: Note in ?seek for Windows
Fair enough. But for the benefit of the unfortunate souls having to
work in Windows, it would be nice if the documentation were as explicit
as possible about what is and is not known about particular issues
(while still being concise). How about the following:
NEW:
#ifdef windows
The value returned by \code{seek()} is known to be unreliable
on Windows systems for text mode files. The Windows documentation
states that the return values from Windows OS seek functions for
text mode files are unreliable (because the Windows file-I/O
functions can insert extra characters at end-of-lines when working
with text mode files.) Binary mode files should not be affected by
this particular issue, but there are known problems on Windows
systems with the reliability of the return value from \code{seek()}
for binary mode files opened in append mode. Clipboard connections
can seek too.
#endif
Tony Plate
Prof Brian Ripley wrote:> I think the proposed change is appropriate only if the return value is
> *known* to be reliable for binary files.
>
> I for one do not trust the writers of an OS whom have made such a
> serious error in one mode (and many other errors elsewhere) not to have
> made one in closely related code. Since it is not Open Source, we
> cannot find out.
>
> On Wed, 15 Jun 2005 tplate at blackmesacapital.com wrote:
>
>> [I started a new bug report for this issue because it was not the
>> primary issue in the original discussion, which was PR#7899]
>>
>> ligges at statistik.uni-dortmund.de wrote:
>> > Tony Plate wrote:
>> > [snip]
>> >>ligges at statistik.uni-dortmund.de wrote:
>> >>[snip]
>> >>>Note that ?seek currently tells us "The value returned
by
>> >>>seek(where=NA) appears to be unreliable on Windows systems,
at least
>> >>>for text files."
>> >>>It would be nice if this comment could be removed, of
course ....
>> >>
>> >>
>> >>May the explanation could be given that this happens with text
files
>> >>because Windows inserts extra characters at end-of-lines when
reading
>> >>"text" mode files (but with binary files, things
should be fine.) This
>> >>particular issue is documented in Microsoft Windows
documentation
>> (e.g.,
>> >>at
http://msdn2.microsoft.com/library/75yw9bf3(en-us,vs.80).aspx, found
>> >>by searching on Google using the terms "fseek windows
documentation").
>> >>Are there any known issues using seek with binary files under
Windows?
>> >>If there are not, then the caveat could be made specific to
text files
>> >>and all vagueness removed.
>> >
>> >
>> > Hmm, all I find (including your link) is Windows CE related ...
>> >
>> > Uwe Ligges
>>
>> For the record, the documentation I pointed to is for Windows 2000 etc,
>> and is not just related to Windows CE (Uwe retracted that claim in a
>> private email).
>>
>> So, the suggestion to refine the note in ?seek stands. Perhaps
>> src/library/base/man/seek.Rd could be changed as follows:
>>
>> OLD:
>>
>> #ifdef windows
>> The value returned by \code{seek(where=NA)} appears to be unreliable
>> on Windows systems, at least for text files. Clipboard connections
>> can seek too.
>> #endif
>>
>> NEW:
>>
>> #ifdef windows
>> The value returned by \code{seek()} is unreliable
>> on Windows systems for text files. This is because the Windows
>> file-I/O functions can insert extra characters at end-of-lines
>> when working with text mode files. Binary mode files should not
>> be affected by this issue. Clipboard connections can seek too.
>> #endif
>>
>> Of course, if someone knows that the return value of seek() is
>> unreliable on Windows for binary files, this documentation change is
>> innappropriate (and then the documentation should probably be changed
>> from "appears to be unreliable, at least for text files" to
"is
>> unreliable, for both binary and text files".
>>
>> -- Tony Plate
>>
>> ______________________________________________
>> R-devel at r-project.org mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>
>>
>
Henrik Bengtsson
2005-Jun-15 20:43 UTC
[Rd] \section{Windows}{...} instead of #ifdef windows ... #endif? (Was: Re: (PR#7943) documentation ...)
Just a comment, that probably applies to a lot more Rd files; when
trying to developer cross-platform R code, it is very useful to have
identical documentation whatever platform you are working on. That is,
I would prefer
\section{Windows-specific comments}{
...
}
rather than
#ifdef windows
...
#endif
This would make it possible to write more robust code (without looking
at the source docs).
/Henrik
tplate at blackmesacapital.com wrote:> Fair enough. But for the benefit of the unfortunate souls having to
> work in Windows, it would be nice if the documentation were as explicit
> as possible about what is and is not known about particular issues
> (while still being concise). How about the following:
>
> NEW:
>
> #ifdef windows
> The value returned by \code{seek()} is known to be unreliable
> on Windows systems for text mode files. The Windows documentation
> states that the return values from Windows OS seek functions for
> text mode files are unreliable (because the Windows file-I/O
> functions can insert extra characters at end-of-lines when working
> with text mode files.) Binary mode files should not be affected by
> this particular issue, but there are known problems on Windows
> systems with the reliability of the return value from \code{seek()}
> for binary mode files opened in append mode. Clipboard connections
> can seek too.
> #endif
>
> Tony Plate
>
>
> Prof Brian Ripley wrote:
>
>>I think the proposed change is appropriate only if the return value is
>>*known* to be reliable for binary files.
>>
>>I for one do not trust the writers of an OS whom have made such a
>>serious error in one mode (and many other errors elsewhere) not to have
>>made one in closely related code. Since it is not Open Source, we
>>cannot find out.
>>
>>On Wed, 15 Jun 2005 tplate at blackmesacapital.com wrote:
>>
>>
>>>[I started a new bug report for this issue because it was not the
>>>primary issue in the original discussion, which was PR#7899]
>>>
>>>ligges at statistik.uni-dortmund.de wrote:
>>>
>>>>Tony Plate wrote:
>>>>[snip]
>>>>
>>>>>ligges at statistik.uni-dortmund.de wrote:
>>>>>[snip]
>>>>>
>>>>>>Note that ?seek currently tells us "The value
returned by
>>>>>>seek(where=NA) appears to be unreliable on Windows
systems, at least
>>>>>>for text files."
>>>>>>It would be nice if this comment could be removed, of
course ....
>>>>>
>>>>>
>>>>>May the explanation could be given that this happens with
text files
>>>>>because Windows inserts extra characters at end-of-lines
when reading
>>>>>"text" mode files (but with binary files, things
should be fine.) This
>>>>>particular issue is documented in Microsoft Windows
documentation
>>>
>>>(e.g.,
>>>
>>>>>at
http://msdn2.microsoft.com/library/75yw9bf3(en-us,vs.80).aspx, found
>>>>>by searching on Google using the terms "fseek windows
documentation").
>>>>>Are there any known issues using seek with binary files
under Windows?
>>>>>If there are not, then the caveat could be made specific to
text files
>>>>>and all vagueness removed.
>>>>
>>>>
>>>>Hmm, all I find (including your link) is Windows CE related ...
>>>>
>>>>Uwe Ligges
>>>
>>>For the record, the documentation I pointed to is for Windows 2000
etc,
>>>and is not just related to Windows CE (Uwe retracted that claim in a
>>>private email).
>>>
>>>So, the suggestion to refine the note in ?seek stands. Perhaps
>>>src/library/base/man/seek.Rd could be changed as follows:
>>>
>>>OLD:
>>>
>>>#ifdef windows
>>> The value returned by \code{seek(where=NA)} appears to be
unreliable
>>> on Windows systems, at least for text files. Clipboard
connections
>>> can seek too.
>>>#endif
>>>
>>>NEW:
>>>
>>>#ifdef windows
>>> The value returned by \code{seek()} is unreliable
>>> on Windows systems for text files. This is because the Windows
>>> file-I/O functions can insert extra characters at end-of-lines
>>> when working with text mode files. Binary mode files should not
>>> be affected by this issue. Clipboard connections can seek too.
>>>#endif
>>>
>>>Of course, if someone knows that the return value of seek() is
>>>unreliable on Windows for binary files, this documentation change is
>>>innappropriate (and then the documentation should probably be
changed
>>>from "appears to be unreliable, at least for text files"
to "is
>>>unreliable, for both binary and text files".
>>>
>>>-- Tony Plate
>>>
>>>______________________________________________
>>>R-devel at r-project.org mailing list
>>>https://stat.ethz.ch/mailman/listinfo/r-devel
>>>
>>>
>>
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>
>