How to use LuaTeX `append_to_vlist_filter` callback

Question

I am considering a solution to the automatic grid typesetting problem though LuaTeX callbacks. The most relevant one seems to be append_to_vlist_filter. (vpack can also work, I support, but a less elegant solution)

However, it seems that it does work properly. The documents is quite vague on its return value.

function(<node> box, <string> locationcode, <number prevdepth>, <boolean> mirrored) 
    return list, prevdepth
end

It is ok to return nothing in which case you also need to flush the box or deal with it yourself. The prevdepth is also optional. Locations are box, alignment, equation, equation_number and post_linebreak

Below is a minimal example,

\documentclass{article}

\directlua{
  function apvlist(head)
    return head
  end
  luatexbase.add_to_callback("append_to_vlist_filter", apvlist, "apvlist")
}

\begin{document}
Test
\end{document}

I assumed that the return value list means the head of a node list. In the simple example, the original box is returned as the head of a single node list. Yet, when compiled there's no page output.

What does the document mean by flush the box or deal with it yourself?

Answer 1

I'd found the same example as Ulrike in luatexja, and so I think the identity function is something like

\documentclass{article}

\directlua{
  function apvlist(head,c,p,b)
    print('adding ' .. type(head) .. ' in context ' .. c)
    node.write(head)
    return nil
  end
  luatexbase.add_to_callback("append_to_vlist_filter", apvlist, "apvlist")
}

\begin{document}
Test
\end{document}

which typesets Test and echoes

adding userdata in context post_linebreak
adding userdata in context box
adding userdata in context box
adding userdata in context box
adding userdata in context box
adding userdata in context box

But the details are still a bit vague.