\documentclass[12pt]{article}
\usepackage{setspace}
\usepackage{a4wide}
\usepackage{xspace, amsmath}
\usepackage[maybess]{hepparticles}
\onehalfspacing

\newcommand{\hepparticles}{\texttt{hepparticles}\xspace}
\author{Andy Buckley, \texttt{andy@insectnation.org}}
\title{The \hepparticles package for \LaTeX\footnote{This document describes \hepparticles as of version 1.4}}

\begin{document}
\maketitle

\begin{abstract}
This package provides macros for typesetting high energy physics particle names
in a consistent, semantic and aesthetically pleasing manner, as well as fixing
problems with math-mode boldness problems in section titles. You may also be
interested in the \texttt{heppennames} and \texttt{hepnicenames} packages, which
use this one to provide a large set of pre-existing particle names.
\end{abstract}

\section{Motivation}
Typesetting the names of high-energy fundamental particles (and their elementary
composites) is well-defined by a set of rules:

\begin{itemize}
\item The basic particle name consists of a large Roman or Greek symbol with
  optional following sub- and super-scripts.
\item Depending on convention, the symbols for particles are either italic or
  upright. Using the latter convention, the symbols should be upright when
  describing a specific particle; if describing a generic class of particles
  they should be italicised (where possible). In italic and bold contexts the
  symbols should adapt by becoming bold and italic themselves where possible.
\item Anti-particles are written with a bar on top of the main symbol (but for
  aesthetic reasons the bar does not extend above the sub- and super-scripts.
\item Supersymmetric partners of Standard Model particles are written as for
  anti-particles but with a tilde in place of the bar. SUSY anti-particles
  (though the use of symbols to represent them is currently uncommon) may be
  written with a bar above the tilde.
\item Resonant states may sport an extra resonance specifier consisting of a
  value in parentheses and optinal following sub- and super-scripts. This
  follows the main particle name.
\end{itemize}

Several issues arise when typesetting these particle names in standard \LaTeX{}:
for starters the requirement of sub- and super-scripts and the need to use Greek
symbols forces us into math mode. But math mode does not usually follow the
surrounding text context for boldness and italicism: this has been fixed in this
specific case by use of the \texttt{maybemath} package. Secondly, the positions
of super-scripts with overlines and tildes are affected: this is also corrected
by this package. By request, the particle typesetting conventions may be
specified as a package option.


\section{Commands}
The commands available are divided into two groups: those which provide
appropriate typeset output for a given semantic description and those which are
purely designed to implement that typesetting, several of which are exposed to
public use for convenience.

\subsection{Semantic commands}
\begin{itemize}
\item For generic particle names e.g. all positively charged leptons:\\
\texttt{$\backslash{}$HepGenParticle\{\textit{main}\}\{\textit{subscript}\}\{\textit{superscript}\}}\\
\texttt{$\backslash{}$HepGenAntiParticle\{\textit{main}\}\{\textit{subscript}\}\{\textit{superscript}\}}

\item For concrete particle names:\\
\texttt{$\backslash{}$HepParticle\{\textit{main}\}\{\textit{subscript}\}\{\textit{superscript}\}}\\
\texttt{$\backslash{}$HepAntiParticle\{\textit{main}\}\{\textit{subscript}\}\{\textit{superscript}\}}

\item For supersymmetric ``sparticles'':\\
\texttt{$\backslash{}$HepGenSusyParticle\{\textit{main}\}\{\textit{subscript}\}\{\textit{superscript}\}}\\
\texttt{$\backslash{}$HepSusyParticle\{\textit{main}\}\{\textit{subscript}\}\{\textit{superscript}\}}\\
\texttt{$\backslash{}$HepGenSusyAntiParticle\{\textit{main}\}\{\textit{subscript}\}\{\textit{superscript}\}}\\
\texttt{$\backslash{}$HepSusyAntiParticle\{\textit{main}\}\{\textit{subscript}\}\{\textit{superscript}\}}

\item For resonance specifiers (just the extra terms):\\
\texttt{$\backslash{}$HepResonanceMassTerm\{\textit{mainterm}\}\{\textit{subscript}\}\{\textit{superscript}\}}\\
\texttt{$\backslash{}$HepResonanceSpecTerm\{\textit{mainterm}\}\{\textit{subscript}\}\{\textit{superscript}\}}

\item For a full particle name and resonance specification:\\
  \texttt{$\backslash{}$HepParticleResonance\{\textit{name}\}\{\textit{mass}\}\{\textit{massSub}\}\{\textit{massSup}\}}\\
  \texttt{$\backslash{}$HepParticleResonanceFull\{\textit{main}\}\{\textit{sub}\}\{\textit{sup}\}\{\textit{mass}\}\{\textit{massSub}\}\{\textit{massSup}\}}\\
  \texttt{$\backslash{}$HepParticleResonanceFormal\{\textit{name}\}$\backslash{}$\\\{\textit{mass}\}\{\textit{massSub}\}\{\textit{massSup}\}\{\textit{spec}\}\{\textit{specSub}\}\{\textit{specSup}\}}\\
  \texttt{$\backslash{}$HepParticleResonanceFormalFull\{\textit{main}\}\{\textit{sub}\}\{\textit{sup}\}$\backslash{}$\\\{\textit{mass}\}\{\textit{massSub}\}\{\textit{massSup}\}\{\textit{spec}\}\{\textit{specSub}\}\{\textit{specSup}\}}\\
  (hurrah, we hit the \TeX{} 9-argument limit!)
  
\item And finally, for containing processes describing particle evolution;\\
  \texttt{$\backslash{}$HepProcess\{\textit{iParticles} $\backslash$HepTo \textit{fParticles}\}}\\
  where \texttt{$\backslash$HepTo} is a normal \texttt{$\backslash$to} arrow
  with a bit of extra space.\footnote{In fact, this space will only be added
    when not compiling via PDF\TeX{}. This is due to a conflict not yet understood *sigh*.}
\end{itemize}

\noindent giving typeset particle names as follows:

\begin{itemize}
\item Normal particles:  \HepParticle{B}{d}{0}, \HepAntiParticle{B}{d}{0}
\item Generic particles: \HepGenParticle{q}{d}{}, \HepGenAntiParticle{\ell}{\mu}{}
\item SUSY particles:    \HepSusyParticle{\chi}{1}{}, \HepGenSusyParticle{q}{2}{}
\item Resonances:        \HepParticleResonance{J\!/\psi}{1S}{}{\star}
\item Process:           \HepProcess{\HepParticle{B}{d}{0} \HepTo \HepParticle{K}{}{-} \HepParticle{\pi}{}{+}}.
\end{itemize}


\subsection{Primitive commands}
A primitive command, \texttt{$\backslash{}$HepParticleStruct}, is provided for
typesetting particle-like structures with a main term and super and sub-scripts
with appropriate automatic changing of the text style into bold, italic and
upright fonts. It also accounts for most vertical spacing problems in the sub-
and super-scripts, largely due to empty script boxes. In addition, three
``styles'': the wrapper macros that apply appropriate text stylings are
available publically. The implementation of the semantic commands is built round
conditionally using these styles within the structure macro.

These macros can be used for implementing particle-like structures with custom
requirements and it's advised that you take a look at the internals of
\texttt{hepparticles.sty} if you're planning on using them.

\begin{itemize}
\item Style which only applies conditional boldness:\\
\texttt{$\backslash{}$HepNormStyle\{\textit{text}\}}
\item Style appropriate for generic particle names:\\
\texttt{$\backslash{}$HepGenStyle\{\textit{text}\}}
\item Style appropriate for concrete particle names:\\
\texttt{$\backslash{}$HepConStyle\{\textit{text}\}}
\item Particle structure:\\
\texttt{$\backslash{}$HepParticleStruct\{\textit{main}\}\{\textit{sub}\}\{\textit{sup}\}}
\end{itemize}

\section{Package options}
By request, the package now typesets particles in italic as well as upright
convention. The choice of convention can be made when the package is loaded with
the \texttt{italic} and \texttt{notitalic} options, e.g.\\
\texttt{$\backslash{}$usepackage[italic]\{hepparticles\}}.
The default mode is upright (i.e. \texttt{notitalic}).

In addition, the \texttt{forceit} option will force \emph{everything} in particle names
to be italic, even if they aren't normally italic in math mode (such as Arabic
numerals). Note that the italic font that will appear here is that used by
\texttt{$\backslash{}$mathit} and so will appear more script-like than normal
math mode. I can't say that I recommend using this option, but it's there for
flexibility's sake.

