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