% Document Type: LaTeX
% Master File: userguide.tex
\documentstyle[11pt,array]{article}

\title{Formating HOL text: the library {\tt latex-hol}}
\author{Wai Wong}
\date{21 May 1991}

\input{../holmacs}

\begin{document}
\maketitle
  
The library {\tt latex-hol} provides HOL users a very convenient means of
formatting HOL text using the \LaTeX\ typesetting system. This library
uses the general pretty printer in the {\tt prettyp} library to
translate HOL text into \LaTeX\ format. After loading the library, a
set of ML functions are defined. Users can use these functions to
generate \LaTeX\ sources of HOL terms, theorems or whole theory. These
can then be incorporated into a document to produce high quality
typeset output.  

\section{Installing the Library}

To install the {\tt latex-hol} library, you need to put all the files
into a directory named {\tt latex-hol}. If the set of files is in its
compiled form, you simply add this directory into HOL's search path
and copy the file {\tt holmacs.tex} to the directory where \LaTeX\
searches for macros. The macros directory in many systems is usually named
{\tt /usr/local/lib/tex/macros} or {\tt /usr/local/lib/tex/inputs}. It
may also be put in the directory of
your private collection of macros. You can now start using {\tt latex-hol}.

 Otherwise, you have to rebuild the library by typing 
\begin{verbatim}
  make clobber
  make all
\end{verbatim}
in the {\tt latex-hol} directory. This should compile all the
necessary files. See the {\tt Makefile} for more information.

\section{Using the Library}

To use the {\tt latex-hol} library, all you need to do is to load the
library into HOL by the command
\begin{verbatim}
  load_library`latex-hol`;;
\end{verbatim}
Now, you can call the function {\tt latex\_thm} to translate a HOL thm
to \LaTeX. It take the name of the theorem as its argument. For
example,
\begin{verbatim}
  latex_thm INDUCTION;;
\end{verbatim}
translates the theorem {\tt INDUCTION} to
\begin{verbatim}
\THM \FORALL P\DOT P \,\CONST{0} \AND 
     (\FORALL n\DOT P \,n \IMP  P \,(\CONST{SUC} \,n)) \IMP 
        (\FORALL n\DOT P \,n)
\end{verbatim}
and displays it on your terminal. You can then yank it and put into a
\LaTeX\ document. You have to input the macro file {\tt holmacs.tex} in
your document in front of the position where the first theorem
appears. The theorem should be put in one of the \LaTeX\ math
modes, i.e., enclosing it in a pair of {\tt \$} signs or between
\verb|\[| and \verb|\]|. After
running \LaTeX, this will be typeset as 
\[\THM \FORALL P\DOT P \,\CONST{0} \AND 
               (\FORALL n\DOT P \,n \IMP  P \,(\CONST{SUC} \,n)) \IMP 
                      (\FORALL n\DOT P \,n)
\]
Notice that all the operators are set in their conventional
mathematical symbols, HOL constants are set in {\constfont sans serif}
font and space is added where it is needed automatically.  The
trailing digits of variables {\tt x1}, {\tt x2} etc. will 
become subscript as in the following theorem RIGHT\_AND\_OVER\_OR
\[
\THM \FORALL t_{1} \,t_{2} \,t_{3}\DOT
        (t_{2} \OR  t_{3}) \AND  t_{1} =
           t_{2} \AND  t_{1} \OR  t_{3} \AND  t_{1}
\]

However, it is not very convenient to copy the text generated by {\tt
latex\_thm} if there are many theorems you want to typeset. Another
function {\tt latex\_thm\_to} will output the text to a file specified
as its first argument. The command
\begin{verbatim}
  latex_thm_to `induct.tex` INDUCTION;;
\end{verbatim}
puts the \LaTeX\ source of the theorem {\tt INDUCTION} into the file
{\tt induct.tex}. If such a file exists, it is overwritten. Otherwise,
a new file is created. you can also append the text into an existing
file using the function {\tt latex\_thm\_add\_to}. This takes the same
argument as {\tt latex\_thm\_to}.

There are also functions to translate terms, types and theorems with
all assumptions. The names of them are obtained by replace {\tt thm}
in the functions introduced above to {\tt term} for terms, {\tt type} for types
and {\tt all\_thm} for theorems with assumptions. 

\section{Typeset a Complete Theory}

