%%
%% Description of the LaTeX package `boldtensors'
%%
%% This program can be redistributed and/or modified under the
%% terms of the GNU Public License, version 2.
%%
%% 2007/06/29
%% Author: Werner Fink <werner@suse.de>
%%
%% 2026/05/21
%% Author: Werner Fink <werner@suse.de>
%%
%% Documentation and examples for the 'boldtensors' package
%%
\documentclass[a4paper]{ltxdoc}
\usepackage[utf8]{inputenc}
\usepackage{amsmath}
\usepackage{iftex}

% Load the modernized package with both options
\usepackage[nabla,differential]{boldtensors}

\title{The `boldtensors' Package}
\author{%
  \copyright\ 1995--2026 Werner Fink and Jürgen Bachteler}
\date{May 21, 2026}

\nofiles
\parindent0em
\parskip1ex

\begin{document}
\maketitle
\thispagestyle{empty}

\section{Introduction}
The \texttt{boldtensors} package provides a convenient shorthand for typesetting 
latin and greek characters in bold and blackboard layouts within the standard 
\verb|\mathversion{normal}| environment. 

It uses active characters to keep the syntax minimal:
\begin{itemize}
    \item \verb|$~T$| produces a bold tensor symbol $~T$.
    \item \verb|$"R$| produces a blackboard bold symbol $"R$ (e.g., for real numbers).
\end{itemize}

\section{Package Options}
The package supports two main options:
\begin{itemize}
    \item \textbf{nabla}: Enables the bold Nabla operator $\nabla$ via the \verb|\nabla| command.
    \item \textbf{differential}: Automatically loads the \texttt{bt-isodiff} package, which 
    redefines the character `$d$' as an upright (roman) operator, compliant with 
    ISO 80000-2 standards.
\end{itemize}

\paragraph{Note on Differential Operators:} 
While \texttt{boldtensors} (via \texttt{bt-isodiff}) provides an easy "global" 
replacement of the `$d$' character for quick typing, users looking for a more 
sophisticated, semantic approach to differential operators are encouraged to 
take a look at the modern \texttt{fixdif} package. \texttt{fixdif} offers 
fine-grained control over spacing and is specifically optimized for 
various engines including Lua\LaTeX.

\section{Example: The Line Element}
Using the \texttt{differential} option, the metric line element can be written 
naturally. Note that the `$d$' is upright while coordinates remain italic:

\begin{verbatim}
\begin{math}
  ds^2 = g_{\alpha\beta} dx^{\alpha} dx^{\beta}
\end{math}
\end{verbatim}

Result:
\begin{math}
  ds^2 = g_{\alpha\beta} dx^{\alpha} dx^{\beta}
\end{math}

\section{Example: Tensor field}
A tensor field of type $(p,q)$ can be fully expanded into its components and 
basis vectors/covectors. While the long form with partial fractions is precise, 
the shorthand notation using $~\partial$ and $~d$ is significantly more 
compact and common in General Relativity:

\begin{verbatim}
%% Standard long form
\begin{math}
  ~T = T_{j_1,\ldots,j_q}^{i_1,\ldots,i_p} %
  \frac{\partial}{\partial ~x^{i_1}}\otimes\cdots\otimes\frac{\partial}{\partial ~x^{i_p}} %
  \otimes d~x^{j_1}\otimes\cdots\otimes d~x^{j_q}
\end{math}

%% Compact shorthand
\begin{math}
  ~T = T_{j_1,\dots,j_q}^{i_1,\dots,i_p} %
  ~\partial_{i_1}\otimes\cdots\otimes~\partial_{i_p} %
  \otimes ~dx^{j_1}\otimes\cdots\otimes ~dx^{j_q}
\end{math}
\end{verbatim}

\begin{displaymath}
  ~T = T_{j_1,\dots,j_q}^{i_1,\dots,i_p} %
  ~\partial_{i_1}\otimes\cdots\otimes~\partial_{i_p} %
  \otimes ~dx^{j_1}\otimes\cdots\otimes ~dx^{j_q}
\end{displaymath}

Note that with the \texttt{differential} option enabled, \verb|~d| automatically 
produces a bold, upright differential operator, maintaining ISO compliance even 
in its bold form.

\section{Example: Einstein Field Equations}
The major advantage of this package is that subscripts, indices, and accents 
can be used on bold symbols without layout or spacing issues. 
Any index is placed correctly according to the font metrics.

In General Relativity, the Einstein field equations relate the geometry of 
spacetime to the energy-momentum content. Using the \verb|~| notation, we can 
represent the Einstein tensor $~G$ and the energy-momentum tensor $~T$ 
as distinct geometric objects:

\begin{verbatim}
\begin{math}
  ~G = \frac{8 \pi G}{c^4} ~T
\end{math}
\end{verbatim}

Result:
\begin{displaymath}
  ~G = \frac{8 \pi G}{c^4} ~T
\end{displaymath}

Where:
\begin{itemize}
    \item $~G$ is the Einstein Tensor (bold).
    \item $G$ is Newton's gravitational constant (italic scalar).
    \item $~T$ is the Energy-Momentum Tensor (bold).
\end{itemize}

This clear visual distinction between tensors and scalars is the primary 
goal of the \texttt{boldtensors} style.

\end{document}