%Copyright (C) 2004  G. Lamprecht, W. Lotz, R. Weibezahn; IWD, Bremen University
%\documentclass{article}
\documentclass{article}

\textheight 235mm \topmargin 0mm \hoffset -10mm
\textwidth 170mm  \oddsidemargin 10mm

\renewcommand{\sloppy}{\tolerance 9999}
\sloppy\hbadness9999

\parindent 0mm   \parskip 1 ex plus 3ex minus 0.5ex
\topsep 0.1ex \partopsep 0.5ex

\newcommand{\offen}{\rule{1em}{2ex}}
\newcommand{\Copyright}%
        {Copyright (C) 2004  G. Lamprecht, W. Lotz, R. Weibezahn; IWD, Bremen University}
\newcommand{\xtem}{{\tt xtem}}
\newcommand{\xtememail}{{\tt Roland.Weibezahn@web.de}}
\newcommand{\htx}{{\tt htx}}
\newcommand{\htxs}{{\tt.htx}}
\newcommand{\shtxs}{*{\tt.htx}}
\newcommand{\LATeX}{(L\hspace*{-.35em}\raisebox{0.45ex}{{\sc a}})\TeX}
\newcommand{\8}{\protect\rule{0.4em}{0.1ex}}
\newcommand{\xtemtexmenu}{{\tt xtem\8{}texmenu}}
\newcommand{\Command}[3]{\par\bigskip\pagebreak[1]{\samepage%
        {\tt #1}\quad {\bf command}\\[0.7ex]Syntax:\quad{\tt#1 \em#2}\par#3\par}}
\newcommand{\command}[3]{\par\smallskip\pagebreak[1]{\samepage%
                                            Syntax:\quad{\tt#1 \em#2}\par#3\par}}
\newcommand{\Commandabr}[3]{\par\bigskip\pagebreak[1]{\samepage%
        {\tt #1}\quad {\bf command}\\[0.7ex]Syntax:\quad{\tt#1 \BrL\em#2\tt\BrR}\par#3\par}}
\newlength{\Syntaxlength}
\settowidth{\Syntaxlength}{Syntax:}
\newcommand{\commandabr}[3]{\par\medskip\pagebreak[1]{\samepage%
                                            Syntax:\quad{\tt#1 \BrL\em#2\tt\BrR}\par#3\par}}
\newcommand{\Commandalt}[2]{\makebox[\Syntaxlength][r]{or:}\quad{\tt#1 \BrL\em#2\tt\BrR}\par}
\newcommand{\BrL}{\tt\symbol{123}}
\newcommand{\BrR}{\tt\symbol{125}}


\title{Definition of the Hypertext Syntax used for \LATeX{} Syntax Help in \xtemtexmenu
        \\ {\normalsize \Copyright}}
\author{G. Lamprecht,
        W. Lotz,
        R. Weibezahn\thanks{e-mail: {\xtememail}}}
\date{May 1998}



\begin{document}

\maketitle

\tableofcontents %\newpage


\bigskip

\section{General Remarks}

This is a first description of the syntax \htx---some sort of an hypertext language
used in the files \shtxs.

{\bf
You may change the \shtxs{} files in \xtem, but at the moment I would not recommend
you to do this, as I want to be free to change the format at least in details
(perhaps to increase the performance, perhaps to make the format more `user friendly').
}

I know, this format is really somewhat `user unfriendly'.
But I wanted to implement the help-function in pure Tcl/Tk/TclX using the Tcl list functions.
Furthermore the \htx{} help files will be written mostly by me myself,
perhaps in some cases also by the local administrator.

A hint for those who want to write/change \shtxs{} files:
each time the help window is `refreshed' by clicking at a tag, the current version of the
corresponding \shtxs{} file is read from disk, so you may edit (and test) `on the fly'.

{\bf Remark:}
The following syntax description is for all \shtxs{} files with exception of the files
{\tt Alphabetical\8{}List.htx}. These files are produced by the program
{\tt Make\8{}alphlist.tcl}, only a subset of the commands described below are
used by this program and the files {\tt Alphabetical\8{}List.htx} are
evaluated by special case procedures (this is for reasons of performance;
on our Sun SPARC this made a speedup from about 8 seconds to 2 seconds for building up
the window with the alphabetical \LaTeX{} index!)




\section{Syntax}

\subsection{General Syntax Rules}

In this section we give some general syntax rules:
\begin{itemize}
\item   Trailing blanks are removed from each input line.
\item   Leading blanks are removed only from continuation lines.
\item   Input lines may be continued: the last character of a line to be continued
        must be a `$\backslash$'; leading blanks of the continuation line are skipped.
        Example:\\
        \verb|  This text is perhaps too long for one line, so it must be continued.|\\
        gives the same result as:\\
        \verb|  This text is perhaps too long for one \|\\
        \verb|  line, so it must be continued.|\\
        or:\\
        \verb|  This text is perhaps too long for one \|\\
        \verb|      line, so it must be continued.|
\item   A `$\backslash$' at the end of a line must be avoided in all other cases.
        Insert an empty in-line command, if necessary (for example insert \verb|@@rm {}|).
        Example:\\
        \verb|  \begin{tabular}{ll}|\\
        \verb|     line1_col1   & line1_col2  \\ @@rm {}|\\
        \verb|     line2_col1   & line2_col2|\\
        \verb|  \end{tabular}|

\item   Default font type is: {\tt hlp\8{}font(normal)}
        (font setting see `Installation \& Maintenance Guide' --- section `install.vst')
\item   All the rest is done by `line commands' and `in line commands':
\end{itemize}



\subsection{Line Commands}

\vspace{-2.5ex}
\Command{@entries}{list\8{}of\8{}entries}{%
 Entries to the alphabetically sorted index, separated by blanks.
 This line is evaluated by {\tt Make\8{}alphlist.tcl}, 
 a batch program which generates file {\tt Alphabetical\8{}List.htx}
}
Example:\\
\verb|  @entries  layout_paragraphs paragraph_layout \addvspace \baselineskip \bigskip|

\Command{@title}{title\8{}text}{%
 Makes the title for this syntax window --- using font {\tt hlp\8{}font(boldlrge)} ---
 followed by a rule line.
}

\Command{@mark}{mark}{%
 {\em mark\/} can be used for the {\tt entry} parameter in the {\tt @@linktag} command,
 this text is positioned at the (top of the) screen, when the linktag is clicked at
 and the text is filled into to text widget.
}

\Command{@update}{}{%
 Updates the syntax help window 
 (used in {\tt Alphabetical\8{}List.htx} for example, as the build-up 
 process takes too much time to wait for it with empty screen).
}

\Command{@section}{section\8{}title\8{}text}{%
 Makes the section title, using font {\tt hlp\8{}font(bold)}.
}

\Command{@bitmap}{bitmap\8{}filename}{%
 Opens an extra window and fills it with a bitmap; 
 the bitmap is taken from\\
 \begin{tabular}{llll}
    & 1. & \tt bitmap\8{}filename.xbm.gz & (X11 bitmap, compressed by {\tt gzip})\\
 or & 2. & \tt bitmap\8{}filename.xbm    & (X11 bitmap, uncompressed)\\
 or & 3. & \tt bitmap\8{}filename.dvi    & (dvi-file)
 \end{tabular}\\
 in the given order.
}

\Command{@begdescription}{}{%
 Starts a new environment (the description section): Inserts a heading line with a
 language-specific text (e.g. `Description:') in font type {\tt hlp\8{}font(bold)}.
 The following text lines are displayed using font {\tt hlp\8{}font(normal)}.
}

\Command{@enddescription}{}{%
 Ends the environment (the description section):
 font-switch to font type used before {\tt @begdescription}.
}

\Command{@begteletype}{}{%
 Starts a new environment;
 the following text lines are displayed using font {\tt hlp\8{}font(bold)}.
}

\Command{@endteletype}{}{%
 Ends the teletype environment: font-switch to font type used before {\tt @begteletype}.
}

\Command{@begsyntax}{}{%
 Starts a new environment (the syntax section): Inserts a heading line with a
 language-specific text (e.g. `Syntax:') using font type {\tt hlp\8{}font(bold)}.
 The following text lines are displayed using font {\tt hlp\8{}font(teletype)}.
}

\Command{@endsyntax}{}{%
 Ends the environment (the syntax section):
 font-switch to the font type used before {\tt @begsyntax}.
}

\Command{@begexamples}{}{%
 Starts a new environment (the examples section): Inserts a heading line with a
 language-specific text (e.g. `Examples:') using font type {\tt hlp\8{}font(bold)}.
 The following text lines are typed using font {\tt hlp\8{}font(telesmll)}.
}

\Command{@endexamples}{}{%
 Ends the environment (the examples section):
 font-switch to the font type used before {\tt @begexamples}.\\
 Opens an extra window and fills it with a bitmap; the bitmap filename is generated
 from the filename of the \htxs{} file (e.g.\ {\tt xyz.htx} $\rightarrow$ {\tt xyz.xbm.gz} /
 {\tt xyz.xbm} / {\tt xyz.dvi}, see above).
}

\command{@endexamples}{{\tt no\8{}bitmap}}{%
 Same as {\tt @endexamples}, but without generating a bitmap window.
}

\Command{@begeval}{}{%
 Starts a new environment:
 Each of the following text lines is evaluated by Tcl before it's displayed;
 by this it's possible to give Tcl commands in the text (should not be used normally,
 as you are using \xtem's internals, which may be changed at next release!).
}
Example:\\
\verb|  @begeval|\\
\verb|  @@linktag {[lindex $hlp_stack 2] [lindex $hlp_stack 3] { OK (previous window) } }|\\
\verb|  @endeval|

\Command{@endeval}{}{%
 Ends the eval environment: evaluation of text-lines is stopped,
 the following text lines are displayed as usual.
}

\bigskip
{\tt @beg\ldots} and {\tt @end\ldots} environments can be (properly) nested.


\subsection{In-line Commands}

In-line commands can be sprinkled into the text

The argument of an in-line command is included in braces;
these braces must be preceded by a blank and must be followed by a blank.
These blanks are not typed in the output.

\Commandabr{@@linktag}{filename entry tag\8{}text}{%
 Inserts a `tag' into the text: by left mouse click at the tag, the current syntax help
 window is replaced by another syntax help window, given by {\em filename}. {\em filename\/}\\
 1. is prefixed by the \xtem{} installation path and the subdirectory for the language 
    specific help-directory
    (e.g.\ \ldots{\tt/xtem/locals\8{}english/} or \ldots{\tt/xtem/locals\8{}german/}\\
 2. gets {\tt.htx} as post-amble.

 {\em tag\8{text}\/} is typed with font type {\tt hlp\8{}font(tag)}
 (normally this will be the same font as {\tt hlp\8{}font(normal)}).
 If trailing blanks arge to be displayed, you must enclose {\em tag\8{text}\/} in
 braces: ``{\tt\BrL~\ldots~\BrR}'' (see example below).

 If the mouse enters or leaves the tag field you notice this by color-inversion.

 The {\em entry\/} parameter is used---in connection with the {\tt @mark} command---for
 localization within the syntax help window.
}
Example: \verb|@@linktag {latex/addtolength length { length commands } }|

 The text ` length commands ' is framed, when you click at this tag, file\\
 \ldots{\tt/xtem/help\8{}english/latex/addtolength.htx} is displayed in the syntax help window.

\commandabr{@@linktag}{{\tt @@bdw\8} filename entry tag\8{}text}{%
 Same as {\tt @@linktag \BrL{\em filename entry tag\8{}text}\BrR},
 yet the tag is not framed but underlined instead.
}

\commandabr{@@linktag}{{\tt @@bdw0} filename entry tag\8{}text}{%
 Same as  {\tt @@linktag \BrL{\em filename entry tag\8{text}\/}\BrR},
 yet the tag is neither framed nor underlined; the user can only notice by
 color-inversion when the mouse enters and leaves the tag.
 This form is suited for `lists of tags'.
}

\Commandabr{@@URLtag}{URL {\tt 0} tag\8{}text}{%
\Commandalt{@@URLtag}{URL {\tt 1} {\BrL}command1{\BrR} tag\8{}text}
\Commandalt{@@URLtag}{URL {\tt 2} {\BrL}command1{\BrR} {\BrL}command2{\BrR} tag\8{}text}
\qquad\ldots\par
 Similar to {\tt @@linktag} command; this command
 inserts an `URL-tag' into the text: by left mouse click at the tag, 
 a browser (from a list of browsers, e.g.\ {}Netscape) is called.
 {\em command1}, {\em command2} etc.\ {} are Unix commands which
 are executed in this order, the result of the first hit (return code 0)
 will substitute the string {\tt\8SUBSTCOM\8} in {\em URL}.
 For more details and examples see ``\xtem{} Installation Guide''.
}


\Commandabr{@@tt}{teletype\8{}text}{%
 The text within the braces is displayed using {\tt hlp\8{}font(teletype)}
}

\Commandabr{@@tl}{teletype\8{}large\8{}text}{%
 The text within the braces is displayed using {\tt hlp\8{}font(telelrge)}
}

\Commandabr{@@ts}{teletype\8{}small\8{}text}{%
 The text within the braces is displayed using {\tt hlp\8{}font(telesmll)}
}

\Commandabr{@@em}{emphasized\8{}text}{%
 The text within the braces is displayed using {\tt hlp\8{}font(italic)}
}

\Commandabr{@@bf}{boldfaced\8{}roman\8{}text}{%
 The text within the braces is displayed using {\tt hlp\8{}font(bold)}
}

\Commandabr{@@bl}{boldfaced\8{}large\8{}roman\8{}text}{%
 The text within the braces is displayed using {\tt hlp\8{}font(boldlarge)}
}

\Commandabr{@@rm}{roman\8{}text}{%
 The text within the braces is displayed using {\tt hlp\8{}font(normal)}
}

\bigskip
In-line commands can be (properly) nested

{\samepage
Examples:\\[0.5ex]
\verb|  @@tt {\begin{verbatim} @@em {Text} \end{verbatim}}|\\
displays the same output as:\\
\verb|  @@tt {\begin{verbatim}} @@em {Text} @@tt {\end{verbatim}}|
}

\smallskip
{\samepage
\fbox{\ ``moving arguments'' } as tag:\\
\verb|  @@linktag {latex/moving_args  _   ``moving arguments'' }|
}

\smallskip
{\samepage
\fbox{\ {\tt\ $\backslash$\,protect\ }} (in teletype font) as tag:\\ 
\verb|  @@linktag {latex/protect protect @@tt { \protect } } |
}


\end{document}
