summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/hepthesis/hepthesis.tex
blob: fddedc3843881283ab55c6b8dfe844221bb1c07e (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
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
\documentclass[12pt]{article}
\usepackage{maybemath,xspace,setspace,fancyvrb,fancybox}
\usepackage{a4wide,url,relsize,sfheaders,underscore}
\usepackage[colorlinks=true,bookmarks=true]{hyperref}
\newcommand{\maybemath}{\texttt{maybemath}\xspace}
\newcommand{\hepthesis}{\texttt{hepthesis}\xspace}

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

\newcommand{\hepthesisversion}{v1.4}
\author{Andy Buckley, \texttt{andy@insectnation.org}}
\title{\hepthesis \hepthesisversion \\ \smaller A class for typesetting academic theses}

\newcommand{\Or}{\texorpdfstring{\ensuremath{\vert}\xspace}{or}}
\newcommand{\manifestsAs}{\texorpdfstring{\ensuremath{\Rightarrow\quad}\xspace}{->}}
\newcommand{\texcmd}[1]{\texorpdfstring{\texttt{\char`\\#1}}{#1}} 
\newcommand{\texenv}[1]{\texorpdfstring{\texttt{#1}}{#1}} 
\newcommand{\texopt}[1]{\texorpdfstring{\texttt{#1}}{#1}}
\newcommand{\texarg}[1]{\texorpdfstring{\texttt{\{#1\}}}{\textbraceleft#1\textbraceright}}
\newcommand{\texargoptgen}[1]{\texorpdfstring{\texttt{[}\gen{#1}\texttt{]}}{\textbraceleft<#1>\textbraceright}}
\newcommand{\texarggen}[1]{\texorpdfstring{\texttt{\{}\gen{#1}\texttt{\}}}{\textbraceleft<#1>\textbraceright}}
\newcommand{\gen}[1]{\ensuremath{\langle\text{\mdseries\itshape#1\/}\rangle}}
\newcommand{\texpkg}[1]{#1}
\newcommand{\texoption}[1]{\texopt{#1}}
\newenvironment{snippet}{\Verbatim}{\endVerbatim}
\newenvironment{fsnippet}%
  {\VerbatimEnvironment
    \begin{Sbox}\begin{minipage}{0.82\textwidth}\begin{Verbatim}}%
  {\end{Verbatim}\end{minipage}\end{Sbox}
    \setlength{\fboxsep}{12pt}\vspace*{4mm}\newline\fbox{\TheSbox}\vspace{4mm}}

\begin{document}
{\sf \maketitle}

\abstract{%
  The \hepthesis class provides an attractive framework in which to write a PhD
  or Masters' degree dissertation. The commands provided by this package permit
  most structural aspects of the thesis to be defined more or less semantically,
  rather than in terms of raw text sizings and position shifts.
}


\section{Introduction}
When I began my PhD in 2001, I was surprised to find that there was no standard
\LaTeX{} thesis class used by students in my field (high-energy particle
physics, hence the ``hep''). In retrospect, this is not so surprising ---
research groups tend to have an informal system of handing down slightly
tailored thesis templates (complete with in line \texcmd{vspace}s,
\texcmd{Huge}s and all the rest) through generations of students without ever
formalising the style and attempting to do it ``properly''. By the time it came
to write my own thesis it was obvious that I would only retain my sanity through
measures of extreme procrastination and so this package came to be. It has now
been edited and hacked on and off since roughly mid-2004, taking stylistic
features from other theses that I've thought attractive and adding features
based on my own pickiness and user requests. The typography isn't motivated by
any formal understanding of the subject, though, so I'm sure there's still
plenty of room for improvement!

This document will document the structure of \hepthesis and how to make it work
with you rather than against you. I may be unable to resist including other
hints and tips on how to make your thesis-writing go smoothly. Please contact me
with suggested improvements, either to the package or to this documentation.


\section{Features}
Why would you want to use \hepthesis? Here's a list of features, so you can
decide for yourself:

\begin{itemize}
\item Semantic macros for defining the front page, abstract, preface, acknowledgements, etc.
\item Macros for quotes, including a full-page quote and chapter-wise quotes
\item Attractive header and footer structures
\item Pre-set margins suitable for binding or for screen viewing
\item Nicely (re-)defined figure, table and equation environments
\item Optional mode for generating hyper-links when building PDF files
\item Built-in draft copy mode with line numbering
\item Maths in section titles etc. will automatically be boldened if appropriate
\end{itemize}


\section{Recommended usage}
The basic usage mode for \hepthesis is to place
%
\begin{snippet}
\documentclass{hepthesis}
\end{snippet}
%
in the preamble of your document. This will then set up the document's appearance and
provide the \hepthesis macros as do the standard \LaTeX{} classes like |article|
and |report|. A more sophisticated and flexible approach is described in 
Appendix~\ref{app:DerivedClass}.

Although strictly unrelated to \hepthesis, it is usual to write each thesis
chapter as a separate |.tex| file and to include it with
\texcmd{include} or \texcmd{input}. You may find it useful to set your
|LATEXINPUTS| environment variable to ensure that the \texcmd{input}'d
files are found by \LaTeX.

\hepthesis takes several optional arguments. Personally, I use
%
\begin{snippet}
\documentclass[hyperpdf,bindnopdf]{hepthesis}
\end{snippet}
%
which produces page-centered, hyper-linked PDF files and PostScript files with
margins suitable for binding and no hyper-links, depending on whether you build
the document using |latex| or |pdflatex|. The details of the \hepthesis options
are described in Section~\ref{sec:Options} of this document.


\section{Requirements}
As \hepthesis aims to allow produce a fairly final version of a thesis without
much additional tweaking, there are quite a few required packages. Most should
be natively available in your \TeX{} distribution; the rest from CTAN.

Here's the mandatory packages:
\begin{itemize}
\item \textbf{scrbook~\cite{scrbook}} (from KOMA-scripts)
\item \textbf{cite~\cite{cite}}
\item \textbf{setspace~\cite{setspace}}
\item \textbf{fancyhdr~\cite{fancyhdr}}
\item \textbf{rotating~\cite{rotating}}
\item \textbf{tocbibind~\cite{tocbibind}}
\item \textbf{caption~\cite{caption}}
\item \textbf{chngpage~\cite{chngpage}}
\item \textbf{varwidth~\cite{varwidth}}
\end{itemize}

\vspace{0.4cm}
\noindent\fbox{\begin{minipage}{0.85\textwidth}\textsl{
%
Note that the \texpkg{subfig}\cite{subfig} (previously \texpkg{subfigure}) 
and \texpkg{ccaption}\cite{ccaption} package, which were required up to 
version 1.3, are no longer needed. 
If you need sub-figures then you should \texcmd{usepackage} the package as 
usual in your document preamble or custom class file, and make use of the 
\texcmd{ContinuedFloat} command for continuation captions, which is 
provided by the mandatory \texpkg{caption} package.
%
}\end{minipage}}
\vspace{0.4cm}

Additionally, there are several packages which are only required depending on
the class options:

\begin{itemize}
\item \textbf{csquotes~\cite{csquotes}:} very standard. Quotation commands will use this if loaded.
\item \textbf{babel~\cite{babel}:} very standard. Quotation commands will use this if loaded.
\item \textbf{a4wide~\cite{a4wide}:} very standard. Disabled with any paper size option other than |a4paper|
\item \textbf{amsmath~\cite{amsmath}:} very, \emph{very} standard. Disabled with the |noams| option
\item \textbf{hyperref~\cite{hyperref}:} very standard. Enabled with the |hyper| option
\item \textbf{booktabs~\cite{booktabs}:} non-standard. Disable with the |nobooktabs| option
\item \textbf{draftcopy~\cite{draftcopy}:} very standard. Enable with the |draft| option
\item \textbf{lineno~\cite{lineno}:} non-standard (?). Enable with the |draft| option
\item \textbf{titling~\cite{titling}:} non-standard (?). Enable with the |titling| option
\item \textbf{sfheaders~\cite{sfheaders}:} non-standard (?). Enable with the |sftitles| option
\end{itemize}

Some other handy packages (which aren't required at all for compatibility with
|hepthesis| but may well help you to write your thesis) are summarised in
Section~\ref{sec:ExtraPackages}.

\subsection{Troublesome interactions}
Unfortunately not all \LaTeX{} packages get on well with each other --- if
you are unlucky then you may get some of \TeX's wondertully cryptic error 
messages on trying to use \texpkg{hepthesis}. Here are the problems that I'm
aware of\dots

\begin{itemize}
\item 
If you have problems with \LaTeX{} complaining about bad definitions of 
\texcmd{pdfstringdefPreHook}, you may be using an old version of \texpkg{csquotes}, 
which doesn't interface well to \texpkg{hyperref}. I think this is fixed in 
\texpkg{csquotes} version 3.2 and later --- it certainly works for version
3.7. Try including the \texpkg{csquotes} package with
%
\begin{snippet}
\usepackage{csquotes}[2007/03/25]
\end{snippet}
%
so that a new enough version will be used.

\item
Similarly, version 0.9 of the \texpkg{varwidth} package has a deformed version
string which means that the package doesn't load properly. This version seems to
have made its way into some \LaTeX{} package distributions, so if you see such
an error then version 0.9a or later can be obtained from CTAN and will work
properly. \texpkg{hepthesis} will check to make sure that the version is as
required and issue a warning if the version on your system is earlier than those
known to be good.

\end{itemize}


\section{Class options}
\label{sec:Options}

\subsection{\texopt{oneside} \Or \texopt{twoside}}
Typeset the thesis for printing in one- or two-sided format: for example, you
may wish to present preview and draft copies in two-sided format, but the final
submission may be required to be single-sided. Changing to single-sided form
will remove the blank facing pages and only use the margins and header/footer
format specified for right-hand pages.

\subsection{\texopt{bind} \Or \texopt{nobind} \Or \texopt{bindnopdf}}
Set the margins to be suitable for printing or screen-viewing. Using the
\texopt{bind} option produces larger inner margins, so that left- and
right-facing pages have LR-reflection symmetry. Using the \texopt{nobind}
option makes the margins equal, so that the pages don't jump around when you
flick through them in |gv| or Adobe Acrobat. The \texopt{bindnopdf} option
will use binding margins when making a PostScript document and screen-view
margins when building a PDF. Note that this option requires some carefulness
with the |.aux| files: this is described in Appendix \ref{app:AuxFileProblem}.

\subsection{\texopt{ams} \Or \texopt{noams}}
Make use of the AMS mathematical package. This re-defines several \hepthesis
mathematical environments using more powerful macros and is enabled by default.
If you don't plan on having any maths in your thesis, then disabling this option
may speed up your build-time a little.

\subsection{\texopt{alphafoot}}
Use alphanumeric footnote markers.

\subsection{\texopt{hidefront} \Or \texopt{hideback} \Or \texopt{hidefrontback}}
Useful for draft builds, these options respectively hide the front matter, the
back matter or both from the \LaTeX{} compilation, giving a faster build time
and meaning you don't have to flick through 20 pages of garbage before
proof-checking the first real content. Note that hiding the back matter will
fail to include the bit where you generate your bibliography, so unless you make
a work-around, all your citations will break.

\subsection{\texopt{draft}}
Prints ``DRAFT'' diagonally across the pages and numbers the lines, suitable for
proof-reading. This makes use of the standard |draftcopy| and the less-standard
|lineno| packages.

\subsection{\texopt{sftitles}}
Uses a sans-serif font for the title page and all chapter, section and
subsection headings. Requires the |sfheaders| package.

\subsection{\texopt{booktabs} \Or \texopt{nobooktabs}}
Use the |booktabs| package to define the \hepthesis tabular environment.
|booktabs| produces publication quality tables, as opposed to \TeX's rather
ropey defaults, and so this option is enabled by default. You can disable it if
your thesis doesn't have any tables and get a slightly faster build, but it is
strongly encouraged that any table presentation uses the |booktabs| look and
feel because it's so much better!

\subsection{\texopt{hyper}}
The |hyper| option is used to activate the |hyperref| package, with some reasonably
sensible default options. Essentially, it's equivalent to putting
%
\begin{snippet}
\usepackage[colorlinks=true,pdfpagemode=FullScreen, \
            bookmarks=true]{hyperref}
\end{snippet}
%
in the preamble of your document.

\subsection{\texopt{hyperpdf}}
|hyperpdf| has the effect of the |hyper| option when building PDF output, and no
effect at all if building PostScript. This can be handy if you consider the PDFs
to be for screen-reading purposes and the PS for printing: you probably don't
want to print a version where all the references and URLs are coloured! Note
that this option requires some carefulness with the |.aux| file, since
alternating between PS and PDF builds involves repeatedly writing and removing
hyperref tokens. A solution to this is described in Appendix \ref{app:AuxFileProblem}.

\subsection{\texopt{index}}
Include the |makeidx| package, to allow an index to be built. Note that you have
to do this by hand and that it's probably best done as a retrospective feature
after you've written the thesis. Not many people want to spend \emph{more} time
with their thesis when they've done enough to pass!

\subsection{\texopt{titling}}
Use the |titling| package to redefine the \texcmd{title} and \texcmd{author}
commands so that their arguments are available through the document as
\texcmd{thetitle} and \texcmd{theauthor}. This is used, for example, by the
\texcmd{titlepage} command. If this option isn't passed, a more basic attempt is
made to do this definition without needing an external package.  It's unclear
whether titling really helps but there may be complicated cases (such as those
where the author includes a \texcmd{thanks}) where |titling| may do a better
job. This is untested, though, and the result of using \texcmd{thanks} in a
|hepthesis| document is to be considered undefined.

\subsection{\texopt{a4paper} \Or \texopt{a4narrow} \Or \texopt{letterpaper} \Or \dots}
Choose the paper size. Duh.


\section{Environments and commands}
The \hepthesis environments and commands are a mix of new macros and tweaked
versions of existing standard ones. The ones that re-define standard macros
can't be disabled (at least, not in this version), so if you don't like them
then you can either hack \hepthesis to be the way you'd like (preferably in a
nice way which I can integrate into a future release) or use something else. The
choice is yours!

Here are the environments and commands, roughly in the order that you'd use them:

\subsection{\texcmd{set{\dots}spacing}\texarggen{spacing}}
A selection of spacing commands are available to change the overall line spacing
of the thesis, or to change the spacing within specific document sections if for
some reason you want to do that. (Personally, I wouldn't --- inconsistent spacing
is very disconcerting.) Here are the available commands, explicitly:
\begin{itemize}
\item \texcmd{setspacing} --- set the following spacings all at once;
\item \texcmd{setfrontmatterspacing}
\item \texcmd{setmainmatterspacing}
\item \texcmd{setappendixspacing}
\item \texcmd{setbackmatterspacing}
\end{itemize}
%
Each command takes a single argument, which can take the values |single|,
|onehalf| and |double|, for single spacing, one-and-a-half spacing
and double spacing respectively. The default is |onehalf|, since I think
that looks most elegant. If making a draft version, double spacing might be
useful since it leaves a bit of room for annotations. I can't recommend single
spacing --- it just looks cramped.
%
\begin{fsnippet}
\documentclass[...]{hepthesis}
\setmainmatterspacing{double}
...
\begin{document}
  ...
\end{fsnippet}


\subsection{\texcmd{set{\dots}extramargins}\texarggen{length}}
A selection of commands are available to change the text width on a per-section
basis. These shouldn't be tweaked too much, but in case you need it, the ability
for configuration is available. The text width itself is not explicitly
specified --- instead the commands take as an argument the width to be added to
both margins. Unless explicitly specified below, all these lengths are zero by
default so any use of these commands with a positive argument is likely to
reduce the text width. Here are the ``large-scale'' extra margins commands:
%
\begin{itemize}
\item \texcmd{setextramargins}\texarggen{len} --- set the following lengths all at once;
\item \texcmd{setfrontmatterextramargins}\texarggen{len}
\item \texcmd{setmainmatterextramargins}\texarggen{len}
\item \texcmd{setappendixextramargins}\texarggen{len}
\item \texcmd{setbackmatterextramargins}\texarggen{len}
\end{itemize}
%
The following commands all add extra margin widths to subsections within the
front matter. Note that they apply \emph{in addition} to the front matter length.
%
\begin{itemize}
\item \texcmd{setabstractextramargins}\texarggen{len} --- |1.5cm| by default;
\item \texcmd{setdeclarationextramargins}\texarggen{len} --- |1.5cm| by default;
\item \texcmd{setacknowledgementsextramargins}\texarggen{len}
\item \texcmd{setprefaceextramargins}\texarggen{len}
\end{itemize}
%
Each command takes a single argument, which is just a \TeX{} length. Here's an example:
\nobreak
%
\begin{fsnippet}
\documentclass[...]{hepthesis}
\setfrontmatterextramargins{1.5}
...
\begin{document}
  ...
\end{fsnippet}


%% TODO Change in v1.5
\subsection{\texcmd{title}\texarggen{title} and \texcmd{author}\texarggen{author}}
The usual commands for setting the author and title. Don't use \texcmd{thanks} in 
the \hepthesis author argument: the results are undefined!
%
\begin{fsnippet}
\title{A study of \BToKPi decays with the \LHCb experiment}
\author{Andrew Gordon Buckley}
...
\begin{document}
  ...
\end{fsnippet}

Once these commands have been executed, the title and author strings are available
via the \texcmd{thetitle} and \texcmd{theauthor} commands. These are used by
\texcmd{titlepage}.

N.B. Up to version 1.3, a special \texcmd{definethesis} command was used to specify
the thesis author and title. While this is still retained for backwards compatibility,
it is deprecated and you should use the standard \texcmd{title} and \texcmd{author}
macros instead. \textbf{\texcmd{definethesis} will be removed in version 1.5}


\subsection{\texenv{frontmatter}, \texenv{mainmatter}, \texenv{appendices} and \texenv{backmatter} environments}
Use these to delimit the auxiliary parts of your thesis from the main feature
(being all that clever work you spent years working on). In practice, these
commands change the page-numbering style and set/reset some section counters
appropriately: the frontmatter and backmatter environments will not use chapter
numbering but will insert the un-numbered chapter titles in the table of
contents. Note that this means appendices should be placed in the appendices
environment between mainmatter and backmatter, rather than in the back matter
itself, which is intended for such things as the bibliography, colophon etc.

\subsection{\texcmd{titlepage}}
The \texcmd{titlepage} macro generates a title page for the thesis and as such
should probably be the first item in the front matter. It takes two arguments:
an optional elaboration of the author name and the description of the award for
which the thesis is being submitted. You may need to use a different macro if
your institution has a very different prescribed format for the layout of thesis
title pages: in such a case, the \texcmd{theauthor} and \texcmd{thetitle}
commands will probably be useful. Here's an example of usage:
%
\begin{fsnippet}
\titlepage[of \\ Churchill College]%
{A dissertation submitted to the University of Cambridge\\ 
for the degree of Doctor of Philosophy}
\end{fsnippet}
%
Additionally, the \texcmd{maketitle} command has been redefined to behave as
\texcmd{titlepage} with two empty arguments. This is only provided to not
confuse users who convert to |hepthesis| from a standard \LaTeX{} class and
expect \texcmd{maketitle} to work: \texcmd{titlepage} is a more powerful
command and should be used by those who are aware of it. That includes you!

\subsection{\texenv{abstract} environment}
Where you present the summary of your thesis: this should be within the
\texenv{frontmatter} environment. The \texenv{abstract} environment takes one
optional argument, which will be the heading above the abstract. If this isn't
specified, the heading will simply be ``Abstract''. This may be useful for
providing a stand-alone summary page, with a snippet like:
%
\begin{fsnippet}
\begin{abstract}%
  [\smaller\thetitle\\ \vspace*{1cm} \smaller{\theauthor}]
\thispagestyle{empty}
This thesis describes all the really cool work I did on...
\end{abstract}
\end{fsnippet}

\subsection{\texenv{declaration} environment}
Where you declare that the thesis was all your own work, lies within word
limits, etc. Use it in the front matter area, of course, with something like
%
\begin{fsnippet}
\begin{declaration}
  This dissertation is the result of my own work...
  \vspace*{1cm}
  \begin{flushright}
    Andy Buckley
  \end{flushright}
\end{declaration}
\end{fsnippet}

\subsection{\texenv{acknowledgements} environment}
A nice little environment for putting all those gushing thank-you's (and the
obligatory thanks to a supervisor). Use it (in the front matter again) like:
%
\begin{fsnippet}
\begin{acknowledgements}
  Of the many people who deserve thanks, some are 
  particularly prominent, for example...
\end{acknowledgements}
\end{fsnippet}

\subsection{\texenv{preface} environment}
Here's where you summarise the structure of the thesis to come, just before the
main matter starts, with something like:
%
\begin{fsnippet}
\begin{preface}
  This thesis describes my research on various aspects of...
\end{preface}
\end{fsnippet}

\subsection{\texcmd{dedication}\texarggen{text}}
Dedicate your thesis to someone/something:
%
\begin{fsnippet}
\begin{mainmatter}
  \dedication{For Jo}
  ...
  \end{frontmatter}
\end{fsnippet}


\subsection{\texcmd{frontquote}\texargoptgen{lang}\texarggen{quote}\texarggen{who}}
Use this at the start of the main matter if you want to present the ethos of
your thesis in a few choice words, for example:
%
\begin{fsnippet}
  \frontquote%
  {Writing in English is the most ingenious torture\\
   ever devised for sins committed in previous lives.}%
  {James Joyce}
  ...
  \end{frontmatter}
\end{fsnippet}
%
\texcmd{frontquote} also takes an optional argument indicating which language the
quote is in. This will change the quotation mark and hyphenation styles, if the 
\texpkg{babel} and \texpkg{csquotes} packages are loaded:
%
\begin{fsnippet}
  \frontquote[french]%
  {Le savant n'\'etudie pas la nature parce que cela est utile; \\
  il l'\'etudie parce qu'il y prend plaisir et il y prend plaisir 
  parce qu'elle est belle.}%
  {Henri Poincar\'e, 1854--1912}
  ...
  \end{frontmatter}
\end{fsnippet}

\subsection{\texcmd{chapterquote}\texargoptgen{lang}\texarggen{quote}\texarggen{who}}
Something flippant/emotive to put at the start of chapters:
%
\begin{fsnippet}
\chapter{\CP violation in the \Bmeson system}
\label{chap:basictheory}
\chapterquote{Laws were made to be broken.}%
  {Christopher North 1785--1854}
  ...
\end{fsnippet}
%
As for \texcmd{frontquote}, an optional language argument can be used.

\subsection{\texenv{colophon} environment}
A colophon is an inscription placed at the end of a book or other work that
talks about how the work was created and what things were used in its creation.
This should go in the back matter of your thesis and is completely optional.
If you use this, please mention \hepthesis' r\^ole in making your thesis! Here's 
an example:
%
\begin{fsnippet}
  \begin{backmatter}
  \begin{colophon}
    This thesis was made with ``hepthesis'' and it was really cool...
  \end{colophon}
  ...
\end{fsnippet}


\subsection{\texenv{table} environment}
Tables --- use like any other table (probably combined with the tabular
environment). It has been slightly modified to be horizontally centered and have
an slightly increased vertical spacing at the top. It supports the standard
\LaTeX{} ``[!htbp]'' float placement specifiers.

\subsection{\texenv{tabular} environment}
If the |booktabs| package is used (enabled by default), then the tabular
environment is re-defined to have a horizontal bar at top and bottom, which
looks much nicer than \TeX's default tables.

\subsection{\texenv{figure} and \texenv{sidewaysfigure} environments}
The \texenv{figure}, \texenv{figure*} and \texenv{sidewaysfigure} environments
are re-defined to be automatically centered.  They support the standard \LaTeX{}
``[!htbp]'' float placement specifiers.

\subsection{\texenv{equation} and \texenv{displaymath} environments}
These environments and their starred versions are re-defined so that
\texenv{equation} behaves like the normal \texenv{displaymath} environment. If
the AMS package is used (which it is by default) then both are redefined to use
the AMS \texenv{align} environment, which is much more powerful: it supports
more intelligent label-placement, sub-equations and boasts a better alignment
syntax than the default \LaTeX{} displayed math environments. The AMS re-defined
\texenv{equation} is suitable for most purposes --- \emph{all} my purposes, in
fact.

\subsection{\texcmd{verysubsection}\texarggen{title}}
A little command for in-line mini section headings, consisting of a boldened
phrase specified by the argument, a bold colon and a space. Just for
convenience, really, when all you want to do is label a paragraph without
incurring all the vertical space of \texcmd{subsubsub...subsection}s. Use it
like:
%
\begin{fsnippet}
\verysubsection{\Tevatron Run II experiments}
Since 1983 and until the commissioning of the \LHC is complete...
\end{fsnippet}

\subsection{Semantic figure widths}
Rather than specifying figure widths in raw terms, like centimetres, or document
parameters like \texcmd{textwidth}, it's nice to be able to have a more semantic
reference. Having a few standard width also helps to keep things looking
consistent through the document. For these reasons, |hepthesis| provides four
standard figure widths, \texcmd{smallfigwidth}, \texcmd{mediumfigwidth},
\texcmd{largefigwidth} and \texcmd{hugefigwidth}, which are defined in terms of
the text width and chosen to avoid overflows. Use them like this:
%
\begin{fsnippet}
\begin{figure}
  \includegraphics[width=\largefigwidth]{ckmfitter-alpha-combined}
  \caption{CKM Fitter constraints on \alphaCKM.}
  \label{fig:CKMFitter}
\end{figure}
\end{fsnippet}
  
Note also that this way of including images will automatically look for an
|.eps| file when building PostScript and a |.pdf| file when building PDF. You
may find the |eps2pdf| and |pdf2eps| utilities useful.

\subsection{Standard in-document reference terms}
It's nice to be able to refer to portions of your document with standard names,
capitalisation, etc. For this reason, I've defined a bunch of macros which give
consistent and sensible capitalisations. Using them systematically will ensure
consistency in your references:
%
\begin{itemize}
\item \texcmd{Chapter} \manifestsAs Chapter
\item \texcmd{Section} \manifestsAs Section
\item \texcmd{Appendix} \manifestsAs Appendix
\item \texcmd{Figure} \manifestsAs Figure
\item \texcmd{Table} \manifestsAs Table
\item \texcmd{Equation} \manifestsAs equation
\item \texcmd{Reference} \manifestsAs reference
\item \texcmd{Page} \manifestsAs page
\end{itemize}

Taking this consistency thing a step further, here are versions of the same
commands which take the reference label as a argument:
%
\begin{itemize}
\item \texcmd{ChapterRef}
\item \texcmd{SectionRef}
\item \texcmd{AppendixRef}
\item \texcmd{FigureRef}
\item \texcmd{TableRef}
\item \texcmd{EquationRef}
\item \texcmd{ReferenceRef}
\item \texcmd{PageRef}
\end{itemize}
%
Using these forms will ensure that the spacing between e.g. the worked
``Chapter'' and the chapter number is always the same, and that it won't wrap
over line breaks. The equation, reference and page forms will call the
\texcmd{eqref}, \texcmd{cite} and \texcmd{pageref} reference macros rather than
\texcmd{ref}, which is used for all others.

\subsection{``thesis---'' prefix versions}
Additionally, all \hepthesis environments and commands have an alternative name,
which is the version described above, prefixed with ``thesis''\footnote{This
  is a hang-over from early versions of my thesis, when I didn't know how to
  robustly extend and re-define environments and commands.}. These forms are
frankly a bit of a pain to use, so use the short versions, please. The
``thesis---'' versions should be considered deprecated and \textbf{will be removed 
in the next release, version 1.5}.


\section{Recommended extra packages}
\label{sec:ExtraPackages}
Here are some other packages it might be good to know about:
\begin{itemize}
\item \textbf{SIunits~\cite{SIunits}:} \emph{the} way to do units and get it right.
\item \textbf{hepunits~\cite{hepunits}:} my extension of |SIunits| to include some common HEP units not used elsewhere.
\item \textbf{hepnames~\cite{hepnames} and hepparticles~\cite{hepparticles}:} my packages for typesetting HEP particle names \emph{properly}, with |hepnames| defining macros for a lot of the standard ones. Requires |maybemath|~\cite{maybemath}
\item \textbf{braket~\cite{braket}:} decent implementation of Dirac bra and ket notation
\item \textbf{cancel~\cite{cancel}:} the best way to do Feynman slashes (in my opinion)
\item \textbf{feynmf/feynmp~\cite{feynmf} and axodraw~\cite{axodraw}:} various approaches to doing Feynman diagrams, especially in equations, inline contexts and so-on.
\end{itemize}
%
and some related software:
%
\begin{itemize}
\item \textbf{FeynDiagram~\cite{feyndiagram} and Jaxodraw~\cite{jaxodraw}}: for Feynman diagrams outside \TeX. You might also
  be interested in my |pyfeyn|~\cite{pyfeyn} program.
\item \textbf{SLAC SPIRES' biblio tools service:} see \url{www.slac.stanford.edu/spires/}
\end{itemize}



\section{An example \texttt{hepthesis} thesis}
Here are some selected snippets from my thesis, which hopefully demonstrate the
features described. I split my thesis into |thesis.cls|, |thesis.sty| and
|thesis.tex| files, with the front matter, back matter and chapters
\texcmd{input}'d into |thesis.tex|. The output was built by running e.g.
%
\begin{snippet}
pdflatex thesis.tex && bibtex thesis && pdflatex thesis.tex
\end{snippet}
%
(though I used a Makefile rather than do it directly). You should note that you
might not be able to build this exact thesis due to missing packages: if you're
writing an HEP thesis then I'd encourage you to use the |hepnames| \LaTeX{}
package for typesetting particle names --- it depends on the extra
|hepparticles| and |maybemath| packages, which you'll also have to download. The
examples used here also rely on the |hepunits| package: you can all these extra
packages from the CTAN~\cite{CTAN}. See Appendix~\ref{app:InstallingPackages} for
a quick guide on how to install personal copies of \LaTeX{} packages.


\subsection{\texttt{thesis.cls}}
{\smaller \VerbatimInput{example/thesis.cls}}

\subsection{\texttt{thesis.sty}}
{\smaller \VerbatimInput{example/thesis.sty}}

\subsection{\texttt{thesis.tex}}
{\smaller \VerbatimInput{example/example.tex}}

\subsection{\texttt{frontmatter.tex}}
{\smaller \VerbatimInput{example/frontmatter.tex}}

\subsection{\texttt{chap1.tex}}
{\smaller \VerbatimInput{example/chap1.tex}}

\subsection{\texttt{chap2.tex}}
{\smaller \VerbatimInput{example/chap2.tex}}

\subsection{\texttt{backmatter.tex}}
{\smaller \VerbatimInput{example/backmatter.tex}}


\section{Wishlist / TODO}
I'm not planning on writing another thesis, but maybe I'll add features if
there's demand. If you add a nice feature, pass it on to me and I'll think about
including it in the package (and will give you some credit, of course). But anyway, 
here's the TODO:
%
\begin{itemize}
\item Make the spacing in the \texcmd{SectionRef} etc. commands customisable.
\item Allow the PDF page style to be specified as a class argument
\item Allow section titles to be centre / right justified?
\item User control of frontmatter title sizes and alignments? (Probably not\dots)
\item Provide different styles for the titlepage etc.
\item Themes, like for Beamer?
\item Make the vertical spacings on the quote, dedication and title pages change by paper size
\end{itemize}


\section{Feedback}
\hepthesis has taken a lot of work\dots I hope you think it was worthwhile and
that you enjoy using it. Or at least, I hope you enjoy writing your thesis more
than you would have done without it! If you're feeling appreciative, then a teeny
credit in your thesis acknowledgements would be hugely appreciated.

Other than that, any feedback on the package is very welcome, especially if it's
constructive criticism! Email your thoughts to
\texttt{hepthesis@insectnation.org}, please.


\section{Acknowledgements}
I'd like to thank all the people who have provided bug reports, patches, suggestions
and who have otherwise helped me to get \hepthesis to the state it's in. See the 
|ChangeLog| file in the distribution for names!


\appendix

\section{Using your own derived document class}
\label{app:DerivedClass}
If you're feeling sophisticated, then you can make your own document class based on 
\hepthesis by placing
%
\begin{snippet}
\LoadClass{hepthesis}
\end{snippet}
%
in your own class definition file. This is a rather nice way of working, since
it allows you to tweak the \hepthesis defaults without cluttering your
|.tex| file with preamble junk.


\section{Installing personal copies of \LaTeX{} packages}
\label{app:InstallingPackages}
Since |hepthesis| depends on several non-standard \LaTeX{} packages, you may have to
download and install them yourself. If you don't have |root| access to the computer
on which you're working then you'll probably have to install them into your own home
directory or similar. Since I expect quite a few prospective users of |hepthesis| will
be non-experts in the ways of \TeX{}, this is a quick guide on what to do.

\begin{enumerate}
\item Make a \TeX{} directory tree in your home directory (or any other area you can write to), e.g.
\begin{snippet}
$ mkdir -p $HOME/local/texmf/tex/latex
$ mkdir -p $HOME/local/texmf/bibtex/bib
$ mkdir -p $HOME/local/texmf/bibtex/bst
\end{snippet}
\item Download the packages from CTAN~\cite{CTAN} or wherever.
\item Follow the packages' installation instructions to install them into the \\
  |$HOME/local/texmf/tex/latex| %$
  directory you made above (or an appropriately-named sub-directory of it if you
  want to be neat). For simple |.sty| or |.cls| files, this will just involve
  copying them into your directory of choice. |.dtx| files will probably require
  running |latex| to build the files to be installed.
\item If you use the |bash| shell, add the following to your |~/.bashrc| file:
\begin{snippet}
export TEXINPUTS="$HOME/local/texmf/tex//:$TEXINPUTS"
export LATEXINPUTS="$HOME/local/texmf/tex/latex//:$LATEXINPUTS"
export BIBINPUTS="$HOME/local/texmf/bibtex//:$BIBINPUTS"
\end{snippet}
or, if you use the |(t)csh| shell, add the following to your |~/.cshrc| file:
\begin{snippet}
setenv TEXINPUTS "$HOME/local/texmf/tex//:$TEXINPUTS"
setenv LATEXINPUTS "$HOME/local/texmf/tex/latex//:$LATEXINPUTS"
setenv BIBINPUTS "$HOME/local/texmf/bibtex//:$BIBINPUTS"
\end{snippet}
\item That's all: the lines above mean that  \LaTeX{} will look for input files
such as classes, packages, images, \texcmd{input}'d |.tex| files etc. recursively under \\
|$HOME/local/texmf/tex/latex| %$
 and that BibTeX will look for its style and database files recursively under
|$HOME/local/texmf/bibtex|.%$
You can probably see how this can be extended to keep your thesis development
directories neat, too!
\end{enumerate}


\section{Distinguishing PS/PDF output in thesis builds}
\label{app:AuxFileProblem}

The options \texopt{bindnopdf} and \texopt{hyperpdf} change the behaviour
depending on whether you're building PDF or PostScript output. This is fine if
you only ever do one, but if you want to switch rapidly between these output
formats then you'll have problems. This is because the |.aux| file, which
records the reference keys and suchlike changes depending on whether you're
making hyper-refs and if the changes of margins force sections on to different
pages.

A nice solution to this involves using a Makefile, which you probably want to be
doing anyway. You'll have to read up on the details of Makefiles (and possibly
GNU automake) elsewhere, but to save on Make-newbie angst, I'll tell you that
the indents in the following snippet \emph{must} be tabs, rather than spaces!
Here goes --- put the following into a file called |Makefile|, change the
|DOCNAME| variable to something which suits your project and run |make thesis| or |make thesispdf|:
\begin{fsnippet}
# For a main thesis LaTeX file called ``thesis.tex''
DOCNAME = thesis

thesis: $(TEXSOURCES) $(DOCNAME).bbl
    test -f $(DOCNAME).aux.ps && cp $(DOCNAME).aux.ps \
      $(DOCNAME).aux || true
    latex $(DOCNAME)
    cp $(DOCNAME).aux $(DOCNAME).aux.ps
    ./thesisstats.sh >> buildlog.dat

thesispdf: $(TEXSOURCES) $(DOCNAME).bbl
    test -f $(DOCNAME).aux.pdf && cp $(DOCNAME).aux.pdf \
      $(DOCNAME).aux || true
    pdflatex $(DOCNAME)
    cp $(DOCNAME).aux $(DOCNAME).aux.pdf
    ./thesisstats.sh >> buildlog.dat
\end{fsnippet}

Otherwise you can just delete the |.aux| file when you change between using
|latex| and |pdflatex|, but this will require more passes, since the
|.aux| file has to be replaced each time.

\begin{thebibliography}{99}
\bibitem{CTAN}{CTAN: \url{http://www.ctan.org}. \url{http://www.tex.ac.uk/tex-archive} is shortened to |ctan:| below.}
\bibitem{scrbook}{scrbook: \url{ctan:/macros/latex/contrib/komascript/}}
\bibitem{cite}{cite: \url{ctan:/macros/latex/contrib/cite/}}
\bibitem{setspace}{setspace: \url{ctan:/macros/latex/setspace/}}
\bibitem{fancyhdr}{fancyhdr: \url{ctan:/macros/latex/contrib/fancyhdr/}}
\bibitem{rotating}{rotating: \url{ctan:/macros/latex/contrib/rotating/}}
\bibitem{tocbibind}{tocbibind: \url{ctan:/macros/latex/contrib/tocbibind/}}
\bibitem{subfig}{subfig: \url{ctan:/obsolete/macros/latex/contrib/subfig/}}
\bibitem{caption}{caption: \url{ctan:/macros/latex/contrib/caption/}}
\bibitem{ccaption}{ccaption: \url{ctan:/macros/latex/contrib/ccaption/}}
\bibitem{chngpage}{chngpage: \url{ctan:/macros/latex/contrib/chngpage/}}
\bibitem{varwidth}{varwidth: \url{ctan:/macros/latex/contrib/varwidth/}}
\bibitem{csquotes}{csquotes: \url{ctan:/macros/latex/contrib/csquotes/}}
\bibitem{babel}{babel: \url{ctan:/macros/latex/contrib/babel/}}
\bibitem{a4wide}{a4wide: \url{ctan:/macros/latex/contrib/misc/a4wide.sty}}
\bibitem{amsmath}{amsmath: \url{ctan:/macros/latex/required/amslatex/math/}}
\bibitem{hyperref}{hyperref: \url{ctan:/macros/latex/contrib/hyperref/}}
\bibitem{booktabs}{booktabs: \url{ctan:/macros/latex/contrib/booktabs/}}
\bibitem{draftcopy}{draftcopy: \url{ctan:/macros/latex/contrib/draftcopy/}}
\bibitem{lineno}{lineno: \url{ctan:/macros/latex/contrib/lineno/}}
\bibitem{titling}{titling: \url{ctan:/macros/latex/contrib/titling/}}
\bibitem{sfheaders}{sfheaders: \url{ctan:/macros/latex/contrib/sfheaders/}}
\bibitem{SIunits}{SIunits: \url{ctan:/macros/latex/contrib/SIunits/}}
\bibitem{hepunits}{hepunits: \url{ctan:/macros/latex/contrib/hepunits/}}
\bibitem{hepnames}{hepnames: \url{ctan:/macros/latex/contrib/hepnames/}}
\bibitem{hepparticles}{hepparticles: \url{ctan:/macros/latex/contrib/hepparticles/}}
\bibitem{maybemath}{maybemath: \url{ctan:/macros/latex/contrib/maybemath/}}
\bibitem{braket}{braket: \url{ctan:/macros/latex/contrib/misc/braket.sty}}
\bibitem{cancel}{cancel: \url{ctan:/macros/latex/contrib/misc/cancel.sty}}
\bibitem{feynmf}{feynmf: \url{ctan:/macros/latex/contrib/feynmf/}}
\bibitem{axodraw}{axodraw: \url{http://www.nikhef.nl/~form/FORMdistribution/axodraw/}}
\bibitem{feyndiagram}{FeynDiagram: \url{http://www.feyndiagram.com}}
\bibitem{jaxodraw}{Jaxodraw: \url{http://http://jaxodraw.sourceforge.net/}}
\bibitem{pyfeyn}{PyFeyn: \url{http://hepforge.cedar.ac.uk/pyfeyn/}}
\end{thebibliography}

\end{document}