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

On 20.05.11 09:46, 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.

Actually, this rule applies to many object modifiers in other objects as 
well. It is not a unique behavior in isosurfaces. And it is documented.

	Thorsten

Post a reply to this message

On 20.05.11 13:06, gregjohn wrote:
> "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.

Your logic is broken - saying that the negation of my statement yields no 
error is not the same as what I said. Sorry.

	Thorsten

Post a reply to this message