On Sat, 26 Dec 1998 18:30:55 -0800, Ken <tyl### [at] pacbellnet> wrote:
>
>  I've kept quite on this waiting to see where it might go
>opion wise and from what I have seen so far indicates leaving
>the docs alone and writing a comprehensive Pov tutorial. A good
>place to start would be based on the Pov VFAQ and of course the
>areas already mentioned needing further clarification.
>  It's my impression there is a lot left lacking in the docs but
>there are also a lot of misconceptions about what the program will
>and will not do. Perhaps this project could also touch on these
>subjects as well. Having this supplement bundled with the program
>might be a good idea but would need authorization from the Pov team
>and they would have to agree with the content. That shouldn't be a
>problem if it's well organized and comprehensive in it's approach.
>
>Areas I feel need covered:
>
> 1. Media
> 2. Animation
> 3. Radiosity
> 4. The Texture and Pigment process
> 5. Conditional statments
> 6. What is in and what is out (the Pov surface normal)
> 7. CSG operations - goes with above
> 8. The camera statement - Seems simple now but there was a time ...
> 9. When to use an external program, include file, etc...
>10. How to convert the output from the above to useful syntax in Pov
>11. Macros !!!
>
>  That's just a few and my poor old fingers are getting tired already.

Like Ken I have held my fire on this subject, although it is one dear
to my heart. I like Ken's idea of a comprehensive Pov tutorial, but I
also think that the basic Pov documentation should be revised on a
regular basis.

In my experience there is no good computer documentation - just some
worse than others. (cf beer ;-) ) Clarity and conciseness are both
extremely important, but are often in conflict and one has to be
balanced against the other.  One of my pet Pov documentation gripes is
in the realm of CSG operations.  It took me ages and much
experimentation to find out how to use inverse (tremendously useful in
CSG).  Nevertheless I think the Pov documentation is very good,
considering it has all been done by voluntary effort (or perhaps
because of this.)

One of the great things about Pov is the ability it gives you to
experiment and quickly find out what works and what doesn't.   That
is, until you hit the buffers with media!  Unless you have an ultra
fast machine experimentation with media takes forever, as I have found
out trying to generate realistic smoke for my steam loco.  So a
comprehensive, well illustrated, tutorial on media would be a boon to
many of us.

In generating documentation (whether tutorial or reference) we are
unlikely to find a paragon who;
a) is an expert in all aspects of PovRay,
b) is able to write simple English well (we have many users who don't
have English as their first language) and
c) can envision all the difficulties a beginner may have.

With the net, however, we have a great opportunity to set up a group
who, communally, have all these virtues.  How about an "ego-less"
documentation group?  A povray.documentation category of this news
group would be a good start, perhaps split up into the sub-topics Ken
has listed.  This category should NOT be the place to post
documentation, but more of a discussion group.  Those who were
interested could take whichever section of the documentation they
thought they could improve, or add a tutorial to, and post their
efforts on their own web sites using html and then advise the group of
their efforts.  There are, of course, quite a few good such sites
already in existance, and perhaps the first step is to generate a
comprehensive list of these.

Participants would have to accept that others might be able to improve
on their uniquely wonderful efforts, but from what I have seen of this
group I don't think that will be a problem!

Sorry for the long posting!

David
"No man but a blockhead ever wrote, except for money." Samuel Johnson

dav### [at] cwcomnet
http://www.hamiltonite.mcmail.com

Post a reply to this message