text: from vectors import *
  
  # Given a line with coordinates 'start' and 'end' and the 
  # coordinates of a point 'pnt' the proc returns the shortest
  # distance from pnt to the line and the coordinates of the
  # nearest point on the line.
  #
  # 1 Convert the line segment to a vector ('line_vec')
  # 2 Create a vector connecting start to pnt ('pnt_vec').
  # 3 Find the length of the line vector ('line-len').
  # 4 Convert line_vec to a unit vector ('line_unitvec').
  # 5 Scale pnt_vec by line_len ('pnt_vec_scaled').
  # 6 Get the dot product of line_unitvec and pnt_vec_scaled ('t').
  # 7 Ensure t is in the range 0 to 1
  # 8 Use  to get the nearest location on the line to the end
  #   of vector pnt_vec_scaled ('nearest')
  # 9 Calculate the distance from nearest to pnt_vec_scaled.
  # 10 Translate nearest back to the start/end line.
  # Malcolm Kesson 16 Dec 2012
  
  def pnt2line(pnt, start, end):
      line_vec = vector(start, end)
      pnt_vec = vector(start, pnt)
      line_len = length(line_vec)
      line_unitvec = unit(line_vec)
      pnt_vec_scaled = scale(pnt_vec, 1.0/line_len)
      t = dot(line_unitvec, pnt_vec_scaled)
      if t < 0.0:
          t = 0.0
      elif t > 1.0:
          t = 1.0
      nearest = scale(line_vec, t)
      dist = distance(nearest, pnt_vec)
      nearest = add(nearest, start)
      return (dist, nearest)
  
  #-------------------------------------------------------
  