In my never-ending quest to help improve/clarify POV-Ray's documentation, here's
a juicy little nugget to sink your teeth into. ;-) Admittedly, this one's
debatable; I suppose it depends on a POV'er's overall knowledge of computer
programming.

The various #fopen/#read/#write sections have what seems to me a bit of
confusion about two important terms-- the file *name* and something called the
FILE_HANDLE_IDENTIFIER (whatever that is!) The end result is that the usage of
these two terms is a bit...ambiguous. (Well, it has certainly caused *me* a lot
of head-scratching over time.)

In the #fopen section, FILE_HANDLE_IDENTIFIER is in fact clearly described as
being different from the file name...
"Where IDENTIFIER is an undefined identifier used to reference this file as a
file handle, "filename" is any string literal or string expression which
specifies the file name."

But the *meaning* of FILE_HANDLE_IDENTIFIER is not dealt with; it's just plopped
down as if we all completely understand this stuff. (I suppose it's
computer-speak for something important in the world of sourcecode
programming--but arcane nonetheless, as it's 'outside' the realm of usual
POV-Ray SDL syntax.) As much as I would *like* to see it explained in layman's
terms, it's not really a problem in and of itself.

The trouble comes when sentences like this one pop up (as in the #write section
of the v3.62 included documentation):
"Where FILE_HANDLE_IDENTIFIER is the previously opened file" and "For example
the following #read directive reads a string, float and vector...

 #read (MyFile,MyString,MyFloat,MyVect)   "

To me, this "MyFile" example reads like a file *name* (which will obviously
cause havoc if it's used there instead). Here's why it strikes me this way:
A) because of the previous sentence equating FILE_HANDLE_IDENTIFIER with the
'opened file' (which would seem to imply the file name itself--that would be an
'opened file' IMO)
B) because a typical(?) user might expect the file *name* to be inserted there
(rather than the esoteric file_handle_identifier term, which AFAIK isn't used
anywhere else in SDL coding)
C) and because in general, 'MyFile' or 'my_file' is a shorthand way of
specifying a generic variable name--as evidenced by the other parts of that
example. It just doesn't *feel* right. Maybe that's a personal thing, but I
think a less-ambiguous name for the FHI would certainly be useful in these
examples. Like...FHI, for example! (Or My_FHI? Hmm...)

Lastly, I always had a nagging feeling that some of these sections contained
typos (not unheard of in the documentation!)--interchanging the
file_handle_identifier with the file name. Of course, that turned out not to be
true...but I didn't know that as I struggled to make sense of the overall
scheme.

When all of this stuff finally 'clicked' for me, it was one of those "Eureka!"
moments. I just wish it had come earlier. ;-) I'm not saying that the docs are
completely unclear; they do explain the basics (given enough re-reading!) But
it's a real chore to easily grasp it all without second-guessing.

From strictly an SDL-programming perspective, I find it surprising that the file
*name* is rarely used in any of the #read/#write commands (except for #fopen.) I
would expect it to be, but no, the FHI is used instead. This relatively odd
situation might be contributing to the lack of clarity. Of course, that's the
way the stuff works. Maybe a simple sentence could be added to point this out.

As always, my only aim is to try and make the docs more easily understandable
'on the first reading'--as there is so much to learn. (Many doc sections are
very well-explained.)

Post a reply to this message