% arabdoc2.tex %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section {Input to \ArabTeX}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

After activating \ArabTeX,
select one of the Arabic writing styles, e.g., \verb"\setarab"
(see Section~\ref {languages}).
Your modified \TeX/\LaTeX\ system will recognize the following items:
                                                  \index{\setarab}

\begin{itemize}

\item normal \TeX/\LaTeX\ text and commands,

\item short {\em Arabic quotations\/} bracketed by \verb"<" and \verb">" .
  These must normally fit onto one line of output,
  except if explicitly broken up by \verb"\\" or \verb"\|" commands
  (see below).
  A quotation may also be started with \verb"\<" except inside a
  \LaTeX\ \verb"{tabbing}" environment.
                                                  \index{Arabic quotation}
                                                  \index{quotation!Arabic}
                                                  \index{tabbing environment}
                                                  \index{environment!tabbing}

\item longer Arabic texts which are bracketed
  by \verb"\begin{arabtext}" and \verb"\end{arabtext}",
  (even when using Plain \TeX!),
  called {\em Arabic Environments\/} in the sequel.
  An {\em Arabic Environment\/} consists of one or more paragraphs
  separated by blank lines or \verb"\par" commands.
                                                  \index{\par}
                                                  \index{\begin{arabtext}}
                                                  \index{\end{arabtext}}
                                                  \index{Arabic environment}
                                                  \index{environment!arabtext}
                                                  \index{environment!Arabic}
\end{itemize}

{\em Arabic quotations\/} and {\em Arabic environments\/} are called
{\em Arabic contexts\/} in the sequel.
                                                  \index{Arabic context}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection {Arabic text elements}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Every {\em Arabic paragraph\/} and every {\em Arabic quotation\/}
is a sequence of the following kinds of {\em Arabic items,}
separated by blank spaces or newlines:
                                                  \index{Arabic item}
\begin{itemize}

\item isolated punctuation marks,
  interpreted as the corresponding Arabic punctuation mark;
                                                  \index{punctuation}
\item ``numbers'', i.e. character sequences starting with a digit.
  A ``number'' will be processed using the normal writing sequence
  from left to right even if it contains letters and/or special characters;
  however, if the final character is a punctuation mark,
  it will be split off and processed separately.
                                                  \index{Arabic number}
\item ``Arabic quotes'' coded as two left quotes or two right quotes each;
  they may also be written directly adjacent to a word.
                                                  \index{Arabic quotes}
\item ``words'', i.e. character sequences starting with a letter or
  a special (non-digit) character followed by a letter.
  A final punctuation mark
  will be split off and processed separately.
  The (coded) characters of a word will in the
  output be arranged from right to left.
                                                  \index{Arabic word}
\item a sequence of words, numbers, and special characters
  enclosed in curly braces \verb"{" and \verb"}" .
  This introduces a new level of \TeX\ grouping; 
  otherwise the constituents are processed normally.
  This feature may be nested.
                                                  \index{Arabic group}
                                                  \index{nesting}
                                                  \index{grouping}
\end{itemize}

Output from all items will be arranged from right to left,
lines will be broken as necessary.

Inside an {\em Arabic Environment,} or in an {\em Arabic quotation,}
you may also have:
                                                  \index{Arabic context}

\begin{itemize}

\item \ArabTeX\ commands with or without parameters.
  These will be executed immediately.
                                                  \index{.\ArabTeX\ commands}
                                                  \index{commands!.\ArabTeX}
\item Some, but not all, \TeX/\LaTeX\ commands (see below).
  These will be executed immediately.
                                                  \index{.\TeX\ commands}
                                                  \index{commands!.\TeX}
                                                  \index{.\LaTeX\ commands}
                                                  \index{commands!.\LaTeX}
\item Short mathematical insertions,
  bracketed by {\em single\/} \verb"$" signs.
  They must fit on one output line and are processed as usual.
  \TeX\ Display mode within an {\em Arabic environment\/} is not provided;
  if it is required,
  the user has to leave the {\em Arabic environment\/} temporarily.
                                                  \index{mathematical insertion}
                                                  \index{insertion!mathematical}
                                                  \index{.\$}
                                                  \index{display mode}
\item short {\em non-Arabic\/} (``Roman'') {\em quotations,} 
  containing text and possibly also \TeX/\LaTeX\ commands, 
  bracketed by \verb"<" and \verb">" .
  These must fit on one output line and introduce a new level of grouping,
  so if they contain any \TeX/\LaTeX\ assignments
  the effects of these will be local by default.
  This feature is not available within an {\em Arabic quotation.}
  The alternate notation \verb"\<" is also {\em not\/} provided. % yet
                                                  \index{non-Arabic insertion}
                                                  \index{Roman insertion}
                                                  \index{insertion!non-Arabic}
                                                  \index{insertion!Roman}
                                                  \index{quotation!non-Arabic}
                                                  \index{quotation!Roman}
\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection {Commands in an {\em Arabic context }}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

A control sequence inside an {\em Arabic context\/} must be separated from
the preceding text item by at least one blank space, newline,
or another control sequence, and may be of the following kinds:
                                                  \index{.\TeX\ commands}
                                                  \index{commands!.\TeX}
                                                  \index{.\LaTeX\ commands}
                                                  \index{commands!.\LaTeX}
                                                  \index{Arabic context}

\begin{itemize}

\item \ArabTeX\ option changing commands.
  These may also be used outside an {\em Arabic Context,}
  and usually follow the \TeX\ grouping rules.
                                                  \index{.\ArabTeX\ commands}
                                                  \index{commands!.\ArabTeX}
\item \verb"\\" for a line break;
  the last line will be padded on the left with spaces.
                                                  \index{\\}
