path: root/support/rnototex/rnototex_guide.tex

\documentstyle[a4wide,duplex20]{report}
%
%   DOCUMENTATION FOR PROGRAM RNOTOTEX
%   WRITTEN IN LATEX USING LSE 
%   R. VENHOLA, 9-MAR-88
%
%   Revised by John Edgecombe,  6-JUL-1988, restricting to RNOTOTEX only
%
% put section headings on top of page
\pagestyle{headings}

% release the LaTeX boundaries for margins
\setlength{\oddsidemargin}{0.5in}
\setlength{\evensidemargin}{0.0in}
\setlength{\topmargin}{0.0in}

% make the page size wider and longer
\setlength{\textwidth}{6.0in}   % 8.5 by 11 page with 1 inch margins
\setlength{\textheight}{8.0in}  % on each side

% generate a title page
\author{R.~Venhola}
\title{ { \Huge \TeX\ \& \LaTeX\ \\ 
\vspace*{1.0ex} 
CONVERSION PROGRAM } \\
RNOTOTEX
}
\maketitle

% An IDX file is to be generated
\makeindex

% A short form command 
\newcommand{\lb}{\large\bf}

\begin{document}

\chapter{Quick Reference}
Execute SETUP.COM ({\tt @SETUP.COM}) to set the DCL command syntax
before using the RNOTOTEX command.

\section{RNOTOTEX}
DCL command format is :

\begin{center}

{\large\bf \$ RNOTOTEX[\ /qualifier] RNO-FILE-SPEC  TEX-FILE-SPEC}

\end{center}

Reads a {\em Digital Standard Runoff} format file and creates the \LaTeX\ 
equivalent.


\subsection{Parameters}

\begin{center}


 {\large\sl RNO--FILE--SPEC }

\end{center}

$\ldots$ is the name of the input DSR format file.  The default type 
is~{\tt{.RNO}}.
\begin{center}


 {\large\sl TEX--FILE--SPEC }

\end{center}
$\ldots$ is the name of the output~{\tt{TEX}} file spec.  The default
type is~{\tt{.TEX}}.

\subsection{/TEX}

\begin{center}

{\large\sl /TEX }

\end{center}

Preserve embedded \TeX\ and \LaTeX\ commands in the input DSR file.  
Any commands found are copied directly to the output~{\tt{.TEX}} file.   The
default is /NOTEX.

\subsection{Example}
The following DCL 
commands convert the DSR file FOO.RNO to FOO.TEX and prints the
LN3 file on the LN03.  The log of the conversion is also printed
and deleted.

\begin{verbatim}

    $ RNOTOTEX FOO.RNO
    $ LATEX FOO.TEX
    $ DVI2LN3 FOO.DVI
    $ PRINT/FORM=TEX FOO.LN3
    $ PRINT/DELETE RNOTOTEX.LOG

\end{verbatim}

Note that there isn't a one-to-one mapping of DSR commands to \LaTeX\ 
commands and that more \LaTeX\ text fits on a page than a RUNOFF file.
The  first output may be messy!   The output~{\tt{.TEX}} file must \index{messy RNOTOTEX output}
edited after examining the first printing.  It may take a few tries to
get the output that you want.

The program was designed for those familiar with both \LaTeX\ and DSR
and would like to upgrade older documents to \LaTeX\ format.
\vspace{10.0cm}
\pagebreak

\chapter{Introduction}
\TeX\ and \LaTeX\ are programs that allow programmers to typeset manuscripts
for high precision output devices, such as the \index{LN03} LN03 linked to the SMOKE
system at CCRS.  \LaTeX\ can be thought of as a usable extension of
\TeX\ .  Raw \TeX\ can be difficult to use.

The input files to the program are created in the same
manner as one would create a RUNOFF source file.  The usual file type 
is ``{\tt{.TEX}}''.
The files are in simple ASCII format, so that they may be created using an
editor such as EDT, SED or \index{LSE} LSE ({\bf L}anguage 
{\bf S}ensitive {\bf E}ditor).  As a note, the current version of
LSE on SMOKE recognises {\tt{TEX}} files and initialises the programming
language to be ``LATEX'', with the appropriate expandable placeholders.

Commands such  as ``\verb+\chapter{Introduction}+'' are 
embedded in the~{\tt{.TEX}}
file. The file is run through either the \TeX\ or \LaTeX\ program, 
which will produces a~{\tt{.DVI}} file (for {\bf D}e{\bf{V}}ice {\bf I}ndependent).
This {\tt{.DVI}} file must be converted to the local print format, which in our
case is done by the program {\bf DVI2LN3}.  

Documentation on \TeX\ and \LaTeX\ commands are given in Knuth\cite{tex-manual}
and Lamport\cite{latex-manual}\footnote{References are listed in the
Bibliography}.
The user requires some familiarity with either \TeX\ or \LaTeX\ 
to use the conversion programs described in this document.

