Tom Melly <tom### [at] tomandlucouk> wrote:
> One oddity in this case is that strlen (and some other string-related functions)
> do not appear under the string function section, but instead are under the
> float-function section. Okay, it returns a float, but IMHO such functions could
> be listed in both sections.

  Functions are categorized based on what they return.
  Functions can take any type of parameters (floats, vectors, strings,
objects...) and it would be too hard and awkward to start categorizing
them according to what they take as parameter. (For example, how would
you categorize the trace() function?)

-- 
#macro M(A,N,D,L)plane{-z,-9pigment{mandel L*9translate N color_map{[0rgb x]
[1rgb 9]}scale<D,D*3D>*1e3}rotate y*A*8}#end M(-3<1.206434.28623>70,7)M(
-1<.7438.1795>1,20)M(1<.77595.13699>30,20)M(3<.75923.07145>80,99)// - Warp -

Post a reply to this message

On Fri, 21 Feb 2003 10:33:12 GMT, mca### [at] aolcom (S McAvoy) wrote:
> Knowing how helpful you are I assume that you meant "how can the documentation
> be improved to help you find what you want to know". 

Yes and no. While working on softwear professionally I'm interested in making
apps as much user-friendly as possible because it makes my profits. In various
projects I'm also responsible for making/updating documentation and I have
direct access to users so I always listen all notes. Relating to POV-World I'm
working on MegaPOV and I know how much there is to improve - for example next
MegaPOV will probably have context help for MegaPOV related keywords (have to
solve some problem there).

In general working with computers requires some assumptions about user. If he is
looking for string related function I expect he will read "String functions"
chapter because logical connection between searched keyword and name of chapter
is obvious. Please note either "function" and "string" keywords appear in
subject of original post so you can't say he has language problems in that area.

I understand user can not know all names of chapters. But then simple search any
combination of "string", "function", "functions", "length" should lead to
something like: http://www.povray.org/search/?s=string+length+function where
either "String functions" and "Float functions" are at top. If he do not tried
search nor read table of content then whatever will be written in documentation
he will never find it. Moreover he used "strlen" keyword which appear in index
of documentation.

My elaborated answer is not offence against original poster because I understand
that's what new users usually do - never start from manual. My answer is against
wrong conclusions mentioned later. Documentation has probably holes but none
documentation hole caused that user to be asking for string length function.

ABX

Post a reply to this message

On Fri, 21 Feb 2003 12:17:09 +0100, ABX <abx### [at] abxartpl> wrote:
> for example next
> MegaPOV will probably have context help for MegaPOV related keywords

Of course I mean Windows port of MegaPOV.

ABX

Post a reply to this message

I'm pleased to hear that MegaPOV will probably have context sensitive help
although I've not used it since POV Ver 3.5 was released, too many other things
to do. Keep up the very good work.
It's true what you say about users, and when your getting paid for supporting
them you just have to "grin and bare it" but when your support is free and done
out of love it can be frustrating to know that if they had read the manual they
would not need to ask.
BTW I read this Q & A a few weeks ago : . Q - What do you call a person who asks
for easily obtainable information. A - A boss."
I understood the response to 'Christopher James Huff' as an attempt to soften
this reply. Writing to news groups can be a means of joining a community and
should be encouraged IMHO. Personally no one I know is the slightest bit
interested in computer graphics and it can get lonely. Maybe that is why I like
to encourage others.

Regards
        Stephen

Post a reply to this message

In article <3e5601e0@news.povray.org>, Warp <war### [at] tagpovrayorg> 
wrote:

>   Functions are categorized based on what they return.

And I personally have never liked this method.


>   Functions can take any type of parameters (floats, vectors, strings,
> objects...) and it would be too hard and awkward to start categorizing
> them according to what they take as parameter. (For example, how would
> you categorize the trace() function?)

"Other"

-- 
Christopher James Huff <cja### [at] earthlinknet>
http://home.earthlink.net/~cjameshuff/
POV-Ray TAG: chr### [at] tagpovrayorg
http://tag.povray.org/

Post a reply to this message

In article <3e56003e.6747031@news.povray.org>,
 mca### [at] aolcom (S McAvoy) wrote:

> I think what George meant was, that to someone starting out using PovRay, the
> manual has too much to much information to take in all at once. Not all users
> are professional IT experts you know. PovRay attracts artists, as well as
> techies, whose search skills may not be the best. It can be daunting trying to
> find information you only have a hazy idea about using a manual you are not
> familiar with. 

