A friend of mine suggested that we try to cover the gap caused by the
absence of "Ray Tracing Creations" --- Maybe do a much updated version of
that. IE.. as Gilles Tran said - A supplemental volume, that while not
encompassing the pov-ray docs, DOES go through and expand on topics, like an
indepth on CSG, beziers, etc,etc...

If the Pov-Team says "Don't use the povray docs.." we might look at doing
this. Or maybe do this from the start... After all, at the moment, nothing
is set in stone. This is just tossing ideas around right now. =)

Twyst

Post a reply to this message

Twyst wrote:
> 
> A friend of mine suggested that we try to cover the gap caused by the
> absence of "Ray Tracing Creations" --- Maybe do a much updated version of
> that. IE.. as Gilles Tran said - A supplemental volume, that while not
> encompassing the pov-ray docs, DOES go through and expand on topics, like an
> indepth on CSG, beziers, etc,etc...
> 
> If the Pov-Team says "Don't use the povray docs.." we might look at doing
> this. Or maybe do this from the start... After all, at the moment, nothing
> is set in stone. This is just tossing ideas around right now. =)
> 
> Twyst

  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.

-- 
Ken Tyler

tyl### [at] pacbellnet

Post a reply to this message

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

David Wilkinson wrote:

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

I agree.

However, as Ken so often and rightfully points out, there is a tremendous
wealth of information in the example files.  Just rendering each of them,
and then examining the source code, is in itself an excellent tutorial.
It is well worth the time.  But many of the questions posted by users
to these groups reveal that it is not a sufficiently exploited resource.

You can lead a horse to water....

Dan

Post a reply to this message

On Sun, 27 Dec 1998 06:58:04 -0800, Dan Connelly <djc### [at] flashnet>
wrote:
>
>.... as Ken so often and rightfully points out, there is a tremendous
>wealth of information in the example files.  Just rendering each of them,
>and then examining the source code, is in itself an excellent tutorial.
>It is well worth the time.  But many of the questions posted by users
>to these groups reveal that it is not a sufficiently exploited resource.
>
>You can lead a horse to water....
>
>Dan

OK point taken, but  rendering the example files takes time and they
are not necessarily relevant to the problem you have in hand.  A
textual guide to the example files would help a great deal.

I have just rendered (again) all four of  the examples in scenes\CSG
and find that they emphasise interesting textures rather than clearly
showing the way that CSG operations can be used.  This just helps to
convince me that an objective look at on improving documentation would
be well worthwhile.

I don't want to criticise POV-Ray developers who are doing a
magnificent job - for which I am sincerely grateful. I just believe
that the POV-Ray community could help to make POV-Ray even more
accessible.  If, for instance, each contributed something of  their
own particular expertise, perhaps by a simplified and well commented
example, it would be a great help to many of us.

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

David Wilkinson wrote:
>
> I have just rendered (again) all four of  the examples in scenes\CSG
> and find that they emphasise interesting textures rather than clearly
> showing the way that CSG operations can be used.  This just helps to
> convince me that an objective look at on improving documentation would
> be well worthwhile.


Okay -- there is room for improvement.  But examples of CSG are
spread throughout the examples.  It is perhaps ironic that the
CSG directory may be below average in its use of CSG :).

You are correct that there is a strong emphasis in the examples
of simpler models with more complex texturing.  The "advanced" directory
is fancier, though -- excellent CSG work can be found in the
fish example and the chess example.

Still, these examples are not extremely well organized.  A coherent
framework might prove useful.

I will, however, bow out of this discussion, leaving it to those willing
to volunteer their time and effort to do the work.  I'd rather concentrate
my efforts elsewhere.

Dan

Post a reply to this message

On Sun, 27 Dec 1998 14:16:08 GMT, dav### [at] mcmailcom (David
Wilkinson) wrote:

>On Sat, 26 Dec 1998 18:30:55 -0800, Ken <tyl### [at] pacbellnet> wrote:
>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. 

As a frustrated denizen of povray.programming, I have to say that
.documentation would be a singularly bad name for a group.  Worse
then .programming.  Unless you want to spend all your time answering
questions about the existing docs.

Post a reply to this message

Ronald L. Parker wrote:
> 
> On Sun, 27 Dec 1998 14:16:08 GMT, dav### [at] mcmailcom (David
> Wilkinson) wrote:
> 
> >On Sat, 26 Dec 1998 18:30:55 -0800, Ken <tyl### [at] pacbellnet> wrote:
> >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.
> 
> As a frustrated denizen of povray.programming, I have to say that
> .documentation would be a singularly bad name for a group.  Worse
> then .programming.  Unless you want to spend all your time answering
> questions about the existing docs.

  I agree. The two tutorial groups that are already in exsistence
would serve the purposed project well.

-- 
Ken Tyler

tyl### [at] pacbellnet

Post a reply to this message

Ken wrote:
> 
> 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 !!!

Late breaking addition to the wish list:

12. Blobs !!!

-- 
Ken Tyler

tyl### [at] pacbellnet

Post a reply to this message

Twyst wrote in message <3681705a.0@news.povray.org>...
>I had a great idea recently...
>
>Do a "User Documentation Project"!
>
>I had the idea while noticing that the Pov-Ray docs, while complete, didn't
>go into much detail in certain cases, and there are people that DO know
>certain aspects very well. (John VanSickle comes to mind....).
>
>It seems to me that much of the manual could do with expanding on topics
>(Media is one example) and tutorials.
>
>So, here's the complete idea:
>1. With the pov-team's permission (please, can we?), rewrite the pov-ray
>docs.
>2. Make it available in a number of formats, from plain text to PDF format.
>3. I would ALSO like to be able to publish a spiral bound volume, and sell
>it at a minimal cost.
>4. I intend for this to be a "group" project. It's a daunting task for a
>single person.




My bad. I forgot to mention that I'm not in this for the money. Any profits
that would come out of this, would A) go to pay for publishing, and B) go to
the pov-team, for stuff like webspace (Don't want another scare, now, do
we?)


Twyst

Post a reply to this message