% +--------------------------------------------------+
% | Typeset this file to get the documentation.      |
% +--------------------------------------------------+
%
% This file is copyrighted (c) 1998, 2000 by Javier Bezos.
% All Rights Reserved.
% 
% This program can be redistributed and/or modified under the terms
% of the LaTeX Project Public License Distributed from CTAN
% archives in directory macros/latex/base/lppl.txt; either
% version 1 of the License, or any later version.

\def\fileversion{1.0}
\def\docdate{August 7, 2000}

\documentclass{ltxguide}
\usepackage{tensind}

\title{The \textsf{tensind} Package for
Tensorial Indexes\footnote{This 
package is currently at version 1.0.}}

\author{Javier Bezos\footnote{For bug reports, comments and
suggestions go to
\texttt{http://www.texytipografia.com}.
English is not my strong point, so contact me when you
find mistakes in the manual. Other packages by the same author:
\textsf{accents, titlesec, dotlessi}.}}

\date{\docdate}

\newenvironment{sample}{\begin{quote}\small\begin{tabbing}%
  \hskip12pc\=\hskip6pc\\}
  {\end{tabbing}\end{quote}}
  
\tensordelimiter{?}
\tensorformat{lrb}

\raggedright

\begin{document}

\maketitle
  
This package provides typographically fine tensorial notation, with the 
following features:
\begin{itemize}
\item Dots filling gaps.
\item Symbol subtitution to easy typing (if you are using greek letters, for 
example).
\item Corrected position of indexes: horizontally, to compensate the small 
displacement in letters
like $f$ (look carefully at $f_*^*$) and vertically, to avoid superscripts 
too raised.
\item Aditional minute corrections are also allowed.
\end{itemize}

\section{User Interface}

\begin{decl}
|\tensordelimiter{<tensor-delim>}|
\end{decl}

Defines |<tensor-delim>| to be a tensor delimiter. In subsequent examples we will 
assume
\begin{verbatim}
\tensordelimiter{?}
\end{verbatim}
and every instance of |?| will actually mean |<tensor-delim>|.

\begin{decl}
|?[<format>]{<nucleous>}{<special-index>}{<special-index>}...|\\
|                       <super-or-sub><super-or-sub>...?|
\end{decl}

Creates a tensor. |<super-or-sub>| is either |_{<index>}{<index>}...| or 
|^{<index>}{<index>}|.
|<nucleous>| is the symbol which indexes will be add to. |<special-index>| is a 
superscript which is neither covariant nor contravariant (dual, 
prime...). In 
one-letter |<index>|, |<special-index>| or |<nucleous>|, curly braces can be 
omitted.
For example:
\begin{sample}
|?R_ij^kl_\alpha^\beta?|     \>        $?R_ij^kl_\alpha^\beta?$\\[2pt]
|?R^ij_kl^\alpha_\beta?|     \>        $?R^ij_kl^\alpha_\beta?$\\[2pt]
|?R**_ij^kl_\alpha^\beta?|   \>        $?R**_ij^kl_\alpha^\beta?$\\[2pt] 
|?R**^ij_kl^\alpha_\beta?|   \>        $?R**^ij_kl^\alpha_\beta?$
\end{sample}

(\emph{Don't forget the closing |?|!})
Finally, |<format>| changes the format in a tensor. (See |\tensorformat| 
below.)

\begin{decl}
|\tensorformat{<format>}|
\end{decl}

The following letter may be used in format.
\begin{itemize}
\item[\texttt{l}] Gaps to the left of the last index are filled with dots.
\item[\texttt{r}] Gaps to the right of the first index are filled.
\item[\texttt{e}] If there is no index (empty), gaps are filled.
\item[\texttt{b}] Only gaps in subscripts are filled.
\end{itemize}

Sensible settings are: none (no dots), |l| and |lrb|.
Further options are:
\begin{itemize}
\item[\texttt{c}] Brings index lines closer.
\item[\texttt{o}] Opens index lines.
\item[\texttt{s}] Styled. |o| in display style and |c| otherwise.
\end{itemize}
These options are mutually exclusive. If none of them is
used, then indexes behave in a similar way to standard ones.
This document sets
\begin{verbatim}
\tensorformat{lrb}
\end{verbatim}

\begin{sample}
|?[]f\prime_ij^kl?|    \>  $?[]f\prime_ij^kl?$\\[2pt]
|?[e]f^ij?|            \>  $?[e]f^ij?$ \\[2pt] 
|?[l]f*_ij^kl?|        \>  $?[l]f*_ij^kl?$\\[2pt]
|?[c]R^ij_kl?|         \>  $?[c]R^ij_kl?$
\end{sample}

\begin{decl}
|\indexdot|
\end{decl}

This macro is the index dot. Defined to |\cdot|. You can
redefine it with |\renewcommand|.

\begin{decl}
|\whenindex{<index>}{<new-index>}{<commands>}|
\end{decl}

Automatically replaces |<index>| (if not enclosed in braces)
by |<new-index>| and the additional |<commands>| are
executed. For example, if you like to use greek indexes:
\begin{verbatim}
\whenindex{a}{\alpha}{}
\whenindex{b}{\beta}{}
\whenindex{g}{\gamma}{}
\end{verbatim}

\whenindex{a}{\alpha}{}
\whenindex{b}{\beta}{}
\whenindex{g}{\gamma}{
}
A |\whenindex{'}{\prime}{}| is performed by the package. For instance
\begin{sample}
|?R'_ijk^abg?|    \>  $?R'_ijk^abg?$
\end{sample}

In |<commands>|, two command for space fine-tuning are provided:
|\sbadjust{<index>}{<comma-space>}| adds |<comma-space>| times
|\,| before the current subscript index if the last superscript index
was |<index>|. Similarly, |\spadjust| adds the space before the current
superscript index if the last subscript index was |<index>|.
For instance, the normal result of |?[]R^ik_lm?| is $?[]R^ij_kl?$, but
with
\begin{verbatim}
\whenindex{k}{k}{\sbadjust{j}{-1}}
\end{verbatim}
\whenindex{k}{k}{\sbadjust{j}{-1}}
is $?[]R^ij_kl?$.
These commands will be ignored if dots are used.

Two further command allowed in |\whenindex|
are: |\omitdot| omits the dot for the current
index, and |\finishdots| omits as well all subsequent indexes.
For example
\begin{verbatim}
\whenindex{;}{\,;\,}{\finishdots}
\end{verbatim}
\whenindex{;}{\,;\,}{\finishdots}

\begin{sample}
|?[lr]A*_i^kl;i?|  \>   $?[lr]A*_i^kl;i?$
\end{sample}

\begin{decl}
|tensor|
\end{decl}

The environment called by |?...?|. Useful if for some reason you
don't want an equivalent defined with |\tensordelimiter| . Example:
\begin{verbatim}
\begin{tensor}[lr]A*_i^kl;i\end{tensor}
\end{verbatim}

\end{document}