summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/hepparticles/hepparticles.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/hepparticles/hepparticles.tex')
-rw-r--r--Master/texmf-dist/doc/latex/hepparticles/hepparticles.tex195
1 files changed, 195 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/hepparticles/hepparticles.tex b/Master/texmf-dist/doc/latex/hepparticles/hepparticles.tex
new file mode 100644
index 00000000000..8b3a5176e63
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/hepparticles/hepparticles.tex
@@ -0,0 +1,195 @@
+\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} \ No newline at end of file