Am 25.05.2011 01:35, schrieb SGeier:

> And where I'm
> coming from, where the documentation and the behaviour of the program
> differ, the program is right and the documentation is wrong.

Where /I'm/ coming from, this is /not/ necessarily the case, but 
definitely depends on various other circumstances; for instance, where 
the program /tolerates/ something that's not explicitly in the docs, 
this is an undocumented feature, may be subject to change without 
notice, and therefore should still be avoided despite being tolerated.

Post a reply to this message

On 25/05/2011 12:51 AM, clipka wrote:
>
> 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.

Now that is sensible.
There is no need to make things worse than they re already are.

-- 
Regards
     Stephen

Post a reply to this message

On 05/24/2011 08:51 PM, clipka wrote:
> No, we won't improve the docs much before the 3.70 repease proper
> (unless some volunteer(s) happen to step up to actively help us with
> them - and by actively I mean more than demonstrating that you didn't
> understand them), for the simple reason that there's lack of manpower in
> that respect. 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.

couldn't agree more with what you've said here ... I think my focus was 
to get stuff (new features) added in as they just weren't documented 
period, and also the code to pull it back out of the wiki in html form. 
I /did/ touch on some house keeping issues that were just plain in need 
of help, but I'm just one person, so for sure there are some areas that 
just didn't get touched. I /still/ give the docs pretty high marks, 
because hey I've seen MUCH worse (other apps) and would be the first to 
admit that there are areas that still need some attention ... everyone 
knows that documentation is usually the /last/ thing to be addressed 
with most projects and everyone hates to do it ;-)

Post a reply to this message

"Alain" <aze### [at] qwertyorg> wrote in message 
news:4ddb1917$1@news.povray.org...

[...]>>>>     [OBJECT_MODIFIERS...]
>>>>     }
>
> Note that all items are lower case, then, you have OBJECT_MODIFIERS in all 
> UPPERCASE. This tells you that OBJECT_MODIFIERS is not in the same 
> category. In fact, it tells that OBJECT_MODIFIERS in not an item.

Pray tell. Could you imagine that this might be the case why I called it "a 
whole class of [object_modifiers]" in the paragraph directly following this 
(that you so politely quoted right here:)

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

Not that it has any bearing on this:

>>>> 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.
>
> The documentations clearly state that all object modifiers must follow all 
> objects items.

It is good to hear that there is at least one thing that the documentation 
"clearly states". Because most parts of the documentations are rather 
unclear.

Surely it wouldn't be too much of a bother if you could kindly direct me to 
the section in the documentation that "clearly states" such a thing? It 
seems that I keep missing all the important parts of the docs and I'd like 
to make sure I have read at least those parts that clearly state things.

[...]
> You seems to confuse "items" and "modifiers".
> Items can be in any order.
> Modifiers also can be specified in about any order. They also MUST follow 
> the last item.

The word "item" has a fairly well-established meaning in the English 
language, a meaning that would make every "thing" inside the {}, including 
any modifier, an "item". If the POV-Ray docs would like the reader to 
understand the term it in a manner incompatible with the common meaning then 
I'm sure they "clearly state" such a thing. Could you please simply tell me 
where I should go to find that?

[...]
>>> "SGeier"<som### [at] somewherecom>  wrote in message
>>> news:<4dd316e8$1@news.povray.org>...
>>
>>> OK, I'm either doing something phenomenally stupid, or there's a blatant
>>> bug
>>
>>> in isosurface{} in 3.7rc3.
> You asked if there was a bug, and there is none.
> It leaves the "something phenomenally stupid" part...

As it turns out there was a third possibility: the documentation is wrong.

This is clearly a problem with my expectations: when I use the RC of some 
software, I expect to find a bug here'n'there. And maybe possibly that I'm 
just using the software wrong. I don't really expect to find documentation 
that

- doesn't document the behaviour of the software correctly AND
- doesn't express the intent of the programmers

[...]
 >>Turns out what I was
>> *really* bumping into was about some subtle distinction about the items I
>> can put into an isosurface{} statement, namely that some of them are
>> "object_modifiers" and assume a special place, while others are
>> object-specific and can go wherever.
>
> Again, "object_modifiers" are not items. It thus don't follows the general 
> rule of order as the items.
>

Oh, so there is such a thing as a "general rule of order"? Surely you can 
point me to the part of the documentation that expresses that rule, right?

And if object_modifiers *must* be in a certain position because they *don't* 
follow that "general rule", then I am concluding that the "general rule" is 
that I can put items into any order? Because that seems to be in direct 
contradiction with Christian Froeschlin's claim "in absence of special 
syntax, everything is to be taken literally and in the order specified."

