\documentclass[12pt]{scrartcl}
\usepackage{maybemath,xspace,setspace,fancyvrb,fancybox}
\usepackage{a4wide,multicol,url,relsize,underscore}
\usepackage{xcolor,braket,amsmath}
\usepackage[colorlinks=true,bookmarks=true]{hyperref}
\usepackage{hepnames}

\onehalfspacing
\DefineShortVerb{\|}
\setlength{\fboxsep}{10pt}
\addtolength{\fboxrule}{0.6\fboxrule}

%% Bold tt font
\DeclareFontShape{OT1}{cmtt}{bx}{n}{<5><6><7><8><9><10><10.95><12><14.4><17.28><20.74><24.88>cmttb10}{}

\newcommand{\texcmd}[1]{\textcolor{red}{\texttt{\char`\\#1}}} 
\newcommand{\texenv}[1]{\textcolor{red}{\texttt{#1}}}
\newcommand{\texopt}[1]{\textcolor{purple}{\texttt{#1}}}
\newcommand{\texopts}[1]{\textcolor{purple}{\texttt{[#1]}}}
\newcommand{\texarg}[1]{\textcolor{violet}{\texttt{#1}}}
\newcommand{\texargs}[1]{\textcolor{violet}{\texttt{\{#1\}}}}
\newcommand{\texpkg}[1]{\texttt{#1}}
\newcommand{\texcls}[1]{\texttt{#1}}
\newcommand{\gen}[1]{\ensuremath{\braket{#1}}}
\newcommand{\texcommand}[1]{\texcmd{#1}} 
\newcommand{\texoption}[1]{\texopt{#1}}
\newenvironment{snippet}{\Verbatim}{\endVerbatim}

\DeclareRobustCommand{\hepparticles}{\texpkg{hepparticles}\xspace}
\DeclareRobustCommand{\hepnames}{\texpkg{hepnames}\xspace}
\DeclareRobustCommand{\heppennames}{\texpkg{heppennames}\xspace}
\DeclareRobustCommand{\hepnicenames}{\texpkg{hepnicenames}\xspace}
\author{Andy Buckley, \texttt{andy@insectnation.org}}
\title{The \hepnames packages for \LaTeX}

\begin{document}
{\sf \maketitle}
%\maketitle

\begin{abstract}
  The \hepnames, \heppennames and \hepnicenames packages provide a large, though
  not entirely comprehensive, library of established high-energy particle
  names. These are flexibly typeset using the \hepparticles package, which
  gracefully adapts the particle typesetting depending on context.

  \heppennames re-implements and augments the particle entity notation scheme
  (PEN) using \hepparticles macros; \hepnicenames uses an alternative, more
  intuitive macro naming scheme to access the simple subset of PEN symbols; and
  \hepnames is a convenience interface to both notations simultaneously.

  Several missing particles have been implemented to augment the naming
  scheme. As well as distinct particle states that were missing in the original
  implementation, alternative representations and ``simple forms'' of existing
  PEN states have been added, occasionally with minimal renaming.

  Particle names not in this scheme can be easily implemented using
  \hepparticles. Contributions to the package, including requests, are of course
  encouraged.
\end{abstract}


\section{Introduction}
\hepnicenames provides a less formally prescribed but more ``natural language''
set of macro names to access the particle names. Listings of macro-to-particle
mappings can be found in the accompanying \texttt{heppennames} and
\texttt{hepnicenames} PDF and PS files and in this document. All of the macros
can be used both in and out of math mode. Unlisted particles can be easily
implemented using \hepparticles directly: please contact the author if you find
a missing state, so it can be added to the library.


\section{Package options}
Both \heppennames and \hepnicenames support the \hepparticles options, simply 
passing those options to \hepparticles. Loading more than one of the packages 
with contradictory options has undefined behaviour, at least as far as the author 
is concerned! For your convenience, the \hepparticles options documentation is 
repeated below:

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 \texopt{italic} and \texopt{notitalic} options, e.g.
\texcmd{usepackage\texopts{italic}\texargs{hepnames}}. The default mode is
upright (i.e.  \texopt{notitalic}).

In addition, the \texopt{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 \texcmd{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, \texopt{maybess} and \texopt{noss}, are available:
using \texopt{maybess} will allow particle names to be typeset in sans-serif if
the surrounding context is sans-serif and \texopt{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 \texopt{maybess} is set by default.


\section{Installation}
\textbf{Requirements:} You will need to be using a \LaTeXe{} system, and 
have installed copies of the \hepparticles package and the \texpkg{maybemath} 
package on which it depends.

To install, simply copy the \texttt{hep*names.sty} files into a location in
your \texttt{LATEXINPUTS} path. Tada!

Now we move on to the lists of macro names in the \hepnicenames and \heppennames
schemes. I'm taken the liberty of placing the \hepnicenames macros first, since
for most purposes they're more intuitive, memorable and (dare I say it?) modern
than the PEN codes.


\section{\hepnicenames macros}
The scheme for the naming of these macros is less rigorous than PEN, but is still
largely prescribed. The main features of the ``nicename'' macro naming scheme are:
%
\begin{itemize}
\item All particle macros start with \texcmd{P}, all antiparticle macros with
  \texcmd{AP}. In some cases, such as the positron, both \texcmd{Ppositron} and
  \texcmd{APelectron} are provided for the \Ppositron symbol, so as not to
  surprise the user.
\item The core of the name is the particle type name in natural language and
  appropriately capitalised, e.g. \texttt{B}, \texttt{Lambda} etc.
\item The optional end part of the command usually specifies the super- or
  sub-script state qualifier, e.g. \texcmd{PBplus} for the \PBplus symbol,
  \texcmd{PZzero} for a \PZ with an explicit superscript zero. The ``zero'',
  ``plus'', ``minus'' and ``pm''/``mp'' strings (for $\pm$ or $\mp$
  respectively) are implemented for every state for which they are possible.
\end{itemize}
%
To combine particle sybol macros in reaction expressions, you should use the
\hepparticles \texcmd{HepProcess} macro, which groups particles together with
nice spacings, including a re-defined \texcmd{to} macro.
%
Complex PEN-specified particles (essentially, the set of excited states with
resonance qualifiers) have not been implemented in the ``nicenames'' scheme.  A
prime motivation for this is that \LaTeX{} does not support numbers in macro
names: spelling the resonance mass numbers out as words would be lengthy and
ridiculous, so the PEN scheme is pretty much as easy to remember as any other in
my opinion. Okay, that's not quite true: ``nicenames'' macros with the ``i, ii,
iii''/``a, b, c'' suffixes would probably be easier, but unless there's demand
for that feature, I can't be bothered implementing it!

\input{hepnicenames-macros}

\clearpage

\section{\heppennames macros}
\heppennames re-implements and augments the particles in the particle entity
notation (PEN) scheme, specifically the \texttt{pennames.sty} \LaTeX{} style.
In several cases, simplified forms of the original PEN macros (e.g. \PZzero's
without the superscript zero, \PJgyi without the resonance specifier\dots) have
been provided. Where this is the case, the PEN notation has usually been changed
to make the simpler form of the symbol correspond to the simplest macro name.
\input{heppennames-macros}

\vspace{1cm}
\noindent
\textbf{Any feedback is appreciated! Email it to \texttt{andy@insectnation.org}, please.}
\newline\newline
In particular, if you find that a particle name is missing, please let me know, 
preferably with a recommended pair of macro names (for the PEN and ``nice'' names)
and a description of how it should by typeset. The best form is to give me an
implementation in terms of the \hepparticles macros, of course!

\end{document}
