use of cart2sph not in line with manual

[J.A. (Hans) Piest]

Dear madam/sir,

I have been struggling with the function (theta,phi,R) = cart2sph(x,y,z) for 
some time and found out that
the description in the octave manual is not exactly in line with its behaviour.

But I found out that:



In the manual it is told that:

'theta represents the angle relative to the positive x-axis'

The angle relative to the positive x-axis is mathematically defined as the 
dotproduct of a position
vector r with the unitvector in the x-direction. This is in line with default 
mathematical representation
of spherical polar coordinates where theta represents the angle between 
position vector and unitvector z axis.
I assumed from the description in the manual that in Octave unit x took over 
the role of unit z, which apparently isn't.

Moreover, the angle phi is the elevation angle above the x-y-plane.

However, I found out that the angle theta using cart2sph is defined as the 
angle of the orthogonal projection
of position vector r onto the xy plane with the unitvector x.
This is in line with the definition of cart2sph in MatLab, where it is 
explicitly said that
theta represents the azimuth angle and phi the elevation angle.


This is in line with the description in the Octave manual.

It would be nice and less confusing if the words azimuth and elevation were 
used in this context, if possible with
a small graph.

Sincerely yours,

Dr. J.A. Piest
Nijmegen
The Netherlands





HOWEVER:
------------------------------------------------------------------------------------
example publication:
CRDS of thin layers : 
www.darklands-sewer-system.eu/outlet/FTP/CavityRingdownPaper.pdf

sailing:
SV Morgenster bottom-up : 
www.darklands-sewer-system.eu/outlet/FTP/bottom-up-small.mov
SV Morgenster top-down  : 
www.darklands-sewer-system.eu/outlet/FTP/top-down-small.mov

rowing:
8+ : 
www.darklands-sewer-system.eu/outlet/FTP/RowingTheClubAcht-28February2015-small.mp4