The {\tt latex-hol} library can also translate a complete hol theory
to be typeset in a way similar to the output of the function {\tt
print\_theory}. The function to generate \LaTeX\ source for a theory
is {\tt latex\_theory\_to}. It takes three arguments: the first is a
string specifying the file name for the output to go, the second is a
boolean value which specifies the format of the output and the last one is
the name of the theory. If the boolean value is {\tt false}, the
output is in standalone format. This means that the \LaTeX\ file
generated can be formatted on its own to form a standalone document.
If it is {\tt true}, the file can be included into a larger document.
For example, 
\begin{verbatim}
  latex_theory_to `bool.tex` false `bool`;;
\end{verbatim}
will generate a file named {\tt bool.tex} which contains the theory
{\tt bool}. You can then just say 
\begin{verbatim}
  latex bool
\end{verbatim}
at you system prompt to produce a typeset document of the {\tt bool} theory.
If you want to include the theory in a larger document, you should use
\begin{verbatim}
  latex_theory_to `bool.tex` true `bool`;;
\end{verbatim}
Then, in the including \LaTeX\ document, you will input the macro file
and the theory file like below
\begin{verbatim}
  \input{holmacs}
  ...
  \input{bool}
\end{verbatim}
The file generated by {\tt latex\_theory\_to} in included format looks like:
\begin{verbatim}
  \theory{xxx}
  \sec{yyy}
  ...
  \sec{yyy}
  ...
  \endthy{xxx}
