|
|
|
|
|
|
| |
| |
|
|
From: Thorsten Froehlich
Subject: Re: Is this a bug in 3.7RC3 ? Or am I missing something?
Date: 20 May 2011 07:26:01
Message: <4dd64fc9@news.povray.org>
|
|
|
| |
| |
|
|
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
|
|
| |
| |
|
|
From: Thorsten Froehlich
Subject: Re: Is this a bug in 3.7RC3 ? Or am I missing something?
Date: 20 May 2011 07:32:23
Message: <4dd65147@news.povray.org>
|
|
|
| |
| |
|
|
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
|
|
| |
| |
|
|
From: Thorsten Froehlich
Subject: Re: Is this a bug in 3.7RC3 ? Or am I missing something?
Date: 20 May 2011 07:39:38
Message: <4dd652fa$1@news.povray.org>
|
|
|
| |
| |
|
|
On 20.05.11 12:14, Jim Holsenback wrote:
> 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
Jim, please remove the note as it is superfluous and does not document
anything special in isosurfaces that does not exist in other objects as
well. The better place to improve is the grammar explanation section (the
equivalent of http://www.povray.org/documentation/view/3.6.1/214/ ). It is
not all that obvious for non-programmers and very brief.
> 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
I would say this is more than a hint - after all, it is a subsection of the
"object modifiers" section :-)
Thorsten
Post a reply to this message
|
|
| |
| |
|
|
From: Thomas de Groot
Subject: Re: Is this a bug in 3.7RC3 ? Or am I missing something?
Date: 20 May 2011 07:40:38
Message: <4dd65336$1@news.povray.org>
|
|
|
| |
| |
|
|
"Thorsten Froehlich" <tho### [at] trfde> schreef in bericht
news:4dd64fc9@news.povray.org...
> 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.
You are certainly right, but as it does not *always* apply, an extra note is
not superfluous here and there. Never take for granted that everything is
obvious for the layman ;-)
As I implied before, it is often a matter of semantics, and we try to tend
towards perfection, which is impossible... but we try, we try!
Thomas
Post a reply to this message
|
|
| |
| |
|
|
From: Thomas de Groot
Subject: Re: Is this a bug in 3.7RC3 ? Or am I missing something?
Date: 20 May 2011 07:50:18
Message: <4dd6557a$1@news.povray.org>
|
|
|
| |
| |
|
|
"Jim Holsenback" <jho### [at] povrayorg> schreef in bericht
news:4dd63f14$1@news.povray.org...
> ah ... finally something of substance! (instead of all this childish
> posturing)
<grin>
> 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
Yes, no doubt about that. It is mainly the fact that you have to be careful
where to place those object modifiers which can be a problem (or not) as it
doesn't always generate a parse error, and sometimes it might just generate
unexpected results I guess.
Poll (not serious): Who knows all the docs content (and their cross-links)
by heart?
Thomas
Post a reply to this message
|
|
| |
| |
|
|
From: clipka
Subject: Re: Is this a bug in 3.7RC3 ? Or am I missing something?
Date: 20 May 2011 07:55:33
Message: <4dd656b5@news.povray.org>
|
|
|
| |
| |
|
|
Am 20.05.2011 03:56, 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're surprised, you ask, you learn, you document what you learned so
that others don't need to ask again. That's how it /could/ work.
The dev team is not constantly skimming through the docs with the eyes
of a new user (how could they!) searching for stuff that's poorly
documented.
Nor does the dev team have an abundance of energy to work on the docs.
Jim is doing a great work on that, but he has a life, too. Essentially
we need people who not only /find/ flaws in the docs, but also /fix/ them.
Another thing that should be noted is that the dev team has changed a
lot over the lifetime of POV-Ray so far; some members left, others went,
and various people outside the official dev team contributed code and/or
documentation. There are things in both the docs and the code the
current dev team does /not/ know by heart.
> You really think those who don't know how POV-Ray works wil create better
> documentation than those who do know it?
That may well be. Software authors who know how their software works
tend to take some things for granted that new users possibly won't.
They're also prone to language that a fellow programmer might
understand, but an artistically oriented user may possibly not.
> 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.
... and I bet you've always supplied a correct, error-free, complete and
end-user-friendly documentation, huh?
If you did, then congrats - you might be the type of person we could
need help from.
> Otherwise you've created a magic binary that people *cannot* get good
> results from.
Well, the source code is there to have a look at, too (and even toy
around with). It's the most precise documentation we cold ever ask for.
(Unfortunately it's not very end-user-palatable.)
> 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.
You know, I have my own approach at things that frustrate me.
A while ago it frustrated me as a POV-Ray end user that while POV-Ray
3.7 beta (I think it was beta 28 or 29) could make use of multiple
cores, it couldn't do so for radiosity.
Knowing that the dev team was pretty busy, I decided to give it a try
and invest some of my /own/ energy into /making/ it use multiple cores
for radiosity.
I did. Previously I had only vague ideas of how POV-Ray worked at its
core, how radiosity worked, and so forth. I invested the energy to
/learn/ how it worked, in order to fix what was frustrating me. Yes, I
did my own share of ranting over the existing radiosity code as I dug
deeper into it - but at the same time I busied myself fixing it.
So pointing out flaws is one thing - ranting about them without adding
anything more helpful is a different thing.
> 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?
Believe me - we /want/ the documentation improved. We just don't have
the energy ourselves at present. There's other things that have priority
(for us as a dev team) over fixing stuff in the docs that hasn't changed
at all from 3.6 to 3.7.
> 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).
I'm not doing it myself because I'm poor at writing end-user docs; being
pedantic as I am, I find it difficult to find a proper balance between
precision and legibility, so it costs me a lot of energy to do such doc
changes. I have a much easier time explaining things to individual
people than to a broad anonymous audience. And if we'd be talking about
a technical specification, where precision is all that matters, I'd have
a much easier time.
> 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.
So Thorsten's advice was "incorrect" because he simply wrote "just add
all_intersections" rather than "just add all_intersections where it fits
according to the documented isosurface syntax"? Great. I prefer to disagree.
Post a reply to this message
|
|
| |
| |
|
|
From: clipka
Subject: Re: Is this a bug in 3.7RC3 ? Or am I missing something?
Date: 20 May 2011 08:43:48
Message: <4dd66204@news.povray.org>
|
|
|
| |
| |
|
|
Am 20.05.2011 03:12, schrieb SGeier:
>> 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.
Yes, it is.
> 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.
It does explicitly specify it in the section you quoted:
> 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.
Read section 3.1.1 "Notation and Basic Assumptions"; nowhere in there
does it say that the items can be specified in arbitrary order, so it's
your assumption that is wrong again here. The fact that /some/ of the
stuff can be re-ordered is, as a matter of fact, a feature documented
elsewhere.
See sections 3.8 "Quick Reference" for a description of the notation
used for the syntax specification, and section 3.8.8.4 "Isosurface" for
the description of the isosurface syntax. There you will find that
ISOSURFACE_ITEMS (including all_intersections) may be specified in
arbitrary order, but must go before OBJECT_MODIFIERS.
> 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
(As you seem to like precision, please note that we're not on usenet;
we're on a private news server.)
>> 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.
Thorsten knew /exactly/ why the stuff was happening that you saw, and I
myself didn't post a reply until I had figured it out as well. (Believe
me, while as a matter of fact I often /do/ start writing responses to
reports of possible errors before checking it out, I virtually never
press "send" before I checked that I'm not talking nonsense.) The only
thing unclear was why you insisted it was an error.
> 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?
Maybe because with your originally posted code we didn't need to examine
things, because your description matched the behaviour /we/ did expect?
> 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).
That was when your problem apparently shifted, from getting an
unexpected (for you) result from your originally posted code to some
rather vague complaint in connection with all_intersections (which you
hadn't mentioned earlier, so we all naturally assumed - and still assume
- you hadn't tried it).
So why are you surprised you're getting a more thorough inspection only
later? It's like you're phoning up the garage complaining to the
mechanic that the engine on your car stutters, and by the way there's a
red light in the display, looking somewhat like a fuel pump (*); not
surprisingly the mechanic will simply recommend to try and fill her up
(knowing that stuttering engines are to be expected when there's a lack
of fuel), but now you start complaining that the fuel pump doesn't fit
in the tank. It's probably only /then/ that the mechanic will consider a
more thorough inspection. (And as it turns out the problem is that you
tried to pump your diesel at a pump for heavy trucks, so you blame the
car manufacturer for failing to make a note of this incompatibility in
the car's user manual.)
(* I am well aware that the example limps here because usually those
lights are well documented. However, the fact that a car needs fuel to
drive is typically taken for granted.)
>> 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).
... or he knows some things mentioned in sections of the docs you didn't
read.
Post a reply to this message
|
|
| |
| |
|
|
From: clipka
Subject: Re: Is this a bug in 3.7RC3 ? Or am I missing something?
Date: 20 May 2011 08:48:51
Message: <4dd66333$1@news.povray.org>
|
|
|
| |
| |
|
|
Am 20.05.2011 09:46, schrieb Thomas de Groot:
> The contained_by in
> isosurfaces is also an object modifier, strictly speaking.
No, not really. Not according to how OBJECT_MODIFIERS is defined
syntactically.
> 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.
Note the same goes for /any/ object type: Object-type specific keywords
must go first, before any generic object modifiers. So do we need such a
sentence in the description of /all/ the primitives?
Post a reply to this message
|
|
| |
| |
|
|
From: clipka
Subject: Re: Is this a bug in 3.7RC3 ? Or am I missing something?
Date: 20 May 2011 08:51:31
Message: <4dd663d3$1@news.povray.org>
|
|
|
| |
| |
|
|
Am 20.05.2011 13:39, schrieb Thorsten Froehlich:
> On 20.05.11 12:14, Jim Holsenback wrote:
>> 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
>>
>
> Jim, please remove the note as it is superfluous and does not document
> anything special in isosurfaces that does not exist in other objects as
> well. The better place to improve is the grammar explanation section
> (the equivalent of http://www.povray.org/documentation/view/3.6.1/214/
> ). It is not all that obvious for non-programmers and very brief.
Maybe it would be good to use the same notation as in the quick
reference, using "&" to list items with arbitrary ordering.
Post a reply to this message
|
|
| |
| |
|
|
From: Thorsten Froehlich
Subject: Re: Is this a bug in 3.7RC3 ? Or am I missing something?
Date: 20 May 2011 09:12:58
Message: <4dd668da$1@news.povray.org>
|
|
|
| |
| |
|
|
On 20.05.11 14:51, clipka wrote:
> Am 20.05.2011 13:39, schrieb Thorsten Froehlich:
>> On 20.05.11 12:14, Jim Holsenback wrote:
>>> 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
>>
>> Jim, please remove the note as it is superfluous and does not document
>> anything special in isosurfaces that does not exist in other objects as
>> well. The better place to improve is the grammar explanation section
>> (the equivalent of http://www.povray.org/documentation/view/3.6.1/214/
>> ). It is not all that obvious for non-programmers and very brief.
>
> Maybe it would be good to use the same notation as in the quick reference,
> using "&" to list items with arbitrary ordering.
I think aligning the quick ref and the remainder of the documentation would
be a good idea. It is a lot of tedious editing required though :-(
Thorsten
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
|
|