sile-typesetter / sile / 14958605596

-- Info nodes are used to store information about what actually ends up on which page.

-- Index terms are an obvious use for this, as well as anything where you wanted to

-- know where something had ended up after the page builder had broken the page.

-- Check out SILE.scratch.info.thispage in your end-of-page routine and see what nodes

-- are there.

end

   else

   end

end

local function newPageInfo (_)

end

local _deprecate = [[

   Directly calling info node handling functions is no longer necessary. All the

   SILE core classes and anything inheriting from them will take care of this

   automatically using hooks. Custom classes that override the class:endPage()

   function may need to handle this in other ways. By calling this hook directly

   you are likely causing it to run twice and duplicate entries.

   end

   end)

end

            category = options.category,

            value = options.value,

         })

      )

end

package.documentation = [[

\begin{document}

\autodoc:note{This package is only for class designers.}

While typesetting a document, SILE first breaks a paragraph into lines, then arranges lines into a page, and later outputs the page.

In other words, while it is looking at the text of a paragraph, it is not clear what page the text will eventually end up on.

This makes it difficult to produce indexes, tables of contents, and so on, where one needs to know the page number for a particular element.

To get around this problem, the \autodoc:package{infonode} package allows you to insert \em{information nodes} into the text stream; when a page is outputted, these nodes are collected into a list, and a class’s output routine can examine this list to determine which nodes fell on a particular page.

\autodoc:package{infonode} provides the \autodoc:command{\info} command to put an information node into the text stream; it has two required parameters, \autodoc:parameter{category=<name>} and \autodoc:parameter{value=<any object>}.

Categories are used to group similar sets of node together.

As an example, when typesetting a Bible, you may wish to display which range of verses are on each page as a running header.

During the command which starts a new verse, you would insert an information node with the verse reference:

\begin[type=autodoc:codeblock]{raw}

SILE.call("info", { category = "references", value = ref }, {})

\end{raw}

During the \code{endPage} method which is called at the end of every page, we look at the list of “references” information nodes:

\begin[type=autodoc:codeblock]{raw}

local refs = SILE.scratch.info.thispage.references

local runningHead = SILE.shaper.shape(refs[1] .. " - " .. refs[#refs])

SILE.typesetNaturally(rhFrame, runningHead);

\end{raw}

\end{document}