% 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}
