"clipka" <ano### [at] anonymousorg> wrote in message 
news:4dd45e2b@news.povray.org...
> Am 18.05.2011 21:00, schrieb SGeier:
>
>> *IF* you are making reference to this sentence:
>>
>>    "By default POV-Ray searches only for the first surface which the ray
>> intersects. But when using an isosurface in CSG operations, the other
>> surfaces must also be found. Therefore, the keyword max_trace must be 
>> added
>> to the isosurface statement. It must be followed by an integer value.
>>
>> *THEN* I'd like to point out that this sentence is false:
>
> Well, actually it's not.
>
>> - The back-side of the isosurface IS the first surface the ray intersects
>> after the sphere is clipped.
>
> The catch is that the back side may be the first surface of the isosurface 
> /within the clipped_by object/ - but /not/ the first surface of the 
> isosurface /per se/ - which the ray intersects.
>
> 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.

[...]
>> Of course there is no reason why 3.7 should conform to the 3.6
>> documentation. Which makes it a bit disingenous to point people to the 
>> 3.6
>> docs when they ask questions about 3.7 regarding behaviour *that is
>> definitely in conflict with the 3.6 documentation*.
>
> That's quite a *bold* statement (in any sense, including typographic); 
> please be aware that /sometimes/ the developers do know POV-Ray better 
> than the average user ;-)

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

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.

I'm happy to go either way - but there IS still a mismatch between 
implementation and documentation here.

> I'd agree that Thorsten may not be the best diplomat - but technically 
> he's right: The behaviour you're observing may be surprising, but works as 
> intended.

To a user of POV-Ray it does not (can not) matter what the programmers 
*intended*. Unless you want every single one of us folks out here to come 
here and post so that you can explain every single one of us what you 
intended. The only thing that *can* matter to us is what is *documented*.

> Maybe the wording in the docs isn't ideal, but aside from that there's 
> nothing wrong.

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. No part of the documentation indicates that the 
back/inside of the isosurface object will be found when the outer clipping 
object is made visible (or the clipped object embedded into a transparent 
object or any such thing). In the case of the sphere object, it is visible 
in both cases, in the case of the isosurface object it is visible in the 
one, but not the other case.

If that is "as intended", then this intention needs to be communicated (in 
the docs, not here).
Which it isn't.

Post a reply to this message