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