"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.

> That said, rather than continuing this interesting nitpicking contest, 
> please take a step back, rethink, and tell us what you /want/ from the dev 
> team.

Here's one thing I definitely want from the dev team: Stop lying. 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*.

3) The POV-Ray documentation is
   *one* *hairy* *clusterfuck*
  (pardon the language, I already toned this down)

POV-Ray is one of the three worst-documented software projects I have ever 
encountered. The other two are samba and ntp. Notice a commonality here? 
Each of these three comes with megabyte upon megabyte of "documentation" 
that *carefully avoids* ever actually spelling anything out. Ever providing 
any actual information. Ever explaining the simple basics.

The reason for this sorry state is

2) The POV-Ray Scene Description Language is
    *one* *hairy* *clusterfuck*

I've written code in languages that require a semicolon at the end of a 
statement. Languages that don't. Languages that allow semicolons but don't 
require them. But POV-Ray is the only language known to me that makes a 
semicolon mandatory for *some* statements, optional for *some* others and 
throws a parse error for yet some others. Some day I'll end a statement with 
", please" and I half expect that to actually work.

Abnd the reason for *that* is

1) POV-Ray was cobbled together over two decades without any kind of 
unifying style document. Various people with various motivations keep adding 
and patching and fiddling and there is no steering committee or mission 
statement or anything that would lead to a self-consistent syntax, 
self-consistent grammar, self-consistent semantics. There is no Persistence 
of Visison of the developers. "Hey, I'd like xyz feature"; "you're welcome 
to write the code for it"; "Oh, ok, I added a flag to the crackle pattern to 
do it".

They're numbered in causal order, as far as I can discern it.

#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? Why is there *nothing* in the docs that 
simply documents what the parser expects and when and where?

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.

Other simple exercise: install the windows version, hit F1, start reading at 
the beginning: Section 1.1 Introduction. The docs call themselves a "book", 
and that's how you read a book. The goal is to read until you have read 
everything you need to render your first scene (no, the demo doesn't count. 
Your *own* first scene). Pages upon pages upon pages upon even more pages of 
blah-blah without any kind of content. If your goal is to *make* people skip 
whole sections of the docs, congrats: you've succeeded. But seriously: keep 
reading. And reading. I think you get all the tools to render a simple scene 
somewhere around section 2.2, so just keep reading.

#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.

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.

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.

Yes, this would require that the developers negotiate amongst themselves 
what it is that they actually want.

And then they'd have to implement it, which I'm sure is less fun than just 
will-nilly throwing yet-another-interpretation of some identifier into the 
parser. But that way someone starting to tinker with POV-Ray could actually 
stand a chance of discerning what is *supposed* to happen, since there would 
in fact be something that *is* *supposed* to happen.

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.

> Yes, the docs badly do need some improvement, but (1) that's not a new 
> issue caused by the 3.6 -> 3.7 transition, and (2) it's not realistically 
> achievable with just adding a bit of more patchwork here and there; what's 
> really necessary is a systematic overhaul, which will possibly include a 
> major rewrite and/or restructuring of many sections.

Step one will be convincing your fellow developers that this is true --  
because they seem to *imagine* that the documentation is great and contains 
all kinda of wonderful things. And they cannot be arsed to read the docs 
themselves to see what a sorry state they're really in.

Step two will be for you to realize that half of the sorry state of the docs 
is a reflection of the sorry state of the parser.

OK, you asked what I want, here I told you.

I'm not necessarily expecting to get all (or any) of that, I'm merely 
answering your question.

Now the *REASON* I want all this is because POV-Ray *could* fill a niche if 
only it worked (and that includes working documentation and a working 
feedback mechanism where developers don't just simply *deny* the reality 
everybody can see with their own eyes).

The concept of a fully analytic ray-tracer is appealing. Yes, I could get 
Blender and start throwing meshes around. I might end up doing that. Like 
many people before me. But I still think the basic *idea* behind POV-Ray is 
sound. I *like* POV-Ray, or I wouldn't come back once a year for year after 
year. But after sufficiently many years I see the execution *bungled* by 
developers who think as long as they had their fun writing code, nothing 
else matters. Screw the users.

Post a reply to this message