\end{verbatim}
where {\tt xxx} is the name of the theory and {\tt yyy} is the parts
of the theory such as `Types' or `Definitions'. By default, the command
\verb|\theory| produces a numbered section heading, \verb|\sec|
produces an unnumbered section heading and \verb|\endthy| draws a rule
to close the theory. You can redefine these commands to suit your
document using \verb|\renewcommand|. For example, 
\begin{verbatim}
  \renewcommand{\theory}[1]{\subsection{#1}}
  \renewcommand{\sec}[1]{\subsubsection{#1}}
  \renewcommand{\endthy}[1]{}
\end{verbatim}
 redefines \verb|\theory| to be subsection, \verb|\sec| to be
subsubsection and \verb|\endthy| not to draw the closing rule.

\section{The HOL macro file}

The macro file {\tt holmacs.tex} defines a set of \LaTeX\ macros for
use with files generated by this translator. The macros can be divided
into two groups: the special symbols and environments.

As you have seen above, the translator converts the HOL special
symbols into \LaTeX\ commands, for example, \verb|/\| becomes
\verb|\AND| and \verb|==>| becomes \verb|\IMP|. The macro file defines
these commands to be the symbols $\AND$ and $\IMP$. All special
symbols are processed in this way. This extra level of translation
give the user the flexibility of changing the symbols. If you prefer a
particular symbol to be set in a different way, you can change the
definition of the corresponding command in your document. For example,
put the command below in your document after the \verb|\input{holmac}|
line
\begin{verbatim}
  \renewcommand{\IMP}{\Longrightarrow}
\end{verbatim}
then the implication sign will be typeset as $\Longrightarrow$.
There are three new environments, namely {\tt ttlist}, {\tt
typelist} and {\tt thmlist}, defined in the macro file. They are used to format theories. The
`Parents' and `Types' sections are in {\tt ttlist}. Text in these
sections is set in a paragraph in {\tt typewriter} font (\verb|\tt|).
The `Constants' and `Infixes' sections are formatted in {\tt typelist}
environment. Each constant is an item in the list.
The constant names are used as item labels
 and the its type is set in {\tt typewriter} font. The `Definitions' and
`Theorems' sections are set in {\tt thmlist} environment. Each theorem
forms an item. The names of the theorems are used as the label and the
theorems are in in-line math mode. You can change the definition of
these environment to suit your style if necessary.

\section{Hints on better  formatting}

Since theorems in a theory file are in in-line math mode, long ones
may be split into several lines by \TeX. The breaks will only occur at
certain places, namely after binary operators and relations.
Sometimes, this will result in \TeX\ to produce overfull or underfull
boxes. This is the time you should give some help to \TeX. You can
tell \TeX\ where you would like a line
break to occur by inserting the command \verb|\allowbreak|  to that point.
If the problem is in the `Constants' or `Infixes' section, you can also use the command \verb|\newline| since
it is not in math mode.

For very long theorems, it is better to put it into an {\tt eqnarray}
environment. For example, the definition theorem {\tt GROUP\_DEF} in the
library {\tt group} reads
\begin{eqnarray*}
\lefteqn{\THM \FORALL G \,prod\DOT \CONST{GROUP} \,(G,prod) =} \\
 & &     (\FORALL x \,y\DOT G \,x \AND  G \,y \IMP  G \,(prod \,x \,y))
           \AND \\
 & &     (\FORALL x \,y \,z\DOT G \,x \AND  G \,y \AND  G \,z \IMP 
           (prod \,(prod \,x \,y) \,z = prod \,x \,(prod \,y \,z)))
           \AND  \\
 & &     (\EXISTS e\DOT G \,e \AND  
 	   (\FORALL x\DOT G \,x \IMP  (prod \,e \,x = x)) \AND 
              (\FORALL x\DOT
                   G \,x \IMP 
                      (\EXISTS y\DOT G \,y \AND  (prod \,y \,x = e))))
\end{eqnarray*}
This is formatted by the commands below
\begin{verbatim}
\begin{eqnarray*}
\lefteqn{\THM \FORALL G \,prod\DOT \CONST{GROUP} \,(G,prod) =} \\
 & &  (\FORALL x \,y\DOT G \,x \AND  G \,y \IMP  G \,(prod \,x \,y))
           \AND \\
 & &  (\FORALL x \,y \,z\DOT G \,x \AND  G \,y \AND  G \,z \IMP 
           (prod \,(prod \,x \,y) \,z = prod \,x \,(prod \,y \,z)))
           \AND  \\
 & &  (\EXISTS e\DOT G \,e \AND  
 	 (\FORALL x\DOT G \,x \IMP  (prod \,e \,x = x)) \AND 
            (\FORALL x\DOT
                 G \,x \IMP 
                   (\EXISTS y\DOT G \,y \AND  (prod \,y \,x = e))))
\end{eqnarray*}
\end{verbatim}
The commands corresponding to the theorem were generated by {\tt
latex\_thm}. Then, they are put in between the \verb|\begin| and
\verb|\end| commands. The command \verb|\lefteqn| is added to outdent
the first line. The \verb|\\| commands are placed at the end of
the lines where line breaks are required and the \verb|&|'s are needed
to force the lines to be indented.

\vspace{2\bigskipamount}

I hope you enjoy the use of this library. Please report any bugs or
suggestion to the author who can be reached at Dept. of Engineering,
University of Warwick, Coventry CV4 7AL, U.K., or via E-mail at {\tt
ww@eagle.warwick.ac.uk}\,.

\appendix
\section{List of Files}

The {\tt latex-hol} library distribution should contain at least the following
files:
\begin{center}
\begin{tabular}{>{\tt}ll}
filters.ml      & functions for converting special characters into \LaTeX\ commands\\
formaters.ml    & user interface of the HOL-to-\LaTeX\ translator \\
hol\_trees.ml    & functions for converting HOL text into parser tree \\
holmacs.tex      & a set of \LaTeX\ macros for HOL \\
latex-hol.ml    & functions for loading the library \\
latex\_sets.pp   & translation rules for the {\tt sets} library \\
latex\_term.pp   & translation rules for HOL terms \\
latex\_thm.pp    & translation rules for HOL theorems \\
latex\_type.pp   & translation rules for HOL types \\
precedence.ml   & definitions of precedence of HOL operators \\
\end{tabular}
\end{center}

If it is distributed in compiled form, the library should contain the
following files:
\begin{verbatim}
latex_sets_pp.ml
latex_term_pp.ml
latex_thm_pp.ml 
latex_type_pp.ml
\end{verbatim}
and {\tt .o} files for all the ML files.
The files whose name end with {\tt \_pp.ml} are generated by the
pretty printer.

\section{List of available ML Functions}

Below is a lists of ML functions in the library for use by the users:
\begin{center}
  \begin{tabular}{>{\tt}l>{\tt}l}
latex\_type	& type -> void	\\
latex\_type\_to	& string -> type -> void \\
latex\_type\_add\_to	& string -> type -> void \\
 & \\
latex\_term	& term -> void	\\
latex\_term\_to	& string -> term -> void \\
latex\_term\_add\_to	& string -> term -> void \\
 & \\
latex\_thm 	& thm  -> void	\\
latex\_thm\_to	& string -> thm -> void \\
latex\_thm\_add\_to	& string -> thm -> void \\
 & \\
latex\_all\_thm	& thm -> void	\\
latex\_all\_thm\_to	& string -> thm -> void \\
latex\_all\_thm\_add\_to	& string -> thm -> void \\
 & \\
latex\_theory\_to	& string -> bool ->string -> void \\
  \end{tabular}
\end{center}
\end{document}
