summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/hepparticles/hepparticles.tex
blob: 354de33cee8333b558dceb207a86fd9991aa9308 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
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}