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

\newcommand{\hepparticles}{\texttt{hepparticles}\xspace}
\author{Andy Buckley, \texttt{andy@insectnation.org}}
\title{The \hepparticles package for \LaTeX\\ \smaller[2] Describing \hepparticles version 2.0}

\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.\\
  This document describes version 2.0, which significantly improves the output
  quality over versions 1.x, removes several macros \& package options, and
  changes dependencies.
\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 optional 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. All the \hepparticles commands may be used either
in or out of math mode.


\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$to \textit{fParticles}\}}.\\
\end{itemize}

% \vspace{-0.5em}

\noindent These commands respectively typeset particle names like this:\\[-1ex]
\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} \to \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 styling are available
% publicly. 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 can typeset 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}
option, i.e.\\
\texttt{$\backslash{}$usepackage[italic]\{hepparticles\}}.
The default mode is upright. % (i.e. \texttt{notitalic}).

The \texttt{forceit}, \texttt{maybess} and \texttt{noss} options have been removed in version 2.0.

% 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 of 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! \hepparticles 2.0 requires the \texttt{subdepth} package.
% 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!


\section{Credit where it's due\dots}
Thanks to Viet-Trung Luu for providing the initial ``way forward'' when writing
this package: his solution, in expanded form, made its way into what is now
the \texttt{maybemath} package. Thanks also to Heiko Oberdiek and Donald Arseneau
for showing how to stop the \texttt{$\backslash{}$mspace}s from turning up in PDF
bookmarks generated by \texttt{hyperref}. Philip Ratcliffe provided the hack
that moves over-lines slightly to the right for use with italic particle symbols.
In version 2.0 I owe a great deal to the subdepth package


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

% In particular, robust solutions for the following would be extremely useful:

% \begin{itemize}
% \item Upright Greek lower case letters (without using e.g. \texttt{pxfonts})
% \item Slightly increase horizontal spacing between particles in
%   \texttt{$\backslash{}$HepProcess} (at present, \texttt{$\backslash{}$,} ends
%   up getting used a lot to keep different particles apart)
% \end{itemize}

\end{document}