Am 26.05.2011 05:15, schrieb SGeier:
> "clipka"<ano### [at] anonymousorg>  wrote in message
> news:4ddc4488$1@news.povray.org...
>> Am 24.05.2011 03:21, schrieb SGeier:
>>> No, it is not an assumption. It is an *observation*.
>>
>> It's an observation that /some/ items can be specified in arbitrary order
>> (and as a matter of fact happens to be true for all non-OBJECT_MODIFIER
>> items). However, it was only your /assumption/ that it was also true for
>> /all/ items including OBJECT_MODIFIER elements.
>
> When I *should* have assumed that it is true for all items *except*
> object_modifiers?
>
> Seriously?
>
> You *document* (in words) that there's a bunch of parameters and you
> *document* (by example) that they can be used in different order but there's
> a problem with *my assumption* because I didn't expect *undocumented*
> exceptions to *documented* behaviour?
>
> Maybe you should take a step back yourself and ask yourself what you imagine
> you're accomplishing with this bullshit.

Trying to accomplish? I guess I'm trying to show you that the language 
you choose does not fit the bill. For one, it is not nearly as precise 
as you'd like the docs to be.

For instance, what I'm saying is that the docs are not /wrong/ (on the 
matter at hand), but only /imprecise/ or /incomplete/ - possibly even 
/misleading/. Your /assumptions/, on the other hand, /are/ (or were) 
wrong. It doesn't matter why that is: Wrong assumptions /are/ wrong 
assumptions, and therefore should be corrected.

> Here's one thing I definitely want from the dev team: Stop lying.

Here's another one of your imprecise choices of words: In my book, 
"lying" means /deliberately/ deceiving someone else. It does /not/ cover 
the full range of "saying something which is wrong". Therefore, your 
above sentence constitutes a severe (and wrongful) insult; I leave it up 
to you how you deal with this, but an apology would be welcome.

Further, I'd like you to have a look around again: Which member of the 
dev team is still - as you call it - "lying" to you in this thread about 
the doc contents?

> Neither
> the program nor the docs nor me nor you benefit from post after post after
> post of claims of this-or-that things that are allegedly "clearly
> documented" that nobody can *show* or *point to* because they *doesn't
> exist*.

Neither do your heated responses help.

> 3) The POV-Ray documentation is
>     *one* *hairy* *clusterfuck*
>    (pardon the language, I already toned this down)
>
> [...]
>
> The reason for this sorry state is
>
> 2) The POV-Ray Scene Description Language is
>      *one* *hairy* *clusterfuck*
>
> [...]
>
> Abnd the reason for *that* is
>
> [...]

Thanks for making your opinion pretty clear. You don't like POV-Ray, or 
the state it is in, or the way it is being developed? Then take it or 
leave it. But do us a favor and stop your ranting, either way.

#3 and #2 are, by the way, well known to the dev team (they'd use a more 
neutral - and more constructive - language though, something like "needs 
a major overhaul"). Matter of fact is that a re-write of the parser is 
on the agenda, including changes to the SDL where necessary, with the 
main goal of separating the existing "hairy clusterfuck" into (a) a core 
language and (b) a kind of "DOM".


> #3 could be massively improved by the developers if only they could be arsed
> to actually *look* at the documentation. Not tell people "xyz is in the
> docs", which doesn't help anybody. Half the time is is NOT in the docs, and
> the other half the correct response is "where in the docs did you look and
> how did you interpret this-or-that sentence" and then move the information
> that people are looking for where people expect it.
>
> There's nothing wrong with the line
>     objectName {mandatoryItems [optional items in any order] [object
> modifiers in any order]}
>
> Why is that line not in the docs?

Maybe because nobody has put it in there?
There are a lot of lines that could help if they were in the docs, yet 
aren't. So, you'll start abusing the dev team again when you find the 
next such case?

As I mentioned before, the dev team currently does not have much surplus 
time and/or energy to tackle such things.

> Why is there *nothing* in the docs that
> simply documents what the parser expects and when and where?

There is, it is called quick reference, and no, it is probably not 
perfect either, but your statement that there is *nothing* in the docs 
is outright wrong (a lie in your terminology).

