> 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