This package allows the exportation of L^{A}TEX registers, like counters, rigid and rubber lengths.^{∗}

Jean-Pierre Drucbert

               drucbert@onecert.fr

1996/09/20

Abstract

This package^{1} allows you to export or import the values of various L^{A}TEX registers like counters and lengths (rigid or rubber). This could be useful to fabricate “composite” documents or to pass some data from a document to another one.

1 The export package

This package is designed to transmit data of type ⟨counter⟩ or ⟨length⟩ from a L^{A}TEX document to another. You must be aware that this package must be used with exterme care. The passing of data is done via a file. A first document exports

\openexport the data by invoking the following sequence of commands:

\closeexport
\Export
\ExportLength
\PreciseExportLength

\openexport{⟨file ⟩}
\Export{⟨counter ⟩}
\Export{⟨counter ⟩}
.
.
.
\ExportLength{⟨length ⟩}
\PreciseExportLength{⟨length ⟩}
.
.

∗This file has version number v1.0.

1

Copyright \begin{matrix}c \\ ◯ \end{matrix} 1996 by Jean-Pierre Drucbert ONERA/CERT GPI Office National d’Études et de Recherches Aérospatiales Centre d’Études et de Recherches de Toulouse Groupe de Prestations Informatiques Complexe Scientifique de Rangueil 2, Avenue Édouard Belin BP 4025 F-31055 TOULOUSE CEDEX FRANCE Email: drucbert@onecert.fr

     .
     \closeexport

where ⟨file⟩ is the file used to carry the data (its name will have the .xpt extension, but you must not give it), ⟨counter⟩ is the name of a L^{A}TEX counter (i.e. one of the well known counters chapter, section, …, equation, etc.), or a counter you have declared by \newcounter. Also, ⟨length⟩ is the name (without the backslash) of a L^{A}TEX length like parskip or of a length declared by \newlength. In the “importing” document, we will find a command \Import{⟨file⟩}. The \ExportLength command exports a length expressed in points (pt) which some fractionnal digits (5 is the maximum), while \PreciseExportLength exports the length expressed in scaled points units (sp, 65536 sp make a point), so it avoids possible rounding errors.

\ExportPageLayout If you want to export all the dimensions (lengths) describing the page layout, just use the \ExportPageLayout command. In a standard way, you should export only that into a given file, which should be imported in the preamble of the importing document. This method allows to have two documents with similar page layouts.

This package is very useful when associated which the dvipaste package, which allows you to prepare rectangular page pieces and to “paste” these page pieces into your document. Warning: if a such pasted piece modifies an imported counter or length, you must take account of that alteration in the document receiving the pasted piece.

The dvipaste package is not available from CTAN archives, but dvipaste.tex is. Get it (and the accompagning files), copy dvipaste.tex into dvipaste.sty, then edit dvipaste.sty to replace \line by \@@line, and read the documentation of dvipaste: you will also need the dvipaste.c program.

A simple example is described in the next pages.

1. the main document a.tex exports the counters equation and chapter, via the file x.xpt, toward the document b.tex. Adding to that, a.tex imports the labels defined in b.tex (using the xr package, from David Carlisle).

              a.tex                                    b.tex
\documentclass{article}%                 \documentclass{article}%
\usepackage%                             \usepackage%
  {...,export,dvipaste,xr,...}             {...,export,dvipaste,...}

\externaldocument{b}

\begin{document}                         \begin{document}

⋮  ⋮  _{⋮  ⋮}

⋮  ⋮  _{⋮  ⋮}

\openexport{x}
\Export{equation}
\Export{chapter}

⋮  ⋮  _{⋮  ⋮}

⋮  ⋮  _{⋮  ⋮}

\closeexport

2. The document b.tex imports the data contained in the file x.xpt, i.e. the

values of the equation and chapter counters.

              a.tex                                    b.tex

                                          \Import{x}

