%% mpicp-oxford.tex 
%% mathspic manual
%% (derived from my file  oxford.tex)
%% Originally presented to UKtug meeting Oxford July 2001
%% RWD Nickalls 
%% added new sections for the next mathsPIC manual
%%-----------------------------

\documentclass[mathsPICmanual.tex]{subfiles}
\begin{document}

%%=============================

\chapter{Accessing \TeX\ parameter values\protect\footnote{Much of this chapter was originally presented by RWD Nickalls to the November 2001 ukTUG meeting.}}
\label{ch:texparameters}

It is sometimes useful for mathsPIC to be able to access \TeX\
parameter values.
For example, \mathsPIC\ could be made to automatically scale
the height and width of a graph to the as yet unknown page
size of the \TeX\ document.
Knowledge of  the \TeX\ parameters
\verb!\textheight! and \verb!\textwidth! during processing
would allow the height and width of a graph to be defined
as a function of these page parameters.

One way of doing this is to include in the \TeX\ file some
code to write the required parameter values to a temporary
data file, in the form of
\mathsPIC\ \verb!var! commands or macros. Using the \mathsPIC\
\verb!system()! command \mathsPIC\ can  run the \TeX\ file,
and then access the parameter values by inputting the data-file.

%-------
\section{Useful \TeX\ commands}

\begin{verbatim}
\settowidth{\variablename}{text}
\settoheight{\variablename}{text}
\settodepth{\variablename}{text}
\end{verbatim}
For example, the following code would put the length of the
word January into the variable \verb!\janlength!.
Note that \verb!\the! gives the value in points, while
\verb!\number! returns the value as an integer in scaled points
(see Table~\ref{tab:beccarismall}).

\begin{verbatim}
\newlength{\janlength}
\settowidth{\janlength}{January}
The length of the word January in points is \the\janlength
The length of the word January in `scaled' points is \number\janlength
\end{verbatim}
The output is as follows (note that \verb!\the\janlength!
returns the numeric points but includes the characters
\verb!pt! on the end).

\begin{verbatim}
The length of the word January in points is 35.16676pt
The length of the word January in `scaled' points is 2304689
\end{verbatim}


\TeX\ has a number of parameters which are classified according
to type, e.g.~integers, dimensions, glue, muglue, token lists.
For a full list of all the \TeX\ parameters which have values which
can be accessed see Knuth (1990; page 272--275).

The token list \verb!\jobname! is very useful as it holds the
filename (but not the filename extension) which \TeX\ is
currently working on, and can be used for generating
derivative temporary files, e.g.~\verb!\jobname!{.dvi},
\verb!\jobname!{.toc} etc.

%-------
\section{Outputting data to a file}
\TeX\ requires a file-number as a handle to identify an `open' file,
and has the command \verb!\newfile! specifically for allocating an unused
file-number to a variable name. We then use the commands
\verb!\openout!, \verb!\write!, and \verb!\closeout!  to open,
write to, and close the file.
For example, the following code will write \texttt{...blah blah
blah ..} to the file \verb!texfiledata.dat! using the file handle
\verb!\outfile!.

\begin{verbatim}
\newwrite\outfile
\openout\outfile=texfiledata.dat
\write\outfile{...blah blah blah....}
\closeout\outfile
\end{verbatim}

Note that the \verb!\write! command only writes the
data to the file when the \verb!.dvi! file is created, so if
these commands are in a file which may not actually create a
\verb!.dvi! file, then we may need to force output (\verb!dvi! file creation)  by including something writable like \verb!\strut! on a line.

Alternatively, we can force \TeX\ to write to the file
immediately (i.e.\ without waiting until it gets to the end of
file processing) by using the \verb!\immediate! command,
remembering to include it with \textit{all} the commands
\verb!\openout!, \verb!\write!, and \verb!\closeout!, as follows.

\begin{verbatim}
\newwrite\outfile
\immediate\openout\outfile=texfiledata.dat
\immediate\write\outfile{...blah blah blah....}
\immediate\closeout\outfile
\end{verbatim}

Since we are interested in accessing the values of \TeX\
parameters, we need to explore some of the \TeX\ commands for
accessing such values.  For example, the commands
\verb!\the!, \verb!\number! and \verb!\showthe! all reveal the
numeric value, but in slightly different formats and location, as follows.


\begin{verbatim}
\the\textwidth      ---> 400.0pt       includes the characters pt
\number\textwidth   ---> 26214400      scaled points (see Table)
\showthe\textwidth  ---> only writes to the log file
\end{verbatim}

For the purposes of \mathsPIC\ accessing the numeric value as a variable or macro, it is most convenient to use the \verb!\number! command
(yields an integer value in the `scaled points' used internally
by \TeX)\footnote{$65536$ scaled points = 1 printers point (pt).}
and to incorporate it into a \mathsPIC\ variable or macro so it is ready
to be used once the temporary file it is written to has been input
by \mathsPIC. For example, the following code allocates the
scaled point value of \verb!\textwidth! to the \mathsPIC\
variable \verb!w555!.

