[luatex] What are user-defined whatsit nodes?

[Stephan Hennig]

Hi,

inserting a user-defined whatsit node between two characters that can
form a valid ligature within a font, e.g., between two characters 'f'
and 'i', prevents the ligaturing mechanism to apply the ligature (see
attached example).

So far, I did interpret the description of user-defined whatsit nodes

  The LuaTeX engine will simply step over such whatsits
  without ever looking at the contents.

as

  User-defined whatsit nodes are kind of phantom nodes that
  never interfere with how LuaTeX works internally. However,
  they may disappear from a node list whenever LuaTeX removes
  nodes adjacent to a user-defined whatsit node.

Though, another view at user-defined whatsit nodes is equally valid

  User-defined whatsit nodes are whatsit nodes and as such
  their presence within a node list might interfere with how
  LuaTeX works internally.

Can LuaTeX developers confirm that the former interpretation is wrong?
If so, I propose adding a clarifying note to the manual.

Thanks,
Stephan Hennig


% -*- coding: utf-8 -*-
\directlua{
% Declare constants.
  local GLYPH = node.id('glyph')
  local WHATSIT = node.id('whatsit')
  local USER_DEFINED = node.subtype('user_defined')
  local CHAR_f = string.byte('f')
  local CHAR_i = string.byte('i')
  local Ncopy = node.copy
  local Nnew = node.new
  local Ninsert_before = node.insert_before
  local Ntraverse = node.traverse
% Create user-defined whatsit.
  local what = Nnew(WHATSIT, USER_DEFINED)
  what.user_id = 20141117
  what.type = 100
  what.value = 0
% Register callback.
  callback.register('hyphenate',
    function (head, tail)
%     Iterate over node list.
      for n in Ntraverse(head) do
        if n.id == GLYPH and n.char == CHAR_i then
          local p = n.prev
          if p.id == GLYPH and p.char == CHAR_f then
            Ninsert_before(head, n, Ncopy(what))
          end
        end
      end
      lang.hyphenate(head, tail)
    end
  )
}
fishing
\bye