3. the it uses this counter in preparing an equation in a logical box:

              a.tex                                    b.tex

                                          \setbox0=\hbox{%
                                            \begin{minipage}{\textwidth}
                                          \begin{equation}
                                          a=b  \label{eq-a}
                                          \end{equation}
                                          \end{minipage}}
                                          \sendout{\box0}

⋮  ⋮  _{⋮  ⋮}

⋮  ⋮  _{⋮  ⋮}

                                          \end{document}

4. The document a.tex “pastes” the piece created by b.tex, then explicitely increments the equation counter, since the pasted piece contains an unaccounted equation ^{2}:

2An other, more general, method would be to “export back” the counter via an other file. This method is used when several counters are involved.

                a.tex                                    b.tex

⋮  ⋮  _{⋮  ⋮}
⋮  ⋮  _{⋮  ⋮}

  \noindent\paste{b}{1}
  \stepcounter{equation}

⋮  ⋮  _{⋮  ⋮}
⋮  ⋮  _{⋮  ⋮}

In fact, the following sequence of actions must be performed here:

latex b to create the files b.dat, which contain the dimensions of the pieces to “paste” and b.dvi contains the pieces themselves. But b.tex will not be able to import anything, because x.xpt has not yet been created;

latex a  to create x.xpt;

latex b to create again b.dat with the right dimensions and b.dvi containing correct values for equation numbers, since importation could be done;

latex a  to take into account the new dimensions in b.dat;
dvipaste a  to “paste” into a.dvi the pieces coming from b.dvi.

