              mparhack.sty

Tom Sgouros

      tomfool@top.gso.uri.edu

Stefan Ulrich

                                   stefanulrich@users.sourceforge.net

v1.3a 2003/05/22

                   CTAN: macros/latex/contrib/supported/mparhack/

Abstract This package implements a workaround for the L^{A}TEX bug that margin-

pars sometimes show up on the wrong margin.

Contents

1 Introduction  1
2 Usage  2
3 Bugs/Restrictions  2
4 Acknowledgements  3

1 Introduction

A persistent problem with the \marginpar command is that the marginalia produced often show up on the wrong margin. This has been noted in the L^{A}TEX bugs database.^{1}

The problem occurs most likely when a marginpar appears near the top of a page. The problem is exacerbated when the page break penalties are adjusted so that the page look is quite ragged. In cases like this, if there is a deal of white space on a page, the marginpars on the next page will be on the wrong side for the same length of the page. The reason for this is that the L^{A}TEX output routine is not in complete synchronization with the TEX page breaker, so that sometimes material might still move to a later page after L^{A}TEX’s marginpar algorithm has determined a page number for the marginpar.

The fix suggested in the bugs database is to insert \pagebreak commands at the places where the page breaks naturally fall; then the marginpars will appear on the correct side. However, this is awkward and unpleasant work for a document that changes regularly, and seems to fly against the spirit of L^{A}TEX.

A different approach was suggested by D. E. Knuth in his Macros for Jill^{2}: make two .dvi files, one with all notes in the left margin, the other one with all notes in the right margin. Then print the odd pages from one file, and the even pages from the other file; merge them by hand.

1See http://www.Uni-Mainz.DE/cgi-bin/ltxbugs2html: latex/2361, latex/2484, latex/2617.

2Originally published in TUGboat 8, pp. 309–314, reprinted in his Digital Typography pp. 185– 193.

However, Knuth also mentions the possibility to use an auxiliar file to save the page information for each marginpar and use this information to position it correctly in a second TEX run; and this is the strategy adopted by mparhack.sty. Each marginpar is assigned a unique number; the output routine writes the number of the last marginpar of each page/column to the .aux file, and this information is used in \@addmarginpar to position the current marginpar on the correct margin.

2 Usage

Just insert \usepackage{mparhack} into your document preamble. After the first run, you’ll probably get the warning message ‘Marginpars may have changed. Rerun to get them right’. This is similar to L^{A}TEX’s warning ‘Label(s) may have changed’; it indicates that the .aux file doesn’t contain the information needed to position the marginpars correctly, due to some changes in the document since the last run. The warning should go away after running L^{A}TEX again (eventually several times if there’s also a table of contents etc.).

debug If you think something is going wrong, the package also has a debug option; this will output a lot of tracing information and will add numbers to the marginpars in the .dvi file for reference.

3 Bugs/Restrictions

• The package works with the twocolumn document option, but not with the multicol package (you can’t use marginpars inside the multicols environment).

• The package uses one command sequence per page, and the total number of command sequences available is limited on most TEX systems. Note however that most current TEX implementations can allocate more than several thousand command names, and some can be configured to allocate more than the default during run-time, so this shouldn’t be a problem for moderately sized documents.

• The package has to hook into three commands of the L^{A}TEX2e output routine (by redefining some command), so it requires at least L^{A}TEX version 1997/04/14 and might break with future L^{A}TEX versions that change these commands. We try to detect this by requiring a version newer than 1997/04/14 and using some heuristics to check if the redefinitions have worked. You should watch out for this warning message:

LaTeX Warning: You have requested release `1997/04/14' of LaTeX,

               but only release `...' is available.

It might be that the package also works with older versions of L^{A}TEX, but this hasn’t been tested. If one of the heuristics detects an incompatible change, it will raise an error:

Package mparhack Error: Couldn't hook into command `xyz'.

It might also happen that the heuristics don’t detect a change properly. If the package simply seems to fail, this could be a reason. In both cases, please

send a bug report to stefanulrich@users.sourceforge.net (if neccessary

including the .log file of your L^{A}TEX run with the debug package option enabled). Suggestions/improvements are also welcome, of course.

4 Acknowledgements

Thanks to Donald Arseneau and Robin Fairbairns for providing detailed hints^{3} on how to implement the page referencing mechanism using only one label per page (instead of one label each marginpar, as in a previous version).

3in <23AUG199920123097@erich.triumf.ca> and <7prb8s$dpr$1@pegasus.csx.cam.ac.uk>, respectively.