Am 19.05.2011 05:06, schrieb SGeier:

>> clipped_by is implemented as follows:
>>
>> (1) The base object's intersection(s) with the ray are determined;
>>
>> (2) for each intersection it is checked whether it is inside the
>> clipped_by object.
>>
>> Any intersections not reported by step (1) are ignored.
>
> Good to know that this is how it is implemented. However this is NOT how it
> is documented. Put the above paragraph into the documentation and
> implementation and documentation are in agreement.

If you think the documentation is bad, then you're happily invited to 
help make it better.

It's not like the developers & other people helping with POV-Ray would 
be paid anything for it; our only payment is the joy of doing it (and 
every programmer knows that implementation work is more fun than writing 
documentation), the joy of seeing people get good results of it, and the 
joy of receiving some motivating feedback from the community now and then.

So if you /want/ anything from us, or want to /insist/ on some point of 
view that the dev team does not share, you're in the wrong place.

> I would hope so - that's why I post things here that do not work as
> documented.

It's one thing to get feedback on things that people /think/ is wrong. 
Getting feedback from someone who /knows better/ (or at least sounds 
like that) is something entirely different.

> There's a perennial communications problem between programmers and users: To
> the programmer, the code is the end-all and be-all. Whatever the code does
> is "true" and if the documentation deviates from it, then the documetation
> is wrong. However from the user perspective, the documentation is all there
> is - it tell me what is *supposed* to happen and if the observed results are
> different then the code is buggy.

No. To the programmer, the /intention/ is the end-all and be-all. If the 
code fails to match that, it is buggy. If the documentation fails to 
match that, it is either wrong (making an explicit statement that is not 
true), incomplete (failing to make an explicit statement that is true 
bot not necessarily obvious to the user), or imprecise (making a 
statement that can be interpreted in a way that is true, but also in 
another way that is not).

In this particular case, the documentation is /incomplete/, but not 
wrong: It does /not/ make an explicit statement about the situation you 
encountered. It does however make a statement about similar situations 
with CSG, which /might/ give resourceful users a hint what's going wrong 
with regard to clipped_by.


BTW, to the end user, the /expectation/ is the end-all and be-all; the 
documentation can only serve to modify those expectations. So if some 
docs do not explicitly mention the program's behaviour in a very rare 
situation, who is outright /wrong/: The documentation, or the user's 
expectations? I dare say the latter, because the docs simply cannot 
foresee all that a user may expect.

Also note that in real life there is no such thing as a /complete/ 
documentation.

> If the wording in the docs leads the reader to expect behaviour different
> from what is implemented, then the wording is far enough from ideal that we
> might as well call it false.

I disagree in some points:

(1) The docs do not /lead/ the reader to expect behaviour different from 
what is implemented in this case. It is /your/ expectation, and all you 
can blame the documentation for is that it did not /lead you away/ from 
that expectation. Provided that you even gave it a chance to do so, by 
thoroughly reading the isosurfaces doc section.

(2) I guess that careful reading of the doc section on isosurfaces 
/will/ lead the majority of readers away from that expectation, at least 
to the degree that they're not too surprised when their original 
expectation proves wrong.

(3) My definition of a "false" documentation is more strict than yours 
seems to be. In my terminology, "incomplete" or "imprecise" is not 
necessarily "false".


> If that is "as intended", then this intention needs to be communicated (in
> the docs, not here).