The person knew the C strlen() function, which strongly implies he is 
not in that group. It would have been very simple to search the 
documentation for "strlen", or just try it in a simple scene. If he 
hadn't known about strlen(), a slightly more complex search would still 
quickly find it, but I would have reacted differently. (the probability 
of him being a newbie or non-coder type would have been much higher)

Anyway, this is getting out of hand. The question has been answered, 
lets drop it. I'm sorry if I appeared excessively rude, but the 
documentation is written to answer these kinds of questions before they 
are asked, it is annoying and frustrating to have that work ignored.

-- 
Christopher James Huff <cja### [at] earthlinknet>
http://home.earthlink.net/~cjameshuff/
POV-Ray TAG: chr### [at] tagpovrayorg
http://tag.povray.org/

Post a reply to this message

Christopher James Huff <cja### [at] earthlinknet> wrote:
>> (For example, how would you categorize the trace() function?)

> "Other"

  Very logical naming? When you want to consult the documentation to
see what was the syntax of that function, you immediately can deduce
by logic that this function is of type "other"? (How do you deduce
that? Perhaps "because it takes lots of mixed-type parameters"? Not
very logical.)

  And what about defined(), dimensions(), dimensions_size(), inside(),
val() and min_extent()? Are they of type "other" (because they use
several types as parameters/return values) or perhaps something else?

  When you know that functions are categorized by their return value,
it's easy to find the function in the documentation. (eg. "min_extent()
returns a vector, thus it's in 'vector functions'")

-- 
plane{-x+y,-1pigment{bozo color_map{[0rgb x][1rgb x+y]}turbulence 1}}
sphere{0,2pigment{rgbt 1}interior{media{emission 1density{spherical
density_map{[0rgb 0][.5rgb<1,.5>][1rgb 1]}turbulence.9}}}scale
<1,1,3>hollow}text{ttf"timrom""Warp".1,0translate<-1,-.1,2>}//  - Warp -

Post a reply to this message

"Warp" <war### [at] tagpovrayorg> wrote in message news:3e563e0a@news.povray.org...
> Christopher James Huff <cja### [at] earthlinknet> wrote:
> >> (For example, how would you categorize the trace() function?)
>
> > "Other"
>
>   Very logical naming? When you want to consult the documentation to
> see what was the syntax of that function, you immediately can deduce
> by logic that this function is of type "other"? (How do you deduce

IMHO a less binary approach would be best - the general convention of
catagorising by return seems good, but in the case of, e.g., strlen, it should
appear in both catagories.

IMHO the manual would benefit from more redundancies based on workflow and
common-sense - though I hasten to add that this is largely a criticism of human
beings rather than the manual.

Post a reply to this message

On Fri, 21 Feb 2003 09:45:46 -0500, Christopher James Huff
<cja### [at] earthlinknet> wrote:


>Anyway, this is getting out of hand. The question has been answered, 
>lets drop it. 
Yes a good idea.

>I'm sorry if I appeared excessively rude, 

No you didn't, nor do I mean to offend.


Regards
        Stephen

Post a reply to this message

In article <3e563e0a@news.povray.org>, Warp <war### [at] tagpovrayorg> 
wrote:

>   Very logical naming? When you want to consult the documentation to
> see what was the syntax of that function, you immediately can deduce
> by logic that this function is of type "other"? (How do you deduce
> that? Perhaps "because it takes lots of mixed-type parameters"? Not
> very logical.)

I see a bunch of categories that it doesn't fit in, and one that it 
does. strlen() isn't a float function, it is a string function. 
Categorizing by purpose makes much more sense.


>   And what about defined(), dimensions(), dimensions_size(), inside(),
> val() and min_extent()? Are they of type "other" (because they use
> several types as parameters/return values) or perhaps something else?

If there were more array manipulation functions it would make sense to 
put dimensions() and dimension_size() in an array category. inside(), 
min_extent(), max_extent(), and trace() could fit in an objects 
category. val() is a string function.


>   When you know that functions are categorized by their return value,
> it's easy to find the function in the documentation. (eg. "min_extent()
> returns a vector, thus it's in 'vector functions'")

min_extent() deals with objects, so it's in the category of functions 
that deal with objects.

-- 
Christopher James Huff <cja### [at] earthlinknet>
http://home.earthlink.net/~cjameshuff/
POV-Ray TAG: chr### [at] tagpovrayorg
http://tag.povray.org/

Post a reply to this message