"Jim Holsenback" <jho### [at] povrayorg> wrote:

> After reading carefully this example in seems to be saying the same thing:
>
> http://wiki.povray.org/content/Documentation:Reference_Section_2#Functions
>

Ah, so it does! :-)

I think the explanations given in the docs could probably be less 'technical',
so as to make more sense to newbies.

Here's how rand() begins:
"Returns the next pseudo-random number from the stream specified by the positive
integer I. You must call seed() to initialize a random stream before calling
rand()."

Egads, that's a lot of tech-speak. First off, it *kind of* sounds like the user
is--or needs to be--already privvy to the 'stream' he's looking for--i.e., "I
need the stream specified by the positive integer 27." Of course, we don't know
what the contents of that stream are (or even what a 'stream' is, if we're REAL
newbies!) so it all sounds confusing/mysterious/unknowable.

Next up is the arcane phrase, "You must call seed..."  Unless the newbie is
already familiar with programming, that word 'call' is rather mysterious. In POV
lingo, it would mean #declare *some variable name* = seed(32). (IF you already
know that, of course!)  Personally, I didn't have the faintest idea what 'call'
meant when I started out...and it made me feel quite 'out of my depth', as if
there was some secret code I had to decipher. Such little dead-end details as
these can be off-putting to a beginner.

Oh, and here's another, from seed:
"seed(I) Initializes a new pseudo-random stream with the initial seed value A."
A or I? What is A?? (Probably a typo, I know--but when one is fishing around for
the meaning of a difficult-to-grasp topic, such a little mystery adds to the
confusion.)

What strikes me about the POV documentation as a whole is that some sections are
written and described very clearly--from a 'humanistic' point of view; while
others seem to lifted verbatim from a programmer's handbook. Granted, the early
iterations of POV-Ray were probably meant only for knowledgeable programmers;
but the documentation is starting to show its age.

Ken

Post a reply to this message