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

[Henrik Bengtsson]

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
> 
>