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

"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

"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

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

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

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

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

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

"clipka" <ano### [at] anonymousorg> schreef in bericht 
news: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 am sure I agree with you here. What I mean to say is that - for the 
layman - contained_by is looked upon in the same way as an 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?

Well, it seems I am not one of those lucky ones who know the docs perfectly 
:-)  Your point is well taken, only I had never really thought about it in 
that way, and I suppose many are in the same position as me...

I think this whole discussion is not useless. We all learned something 
essential it seems. Hurray!  :-)

Thomas

Post a reply to this message

Have the clocks gone back 10 years?
Have we returned to the days where the simplest question was met by RTFM?

I thought that we had developed into a nice community not one that 

Post a reply to this message