summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/hepparticles/hepparticles.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/hepparticles/hepparticles.tex
Initial commit
Diffstat (limited to 'macros/latex/contrib/hepparticles/hepparticles.tex')
-rw-r--r--macros/latex/contrib/hepparticles/hepparticles.tex225
1 files changed, 225 insertions, 0 deletions
diff --git a/macros/latex/contrib/hepparticles/hepparticles.tex b/macros/latex/contrib/hepparticles/hepparticles.tex
new file mode 100644
index 0000000000..354de33cee
--- /dev/null
+++ b/macros/latex/contrib/hepparticles/hepparticles.tex
@@ -0,0 +1,225 @@
+\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}