Note that the xr package, from David Carlisle, allows you to pass ⟨label⟩ information (i.e. to use \ref{⟨label⟩} or \pageref{⟨label⟩} when the ⟨label⟩ is defined by \label{⟨label⟩} in an other L^{A}TEX document.

1.1 Figures and Tables

\xcaptionf In the case of a figure or table which is “pasted” this way into a document with \xcaptiont its caption, this one will not be present in the list of figures or tables. An easy

solution is to use a \xcaptionf{⟨caption⟩} (or \xcaptiont{⟨caption⟩} for a table) command. These commands will increment the figure or table counter.

1.2 Inserting several pages

Sometimes, you wiil need to separately typeset several pages of a document. To accomplish that, you prepare a second document containing only the desired pages. This second document will need, by exemple, some packages not used in the main document (often because they require too much resources). To get correctly numbered pages, figures, tables, notes, etc., in the main document and in the secondary document, you just have to export the corresponding counters from the main document before the insertion, to import them at the beginning of the secondary document, to export them again (vi an other file) at the end of the secondary document, and at least to import them (via this second file) after the insertion into the main document.

It will certainly be necessary to transmit the page counter, which is named “page”. You must then add a \clearpage command before the exportation. This is mandatory only if the exported value must be used to number the page which follows the exportation. Do not export the page counter to an auxiliary document in which you are creating pieces to be “pasted” into your document (in such an auxiliary document, the “page counter” is in fact a counter of pieces to be pasted.

The insertion is only logical: you will have to do it manually in the printed paper sheets, or to use software tools manipulating .dvi files (e.g. dvidvi, dviselect, and dviconcat). A serious problem subsists: if they are sectionning commands and floating elements (like figures and tables) with captions in the secondary document, what to do to have a correct table of contents, a correct list of figures and tables in the main document? A similar problem arises for the bibliography. You just need to add, in the main document, at the insertion point, a

\AddInputInAux command:
     \AddInputInAux{⟨secondary document ⟩.aux}

and so the .aux file of the secondary document will be considered as an auxiliary file (of first or second level) of the main document. This method has a small drawback: if you declare the main document as an external document (as defined by the xr package) of the secondary document in order to be able to reference labels of the main document (or of parts of it) from the secondary one, you will have to use the optionnal argument in the command:

     \externaldocument[⟨optiannal arg. ⟩]{⟨main document ⟩}
     \externaldocument[⟨optionnal arg. ⟩]{⟨part of main document ⟩}

else the labels in the main document (or parts of it) would be considered as defined twice during the processing of the secondary document. This happens not often, but if you have this problem, the solution is simple but not evident.

2 Implementation

1 ⟨∗package⟩

\export First, we declare the \export write channel:

 2 \newwrite\export

\openexport The command \openexport announce the beginning of a sequence of exportations and opens the file which will be used to carry the data:

 3 \def\openexport#1{%
 4 \typeout{^^JExportations into #1.xpt.^^J}%
 5 \immediate\openout\export #1.xpt}

\closeexport The command \closeexport terminates a sequence of exportations by closing the file and announcing. Opening and closing are \immediate.

 6 \def\closeexport{\immediate\closeout\export%
 7 \typeout{^^JEnd of exportations.^^J}}

\ExportLength And now, the exporting commands. To export a length in points, we just use \the⟨¡⟩length¿ and write it as an argument of a \setlength command. This command may be used for rigid and rubber lengths, because \the gives the shrinking and stretching parts of a rubber length.

 8 \def\ExportLength#1{%
 9 \typeout{Exportation of length #1}%
10 \immediate\write\export{\string\setlength{\csname #1\endcsname}%
11 {\the\csname #1\endcsname}}}

\PreciseExportLength But for rigid lengths (for rubber ones, you would lose the skrinking and stretching parts), you shoud use \PreciseExportLength, which export the length expressed in scaled points. The trick is to use \number in place of \the, and adding sp for units.

12 \def\PreciseExportLength#1{%
13 \typeout{Precise exportation of length #1}%
14 \immediate\write\export{\string\setlength{\csname#1\endcsname}%
15 {\number\csname #1\endcsname sp}}}

\Export Exporting a counter is rather trivial, using \@arabic to get its value from the internal name of the L^{A}TEX counter.

16 \def\Export#1{%
17 \typeout{Exportation of counter #1}%
18 \immediate\write\export{\string\setcounter{#1}%
19 {\@arabic\csname c@#1\endcsname}}}

\Import Importing the data is easy: open the file for reading, read it: the \setcounter and \setlength commands are executed, then close it.

20 \def\Import#1{%
21 \typeout{^^JImportations from #1.xpt^^J}%
22 \InputIfFileExists{#1.xpt}{\relax}{\relax}}

\xcaptionf Now, the two caption commands. They increment the figure or table counter, then call the internal macro \@xcaption. We provide \xcaption if you have other classes of floats.

23 \def\xcaptionf{\refstepcounter{figure} \@dblarg{\@xcaption{figure}}}

\xcaptiont
24 \def\xcaptiont{\refstepcounter{table} \@dblarg{\@xcaption{table}}}
\xcaption
25 \def\xcaption#1{\refstepcounter{#1} \@dblarg{\@xcaption{#1}}}
\@xcaption
26 \long\def\@xcaption#1[#2]#3{\par\addcontentsline{\csname
27 ext@#1\endcsname}{#1}{\protect\numberline{\csname
28 the#1\endcsname}{\ignorespaces #2}}%
29 %  ^^A \begingroup
30 %  ^^A  \@parboxrestore
31 %  ^^A  \normalsize
32 %  ^^A  \@makecaption{\csname fnum@#1\endcsname}{\ignorespaces #3}\par
33 %  ^^A \endgroup

34 }

\iprotected@write We need these two internal macros for \AddInputInAux. They are slighty modified copies of similar macros in the L^{A}TEX kernel.

35 \def\iprotected@write#1#2#3{%
36  \begingroup
37  \let\thepage\relax
38  #2%
39  \let\protect\@unexpandable@protect
40  \edef\reserved@a{\immediate\write#1{#3}}%
41  \reserved@a
42  \endgroup
43  \if@nobreak\ifvmode\nobreak\fi\fi

44 }

\@inputx
45 \def\@inputx#1{{\def\bibcite##1##2{\relax}\@input{#1}}}

\AddInputInAux This macro write an \@inputx of the given file into the .aux file.

46 \def\AddInputInAux#1{%
47 \iprotected@write\@auxout
48  {%
49  \let\label\@gobble \let\index\@gobble \let\glossary\@gobble}%
50  {\string\@inputx{#1}%
51  }%
52 }%

\ExportPageLayout This macro is just a list of exportations of the lengths defining the page layout, because it would be so boring to type all that!

53 \def\ExportPageLayout{%
54 \PreciseExportLength{hsize}
55 \PreciseExportLength{vsize}
56 \PreciseExportLength{hoffset}
57 \PreciseExportLength{voffset}
58 \PreciseExportLength{linewidth}
59 \PreciseExportLength{columnwidth}
60 \PreciseExportLength{columnsep}
61 \PreciseExportLength{columnseprule}

62 \PreciseExportLength{parindent}
63 \PreciseExportLength{hoffset}
64 \PreciseExportLength{voffset}
65 \PreciseExportLength{oddsidemargin}
66 \PreciseExportLength{evensidemargin}
67 \PreciseExportLength{headheight}
68 \PreciseExportLength{headsep}
69 \PreciseExportLength{textheight}
70 \PreciseExportLength{textwidth}
71 \PreciseExportLength{paperheight}
72 \PreciseExportLength{paperwidth}
73 \PreciseExportLength{marginparsep}
74 \PreciseExportLength{marginparwidth}
75 \PreciseExportLength{marginparpush}
76 \PreciseExportLength{footskip}}
77 \endinput

Index

Numbers written in italic refer to the page where the corresponding entry is described, the ones underlined to the code line of the definition, the rest to the code lines where the entry is used.

Symbols

\@arabic . . . . . . . . . 19 \@auxout . . . . . . . . . 47 \@gobble . . . . . . . . . 49 \@input . . . . . . . . . . 45 \@inputx . . . . . . . \underline{45}, 50

\@makecaption . . . . . 32
\@unexpandable@protect

. . . . . . . . . . . . 39

\@xcaption . . 23–25, \underline{26}

A

\AddInputInAux . . . 5, \underline{46}

B

\begingroup . . . . . 29, 36

\bibcite . . . . . . . . . 45

C

\closeexport . . . . . 1, \underline{6}

\closeout . . . . . . . . . 6

E

\endgroup . . . . . . 33, 42 \Export . . . . . . . . . 1, \underline{16}

\export \underline{2}, 5, 6, 10, 14, 18

                          \ExportLength . . . . 1, \underline{8}
                          \ExportPageLayout 2, \underline{53}

G \glossary . . . . . . . . 49

I

                          \if@nobreak . . . . . . . 43

\ifvmode . . . . . . . . . 43

                          \immediate . . . . . . .

5, 6, 10, 14, 18, 40

\Import . . . . . . . . . . \underline{20} \index . . . . . . . . . . . 49

                          \InputIfFileExists . 22
                          \iprotected@write  \underline{35}, 47

L \label . . . . . . . . . . . 49

N \newwrite . . . . . . . . . 2 \nobreak . . . . . . . . . 43 \number . . . . . . . . . . 15

O

                                                   \openexport . . . . . . 1, \underline{3}

\openout . . . . . . . . . . 5

P

                                                   \PreciseExportLength

. . . . . 1, \underline{12}, 54–76

R

                                                   \reserved@a . . . . . 40, 41

S

                                                   \setlength . . . . . 10, 14

\string . . 10, 14, 18, 50

T \thepage . . . . . . . . . 37

W \write … 10, 14, 18, 40

X \xcaption . . . . . . . . \underline{25}

                                                   \xcaptionf . . . . . . 4, \underline{23}
                                                   \xcaptiont . . . . . . 4, \underline{24}