summaryrefslogtreecommitdiff
path: root/support/rnototex/rnototex_guide.tex
blob: f51e8d6fea3839af55b5736be052736ec3b894b2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
\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}