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

On 04/23/2013 10:22 PM, Kenneth wrote:
>  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.

SDL follows other programming languages fairly closely in that fopen (in 
this case) returns a /pointer/ to the variable FILE_HANDLE_IDENTIFIER 
... here's a php example to illustrate what I'm talking about:


$HtmlOut = fopen ("documentation/".$FileBrand."/".$OutFile.".html", "wt");

then when I write to or close the file:

fwrite ($HtmlOut, $Page);
fwrite ($HtmlOut, $FixedPanel);
fwrite ($HtmlOut, "<div class=\"Content\">\n");

fclose ($HtmlOut);

IMHO: I don't think there's a clarification needed here ... sorry

Post a reply to this message

> SDL follows other programming languages fairly closely in that fopen (in
> this case) returns a /pointer/ to the variable FILE_HANDLE_IDENTIFIER
> ... here's a php example to illustrate what I'm talking about:

Anyone who has experience with handling files in any other programming 
or scripting language should not have a problem. The issue is with 
people who don't have any previous experience, where SDL is their first 
encounter of such concepts. It's sometimes hard for people with vast 
amounts of experience to imagine how those with no experience might 
interpret such documentation.

Anyway the real question is should the POV documentation assume at least 
a basic knowledge of how file IO works in other languages? If yes, it 
should probably state this at the start of the section (and perhaps a 
useful link for those without such experience), or if no then it should 
explain the concept of a file handle and how it is used (surely can't 
take more than a paragraph or two).

Post a reply to this message

On 04/24/2013 09:14 AM, scott wrote:
>> SDL follows other programming languages fairly closely in that fopen (in
>> this case) returns a /pointer/ to the variable FILE_HANDLE_IDENTIFIER
>> ... here's a php example to illustrate what I'm talking about:
>
> Anyone who has experience with handling files in any other programming
> or scripting language should not have a problem. The issue is with
> people who don't have any previous experience, where SDL is their first
> encounter of such concepts. It's sometimes hard for people with vast
> amounts of experience to imagine how those with no experience might
> interpret such documentation.
>
> Anyway the real question is should the POV documentation assume at least
> a basic knowledge of how file IO works in other languages? If yes, it
> should probably state this at the start of the section (and perhaps a
> useful link for those without such experience), or if no then it should
> explain the concept of a file handle and how it is used (surely can't
> take more than a paragraph or two).
>

I think the fopen directive (the paragraph after the syntax diagram) 
explains the concept adequately, however I'll admit the inconsistent 
usage of IDENTIFIER /instead/ of FILE_HANDLE_IDENTIFIER as the following 
examples use ... is perhaps the true root of the misunderstanding.

Post a reply to this message

> On 04/24/2013 09:14 AM, scott wrote:
>>> SDL follows other programming languages fairly closely in that fopen (in
>>> this case) returns a /pointer/ to the variable FILE_HANDLE_IDENTIFIER
>>> ... here's a php example to illustrate what I'm talking about:
>>
>> Anyone who has experience with handling files in any other programming
>> or scripting language should not have a problem. The issue is with
>> people who don't have any previous experience, where SDL is their first
>> encounter of such concepts. It's sometimes hard for people with vast
>> amounts of experience to imagine how those with no experience might
>> interpret such documentation.
>>
>> Anyway the real question is should the POV documentation assume at least
>> a basic knowledge of how file IO works in other languages? If yes, it
>> should probably state this at the start of the section (and perhaps a
>> useful link for those without such experience), or if no then it should
>> explain the concept of a file handle and how it is used (surely can't
>> take more than a paragraph or two).
>>
>
> I think the fopen directive (the paragraph after the syntax diagram)
> explains the concept adequately, however I'll admit the inconsistent
> usage of IDENTIFIER /instead/ of FILE_HANDLE_IDENTIFIER as the following
> examples use ... is perhaps the true root of the misunderstanding.

Quite possible.
In this case, the solution would be to use only FILE_HANDLE_IDENTIFIER 
or MY_FILE_IDENTIFIER in the documentation.
Also, make double clear that the identifier is that returned by the 
#open command by using the same name everywhere.

Most peoples realy have no clue what a "handle" or a "pointer" is in 
computer languare or programming. Also, when learning programming, it's 
often one of the most arduous and confusing topic...


Alain

Post a reply to this message

On 04/24/2013 04:40 PM, Alain wrote:

>> I think the fopen directive (the paragraph after the syntax diagram)
>> explains the concept adequately, however I'll admit the inconsistent
>> usage of IDENTIFIER /instead/ of FILE_HANDLE_IDENTIFIER as the following
>> examples use ... is perhaps the true root of the misunderstanding.
>
> Quite possible.
> In this case, the solution would be to use only FILE_HANDLE_IDENTIFIER
> or MY_FILE_IDENTIFIER in the documentation.
> Also, make double clear that the identifier is that returned by the
> #open command by using the same name everywhere.
>
> Most peoples realy have no clue what a "handle" or a "pointer" is in
> computer languare or programming. Also, when learning programming, it's
> often one of the most arduous and confusing topic...

OK then ... corrected the inconsistencies on this entire page:

