The output routine is called either by TeX's normal page-breaking
mechanism, or by a macro putting a penalty of < or = -10000 in the output
list. These large penalties communicate with the OTR. For example a penalty of -10001 is a clearpage, whereas a -10004 is a float insertion etc.
Information on LaTeX output routine is very hard to find - and guessing from the comments in LaTeX's source, it is also hard to follow even for the LaTeX team!
The output routine is one of the more mysterious pieces
of TeX. The chapter of the TeXbook discussing output
routines claims that designing output routines makes one
achieve the level of a Tex Grandmaster.
As is so often the case, mastery of the concept of an
output routine in plain TEX will only barely prepare you
for the complexities awaiting you with LaTeX’s variant of
an output routine. However, it is better to start by studying TeX's OTR first. Luckily, there is some help in a series of articles by that great TeX exegete David Salomon. They are all available online as TUGBoat articles.
Output Routines: Examples and Techniques. Part I: Introduction and Examples.
Output Routines: Examples and Techniques. Part II: OTR Techniques
Output Routines: Examples and Techniques. Part III: Insertions
Output routines: Examples and techniques Part IV: Horizontal techniques
Read the last part first!
For LaTeX you can read Frank Mittelbach's, published paper xo-pfloat.pdf
in which he explains some of the problems facing the team, when dealing with the output routine. Reading it you will appreciate that floats is still one of the hard Computer Science problems and feel a bit of sympathy for Microsoft trying to do it interactively for multi-page documents!
There is also an article by David Kastrup Output Routine Requirements for Advanced Typesetting Tasks (Proceedings of EuroTEX 2003) outlining some of the difficult areas and specifications for generic routines
This would give you a bit of background to start deciphering source2e itself. It is not all that hard, but one needs to get a good grounding at the standard building blocks such as insertions lists, here points etc.
In a nutshell all floats are put in boxes and then lists and unboxed by the algorithm. sometimes mind-boggling lists such as this.
\gdef\@freelist{\@elt\bx@A\@elt\bx@B\@elt\bx@C\@elt\bx@D\@elt\bx@E
\@elt\bx@F\@elt\bx@G\@elt\bx@H\@elt\bx@I\@elt\bx@J
\@elt\bx@K\@elt\bx@L\@elt\bx@M\@elt\bx@N
\@elt\bx@O\@elt\bx@P\@elt\bx@Q\@elt\bx@R}
These boxes are sometimes not enough and great insight can be obtained by reading the documentation of related packages such as morefloats, which simply adds more boxes to the above list using 100's of expandafters!
There are some useful macros in the code - one the way of using @elt lists (they just equivalent to Knuth's double slashes). @elt is just a Lisp relic and is an abbreviation for element). Also look up @bitor, xbitor etc..
Looking for hooks? Perhaps you can use the AtBeginDvi in a similar way that bobhook used it to add water-marks to a page.
Lastly, just to touch on the kludgeins. Depending on one's interpretation they can either be an ill-assorted collection of poorly-matching parts, forming a distressing whole or the more German witty or smart, I go for the latter! My favourite quote from the source!
The star form of this command is
dedicated to Leslie Lamport, the other
we need for ourselves (FMi, CAR).
Great Team with a good sense of humour! Can't wait to hear from the other members here of the LaTeX3 way!
A personal list of list for heavy LaTeX users:
- More Math into LaTeX, 4ed. (easier)
- A Guide To LaTeX, 4ed.
- Digital Typography Using LaTeX. Springer.
More advanced:
- The LaTeX Companion, 2ed.
- The LaTeX Graphics Companion, 2ed.
And more: Many documents of LaTeX packages (user-level).
A personal useful book list for macro writers:
A personal useful (package) documentation list for package and class writers, general purpose:
- clsguide: LaTeX2e for class and package writers.
- source2e: Documented source code of LaTeX kernel.
- classes: Documented source code of LaTeX standard classes.
- macros2e: Martin's useful manual for LaTeX internal macros. (c.f. source2e)
- eTeX's manual.
- etoolbox: a useful toolbox of eTeX. For modern packages it is really useful.
- keyval: Support for key-value interface.
- pgfkey or xkeyval or l3keys2e: More advanced key-value interface.
- Some packages of Oberdiek bundle: ifpdf, ifxetex, ifluatex, atbegshi, kvoptions, zref, ...
- Some packages of tools bundle: array, calc (c.f. eTeX's primitives), fontsmpl (c.f. fonttable), layout (c.f. layouts), showkeys, trace, xspace, ...
- expl3, interface3 and source3 (i.e. l3kernel bundle): Introduction of LaTeX3 syntax and documented (developing) LaTeX3 kernel.
- Some packages of l3packages bundle, especially xparse.
- Documents of pdfTeX, and maybe XeTeX and LuaTeX.
To be continued... I'll add links for the documents.
Best Answer
I now compiled such a document listing all internal macros of LaTeX2e which are also useful for package authors. The work title is "List of internal LaTeX2e Macros useful to Package Authors" and I'm planning to release it on CTAN 'soon' (e.g. as '
macros2e') when its out of the beta stage.The beta release can be found on my website. There is also a feedback form and email address on the website. Please do not hesitate to suggest more macros I might have overlooked, better explanations of already listed macro, report errors of any kind or anything else.
Update 26th July 2011
It is now on CTAN. The source repository is public. Please feel free to provide comments, patches or open an issue ticket if you find anything which can be improved.