Understanding the template

Question

for my thesis I got handed a TeX template and I was trying to understand the code before doing anything redundant or useless. I got most of it figured out but then there's this piece of code I can't decipher:

\makeatletter
 \def\thebibliography#1{\chapter*{References\@mkboth
  {REFERENCES}{REFERENCES}}\list
  {[\arabic{enumi}]}{\settowidth\labelwidth{[#1]}\leftmargin\labelwidth
\advance\leftmargin\labelsep
\usecounter{enumi}}
\def\newblock{\hskip .11em plus .33em minus .07em}
\sloppy\clubpenalty4000\widowpenalty4000
\sfcode`\.=1000\relax}
\makeatother

It's right before the bibliography.
Is anyone able to help me understand this arcane language?

Does your template also provide code for \endthebibliography? — Mico, Mar 06 '19 at 20:55
@Mico no, after that there's just the bibliography and the document ends. — Superuser27, Mar 06 '19 at 21:25
That template is mandatory in your University? If not, you are taking too long to delete it. My suggestions: (1) Start with a standard class as book, scrbook or memoir (2) Add only what you really understand and what you really really need (3) Take ideas from anywhere, but last site to search for outstanding code are the thesis templates (4) Write your bibliography using biblatex, not writing directly \bibtems in the thebibliography environment (5) Remember the KISS principle. — Fran, Mar 06 '19 at 22:06
@Fran it is not mandatory but since it provides a lot of useful functions I would rather not start from scratch. And for didactic reasons I'd like to understand the code fully, to be able to appreciate it, understand it, and edit as needed and not just random trial-and-error — Superuser27, Mar 07 '19 at 10:09
In this case there are probably 'better' ways (which are conceptually nicer and compatible with more standard idioms) to achieve the same result. (It should be enough to redefine \bibname to read "References", this could be done as in https://tex.stackexchange.com/q/82993/35864). That need not mean that the entire template is bad and should be avoided. But given the extensive contact many users here have had with bad templates it is good to be on guard. — moewe, Mar 07 '19 at 10:19
If this template was provided by your institution that is a reason to keep using it, but as soon as it turns out that it does not provide the exact output required in the guidelines it is probably safer to chuck it out and start from scratch than trying to find the issue in a (possibly very complicated) template. — moewe, Mar 07 '19 at 10:20
@moewe there are no issues with the template: it's fully working. I am just trying to understand what each bit does before moving on — Superuser27, Mar 07 '19 at 10:21
Of course the really bad issues only rear their heads a few hours before the important deadline. — moewe, Mar 07 '19 at 10:28
@Superuser27 For didactic purposes learn about TeX primitives in books like TeX by Topic or the TeXbook, but for practical purposes for an average user is better avoid mess too much the preamble (or worse, the contents) with low level formatting code (as the chunk you showed above), as most probably there are a better/easier/simple/cleaner/updated/confiable solution out there to obtain the same look & feel. May start from scratch seems not a good idea at first, but first impressions are misleading. — Fran, Mar 07 '19 at 12:26

moewe · Accepted Answer · 2019-03-07T07:20:33.520

With slightly different indentation the code reads

\makeatletter
\def\thebibliography#1{%
  \chapter*{References\@mkboth{REFERENCES}{REFERENCES}}%
  \list
    {[\arabic{enumi}]}
    {\settowidth\labelwidth{[#1]}%
     \leftmargin\labelwidth
     \advance\leftmargin\labelsep
     \usecounter{enumi}}%
  \def\newblock{\hskip .11em plus .33em minus .07em}%
  \sloppy
  \clubpenalty4000
  \widowpenalty4000
  \sfcode`\.=1000\relax}
\makeatother

It modifies the command \thebibliography that forms the basis of the begin code of

\begin{thebibliography}{<longest label>}
\bibitem{<key>} <entry text>
\end{thebibliography}

In detail

  \chapter*{References\@mkboth{REFERENCES}{REFERENCES}}%

First the code typesets an unnumbered chapter References and adds running heads on both sides reading REFERENCES.

  \list
    {[\arabic{enumi}]}

The bibliography is typeset as a list using the counter enumi (a bit unusual, the standard implementations use the counter enumiv, but normally that does not matter). The label number/label is wrapped in square brackets

    {\settowidth\labelwidth{[#1]}%
     \leftmargin\labelwidth
     \advance\leftmargin\labelsep
     \usecounter{enumi}}%

This is standard stuff that sets up a list with sensible margins for this scenario.

  \def\newblock{\hskip .11em plus .33em minus .07em}%

Defines the additional stretchable space that \newblock inserts. \newblock is a command issued by many bibliography styles to separate larger blocks of information in the bibliography. It allows for visual separation and can help improve line breaking with its additional stretchiness.

  \sloppy

Sets parameters for line breaking, see What is the meaning of \fussy, \sloppy, \emergencystretch, \tolerance, \hbadness?. This setting is usually good at avoiding overfull, but could give sub-par result for longer paragraphs of text. For the bibliography that is probably acceptable.

  \clubpenalty4000
  \widowpenalty4000

Sets parameters to control widows and orphans. See How do I prevent widow/orphan lines? and https://texfaq.org/FAQ-widows.

  \sfcode`\.=1000\relax

Disable the larger space after sentence-ending .s in the bibliography. See also Double space between sentences.

Compared to the standard definition in report.cls (it's the same in book.cls and only slightly different in article.cls)

\newenvironment{thebibliography}[1]
     {\chapter*{\bibname}%
      \@mkboth{\MakeUppercase\bibname}{\MakeUppercase\bibname}%
      \list{\@biblabel{\@arabic\c@enumiv}}%
           {\settowidth\labelwidth{\@biblabel{#1}}%
            \leftmargin\labelwidth
            \advance\leftmargin\labelsep
            \@openbib@code
            \usecounter{enumiv}%
            \let\p@enumiv\@empty
            \renewcommand\theenumiv{\@arabic\c@enumiv}}%
      \sloppy
      \clubpenalty4000
      \@clubpenalty \clubpenalty
      \widowpenalty4000%
      \sfcode`\.\@m}
     {\def\@noitemerr
       {\@latex@warning{Empty `thebibliography' environment}}%
      \endlist}
\newcommand\newblock{\hskip .11em\@plus.33em\@minus.07em}

we note the following differences:

Your code only redefines the begin code (presumably the end code is left unchanged).
Your code uses enumi instead of enumiv. In practice that difference should hardly matter.
The standard code has customisable macros in some places where your code has hard-coded values ([...] vs \@biblabel{...}; References vs \bibname; ).
- In particular the standard classes would print \bibname, which defaults to Bibliography, while your code has References hard-coded. This is about the only visible difference between your code and the standard definition for 'normal use' (assuming the standard definition of \def\@biblabel#1{[#1]}, which is hard-coded in your definition).
Since your code redefines \newblock in the begin code, all changes that are made to that command in the document will be void.

FWIW I found http://kb.mit.edu/confluence/x/YJ47 which recommends pretty much the code you showed. Alan Hoenig's TeX Unbound: LaTeX & TeX Strategies for Fonts, Graphics, & More shows a similar definition on p. 546. The definition is quite similar in style to the one in apalike.sty. I also found several LaTeX 2.09 .stys with similar idioms using enumi (http://mirrors.ctan.org/macros/latex209/contrib/misc/chapref.sty, http://mirrors.ctan.org/macros/latex209/contrib/misc/cites.sty). Maybe the code is inspired by older LaTeX 2.09 code?

Understanding the template

1 Answers1