% fileform.doc 18 Jul 91
%------------------------------------------------------------
% Copyright 1990 by J.Schrod.
%
% fileformats for TeX and MF (usage of WEAVE like output in LaTeX)
%
% [LaTeX style option, in MAKEPROG]
%
% VERSION HISTORY (MSCF -- most significant change first)
%
% DATE WHO REMARK
% 91-07-18 js define \MF only if it is not already defined
% 90-12-05 js no line break between \cmd definition and explanation
% ragged right within \cmd definition
% 90-12-03 js allows a line break within \cmd definition
% 90-11-07 js added PL support, paintletter environment
% 90-07-05 js first release
% author's current address:
%
% Technical University of Darmstadt
% Institut f\"ur Theoretische Informatik
% Joachim Schrod
% Alexanderstr. 10
%
% D-W-6100 Darmstadt
% FR Germany
%
% Tel. (+6151) 16-3711
% Email: xitijsch@ddathd21.bitnet
%%%%
%%%%
%%%% These TeX macros were documented with the documentation system
%%%% MAKEPROG and automatically converted to the current form.
%%%% If you have MAKEPROG available you may transform it back to
%%%% the original input: Remove every occurence of three percents
%%%% and one optional blank from the beginning of a line and remove
%%%% every line which starts with four percents. The following lex
%%%% program will do this:
%%%%
%%%% %%
%%%%
%%%% ^%%%\ ? ;
%%%% ^%%%%.*\n ;
%%%%
%%%% MAKEPROG may be obtained over the net from the Bitnet-Listserver
%%%% LISTSERV@DHDURZ1 (filelist WEBWARE) or via ftp from ftp.th-darmstadt.de
%%%% in the directory /pub/tex/src-webware.
%%%%
%%%%
%%% \documentstyle[progltx]{article}
%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% %
%%% % local macros
%%% %
%%% \makeatletter
%%% \let\mc=\small % for names like GNU
%%% \@onesizefont\logo{logo10}
%%% \def\MF{{\logo META}\-{\logo FONT\/}}
%%% \def\WEB{{\tt WEB\/}}
%%% \def\WEAVE{{\tt WEAVE\/}}
%%% \def\GNU{{\mc GNU}}
%%% \makeatother
%%% %
%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% \begin{document}
%%% % \title{\TeX{} and \MF{} File Formats} % should be done in this way
%%% \title{\TeX{} and METAFONT File Formats} % blame LaTeX!!
%%% \author{\sc Joachim Schrod}
%%% \maketitle
%%% \chap Introduction.
%%% The {\tt DVI\/} Driver Standard contains the description of common
%%% file formats ({\tt DVI}, {\tt TFM}, {\tt PK}, etc.)\ as appendices.
%%% These descriptions are taken from \WEB{} programs. Weaving the \WEB{}
%%% programs results in a \TeX{} source, but sprinkled with macros from
%%% {\tt webmac}. These macros are not only used for typesetting symbolic
%%% identifiers needed for the definition of opcodes, in the definition
%%% of the {\tt PK\/} format even a whole Pascal program must be typeset
%%% -- the description of decoding run counts is given as a Pascal {\bf
%%% function}.
%%% The macros defined below allow such a typesetting. They were
%%% developped in 1988 as a part of a general macro package called {\mc
%%% WEBSET} which allows the direct inclusion of \WEAVE{} output in
%%% several macro packages (among others \LaTeX{}). But {\sc Don Hosek}
%%% has asked for a \LaTeX{} markup so that we cannot use these macros
%%% directly. (A \LaTeX{} markup has the advantage that it may be altered
%%% by more people than a \WEB{} markup.) The macros defined here are
%%% renamed for better readability, and they are only those few macros
%%% needed for typesetting the file formats.
%%% At the First European TUG Conference in Cork 1990 Barbara Beeton asked
%%% me if I would like to supply a brochure with {\it all\/} file formats
%%% formally defined in context with the systems \TeX{} and \MF{}. The
%%% file formats of the |DVI| driver standard were more than half of the
%%% needed definitions, but the rest require additional markups. So this
%%% macro file was enhanced and renamed from ``File Formats For the {\tt
%%% DVI\/} Driver Standard'' to ``\TeX{} and \MF{} File Formats''
%%% If you want to incorporate \WEB{} programs or parts of them into
%%% documents which are to be published you should contact me. In my
%%% opinion the macros below are no starting point for such a task.
%%% \beginprog
\immediate\message{TeX and MF file formats <18 Jul 91>}
%%% \endprog
%%% \sect This style option is free software; you can redistribute it
%%% and/or modify it under the terms of the \GNU{} General Public License
%%% as published by the Free Software Foundation; either version~1, or
%%% (at your option) any later version.
%%% This style option is distributed in the hope that it will be useful,
%%% but {\bf without any warranty\/}; without even the implied warranty
%%% of {\bf merchantability\/} or {\bf fitness for a particular purpose}.
%%% See the \GNU{} General Public License for more details.
%%% You should have received a copy of the \GNU{} General Public License
%%% along with this style option; if not, write to the Free Software
%%% Foundation, Inc., 675~Mass Ave, Cambridge, MA~02139, USA.
%%% \sect \begin{sloppypar}
%%% Before we start we declare some shorthands for category codes. By
%%% declaring the underscore~`(|_|)' as a letter we can use it in our
%%% macro names. (I agree with D.~Knuth that
%%% |\identifier_several_words_long| is more readable than
%%% |\IdentifierSeveralWordsLong| and in every case better than
%%% |\p@@@s|.) But as we have to restore the category codes at the end of
%%% this macro file we store its former value in the control sequence
%%% |\uscode|. This method is better than the usage of a group because
%%% not all macros have to be defined global this way.
%%% \end{sloppypar}
%%% \beginprog
\chardef\letter=11
\chardef\uscode=\catcode`\_
\catcode`\_=\letter
%%% \endprog
%%% \sect We have to typeset typical tokens like string elements or
%%% identifiers, descriptions of the commands found in the files.
%%% Furthermore we have to define the |webprog| environment which allows
%%% to typeset the Pascal function {\it pk\_packed\_num\/} -- but {\it
%%% only this\/} function\,\dots
%%% But before we start to implement the above we just define the logo
%%% |\MF| (\MF{}) needed e.g.\ by the {\tt GF\/} format text. This
%%% definition is only needed if it was not done before by other style
%%% options.
%%% \beginprog
\ifx \MF\undefined
\@onesizefont\logo{logo10}
\def\MF{{\logo META}\-{\logo FONT\/}}
\fi
%%% \endprog
%%% \chap Tokens.
%%% String elements will be typeset with |\str|. This allows to print all
%%% special \TeX{} characters with a preceding backslash. To implement
%%% this we use character definitions of {\tt webmac\/} -- which are in
%%% uppercase so that they are hopefully not in conflict with other
%%% macros. These character definitions will be used locally in~|\str|.
%%% \beginprog
\chardef\AM=`\& % ampersand character in a string
\def\AT!{@} % at sign for control text
\def\BS{{\tt\char`\\}} % backslash
\chardef\HA=`\^ % hat in a string
\chardef\LB=`\{ % left brace in a string
\def\LQ{{\tt\char'22}} % left quote in a string
\chardef\RB=`\} % right brace in a string
\def\RQ{{\tt\char'23}} % right quote in a string
\def\SP{{\tt\char`\ }} % (visible) space in a string
\chardef\TL=`\~ % tilde in a string
\chardef\UL=`\_ % underline character in a string
\def\str#1{% % strings (in typewriter)
\leavevmode
\hbox{\tt
\let\\\BS % backslash in a string
\let\'\RQ % right quote in a string
\let\`\LQ % left quote in a string
\let\{\LB % left brace in a string
\let\}\RB % right brace in a string
\let\~\TL % tilde in a string
\let\^\HA % hat in a string
\let\ \SP % space in a string
\let\_\UL % underline in a string
\let\&\AM % ampersand in a string
#1%
}%
}
%%% \endprog
%%% \sect Keywords are only needed in the {\tt TFM\/} description for the
%%% specification of the header -- this is done in a Pascal notation with
%%% {\bf array\/}'s.
%%% Often needed are identifiers.
%%% \beginprog
\def\res#1{% % reserved words (in bold)
\leavevmode
\hbox{\bf #1\/}%
}
\def\id#1{% % identifiers (in italics)
\leavevmode
\hbox{\it #1\/\kern.05em}%
}
%%% \endprog
%%% \sect We do not introduce new names for typesetting non-decimal
%%% constants.
%%% \beginprog
\def\H#1{%
\leavevmode
\hbox{\rm\char"7D\tt #1}%
}
\def\O#1{%
\leavevmode
\hbox{\rm\char'23\kern-.2em\it #1\/\kern.05em}%
}
%%% \endprog
%%% \chap Definition of Commands.
%%% Commands will be marked with |\cmd|. Following this markup will be a
%%% description of the opcode, usually both symbolic and numeric, which
%%% is to be terminated by a comma. The Operand description follows and
%%% is terminated by a dot. The operand description is typeset in math
%%% mode, with active spaces. After this command specification comes the
%%% next paragraph: a verbal description of the command.
%%% The implementation is simple: we establish a hanging indentation for
%%% the command specification and start with the opcode itself,
%%% unindented. Since during the typesetting of the operands blanks shall
%%% be active we establish them first and call |\get_operands|
%%% afterwards. So during the tokenization of the parameter of
%%% |\get_operands| we will regard all blanks.
%%% \beginprog
\def\cmd #1,{%
\endgraf
\smallbreak
\bgroup
\rightskip \z@ plus 1em % may be typeset raggedright
\hangindent 4em
\noindent #1%
\obeyspaces
\get_operands
}
%%% \endprog
%%% \sect We must define the active blank to work like `{\tt
%%% \char`\\\char`\ }' but our macros should be written indented according
%%% to their structure. So we just establish the meaning of active blank
%%% and call |\set_operands| with the parameter token list.
%%% \beginprog
\begingroup\obeyspaces
\gdef\get_operands#1.{\def {\allowbreak\ }\set_operands{#1}}
\endgroup
%%% \endprog
%%% \sect If there are no operands for this command we have finished the
%%% command specification. Afterwards we delimit the operands from the
%%% opcode by a quad and typeset them in math mode. Closing the group
%%% removes the special meaning of the active blank.
%%% The command description is typeset with only half the indentation of
%%% the specification but with no vertical skip between. (\TeX{} inserts
%%% the |\parskip| at the beginning of a new paragraph, so we just begin
%%% the new paragraph inside a group where |\parskip| is~0\,pt.)
%%% \beginprog
\def\set_operands#1{%
\def\op{#1}%
\ifx \op\empty
\else \quad \ignorespaces $#1$%
\fi
\par
\egroup
\nobreak
\hangindent 2em
\hangafter \z@
{\parskip\z@skip \noindent}%
\ignorespaces
}
%%% \endprog
%%% \sect Belonging to the command descriptions is a collection of all
%%% opcodes to get an overview. They are typeset like \WEB{} defines
%%% (what they originally were). We have to supply comments which will be
%%% enclosed in braces; the corresponding macro |\C| will always be
%%% called outside of math mode.
%%% Both macros are smaller versions of those found in {\tt webmac}.
%%% \beginprog
\def\define{% % begin `define'
\endgraf
\hangindent 8em
\res{define }%
}
\def\C#1{% % comments
$\hfil\penalty-\@ne\hfilneg
\quad \lbrace \,$#1$\, \rbrace
$%
}
%%% \endprog
%%% \sect The Pascal Function.
%%% All macros we have to define for the Pascal function are defined
%%% inside the |webprog| environment. This is different to {\mc WEBSET\/}
%%% where these macros are defined globally.
%%% At first we start with the definition of the amount of indentation for
%%% each part of a compound statement. A few supplementary boxes for
%%% realizing the ``{\it outdent\/}'' of one statement are needed (here we
%%% follow the implementation of {\tt webmac\/}).
%%% \beginprog
\newdimen\indsize % one indentation unit
\indsize=2em
\newdimen\ind % current indentation
\newbox\bak
\setbox\bak=\hbox to -\indsize{} % backspace one unit
\newbox\bakk
\setbox\bakk=\hbox to -2\indsize{} % backspace two units
%%% \endprog
%%% \sect The |webprog| environment defines all macros needed to typeset
%%% the function {\it pk\_packed\_num}. Strings, reserverd words,
%%% identifiers (one and more letters long), and a few math symbols are
%%% needed in their \WEB{} markup. The beginning of the program part with
%%% |\P| is realized by |\WEB_prog_mode| which will be implemented in the
%%% next section.
%%% At last the \WEB{} macros for controling the indentation are needed,
%%% their names consist of one digit: |\1|~increases, |\2|~decreases the
%%% current indentation, |\3|~is an optional break within a statement,
%%% |\4|~backspaces one indentation unit (used at the beginning of a
%%% line), |\5|~is an optional break between two statements, and |\6|~is a
%%% forced break between two statements.
%%% \beginprog
\def\webprog{%
\endgraf
\medbreak
\let\.\str
\let\&\res
\let\\\id
\def\|##1{% % identifiers with one letter
\leavevmode
\hbox{$##1$}%
}%
\let\I\ne
\let\K\gets
\let\L\le
\let\P\WEB_prog_mode
\def\1{%
\global\advance \ind by \indsize
\hangindent\ind
}%
\def\2{\global\advance \ind by -\indsize}
\def\3##1{\hfil \penalty ##10 \hfilneg}%
\def\4{\copy\bak}%
\def\5{%
\hfil \penalty-\@ne \hfilneg
\kern .5em
\kern \tw@\indsize \copy\bakk
\ignorespaces
}%
\def\6{%
\ifmmode
\else\endgraf
\hangindent \ind
\noindent \kern\ind \copy\bakk
\ignorespaces
\fi
}%
}
%%% \endprog
%%% \sect Typesetting Pascal programs requires other paragraph shape
%%% values than typesetting text. |\WEB_prog_mode| establishes them and
%%% starts the program in horizontal mode; it will be called within a
%%% group.
%%% The values established are no paragraph skip and no indentations
%%% because each major part (delimited by |\6|) of a program will be a
%%% paragraph. Statements may not reach the right margin or they may even
%%% stick a bit into. After the statement separator (`|;|') we just let a
%%% little bit more space. Hyphenation is of no sense within programs.
%%% \beginprog
\def\WEB_prog_mode{%
\parskip\z@skip
\parindent\z@
\rightskip \z@ plus 100\p@ minus 10\p@
\sfcode`; 3000
\pretolerance\@m
\hyphenpenalty\@m
\exhyphenpenalty\@m
\global\ind \thr@@\indsize % standard indentation
\hangindent\ind
\ifvmode
\noindent \kern\ind \copy\bakk % go in horizontal mode
\fi
}
%%% \endprog
%%% \chap Letter shapes.
%%% Sometimes letters with their pixels are shown as an example. Then the
%%% |letter| environment may be used: Every line is a pixel row and must
%%% start with `|&|'. White pixels are input as blanks, black pixels are
%%% as stars. Tabs must not be used. A `|+|' is used for the reference
%%% point of a character. The rest of the line after |\begin{letter}| is
%%% ignored.
%%% The output is centered, every line is preceded with a line number.
%%% \beginprog
\newcount \letter_lines
\def\paintletter{%
\center \noindent
\vtop\bgroup
\setup_letter
\global\letter_lines\z@
\ialign\bgroup
\global\advance\letter_lines\@ne
\hfil \number\letter_lines ##\quad &%
##\hfil\crcr
}
\def\endpaintletter{%
\crcr
\egroup
\egroup
\endcenter
}
%%% \endprog
%%% \sect |\setup_letter| sets up the new meaning of all required
%%% characters. The general font is Roman in footnote size, used only for
%%% the row numbers. The lines are exactly 10pt apart.
%%% \beginprog
\def\setup_letter{%
\let\par\crcr \obeylines
\setup_letter_blank
\setup_letter_star
\setup_letter_plus
\footnotesize
\baselineskip 10\p@
}
\begingroup
\catcode`\ =\active
\gdef\setup_letter_blank{\obeyspaces \let \letter_white}
\endgroup
\begingroup
\catcode`\*=\active
\gdef\setup_letter_star{\catcode`\* \active \let*\letter_black}
\endgroup
\begingroup
\catcode`\+=\active
\gdef\setup_letter_plus{\catcode`\+ \active \let+\letter_reference}
\endgroup
%%% \endprog
%%% \sect Every pixel in the letter is typeset 10\,pt high and 10\,pt
%%% wide, black pixels are painted by a square of $7\times 7\,pt$. The
%%% height of the pixels is already set by the |\baselineskip|, we have to
%%% take care of the width.
%%% \beginprog
\def\letter_white{\hbox to 10pt{\hfil}}
\def\letter_black{\hbox to 10pt{\vrule height 7pt width 7pt depth 0pt \hfil}}
\def\letter_reference{\hbox to 10pt{\tentt +\hfil}}
%%% \endprog
%%% \chap Specialities for property lists.
%%% There are two formally defined file formats in textual
%%% representation, property lists for |TFM|~files (|PL|), and property
%%% lists for |VF|~files (|VPL|). The last are nearly a superset of the
%%% former ones. Therefore we give the \TeX{}er the opportunity to discard
%%% the |PL|~definition parts in the |VPL|~definition. Appropriate
%%% references are inserted then. This is controlled by the switch
%%% |\ifPL|.
%%% \beginprog
\newif\ifPL
%%% \endprog
%%% \sect But there is a minor problem: The definition of a decimal number
%%% in a property list is not the same. We provide a token variable which
%%% will hold the respective description.
%%% \beginprog
\newtoks\DecimalDescription
%%% \endprog
%%% \sect We are finished and just have to restore the category code of
%%% the underscore. As usually, we add an |\endinput| so that garbage may
%%% follow.
%%% \beginprog
\catcode`\_=\uscode
\endinput
%%% \endprog
%%% \end{document}