Program {\bf RNOTOTEX} reads a DSR format file 
(i.e.~FOO.RNO) and writes the equivalent\footnote{Well, not {\em really}
equivalent, as you will find out in later} TEX format
file (FOO.TEX).

\chapter{RNOTOTEX}
Program {\bf RNOTOTEX} will read a DEC Standard RUNOFF (DSR) format text file,
translate the RUNOFF commands to \LaTeX\ commands and write the corresponding
TEX file.  The output file may then be processed by \LaTeX\ and printed
on the local high quality printer.  To use {\bf RNOTOTEX} one must have
executed the DCL command procedure
``SETUP'' as described
in the first chapter.

\section{Execution}
Program {\bf RNOTOTEX} requires two files names on the command line : the
input~.RNO file and the output~{\tt{.TEX}} file.  For example~:
\begin{verbatim}

  $ RNOTOTEX FOO.RNO FOO.TEX

\end{verbatim}
translates the file FOO.RNO to the file FOO.TEX.   The program does not
require any user input.

\section{Translation Actions}
The program does four tasks.  It will translate RUNOFF sectioning commands
to \LaTeX\ sectioning commands, translate RUNOFF flags to \LaTeX\ commands,
translate RUNOFF page directives to \LaTeX\ page directives and adjust
\LaTeX\ counters by the same amount as RUNOFF counters are to be adjusted.

\subsection{Conversion of Sectioning Commands}
{\bf RNOTOTEX} converts RUNOFF sectioning commands to \LaTeX\ sectioning 
commands. 
The output \LaTeX\ style is always {\tt report } in 10 point font.
The sectioning command are converted in table~\ref{section-commands}.
\begin{table}
\begin{tabular}{ll}
{\lb RUNOFF }	    & {\LaTeX\ \lb Command Generated} \\
 .HL1 text      & \verb+\chapter{text}+ \\
 .HL2 text      & \verb+\section{text}+ \\
 .HL3 text      & \verb+\subsection{text}+ \\
 .HL4 text      & \verb+\subsubsection{text}+ \\
 .HL5 text      & \verb+\paragraph{text}+ \\
 .HL6 text      & \verb+\subparagraph{text}+ \\
\end{tabular}
\caption{Conversion of RUNOFF Sectioning Commands\label{section-commands}}
\end{table}

\subsection{Conversion of RUNOFF Flags}
RUNOFF flags are converted to \LaTeX\ commands by {\bf RNOTOTEX}.  
This is a direct
conversion process, i.e.~a RUNOFF underline command is converted to a
\LaTeX\ underline command.  This does not always produce the prettiest
results (as one can use {\bf bold} and {\it italic} fonts in \LaTeX\ ),
but it is consistent.  The author regrets that {\bf RNOTOTEX} does not
have the aesthetic sense to decide when a font is more appropriate than \index{esthetic sense}
a converted RUNOFF command.  The conversion process for RUNOFF flags
is table~\ref{flag-commands}.
\begin{table}
\begin{tabular}{lcl}
{\lb RUNOFF Flag } & {\lb Flag } & {\LaTeX\ \lb Command Generated} \\
{\lb Name        } & {\lb Char } &		\\
Accept			& \_		   & \verb!\verb+?+! \\
Bold			& *		   & \verb+{\bf+$\cdots$\verb+}+ \\
Break			& \verb+|+	   & \verb+\\+ \\
Capitalize		& \verb+<+	   & (see below) \\
Comment		        &  !		   & \% \\
Hyphenate		& =		   & \verb+\hyphenate{+$\cdots$\verb+}+ \\
Index			& \verb+>+	   & \verb+\index{+$\cdots$\verb+}+ \\
Lowercase		& $\backslash	$  & (see below) \\
Overstrike		& \%		   & \verb+{\bf+$\cdots$\verb+}+ \\
Period		        & +		   & \verb+\frenchspacing+ \\
Space			& \#		   & \verb*+\ + \\
Subindex		& \verb+>+         & \verb+\index{+$\cdots$\verb+}+ \\
Substitute		& \$		   & {\em not translated } \\
Underline		& \&		   & \verb+\underline{+$\cdots$\verb+}+ \\
Uppercase               & \verb+^+         & (see below) \\
\end{tabular}
\caption{Conversion of RUNOFF Flags\label{flag-commands}}
\end{table}

Characters following CAPITALIZE, LOWERCASE or UPPERCASE flags are converted
to the appropriate case during the translation process by {\bf RNOTOTEX},
unless they are paired with other flags.  In these other cases, the flags in
RUNOFF lock another flag on, such as the {\bf bold}ing flag described
in the DSR manual\cite{dsr-manual} on page 3-6.  {\bf RNOTOTEX} will lock the
appropriate flag to the state it is in and produce the appropriate 
\LaTeX\ commands.  
\pagebreak
For example, {\bf RNOTOTEX} will convert~:
\begin{verbatim}

 ^*These words are in bold face.\*

        to

  {\bf These words are in bold face.}