> Simple exercise: Create a document that brings someone up-to-speed who's
> never touched POV-Ray and wont be able to get back to you to ask questions.
> You have, say, 10 pages to write everything a new user needs to know. No
> more. No megabytes of tutorials. And no, not a "quick reference" either: You
> will have to write the sentences that the current docs lack: "Every scene
> needs a camera, should probably have at least one object of some sort so
> there's something to look at and usually should probably also have a
> light_source". That's one-and-a-half lines of text and it contains more
> information than the first ten pages of the POV-Ray docs combined.

Good exercise. You're welcome to do it. Apparently you /love/ to write 
docs and are tremendously good at it.

> #2 Is harder, but would require little more than all dev-folks coming
> together and laying out how POV-Ray is actually *supposed* to work. Spell it
> out *without* writing code: How do you want things to happen, how should
> they be structured.
>
> Then implement what you decided.

Sounds simple, and every developer knows that this is the "right" way to 
do things, but non-commercial open source projects follow different 
rules. At least this one does, and I guess it's necessary in order to 
not lose too much momentum.

> No sane developer will *design* a language where some statements *must*
> start with a "#", while some others *can* have a "#" at the beginning.
> "sphere" and "#sphere" are both acceptable, "declare" throws a warning but
> works, "if" is an error. That's just absurd. Some mechanisms take parameters
> in {} braces, others take them in () brackets. Some places take "x" to be a
> unit vector, some others interpret it as a float. *Of course* the
> documentation is going to be complete bullshit if the thing to be documented
> is bullshit.

The SDL is the result of decades (!) of growth, with varying dev teams, 
and many contributions from the community, that hasn't been trimmed much 
in all that time for the sake of backward compatibility. Do you 
seriously expect such a plant to still be anywhere close to self-consistent?

> Just in this one thread I've heard from one person that there is a supposed
> "general rule" of order that is that everything can be in arbitrary order
> except for object_modifiers and from another person that "unless there is
> special syntax, everything should be taken literally in the order given".
> These two are in mutual contradiction. NEITHER of these two can be found in
> the documentation. This is where I'd want the developers to talk amongst
> each other and decide which of these behaviours they actually *want*, then
> *implement* that and then *document* it.

There is not a contradiction there: The one person described how the 
program actually works, and how the syntax is according to the Quick 
Reference. The other person described how the syntax notation in the 
main documentation is to be interpreted in order to be on the "safe side".

> POV-Ray has had two decades for the various shifting dev-teams to come to
> *some* basic understanding of how things *should* happen. A brief style
> manual. Some outline what the syntax rules should be. What the actual rules
> of the parser should be. Something against which it can be measured whether
> or not adding yet another keyword-with-its-own-incompatible-sub-syntax is
> the right thing to do.
>
> And it is pretty clear that none of that ever happened.

And it /is/ going to happen. Not because of your ranting though, but 
because the dev team has already been percieving it as a necessity for 
quite a while.

Just like it was a necessity to get some complete and consistent gamma 
handling in place at last. Or to make alpha channel handling more 
consistent. Or to make sky_sphere filter behaviour consistent with 
behaviour of a large regular sphere with filter.

Notice something? Consistency /is/ something the dev team is aiming for 
these days.

Post a reply to this message

On 5/19/2011 18:56, SGeier wrote:
> You really think those who don't know how POV-Ray works wil create better
> documentation than those who do know it?

For many kinds of documentation (and pretty much all documentation that 
you're not supposed to look at the source code while using), this is a given.

Indeed, it's one of the primary reasons to write the documentation first. 
All this talk about "test driven design" is merely there to make programmers 
write documentation before they code. One winds up with excellent 
documentation if one writes the manual, then implements what the manual says.

 > "how should we have written the answer to this

If once you get the answer you don't add it to the docs where you expected 
to find it, then you're part of the problem. :-) Now that there's a wiki and 
a bug tracker, at least.

 > the program as shipped is the final documentation.

This of course is nonsense, as it would imply it's impossible to have a 
buggy program.

-- 
Darren New, San Diego CA, USA (PST)
   "Coding without comments is like
    driving without turn signals."

Post a reply to this message