\begin{verbatim}
\immediate\write\outfile{var w555 = \number\textwidth}
\end{verbatim}
If the \verb!\textwidth! was 400pt (14.058 cm), then the
output of the above line would be as follows
($65536$ scaled points = 1 printers point pt).

\begin{verbatim}
var w555 = 26214400
\end{verbatim}
In practice, it is useful to have this line commented to
indicate which \TeX\ parameter the value relates to, as follows.
\begin{verbatim}
var w555 = 26214400%  \textwidth (scaled points)
\end{verbatim}
However, since what came after the \verb!%! symbol
would be ignored in this setting, we need to
define the \verb!%! as a character we can print to a file, by allocating
it the catcode 12 (instead of the catcode of 14 which it normally has),
and calling it by a different name (\verb!\percentchar!), and delimiting the whole line by a curley brace (to keep it local),  as
follows.\footnote{From: Abrahams, Berry and Hargreaves (1990), p~292.}

\begin{verbatim}
{\catcode`\%=12   \global\def\percentchar{%}}%
\end{verbatim}

So now, the following code will also include a trailing comment
indicating the \TeX\ name of the parameter.

\begin{Verbatim}
\newcommand{\comment}{\percentchar\space}
\immediate\write\outfile{var w555 = \number\textwidth
	 \comment\textwidth is \the\textwidth}
\end{Verbatim}
For example, the resulting line in the output file is as follows.

\begin{verbatim}
var w555 = 29368707% \textwidth is 448.1309pt
\end{verbatim}

%%------------table ----------------------


%% define a strut for the table
\newcommand{\tablestrut}{\rule[-2pt]{0pt}{13pt}} %% used in the units Table

\begin{table}[hbt]
\begin{center}
\begin{minipage}{0.8\textwidth}
\caption{Note that for accurate working always use scaled points (sp) and convert in a single step using  the following convertion factors
 (modified from: Beccari C, 1991)}
 \label{tab:beccarismall}
\end{minipage}

\medskip
\begin{tabular}{|c||c|}
\hline
\multicolumn{1}{|c||}{\tablestrut }&
\multicolumn{1}{|c|}{sp}\\
\hline
\hline
\tablestrut mm & $186467.98$    \\
\hline
\tablestrut cm & $1864679.8$     \\
\hline
\tablestrut pt & $65536$        \\
 \hline
\tablestrut in &  $4736286.70$    \\
\hline
 \end{tabular}
 \end{center}
 \end{table}
%%--------------end of table--------------------------------------



\section{The final code}

So now we can put all this code together into one chunk
within the target \TeX\ file, or more usefully, keep it as a
separate file which can then just be \verb!\input! whenever it
is required.
For example inputting the following file
(and {\LaTeX}ing it) will
output a data file containing appropriate  \mathsPIC\  commands
with the embedded values of \verb!\textwidth! and
\verb!\textheight!. Note that in the following example we have defined two \mathsPIC\ macros called \verb!textwidthcms! and \verb!textheightcms! which will contain the relevant values in cms (see Table~\ref{tab:beccarismall} for conversion factors).

\begin{verbatim}
%% grabtexdata.tex
%-----------------
\scrollmode  % prevent LaTeX stopping if there are errors
%---------------------
% make a print command  macro
\newcommand{\print}[1]{\immediate\write\outfile{#1}}
%---------------------
% make a comment % command  macro
% first need to define percentchar for the write statement
% (From "TeX for the Impatient" (1990), p 292)
{\catcode`\%=12   \global\def\percentchar{%}}%
\newcommand{\comment}{\percentchar\space}
%
% make a \macro command --> %def<space>
\newcommand{\mydef}{def}
\newcommand{\macro}{\percentchar\mydef\space}
%----------------------
% create and open a new file with filename = textfiledata.dat
\newwrite\outfile
\immediate\openout\outfile=texfiledata.dat
%----------------------
%% write file header & general info
\print{\percentchar\percentchar\space file: texfiledata.dat}
\print{\percentchar\percentchar\space accessing TeX parameter values}
%---------------------
%% now get \textwidth and \textheight values from the tex file
\print{var w555 = \number\textwidth\comment\textwidth=scaled points}
\print{var w556 = \number\textwidth\comment\textwidth=\the\textwidth}
\print{var w557 = \number\textwidth/1864679.8\comment (\textwidth in cms)}
\print{\comment ============}
\print{\macro textwidthcms()\number\textwidth/1864679.8\comment}
\print{\macro textheightcms()\number\textheight/1864679.8\comment}
\print{\comment ============}
%--------------------
% close the file
\immediate\closeout\outfile
\end{verbatim}
In practice one would simply include the following line
\begin{verbatim}
\input{grabtexdata.tex}
\end{verbatim}
in the \TeX\ file we want  data from (say, \verb!myfile.tex!), and then \LaTeX\ the file to generate the output data file.
Alternatively we could \LaTeX\ the file from within \mathsPIC\
using the \verb!system! command, and then input the resulting data  file as follows.
\begin{verbatim}
system(``latex2e myfile.tex'')
input(texfiledata.dat)
\end{verbatim}
Either way, the resulting
output data file \texttt{texfiledata.dat} for a file having a  standard \verb!{article}! format  is as follows
\begin{verbatim}
%% texfiledata.dat
%% accessing TeX parameter values
var w555 = 22609920% \textwidth =scaled points
var w556 = 22609920% \textwidth =345.0pt
var w557 = 22609920/1864679.8% (\textwidth in cms)
% ============
%def textwidthcms()22609920/1864679.8%
%def textheightcms()39190528/1864679.8%
% ============
\end{verbatim}
Once the above file (\verb!texfiledata.dat!) is input into a \mathsPIC\ file
we can then use \mathsPIC\ commands to  manipulate the textwidth and textheight values, as shown in the following example \mathsPIC\ file.

