TFormNormal not working?

The documentation is wrong.

The Normal in TFormNormal refers to perpendicularity. Suppose two vectors v1 and v2 are perpendicular, i.e. their dot product is zero. Transform v1 with TFormVector and v2 with TFormNormal. The resulting vectors are again perpendicular.

The transformed v2 is also scaled to length one, another meaning for the word normalize.

The real source of confusion is that the flawed description in the documentation is correct if there is no scaling.

I dredged up this example from my stockpile of old code:

; This shows how to find vertex positions and normals with a scaled entity.
; Use left/right mouse buttons to move around the scaled sphere.

Graphics3D 640, 480, 0, 1
AmbientLight 50,50,50

lt = CreateLight() : RotateEntity lt, 0, 90, 0

sph = CreateSphere( 16 )

cam = CreateCamera() : PositionEntity cam, 0,0, -10 : CameraZoom cam, 4

cone = CreateCone()
ScaleMesh cone, 0.1, .25, 0.1
PositionMesh cone, 0, 0.26, 0

EntityColor cone, 0, 100, 100

surf = GetSurface(sph,1)
maxV = CountVertices( surf ) - 1

ScaleEntity sph, 2, .8, 2

v = 150  ; start at a vertex we can easily see

While Not KeyDown(1)

	PositionMarker( sph, 1, v, cone )
	RenderWorld
	Text 250, 400, "Vertex: " + v	
	Flip

	v = v + MouseDown(2) - MouseDown(1)   :   Delay 50
	
	If v > maxV Then v = 0
	If v < 0 Then v = maxV	

Wend


Function PositionMarker( mesh, surface_index, vert, marker )

	surf = GetSurface( mesh, surface_index )

	x# = VertexX( surf, vert )
	y# = VertexY( surf, vert )
	z# = VertexZ( surf, vert )

	nx# = VertexNX( surf, vert )
	ny# = VertexNY( surf, vert )
	nz# = VertexNZ( surf, vert )
	
	; Position and normal are correct for the underlying mesh, but
	; not for the scaled entity. Here's how to transform them.
		
	TFormPoint x,y,z, mesh, 0    ; the 0 means world coordinates
	x = TFormedX()
	y = TFormedY()
	z = TFormedZ()

	TFormNormal nx,ny,nz, mesh, 0 
	nx = TFormedX()
	ny = TFormedY()
	nz = TFormedZ()

	PositionEntity marker,  x,  y,  z	
	AlignToVector  marker, nx, ny, nz, 2
	
End Function