(4) There is no /need/ to communicate the programmers' intentions to the 
users. It's probably /helpful/, but there is no such /obligation/ to the 
dev team - neither legally (see the license) nor morally (what you get 
from the dev team is a free gift, and you can either take it or leave 
it, and there's nothing you can /demand/ on top).

Post a reply to this message

"Thorsten Froehlich" <tho### [at] trfde> wrote in message 
news:4dd41abd@news.povray.org...
> On 18.05.11 21:00, SGeier wrote:
>
> It certainly helps to read the documentation when being pointed to it, 
> rather than complain about being helped

It /also/ certainly helps to try a non-functioning case of code when being 
pointed to it, rather than complain about being helped. Because that's what 
*I'm* doing when I point out things that don't work: help you. By either 
alerting you to buggy code (code that does not work as intended) or buggy 
documentation (documentation that does not communicate how things are 
intended to work).

>... add all_intersections and just be happy.

Why don't you try it yourself?

Seriously: Why not?

I gave you the best bug-report I can think of writing; with a few discrete 
steps where I describe at each step why I am taking it, what I expect to see 
and what I actually see.

What do I have to do to motivate you to simply follow along with my example, 
see for yourself where things stop working - and then enter that line and 
see it /start/ working. Wouldn't that give you satisfaction? Why are you so 
afraid of simply trying it? What do you have to lose here?

Let me save you typing effort and reproduce the whole file so you can just 
cut/paste it:

// --------------------start here
  #version 3.7;
  global_settings { assumed_gamma 2.2 }

  camera{ location 5 look_at 0 right x*4/3 }
  light_source{<2,4,8>, <1, .8, .6> }

  sky_sphere {pigment {gradient -y}}

  #declare clipper = difference {box {-2 2} box {<0,-3,0> 3}}

  isosurface{function{ sqrt(x*x+y*y+z*z) }
        threshold 2 max_gradient 100 contained_by{ box {-5 5} }
          clipped_by { clipper }
          pigment {rgb 1}
          all_intersections
        }
//--------------------end here

See: I have the best documentation there is: the program itself. Whatever 
the program does is whatever it does. You may /imagine/ that you know it 
better than me, but I've actually looked at it. I get to see the actual 
binary, produced by compiler 'x', using library 'y' interacting with OS 'z'. 
(OS'es are Windows Server.03 32bit and and Server.08 64bit just in case 
anybody really cares).

Post a reply to this message

Am 19.05.2011 20:47, schrieb SGeier:

> Let me save you typing effort and reproduce the whole file so you can just
> cut/paste it:
>
> // --------------------start here
>    #version 3.7;
>    global_settings { assumed_gamma 2.2 }
>
>    camera{ location 5 look_at 0 right x*4/3 }
>    light_source{<2,4,8>,<1, .8, .6>  }
>
>    sky_sphere {pigment {gradient -y}}
>
>    #declare clipper = difference {box {-2 2} box {<0,-3,0>  3}}
>
>    isosurface{function{ sqrt(x*x+y*y+z*z) }
>          threshold 2 max_gradient 100 contained_by{ box {-5 5} }
>            clipped_by { clipper }
>            pigment {rgb 1}
>            all_intersections
>          }
> //--------------------end here
>
> See: I have the best documentation there is: the program itself. Whatever
> the program does is whatever it does. You may /imagine/ that you know it
> better than me, but I've actually looked at it. I get to see the actual
> binary, produced by compiler 'x', using library 'y' interacting with OS 'z'.
> (OS'es are Windows Server.03 32bit and and Server.08 64bit just in case
> anybody really cares).

You didn't actually /try/ the code you posted, did you? Otherwise you'd 
have noticed that above code does not support your point at all, but 
instead just gives a parse error.

all_intersections needs to go before the clipped_by statement. That, by 
the way, is in the docs, too.

Once you place all_intersections at the /right/ place everything /will/ 
be fine.

You're complaining that Thorsten did not try out the code you posted - 
but why should he, if he knows POV-Ray good enough (and yes, obviously 
better than you) that he's not in the least surprised, and can even tell 
you /why/ it is happening? (Besides, what makes you so sure that he 
didn't try it?)

Post a reply to this message

"clipka" <ano### [at] anonymousorg> wrote in message 
news:4dd5a5ed$1@news.povray.org...
> Am 19.05.2011 20:47, schrieb SGeier:
>
>> Let me save you typing effort and reproduce the whole file so you can 
>> just
>> cut/paste it:
>>
>> // --------------------start here
>>    #version 3.7;
>>    global_settings { assumed_gamma 2.2 }
>>
>>    camera{ location 5 look_at 0 right x*4/3 }
>>    light_source{<2,4,8>,<1, .8, .6>  }
>>
>>    sky_sphere {pigment {gradient -y}}
>>
>>    #declare clipper = difference {box {-2 2} box {<0,-3,0>  3}}
>>
>>    isosurface{function{ sqrt(x*x+y*y+z*z) }
>>          threshold 2 max_gradient 100 contained_by{ box {-5 5} }
>>            clipped_by { clipper }
>>            pigment {rgb 1}
>>            all_intersections
>>          }
>> //--------------------end here
>>
>> See: I have the best documentation there is: the program itself. Whatever
>> the program does is whatever it does. You may /imagine/ that you know it
>> better than me, but I've actually looked at it. I get to see the actual
>> binary, produced by compiler 'x', using library 'y' interacting with OS 
>> 'z'.
>> (OS'es are Windows Server.03 32bit and and Server.08 64bit just in case
>> anybody really cares).
>
> You didn't actually /try/ the code you posted, did you?

Yes, I did. Noting that this doesn't work.

> Otherwise you'd have noticed that above code does not support your point 
> at all, but instead just gives a parse error.

Indeed, it does. Which I noticed. Which is why I was trying to coax Thorsten 
Froehlich into trying his own suggestion. Which was this:

> add all_intersections and just be happy.

Which does not work. Thank you for trying it. Thank you for noticing that 
*the advice given by people who know the program so well DOES NOT WORK*.

> all_intersections needs to go before the clipped_by statement.

Thank you for pointing that out. Always pleased to learn something.

> That, by the way, is in the docs, too.

No, it is not.

This is exactly where our views on the documentation differ drastically. 
Yes, now that you mention it, I can see how one *could* read the 
documentation such as to suggest that. However it *definitely* does not 
contain the sentence

"all_intersections needs to go before the clipped_by statement."

or any sentence anywhere close to it.

Here's what section 3.4.4 of the documentation shipping with the windows 
verion *actually* says:
isosurface {
  function { FUNCTION_ITEMS }
  [contained_by { SPHERE | BOX }]
  [threshold FLOAT_VALUE]
  [accuracy FLOAT_VALUE]
  [max_gradient FLOAT_VALUE]
  [evaluate P0, P1, P2]
  [open]
  [max_trace INTEGER] | [all_intersections]
  [OBJECT_MODIFIERS...]
  }
This tells me that a number of items can occur inside the isosurface{} 
entity. For example [threshold ...] or [contained_by ...] and a whole class 
of [object modifiers]. Nowhere in the docs is any mention that their order 
matters in any way and as a matter of fact some of the examples in the 
tutorial have them in an order different from the above.

If the [object modifiers] have a special status here, in that they *have* to 
be at any one particular place (at the end), then that needs to be spelled 
out. If it isn't spelled out, then you cannot claim that it is in the docs.

Here is a place where the documentation might not be in direct contradiction 
with the behavior of the program, but the program certainly doesn't behave 
as documented. [all_intersections] can apparently go anywhere it wants in 
that list up there *except* after [object modifiers] -- and users are 
supposed to magically know that even though it is definitely NOT written 
anywhere.

And when someone like myself complains about the documentation we're being 
told that we should improve it. But of course we *cannot* improve it since 
there is no way to find out what the real behaviour actually *is*, since the 
documentation doesn't mention it and asking on usenet gets me helpful advice 
like

> add all_intersections and just be happy.

which I had seen, tried, and noticed it didn't work. So I figured that 
something changed since the docs were written, so I post here.

So it turns out the whole thing was *really* not about clipping at all, all 
the blah-blah about reading the documentation on clipping and max_trace and 
all_intersections was completely besides the point. Apparently neither you 
nor Thorsten had the slightest idea what was wrong, you just immediately 
assumed that *obviously* I hadn't read the documentation and *obviously* you 
know exactly what's going on, no need to actually investigate anything or 
think about anything.

Cool, so there's nothing wrong with the binary, it's the documentation that 
is unclear. Good to know.

Now why is it like pulling teeth to get someone to actually come out and 
examine things and state these things here on the ng? Until I posted the few 
lines there in toto, nobody around here had even *tried* to diagnose what my 
problem might be -- you all just assumed you knew exactly what the problem 
was (and it turned out to be somewhere else).

> You're complaining that Thorsten did not try out the code you posted - but 
> why should he, if he knows POV-Ray good enough (and yes, obviously better 
> than you) that he's not in the least surprised, and can even tell you 
> /why/ it is happening? (Besides, what makes you so sure that he didn't try 
> it?)

Because his answer "add this line to your SDL and it'll all work" did NOT 
work. Either he doesn't know POV-Ray as well as you both think, or he knows 
it *too* well, where he's not stating what assumptions *he* is making (which 
is exactly what I find myself accused of).

Post a reply to this message

"clipka" <ano### [at] anonymousorg> wrote in message 
news:4dd541fb@news.povray.org...
> Am 19.05.2011 05:06, schrieb SGeier:
>
> If you think the documentation is bad, then you're happily invited to help 
> make it better.

I am honestly not being facetious when I (honestly, serious!) ask: How is 
that supposed to work, when I don't know how POV-Ray works? I look into the 
documentation when something doesn't work as I expect. I learn something, 
try something, and realize it doesn't work as written in the docs either. 
How on earth am I supposed to now suddenly write better docs?

I've been poking my head into POV-Ray for several years now - I d/l the 
current version, I tinker with it, I give up. Because every time I run into 
the same kinds of problems that aren't documented and when I ask about them 
nobody takes the time to examine what was communicated how in the docs and 
when I complain about the docs I'm being told that I'm free to make them 
better. But how should I do that, when I don't even understand some very 
basic, simple things about POV-Ray *because they're not documented*?

You really think those who don't know how POV-Ray works wil create better 
documentation than those who do know it?

> It's not like the developers & other people helping with POV-Ray would be 
> paid anything for it; our only payment is the joy of doing it (and every 
> programmer knows that implementation work is more fun than writing 
> documentation), the joy of seeing people get good results of it, and the 
> joy of receiving some motivating feedback from the community now and then.

I've been writing (and giving away) code since the eighties, I understand 
that joy. But I also understand that the chance of "seeing people get good 
results of it, and the joy of receiving some motivating feedback from the 
community" increases when people actually have chance to use my creations --  
which requires clear, unambiguous documentation. In which someone can find 
what they're looking for.

Otherwise you've created a magic binary that people *cannot* get good 
results from.

I understand well, that in the end you're just hurting yourself by not 
taking the opportunity to take every post to these ng as an opportunity to 
ask "how should we have written the answer to this in the docs and where did 
you look for it". But exactly *because* I've written my share of software, 
it frustrates me to no end that there's something here that seems pretty 
solid enough and appears to be getting better every time I look -- but it 
will never be something I use in any serious way, because nobody who knows 
the inner workings can be bothered to write down what is actually going on 
in this piece of code.

> No. To the programmer, the /intention/ is the end-all and be-all. If the 
> code fails to match that, it is buggy. If the documentation fails to match 
> that, it is either wrong (making an explicit statement that is not true), 
> incomplete (failing to make an explicit statement that is true bot not 
> necessarily obvious to the user), or imprecise (making a statement that 
> can be interpreted in a way that is true, but also in another way that is 
> not).

It's all fine that you have all these fine levels of gradation in which 
documentation fails. To the end-user, however, they make no difference: As 
Feynman said "if it disagrees with experiment, it's wrong".

But OK: so the documentation is "incomplete". Yet nobody is changing it. 
Instead *I* have been asked to improve on it - even though I have no idea of 
the very things that made me post here in the first place. It would be great 
if every post to these ng was taken as an opportunity to improve your 
stuff -- but if you don't want to do that, then why bother in the first 
place? Why even have these ng?

Once you posted the order in which the intersection test and clipping 
happen, that side of POV-Ray's behaviour was clear to me. So why haven't you 
put that explanation into the docs yet? Yes, I could try to do it myself, 
but I'd only mess it up in some subtle way since I only heard of it the 
first time yesterday (or whenever I read your reply).

> BTW, to the end user, the /expectation/ is the end-all and be-all; the 
> documentation can only serve to modify those expectations. So if some docs 
> do not explicitly mention the program's behaviour in a very rare 
> situation, who is outright /wrong/: The documentation, or the user's 
> expectations? I dare say the latter, because the docs simply cannot 
> foresee all that a user may expect.
>
> Also note that in real life there is no such thing as a /complete/ 
> documentation.

Actually, there is: the program as shipped is the final documentation. If 
you aren't sure about something, feed it to the program and see what 
happens. Whatever that is, that's how this program works.

Much of that can be predicted if you know the source, some details may hinge 
on details in some library or the compiler or OS. If someone says "just add 
all_intersections" and I add all_intersections and the result is a 
parse-error, then the advice was wrong. You may niggle over "incomplete" or 
"imprecise" or whatever, but when everything is said and done, following the 
advice to the dot leads to a parse error. *correct* advice solves my 
problem. *good* advice is like much of what you've been doing: pointing out 
what's wrong and where and how.

[...]
>> If that is "as intended", then this intention needs to be communicated 
>> (in
>> the docs, not here).
>
> (4) There is no /need/ to communicate the programmers' intentions to the 
> users. It's probably /helpful/, but there is no such /obligation/ to the 
> dev team - neither legally (see the license) nor morally (what you get 
> from the dev team is a free gift, and you can either take it or leave it, 
> and there's nothing you can /demand/ on top).

The concept of "need" is always tied to a purpose of some sort: in order to 
achieve X you *need* to Y.

If, to the programmers, the intent is the end-all be-all (as you claimed, 
and as I'm happy agreeing with) and if the programmers hope that people will 
get good use out of their producs (as you maintain and as I have no quarrels 
agreeing with) then they *need* to document their intent.

You are the only one here construing any kind of legal or moral dimension to 
the term "need".

Post a reply to this message

"SGeier" <som### [at] somewherecom> wrote:
> Here's what section 3.4.4 of the documentation shipping with the windows
> verion *actually* says:
> isosurface {
>   function { FUNCTION_ITEMS }
>   [contained_by { SPHERE | BOX }]
>   [threshold FLOAT_VALUE]
>   [accuracy FLOAT_VALUE]
>   [max_gradient FLOAT_VALUE]
>   [evaluate P0, P1, P2]
>   [open]
>   [max_trace INTEGER] | [all_intersections]
>   [OBJECT_MODIFIERS...]
>   }
> This tells me that a number of items can occur inside the isosurface{}
> entity. For example [threshold ...] or [contained_by ...] and a whole class
> of [object modifiers]. Nowhere in the docs is any mention that their order
> matters in any way and as a matter of fact some of the examples in the
> tutorial have them in an order different from the above.

Actually, you misread the grammar: As there is no "|" between the
isosurface-specific modifiers and the "[OBJECT_MODIFIERS...]", the grammar
clearly states that putting "all_intersections" after "[OBJECT_MODIFIERS...]" is
not possible.

BTW, that you find at http://www.povray.org/documentation/view/3.6.1/214/  ;-)

    Thorsten

Post a reply to this message

"clipka" <ano### [at] anonymousorg> schreef in bericht 
news:4dd5a5ed$1@news.povray.org...
> all_intersections needs to go before the clipped_by statement. That, by 
> the way, is in the docs, too.

In all fairness, and without wanting to further the debate, this is neither
in the docs, nor in the tutorials. Well, at least I did not find it. Neither
is clipped_by mentioned by the way, in the isosurface section, so the error
seems very comprehensible to me.

The logical stream of thought probably is that contained_by and clipped_by
are equivalent (which they are not?) and as contained_by is mentioned before
all_intersection in the docs....

No need to hone the sabers now  ;-)

Thomas

Post a reply to this message

[after reading Thorten's message above]
... and which shows, there is a semantic problem, difficult to solve in 
fact. Increased by the number of non-native speakers among us.. I have the 
impression that many people (me included) not always realise that Object 
Modifiers is much more than just transformations. :-)  The contained_by in 
isosurfaces is also an object modifier, strictly speaking.

I think that in this case, there should be a little sentence in the docs 
just stressing that all isosurface parameters have to be placed *before* 
any object modifier.

I hope this helps....

Thomas

Post a reply to this message

On 05/20/2011 04:46 AM, Thomas de Groot wrote:
> [after reading Thorten's message above]
> ... and which shows, there is a semantic problem, difficult to solve in
> fact. Increased by the number of non-native speakers among us.. I have the
> impression that many people (me included) not always realise that Object
> Modifiers is much more than just transformations. :-)  The contained_by in
> isosurfaces is also an object modifier, strictly speaking.
>
> I think that in this case, there should be a little sentence in the docs
> just stressing that all isosurface parameters have to be placed *before*
> any object modifier.
>
> I hope this helps....
>
> Thomas
>
>
ah ... finally something of substance! (instead of all this childish 
posturing) I added a "Note" just after the syntax diagram:

http://wiki.povray.org/content/Documentation:Reference_Section_4.2#Isosurface_Object

oh and btw the clue that clipped_by is indeed an object modifier is in 
the first sentence:

http://wiki.povray.org/content/Documentation:Reference_Section_4.5#Clipped_By

Post a reply to this message

"Thorsten Froehlich" <nomail@nomail> wrote:
> "SGeier" <som### [at] somewherecom> wrote:
> > Here's what section 3.4.4 of the documentation shipping with the windows
> > verion *actually* says:
> > isosurface {
> >   function { FUNCTION_ITEMS }
> >   [contained_by { SPHERE | BOX }]
> >   [threshold FLOAT_VALUE]
> >   [accuracy FLOAT_VALUE]
> >   [max_gradient FLOAT_VALUE]
> >   [evaluate P0, P1, P2]
> >   [open]
> >   [max_trace INTEGER] | [all_intersections]
> >   [OBJECT_MODIFIERS...]
> >   }
> > This tells me that a number of items can occur inside the isosurface{}
> > entity. For example [threshold ...] or [contained_by ...] and a whole class
> > of [object modifiers]. Nowhere in the docs is any mention that their order
> > matters in any way and as a matter of fact some of the examples in the
> > tutorial have them in an order different from the above.
>
> Actually, you misread the grammar: As there is no "|" between the
> isosurface-specific modifiers and the "[OBJECT_MODIFIERS...]", the grammar
> clearly states that putting "all_intersections" after "[OBJECT_MODIFIERS...]" is
> not possible.
>
> BTW, that you find at http://www.povray.org/documentation/view/3.6.1/214/  ;-)
>
>     Thorsten


I just tried max_gradient before threshold. The scene did not bomb out in the
way that putting all_intersections in the wrong place does. His point is valid.

Post a reply to this message