http://wiki.povray.org/content/Reference:File_I/O_Directives#The_fopen_Directive

Post a reply to this message

scott <sco### [at] scottcom> wrote:
>
> The issue is with
> people who don't have any previous experience, where SDL is their first
> encounter of such concepts. It's sometimes hard for people with vast
> amounts of experience to imagine how those with no experience might
> interpret such documentation.
>

Indeed. (And that describes *me* pretty well.) Of course, this goes to the heart
of a more basic question: What level of programming knowledge/experience is a
new POV-Ray user supposed to be familiar with? I would like to think that it
need'nt be on the level of the developers! But I could be wrong.

The thing that strikes me about the documentation (and has always done so) is
that some sections are VERY clear in their descriptions--practically no
fore-knowledge required--while others seem to be holdovers from the days when
dedicated programmers wrote things only for other dedicated programmers--full of
tech-speak. (I do realize that the documentation has been a large group effort
over time, with some writers being, shall we say, more attuned to teaching
beginners in an engaging and not-overly-technical style.) I admit it needs to be
a fine balance. I guess my overall concept of 'instruction manuals' in general
is that they should teach in a way that makes concepts and details clear from
the get-go. Without *unnecessary* head-scratching.

There's another element to this though (and it isn't directed at any particular
individual--I've seen it many times over the years in various guises.):
Sometimes there seems to be a bit of built-in...resistance...to making
'simplifying' changes to the documentation. At times it even takes the form of
an expressed dislike of "spoon feeding" a POV-Ray user who has questions about a
particular subject (usually with the admonition to simply "RTFM.") I'm not sure
I understand where this attitude comes from; but it has always been a rather
self-defeating one, IMO. If the desire of all of us is to expand the user base
of POV-Ray, it seems to make sense to make the program easy to learn, via
well-thought-out documentation. And the typical user should have input to this
process--if only to make suggestions-- because he or she is the one 'down in the
trenches' working with it all the time.

Plus, it's a great learning tool! Sometimes a bit difficult to learn, though,
and it need'nt be.

Post a reply to this message

James Holsenback <nom### [at] nonecom> wrote:
> On 04/24/2013 09:14 AM, scott wrote:

> I think the fopen directive (the paragraph after the syntax diagram)
> explains the concept adequately, however I'll admit the inconsistent
> usage of IDENTIFIER /instead/ of FILE_HANDLE_IDENTIFIER as the following
> examples use ... is perhaps the true root of the misunderstanding.

Basically, yes, (And thanks for making the change to the wiki--I just took a
look.)

BUT (and I hate to beat this poor old horse much longer) the question of what is
an 'open file' there still rankles me.  It's this line in the docs (used
repeatedly):

"Where FILE_HANDLE_IDENTIFIER is the previously opened file."

In purely SDL nomenclature, would that really be considered the opened file? I
know this seems like I'm nit-picking about semantics, but in all other uses in
POV-Ray, an 'opened file' would be a file *name* (like my_scene.pov or
my_include.inc.) Perhaps in a different or more advanced programming
environment, FILE_HANDLE_IDENTIFIER would indeed mean just such a thing. But
within POV-Ray, 'opened file' may not be the right moniker to use. (I admit that
I don't have any clue what it could be changed to and still make sense in that
sentence, as the concept is beyond me. 'Pointer'??)

BTW, I did try searching for #read (#write etc) in the wiki before posting this
thread, but it didn't pull up anything there(!). Entering 'write' did--no #
sign--but nothing in the list of topics seemed appropriate (or maybe I didn't
look closely enough.) I didn't think to try 'I/O directives.'

Post a reply to this message

Alain <kua### [at] videotronca> wrote:

>
> Most peoples realy have no clue what a "handle" or a "pointer" is in
> computer languare or programming. Also, when learning programming, it's
> often one of the most arduous and confusing topic...
>

I would certainly agree with that--using myself as an example. I would assume
that people come to POV-Ray from a wide variety of disciplines, not just
'computer programming.' Art, or maybe just a simple desire to reproduce in 3D
what's in 'the mind's eye.'(My own background is really in mechanical design,
and most of my work has been done without computer help--although I do have
*some* rudimentary knowledge of programming, from 'the old days.')

Of course, using a code-writing program like POV-Ray does require some knowledge
of (or ability with) logical concepts, as well as some (not-too-difficult) math.
But learning the program should follow relatively easily from there--*if* the
learning process is not short-circuited by unclear instructions/ documentation/
etc. "Make the learning process easy!" is my philosophy.

Post a reply to this message

On 04/25/2013 01:59 AM, Kenneth wrote:
> James Holsenback <nom### [at] nonecom> wrote:
> BUT (and I hate to beat this poor old horse much longer) the question of what is
> an 'open file' there still rankles me.  It's this line in the docs (used
> repeatedly):
>
> "Where FILE_HANDLE_IDENTIFIER is the previously opened file."

think of it this way ... gotta open the box for the first time, before 
ya grab a cookie! Don't have to re-open the box to get another cookie. 
The file handle keeps track of where you left off. When you're done you 
can either close, or let the implied close at the end of the parse 
process do it!

Post a reply to this message