\end{verbatim}

\subsection{Conversion of RUNOFF Directives}
RNOTOTEX converts RUNOFF directives to \LaTeX\ directives.
RUNOFF allows one to enable or disable flags and change the
default flag character for a flag.  {\bf RNOTOTEX} will recognise these
commands and change the internal parsing setup so that the flag is
(or is not) recognised by the character specified.  See the RUNOFF commands
``ENABLE'', ``DISABLE'', ``FLAGS'' and ``NO FLAGS'' described in the
RUNOFF manual.

In addition, {\bf RNOTOTEX} will translate RUNOFF commands such as ``NOFILL'',
``INDENT'' and ``LIST'' in the manner described in table~\ref{directive-commands}.
\begin{table}
\begin{tabular}{ll}
{\lb RUNOFF }		    &  {\LaTeX\ \lb Command Generated} \\
.APPENDIX		    & \verb+\appendix+ \\
.BLANK $n$		    & \verb+\vspace{+$n$+\verb+}+ \\
.BREAK			    & \verb+\linebreak+ \\
.CENTRE {\it text }         & \verb+\begin{centering}+ \\
			    &   {\it text } \\
			    & \verb+\end{centering}+ \\
.FOOTNOTE {\it text}	    & \verb+\footnote{+{\it text }\} \\
.INDENT			    & \verb+\indent+ \\
.JUSTIFY		    & \verb+\obeylines \obeyspaces+ \\
.LIST $n$,``q''		    & \verb+\begin{enumerate}+ \\
.LITERAL		    & \verb+\begin{verbatim}+ etc. \\
.NOFILL			    & \verb+\sloppy+ \\
.PAGE			    & \verb+\pagebreak[4]+ \\
.SPACING		    & \verb+\setlength{\baselineskip}{n}+ \\
.SUBTITLE  {\it text}	    & \verb+\pagestyle{myheadings}+ etc. \\
.TITLE {\it text}	    & \verb+\pagestyle{myheadings}+ etc. \\
\end{tabular}
\caption{Conversion of RUNOFF Directives\label{directive-commands}}
\end{table}

\subsection{Conversion of RUNOFF Counters}
{\bf RNOTOTEX} converts the RUNOFF counter changes to \LaTeX\ counter
adjustment changes.  The conversion process in described in
table~\ref{counter-commands}.
\begin{table}
\begin{tabular}{ll}
{\lb RUNOFF}	       & {\LaTeX\ \lb Command Generated} \\
.NUMBER APPENDIX $n$   & \verb+\setcounter{\chapter}{+$n$\verb+}+ \\
.NUMBER LEVEL    $s,n$ & \verb+\setcounter{s}{n}+ \\
.NUMBER LIST     $n$   & \verb+\setcounter{\enumi}{n}+ \\
.NUMBER PAGE     $n$   & \verb+\setcounter{\page}{n}+ \\
\end{tabular}
\caption{Conversion of RUNOFF Numbering\label{counter-commands}}
\end{table}

\section{The Conversion LOG File}
Each time {\bf RNOTOTEX} is executed, it generates the file {\tt RNOTOTEX.LOG}.
It is a record of each conversion used to generate the output \LaTeX\ commands.
It is useful to users less familiar with \LaTeX\ and wish to learn by
trial and error rather than by reading the manual.  It may also be
useful to experienced \LaTeX\ users to quickly identify what \LaTeX\ will
produce as output from the generated TEX file without going through
a complete printing.  

It is recommended that the log file be printed and deleted for each
execution.  For example, the batch job~:
\begin{verbatim}

  $ @DCL:TEX_CONVERSION_SETUP
  $ RNOTOTEX REPORT NEW_REPORT
  $ PRINT/DELETE RNOTOTEX.LOG

\end{verbatim}
generates the file NEW\_REPORT.TEX from the file REPORT.RNO and prints
the log of the conversion process.  The user can the examine the printed
log file and decide upon the editing required to produce a ``nice''
\LaTeX\ output.


\begin{thebibliography}{99}
\addcontentsline{toc}{chapter}{Bibliography}

\bibitem{latex-manual} Leslie Lamport {\em \LaTeX\ User Guide \& Reference} \\
Addison-Wesley Publishing Company, 1986 

\bibitem{tex-manual} Donald E.~Knuth {\em The \TeX book} \\
Addison-Wesley Publishing Company, 1984 

\bibitem{metafont-manual} Donald E.~Knuth {\em The METAFONT Book} \\
Addison-Wesley Publishing Company, 1986

\bibitem{dsr-manual} Digital Equipment Corporation {Digital Standard RUNOFF
(DSR) Reference Manual } \\
Order \# AA-Z301B-TE, July 1985

\end{thebibliography}
\clearpage

\setcounter{page}{0}
\pagenumbering{roman}
\tableofcontents
\listoftables

\end{document}