\item \verb"\|" for a line break;
  the last line will be aligned.
  If it comes out very badly spaced,
  automatic stretching might help (see Section~\ref{misc}).
                                                  \index{"\"|}
                                                  \index{stretching}
\item \verb"\indent" or \verb"\par" (or a blank line) for a new paragraph,
  \verb"\noindent" for a new paragraph without indentation;
 ({\em not inside Arabic quotations\/}).
                                                  \index{\par}
                                                  \index{\indent}
                                                  \index{\noindent}
\item \verb"\emphasize "{\em Arabic\_item\/} will put a bar
  over the {\em Arabic item.}
                                                  \index{\emphasize}
\item \verb"\emphasize {"{\em group\_of\_Arabic\_items\/}\verb"}" will
  put a bar over the indicated group of {\em Arabic items.}
                                                  \index{\emphasize}
\item \verb"\setnash, \setnashbf, \setnastaliq" font selection commands,
  see Section~\ref {fonts}.
                                                  \index{\setnash}
                                                  \index{\setnastaliq}
                                                  \index{\setnashbf}
\item size changing \LaTeX\ commands like \verb"\large" etc.,
  only if \LaTeX\ is used!
                                                  \index{size changing}
                                                  \index{commands!size changing}
\item the following commands:
  \verb"\footnote" (observe that the syntax for Plain \TeX\
  and \LaTeX\ is different!),
  \verb"\marginpar" (also with Plain \TeX,
  analogous to the \LaTeX\ usage).
                                                  \index{\footnote}
                                                  \index{\marginpar}
\item the \TeX/\LaTeX\ commands
  \verb"\smallskip",  \verb"\medskip",  \verb"\bigskip",  \verb"\input",
  \verb"\hfill", \verb*"\ " (for a space), \verb"\space"
  with their usual meaning.
                                                  \index{\smallskip}
                                                  \index{\medskip}
                                                  \index{\bigskip}
                                                  \index{\input}
                                                  \index{\hfill}
                                                  \index{\space}
                                                  \index{. @\verb*/\ /}
\item \verb"\nospace" will place the adjacent items in the output
in contact, without any intervening space.
                                                  \index{\nospace}
\item \verb"\hspace {"{\em width\/}\verb"}" will introduce the indicated
amount of spacing in the output.
                                                  \index{\hspace}
\item \verb"\mbox {"{\em text\/}\verb"}" puts the {\em text\/}
  into a box that will not be split across a line break.
                                                  \index{\mbox}
\item \verb"\spreadbox {"{\em width\/}\verb"}{"{\em text\/}\verb"}" 
  spreads out the {\em text\/} to the indicated {\em width.}
  This may be useful e.g., when typesetting poetry.\\
  \verb"\spreadbox {"{\em width\/}\verb"}{"{\em text\/}\verb"\hfill }" 
  will inhibit the spreading,\\
  \verb"\spreadbox {"{\em width\/}\verb"}{\hfill "{\em text\/}\verb"\hfill }" 
  will center the {\em text\/} inside the box.\\
  \verb"\spreadbox {"{\em width\/}\verb"}{\hfill }" or
  \verb"\spreadbox {"{\em width\/}\verb*"}{ }" 
  just introduces the indicated amount of horizontal space, as will
  \verb"\hspace {"{\em width\/}\verb"}".
                                                  \index{\hfill}
                                                  \index{\hspace}
                                                  \index{\spreadbox}

  If two boxing commands follow each other without any intervening
  blank space in the input, there will also be no resulting space
  between the boxes in the output.
                                                  \index{commands!boxing}
                                                  \index{boxing commands}
\item \verb"\centerline {"{\em text\/}\verb"}" will start a new line
  whose contents are centered
 ({\em not inside Arabic quotations\/}).
                                                  \index{\centerline}
\item \verb"\spreadline {"{\em text\/}\verb"}" will start a new line
  whose contents are spread out over the whole width of the page
  ({\em not inside Arabic quotations\/}).
  It is approximately equivalent to 
  \verb"\spreadbox {\hsize }{"{\em text\/}\verb"}".
                                                  \index{\spreadline}
\item User defined commands whose expansion produces legal \ArabTeX\ input
  may be called by \verb"\docommand {"{\em command and parameters\/}\verb"}".
  The command is expanded exactly once,\footnote
  {This is no strong restriction as the expansion may contain
  \verb"\docommand" calls again.}
  and the result is processed by \ArabTeX\ again.
  Any side effects of the expansion will be local.
                                                  \index{\docommand}
                                                  \index{commands!user defined}
                                                  \index{user defined commands}
\item Parameter assignments inside an {\em Arabic context\/} may be performed
  by \verb"\doassign {"{\em parameter\/}\verb"}{"{\em value\/}\verb"}".
  The effect is normally local except if the form
  \verb"\doassign {\global "{\em parameter\/}\verb"}{"{\em value\/}\verb"}"
  is used.
                                                  \index{\doassign}
                                                  \index{assignment}
\item Any non-recognized command will generate an error message
  and will be echoed verbatim in the output.
  Even though \ArabTeX\ tries hard to get into synchronization again,
  additional spurious errors may occur.
                                                  \index{commands!illegal}
\item inside an {\em Arabic Context\/}
  no further \LaTeX\ or \ArabTeX\ environment may be nested
  (with the possible future exception of list environments%
  ; these are not yet implemented%
  .)
                                                  \index{nesting}
                                                  \index{lists}
\end{itemize}

For a list of all available commands, consult the Index to this report.
As a reminder, a list of all commands that are valid inside Arabic text
will appear in the log file.
                                                  \index{commands!overview}

\endinput
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%