[...]
> This is that way at least since version 1.
>
> primitive_name{mendatory_items [optional_items_in_any_order] 
> [OBJECT_MODIFIERS_IN_ANY_ORDER]}

That line there - can you show me where I can find that in the docs? 
Obviously it must be in there somewhere if it has been that way since 
version 1. Thanks.

> If you look around, you'll find that:
> Most of the time, max_gradient immediately FOLLOWS the function. It's 
> question of style and general concensus.
> Also, most of the time, contained_by is the last isosurface parameter. 
> Also a question of style and concensus.

And where, exactly, would I do that "looking around" thing you're talking 
about? The newsgroups have very little POV code on them, and where they do 
it's usually someone posting something that *doesn't* work.

I guess the obvious place would be the "code samples" section of the 
documentation. Oh, sorry, there is no such section. Hummm ...

> max_trace_level apply exclusively to transparency and reflections, never 
> ever to any surface that can never be visible.

I think you might benefit from reading the actual message I posted here that 
started the thread. It would allow you to make comments that have a bearing 
on the matter at hand. The suface I was writing about  was perfectly visible 
*if* it was encased in a transparent object. It vanished when the enclosing 
transparent object was removed. The issue is thus *very much* one of 
"transparency and reflection" and nobody here anywhere wrote about a surface 
"that can never be visible".

It would be possible to *make* the surface in question "never be visible" by 
setting
 global_settings {max_trace_level 1}

> max_trace/all_intersections is very different and there is no "magic" 
> transforming one into the other.
> max_trace_level is a global setting that affect the evaluation of tracing 
> rays.
> max_trace is an object attribute specific to the isosurface in exactly the 
> same way that max_gradient is. It affect how the isosurface is evaluated 
> if there are surfaces that can't be seen. Please note that ther is NO 
> "_level" here. They do LOOK similar, but are totaly different things.

Both are instructions that tell POV-Ray how many ray-surface intersections 
to follow before giving up.

I am at a loss how a sentient being can claim that they are "totally 
different things".

Post a reply to this message

> "Alain"<aze### [at] qwertyorg>  wrote in message

>> The documentations clearly state that all object modifiers must follow all
>> objects items.
>
> It is good to hear that there is at least one thing that the documentation
> "clearly states". Because most parts of the documentations are rather
> unclear.

Maybe if you look in the documentations for object modifiers...
You'll see that clipped_by IS an object modifier.
You'll also see, at the top, that object modifiers must be at the end of 
any object's definition.


>
> I am at a loss how a sentient being can claim that they are "totally
> different things".
>
>

max_trace_level (default value 5) is how many ray-surface to follow when 
you have refraction or reflection. Each surface do have an effect on the 
value of a specific pixel. In 3.7, contrary to versions 3.6.2 and 
earlier, plain transparent surfaces that don't reflect nor refract are 
not counted against max_trace_level.
When you exeed max_trace_level, the colour returned is black (rgb 0).

max_trace (default value 1) is, for an isosurface in a CSG, how many 
surface to EVALUATE or FIND. Here, the crossed surface don't have ANY 
effect when computing the falue of a pixel.

If you set max_trace_level 1, it means that you stop following new rays 
after the first reflection or refraction. You'll get black instead of 
reflection or refractions.

With max_trace 1, the second and successive surfaces are not evaluated. 
That means that you don't find when you exit the isosurface.

Post a reply to this message

"Alain" <aze### [at] qwertyorg> wrote in message 
news:4ddd2c02$1@news.povray.org...

>> "Alain"<aze### [at] qwertyorg>  wrote in message
>
>>> The documentations clearly state that all object modifiers must follow 
>>> all
>>> objects items.
>>
>> It is good to hear that there is at least one thing that the 
>> documentation
>> "clearly states". Because most parts of the documentations are rather
>> unclear.
>
> Maybe if you look in the documentations for object modifiers...
> You'll see that clipped_by IS an object modifier.


OK, I am rapidly losing my patience here. The following is a cut-and-paste 
of the complete pertinent sections of the *currently shipping* 3.7RC3 
windows help file:

============== begin cut/paste =============================
3.4.9 Object Modifiers
A variety of modifiers may be attached to objects. The following items may 
be applied to any object:

