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

Here's my 0.02$:

- As an experienced programmer, I'm perfectly familiar with the file 
handles concept, and why it is done.

- I recall though that when I first encountered this concept, I found it 
counter-intuitive as well; I'd have expected the file to be identified 
by its name always.

- The concept may be easier to understand if the user is made aware that 
he can have one and the very same file open multiple times for reading.

Post a reply to this message

James Holsenback <nom### [at] nonecom> wrote:
> On 04/25/2013 01:59 AM, Kenneth wrote:

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

Hey, that's a pretty good analogy (especially for folks like me, heh heh.) I
hadn't thought of it that way.

Put it in the docs!  ;-P ;-P

Post a reply to this message

Having worked in a variety of fields and on numerous projects of differing
levels of complexity, I find that:
a) it's useful to have several ways to do the same thing.
[mouse clicks, keyboard strokes, macros, etc.]
b) what is useful to the beginner can grow to be annoying to the experienced
user.
c) There is usually "THE" documentation, which often sucks because it seems it's
either written by "the guy" who wrote the code, or someone so experienced with
the thing that they're describing, that they have a certain level of myopia and
can't see certain things that are staring them in the face.  Like reading
straight through the typos or unmodified cut-and-paste items that you told
yourself you'd go back and fix "later."  Then there's the annoying "Someone took
the time to write a manual / help file / error code, but it gives the end user
absolutely no useful information" syndrome.  (Internal error 34!)
Then there is 3rd-party documentation - like Chilton's or Haynes manuals for
cars.

"The" manual may benefit from having something along the lines of and experience
level option, where the user can turn on/off show/hide differing levels of
information.  The new user may want a lengthy explanation with pictures and
example code, whereas an experienced user may really only want to check the
syntax of a command without having to wade through the introductory info.

If the Manual were made available in such a way that the end user could set this
up themselves, they could have
"the" manual
sphere_official.hlp

annotations for themselves
Mysphere.hlp

and perhaps import informational tidbits and pieces of helpful / illuminating
code from other users
[click here to download JimBobs_sphere.hlp]
news.pov.org.wicked_clear_examples...  whatever.

and it wouldn't tax the official POV team's excellent people.

*****
One of things I have learned over the years, is that some people think well in
the abstract, and other can only handle concrete examples.
So while it's instantly obvious to some people that x is a variable, and that
x+2=5 or 5-2=x or 5-2-x=0, other people may need a more concrete example. "When
x=3, then x+2=5...  It's a silly example, but it's only meant to illustrate what
I mean.
So just give a concrete example of what FILE_HANDLE_IDENTIFIER _IS_, and be done
with it.

Because it seems kinda silly to me to try to keep the manual ... er, brief and
concise, yet have endless threads on How Do I... What is the command for... Use
the FooBar() Directive Instead.... {should be cross-indexed under Similar
commands/topics}, etc.  Provide mention to, a link, or something to a
meta-manual.   A URL is brief, the referenced website may contain terabytes of
information...

It seems ... almost ludicrous to me that POV-Ray Help "can't" search for "IF".
Really?  But I _want_ it to.  Let me make it.  Heck, MS Word Pad would let me...

So, if there's a POV "community" out here - let's share our communal knowledge
and understanding, and let THE END USER document it all in the manner they see
fit.  Instead of "see THIS thread" or rtfm, you can just post a copy of your
..hlp file that you use, and they can do with it whatever they wish.

Post a reply to this message