Two documentation suggestions

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

Two documentation suggestions

Aman Verma
First, I just wanted to say how impressed I am at the remarkable brevity
of the Lua reference manual. In reading it, I have come across a couple
of issues that I think could be fixed:

One
===
The description of the second parameter to `os.date` is this:

> If the time argument is present, this is the time to be formatted (see
> the os.time function for a description of this value). Otherwise, date
> formats the current time.

I think it would be clearer if it specified that the reader should look
at the _return value_ of `os.time`. Otherwise, it is unclear which part of
the description of `os.time` the reader should look at: the return value
or the parameter.

Also, I'm not sure what the policy is for updating reference manuals for
unsupported versions of Lua, but this oversight exists in all the
manuals since 5.1.

Two
===
The documentation for `io.open` mentions opening a file in binary mode:

> The mode string can also have a 'b' at the end, which is needed in some
> systems to open the file in binary mode.

Perhaps this explanation is enough for someone who knows C. But as
someone who is simply a Lua user (not an embedder), this sentence is
vague. Is it possible to add more detail or is this one of the
implementation-defined things?

Best regards,
Aman
Reply | Threaded
Open this post in threaded view
|

Re: Two documentation suggestions

Oliver Kroth
This is neither a Lua nor a C thing. It is actually a peculiarity of
CP/M / MSDOS / Windows, which have two modes for reading files:

A text mode where a newline is "corrected" to CR-LF, and the end of the
file is at the first ^Z ('\x1A'),
and a binary mode where this processing is not done.

When you open a PNG file, you will by design (of the file) need binary
mode on those systems.

Oliver

> Two
> ===
> The documentation for `io.open` mentions opening a file in binary mode:
>
>> The mode string can also have a 'b' at the end, which is needed in some
>> systems to open the file in binary mode.
> Perhaps this explanation is enough for someone who knows C. But as
> someone who is simply a Lua user (not an embedder), this sentence is
> vague. Is it possible to add more detail or is this one of the
> implementation-defined things?
>
> Best regards,
> Aman
>
Reply | Threaded
Open this post in threaded view
|

Re: Two documentation suggestions

Viacheslav Usov
On Tue, Nov 10, 2020 at 2:27 PM Oliver Kroth <[hidden email]> wrote:

> This is neither a Lua nor a C thing.

This is a C (standard library) thing, because this is documented in
the C language standards.

> It is actually a peculiarity of > CP/M / MSDOS / Windows, which have two modes for reading files:

Neither MS-DOS nor Windows have two file modes that would be similar
to the C "binary" and "text" "streams" (with reference to, e.g., ISO
C99 Standard 7.19.2). MS-DOS and Windows API expose files as bytes
streams (or possibly sequences of fixed-size blocks of bytes), and
they most certainly do not do any kind of translation.

Cheers,
V.
Reply | Threaded
Open this post in threaded view
|

Re: Two documentation suggestions

William Ahern
On Tue, Nov 10, 2020 at 05:43:14PM +0100, Viacheslav Usov wrote:

> On Tue, Nov 10, 2020 at 2:27 PM Oliver Kroth <[hidden email]> wrote:
>
> > This is neither a Lua nor a C thing.
>
> This is a C (standard library) thing, because this is documented in
> the C language standards.
>
> > It is actually a peculiarity of > CP/M / MSDOS / Windows, which have two modes for reading files:
>
> Neither MS-DOS nor Windows have two file modes that would be similar
> to the C "binary" and "text" "streams" (with reference to, e.g., ISO
> C99 Standard 7.19.2). MS-DOS and Windows API expose files as bytes
> streams (or possibly sequences of fixed-size blocks of bytes), and
> they most certainly do not do any kind of translation.

Microsoft's documentation for fread says[1],

  If the given stream is opened in text mode, Windows-style newlines are
  converted into Unix-style newlines. That is, carriage return-line feed
  (CRLF) pairs are replaced by single line feed (LF) characters

and for fwrite says[2],

  If stream is opened in text mode, each line feed is replaced with a
  carriage return-line feed pair.

I assume (Classic) Mac OS performed similar translation as it used a single
carriage return for EOL.

[1] https://docs.microsoft.com/en-us/cpp/c-runtime-library/reference/fread?view=msvc-160
[2] https://docs.microsoft.com/en-us/cpp/c-runtime-library/reference/fwrite?view=msvc-160
Reply | Threaded
Open this post in threaded view
|

Re: Two documentation suggestions

Viacheslav Usov
On Tue, Nov 10, 2020 at 9:47 PM William Ahern
<[hidden email]> wrote:

> Microsoft's documentation for fread says

fread and fwrite (and fopen) are not Windows API. The relevant [1]
Win32 API would be CreateFile(A/W), ReadFile and WriteFile, which
support nothing like "binary" or "text" modes.

The documentation that you cited is of Microsoft's C/C++ compiler,
which is not part of Windows, nor is it required to develop for
Windows [2], even though it is frequently used for that.

Other C implementations that target Windows may well have different conventions.

Cheers,
V.

[1] I am talking about regular application development for Windows,
for which Microsoft officially designates the Win32 API [3].
Technically there is a lower-level "native" API, which is only
partially documented and even then ostensibly only for the purpose of
driver development. The relevant native API would be ZwCreateFile,
ZwReadFile and ZwWriteFile, which are fully documented and again
support nothing like binary/text modes.

[2] I am still talking about user-mode applications. Even for
user-mode development it is not a straight-forward matter to cite
Microsoft's documentation that clearly states that third-party
compilers would work, but the mere existence of Cygwin and MinGW
demonstrates that.

[3] "The Win32 API (also called the Windows API) is the original
platform for native C/C++ Windows applications that require direct
access to Windows and hardware. It provides a first-class development
experience without depending on a managed runtime environment like
.NET and WinRT (for UWP apps for Windows 10). This makes the Win32 API
the platform of choice for applications that need the highest level of
performance and direct access to system hardware."
https://docs.microsoft.com/en-us/windows/win32/desktop-programming