{\color{blue}
\begin{verbatim}
\documentclass[a4paper]{article}
\usepackage{mathspic}
\begin{document}
\end{verbatim}
}\joinverbatim
\begin{verbatim}
.....
system(``latex2e myfile.tex'')
inputfile(texfiledata.dat)
var w=&textwidthcms, w2= &textwidthcms/2
var h=&textheightcms, h2=&textheightcms/2
...
\end{verbatim}
\joinverbatim
{\color{blue}
\begin{verbatim}
\end{document}
\end{verbatim}
}
%---------------
Processing  the \mathsPIC\ file gives  the folllowing output. Notice how useful it is to have the accompanying comments.
\begin{verbatim}
%% inputfile(texfiledata.dat)
%% ... start of file <texfiledata.dat> loop [1]
%%% Iteration number: 1
%% texfiledata.dat
%% accessing TeX parameter values
%% var w555 = 22609920% \textwidth =scaled points
%% w555 = 22609920
%% var w556 = 22609920% \textwidth =345.0pt
%% w556 = 22609920
%% var w557 = 22609920/1864679.8% (\textwidth in cms)
%% w557 = 12.1253632929364
% ============
%def textwidthcms()22609920/1864679.8%
%def textheightcms()39190528/1864679.8%
% ============
%% ... end of file <texfiledata.dat> loop [1]
%% var w=22609920/1864679.8, w2= 22609920/1864679.8/2
%% w = 12.1253632929364
%% w2 = 6.0626816464682
%% var h=39190528/1864679.8, h2=39190528/1864679.8/2
%% h = 21.0172963744231
%% h2 = 10.5086481872116
\end{verbatim}



\end{document}