Finally, a pair of options, \texttt{maybess} and \texttt{noss}, are available:
using \texttt{maybess} will allow particle names to be typeset in sans-serif if
the surrounding context is sans-serif and \texttt{noss} has the converse effect.
Note that since there is no italic sans-serif math font in LaTeX, generic
particle names will not be typeset in italic sans font. Maybe this behaviour
will change in future if there's lots of enthusiasm for a fix. However, it looks
pretty good at the moment and I suspect most people will want sans-serif
particle names in sans documents, so \texttt{maybess} is set by default.

\section{Known problems}
Since this package messes around quite a bit with the sub- and super-scripts,
not everything you might want to do can be done. Sorry\dots

\begin{itemize}
\item To make the macros a bit ``safer'', the output is wrapped in a pair of
  braces --- i.e. it's intended as a packaged unit. Hence you can't add new
  indices using math mode scripting\dots this example hopefully illustrates what
  I mean in that it doesn't accomplish the intended effect of placing the $i$
  subscript directly underneath the \HepParticle{B}{}{} meson superscript.\\
  \texttt{\$$\backslash{}$HepParticle\{B\}\{\}\{+\}\_i\$} $\quad \Rightarrow
  \quad \HepParticle{B}{}{+}_i$ \\
  I don't consider this a problem --- the package structures already manoeuver
  the vertical positioning if the scripts so much that compliance with
  externally applied indices is pretty much guaranteed not to happen.  If you
  want this sort of effect then you should use the
  \texttt{$\backslash{}$HepParticleStruct} macro.
\item When putting particle names in sub or superscripts it's a good idea to
  wrap them in braces. I'd like to be able to avoid this requirement but
  wrapping everything in braces, despite removing compile errors, hasn't done
  the trick of actually making the sub/sup-script work as intended. Please let
  me know how to do it, should the answer spring to mind\dots
\end{itemize}



\section{Installation}
\textbf{Requirements:} You will need to be using a \LaTeXe{} system to use
\hepparticles. Hopefully this isn't a problem --- I wasn't feeling up to writing
a Plain \TeX{} version! In addition, you'll need the \texttt{maybemath} package
(get a recent version: the first release has bugs which were only discovered
when writing the 1.4 version of this package).

To install, simply copy the \texttt{hepparticles.sty} file into a location in
your \texttt{LATEXINPUTS} path. Tada!

\vspace{2cm}
\centering
\noindent Any feedback is appreciated! Email to \texttt{andy@insectnation.org}, please.

\end{document}