# [OS X TeX] Creating custom formats (was: TL-2007 missing .sty files)

Ross Moore ross at ics.mq.edu.au
Thu Jan 25 18:04:28 EST 2007

Hi Gary, Josep, and others,

On 26/01/2007, at 1:23 AM, Gary L. Gray wrote:

>>> then you can typeset a document with this format (with TeXShop)
>>> by putting:
>>>
>>> %!TEX TS-program = books
>>>
>>> at the top of the file you are typesetting.
>>
>> (of course, commenting out all the previous preamble)
>>
>> it stops at \begin{document}, the first uncommented line of the
>> file, complains that \normasize is not defined, and says there
>> must be something wrong witht the base class file. Besides, I see
>> no indications in the log window that the .fmt file has been used,
>> but it must be so since it does not complain that \documentclass
>> is missing, or that it is undefined as well...
>
>
> Hmmmm. Two things:
>
> (1) I assume that you didn't exactly use:
>
> %!TEX TS-program = books
>
> since with the the instructions above, it should be:
>
> %!TEX TS-program = FormatName
>
> You need to insert the name of your format.
>
> (2) Did you verify that a document typesets with the preamble you
> are using to create the format before creating the format?
>
> Those are the only two things I can see that would be preventing
> this from working for you.

No; there can be other, more fundamental reasons than these.

Firstly there is the issue of search-paths.

If there are more format files to be loaded --- that is,
\usepackage{...}  commands that have not been included within
the format --- then the search-paths may need to be setup
for the new format.

This can require an edit within the  texmf.cnf  file.
e.g. my  texmf.cnf  file contains a line:

TEXINPUTS.xelatex = .;$TEXMF/{xetex,tex}/{xelatex,latex,generic,}// Suppose I build a format (using xetex) called xthesis.fmt say. Then to find packages with the new format I'll need also a line: TEXINPUTS.xthesis = .;$TEXMF/{xetex,tex}/{xelatex,latex,generic,}//

With packages based upon LaTeX you'll need to check whether there
is a variable   TEXINPUTS.latex  in the  texmf.cnf  file.
If so, then you'll need a line for your new formats, analogous
to the above example.

Most probably this isn't going to be a problem; e.g.
there are no TEXINPUTS variables defined, or nothing specific
to a particular format. That's quite normal, and the generic
paths will suffice.

The second issue concerns use of auxiliary files;
e.g.  .aux  .toc  etc.

You cannot just put  \dump  *anywhere* in a LaTeX document.

For example

\input latex.ltx
\documentclass{...whatever...}
... load some packages and inputs ...
\begin{document}
\dump

will most certainly *not* work as you would like.

The resulting format cannot maintain a link to the .aux file.
When you process a document using this format, the commands
to open and process the  .aux  file are never encountered,
since these happen as a result of  \begin{document}
and the results of that coding have been frozen into the
format. Not only was the filename different then, but
that file was closed long ago, and your processing run

This "auxiliary-file" aspect applies to any package that
uses extra files to handle information; e.g. for multiple
indexes, mini- tables-of-contents, change-bars, etc.
Indeed, there are quite a lot of packages that cannot work
with home-grown format files, without special care being
taken about how the format is built.

Thus your document structure, when building the format
needs to look like:

\input latex.ltx
\documentclass{...whatever...}
... load safe packages and inputs ...
\dump   %  processing finishes here !!!
%  so you can omit what comes below.
... load unsafe packages and inputs ...
\begin{document}
...
\end{document}

and when using it, your document must look like:

%  \input latex.ltx
%  \documentclass{...whatever...}
%  ... load safe packages and inputs ...
%  \dump
... load unsafe packages and inputs ...
\begin{document}
...
\end{document}

where the %-commented lines can be omitted altogether.

Now LaTeX does a lot of internal processing, when
\begin{document} is encountered; e.g. setting-up
The above considerations mean that you cannot avoid
doing this work, so your customised format doesn't
actually save you a lot of time.

With computers getting ever faster, there really
is not a lot of point to "building your own" anymore.

I once wrote a package called  ldump.sty  that gave
the means to compile efficient formats for use with
LaTeX documents. It made some fundamental changes
to LaTeX internals, so that the "safe" operations
that take place at \begin{document} could be frozen
into the format, but "unsafe" ones (such as opening
the .aux file) would not be.
To use it, you need to be aware of which packages
are safe and which not, and structure your document's
preamble accordingly. The package is shipped with
LaTeX2HTML and is described in a TUGboat article.

Unfortunately, it had to be modified slightly with
subsequent changes to LaTeX itself.
I've not bothered to keep it up-to-date, since computers
got faster and the benefits were no longer so significant.
(Probably it still works just fine, but I'm not prepared
to guarantee that.)

>
> Let us know.
>
> All the best,
>   Gary

Hope this helps,

Ross

------------------------------------------------------------------------
Ross Moore                                         ross at maths.mq.edu.au
Mathematics Department                             office: E7A-419
Macquarie University                               tel: +61 +2 9850 8955
Sydney, Australia  2109                            fax: +61 +2 9850 8114
------------------------------------------------------------------------