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

From: Henrik Bengtsson <hb_at_maths.lth.se>
Date: Wed 15 Jun 2005 - 20:43:33 GMT

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@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@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@statistik.uni-dortmund.de wrote:
>>>
>>>>Tony Plate wrote:
>>>>[snip]
>>>>
>>>>>ligges@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@r-project.org mailing list
>>>https://stat.ethz.ch/mailman/listinfo/r-devel
>>>
>>>
>>

>
> ______________________________________________
> R-devel@r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>

>

R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel Received on Thu Jun 16 06:54:43 2005

This archive was generated by hypermail 2.1.8 : Mon 24 Oct 2005 - 22:27:19 GMT