OBJECT_MODIFIER:
  clipped_by { UNTEXTURED_SOLID_OBJECT... } |
  clipped_by { bounded_by }                 |
  bounded_by { UNTEXTURED_SOLID_OBJECT... } |
  bounded_by { clipped_by }                 |
  no_shadow                  |
  no_image [ Bool ]          |
  no_radiosity [ Bool ]     |
  no_reflection [ Bool ]     |
  inverse                    |
  sturm [ Bool ]             |
  hierarchy [ Bool ]         |
  double_illuminate [ Bool ] |
  hollow  [ Bool ]           |
  interior { INTERIOR_ITEMS... }                        |
  material { [MATERIAL_IDENTIFIER][MATERIAL_ITEMS...] } |
  texture { TEXTURE_BODY }   |
  interior_texture { TEXTURE_BODY } |
  pigment { PIGMENT_BODY }   |
  normal { NORMAL_BODY }     |
  finish { FINISH_ITEMS... } |
  photons { PHOTON_ITEMS...}
  radiosity { RADIOSITY_ITEMS...}
  TRANSFORMATION
Transformations such as translate, rotate and scale have already been 
discussed. The modifiers Textures and its parts Pigment, Normal, and Finish 
as well as Interior, and Media (which is part of interior) are each in major 
chapters of their own below. In the sub-sections below we cover several 
other important modifiers: clipped_by, bounded_by, material, inverse, 
hollow, no_shadow, no_image, no_reflection, double_illuminate and sturm. 
Although the examples below use object statements and object identifiers, 
these modifiers may be used on any type of object such as sphere, box etc.

3.4.9.1 Bounded_By
[...]

3.4.9.2 Clipped_By
The clipped_by statement is technically an object modifier but it provides a 
type of CSG similar to CSG intersection. The syntax is:

CLIPPED_BY:
  clipped_by { UNTEXTURED_SOLID_OBJECT... } |
  clipped_by { bounded_by }
Where UNTEXTURED_SOLID_OBJECT is one or more solid objects which have had no 
texture applied. For example:

object {
  My_Thing
  clipped_by{plane{y,0}}
  }
Every part of the object My_Thing that is inside the plane is retained while 
the remaining part is clipped off and discarded. In an intersection object 
the hole is closed off. With clipped_by it leaves an opning. For example the 
following figure shows object A being clipped by object B.

[image here]

You may use clipped_by to slice off portions of any shape. In many cases it 
will also result in faster rendering times than other methods of altering a 
shape. Occasionally you will want to use the clipped_by and bounded_by 
options with the same object. The following shortcut saves typing and uses 
less memory.

object {
  My_Thing
  bounded_by { box { <0,0,0>, <1,1,1> } }
  clipped_by { bounded_by }
  }
This tells POV-Ray to use the same box as a clip that was used as a bound.

3.4.9.3 Double_Illuminate
[...]
==================== end cut/paste ======================

> You'll also see, at the top, that object modifiers must be at the end of 
> any object's definition.
>

No, I will NOT see that because it is NOT in the documentation.

At this point, there are two possiblities left:

1) You have no idea what is actually in the documentation and you cannot be 
bothered to look it up and actually inform yourself OR

2) You are deliberately lying

Either way, you are NOT qualified to tell other people who have actually 
LOOKED at the documentation what is or isn't supposedly in there.

I asked you for pointers to *several* things you claimed were allegedly in 
the documentation.

You provided *none*.

I do not know what you imagine you're accomplishing by this, but neither 
POV-Ray, nor the POV-Ray documentation, nor myself or the dev-team benefit 
from people making *false* claims about what is actually in the actual 
documentation.

Post a reply to this message

"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

Le 26/05/2011 02:47, SGeier a écrit :
> No, I will NOT see that because it is NOT in the documentation.
> 

Instead of focusing your rage on this thread, what about using all that
energy to contribute to the documentation itself (on the pov-wiki pages)?

I'm sure you know the right spot to add or amend a paragraph or two
about the behaviour you observed (i.e. all specific object options must
be before the very first option from OBJECT_MODIFIER). At least you
would be expecting it there, so, in fact, you do know that place.

> I asked you for pointers to *several* things you claimed were allegedly in 
> the documentation.

I used to know the povray documentation by heart... but it was at the
time of 3.1 (well, I started with 2.12 of something not called povray).

I get a bit lost with the 3.5 and further. (and it seems there is
duplicate data for the SDL: often in the object description, and later
in the SDL summary. It's like having two watches (clock), if they are
different, I'm unable to know which one is true (if any)).

I would reckon (but I'm not able to provide a better tool) that the
search engine on the wiki is far too weak, at least for my taste, i'm
never able to find a good match. I might not be using the right wordings.

-- 
Software is like dirt - it costs time and money to change it and move it
around.

Just because you can't see it, it doesn't weigh anything,
and you can't drill a hole in it and stick a rivet into it doesn't mean
it's free.

Post a reply to this message

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