\section{Windows}{...} instead of #ifdef windows ... #endif? (Was: Re: (PR#7943) documentation ...)

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