0

I am writing a large document and recently had a weird bug crop up regarding the order of my references. I've now resolved it, but I'm not sure how it was able to occur, or why my solution even worked. I'd like to understand this so I can find other similar bugs if they exist, or at least be confident my references are ordered correctly without having to go through 200+ pages with a fine-toothed comb.

My document is in roughly this form:

\documentclass{book}
\usepackage{cleveref}
\usepackage{cite}
\usepackage[nottoc]{tocbibind}

\begin{document}

\frontmatter
\tableofcontents

\mainmatter
\include{Chapter1}
\include{Chapter2}
\include{Chapter3}

\backmatter
\bibliographystyle{unsrt}
\bibliography{bibfile}

\end{document}

And the output looked something like this:

"Lorem ipsum dolor sit amet, consectetur adipiscing elit.[1] Duis cursus dictum purus,[2] sit amet malesuada diam viverra vel.[3] Donec et velit sit amet lorem lobortis vulputate.[20] Aenean vel leo tempor,[4] fringilla nisl eget, mollis arcu.[5]

Bibliography

  1. Dummy reference A, Journal of Foo Bar, vol 1, 1999.

  2. Dummy reference B, Journal of Bar Foo, vol 12, 2000.

  3. etc"

For some reason I was never able to determine, reference 20 was not numbered correctly. It was the 4th reference cited in the document (including in captions, TOC, etc), but it was assigned the number 20 instead of 4. Out of the references that I explicitly checked, there were no other similar issues. Compiling the document multiple times didn't correct the order. At some point I opened up the .bib file and moved the offending reference to a different random point in the .bib file and suddenly everything was fine. There is no difference in the code in the main document, and in theory the .bib file should give the same result regardless of the order of the references, yet this seemingly irrelevant change has made it go from not working to working. As a side note, at no point was there a problem compiling the document, and there were never any error messages, either before or after the fix.

Can anyone explain what happened here? Or how I might avoid similar issues in the future?

Ulysses
  • 1,933
  • 1
    You have not shown any relevant code to allow anyone to help! do you have any citations in table captions or section headings etc. – David Carlisle Jul 26 '18 at 07:13
  • Sounds like an problem in the bib. Did you ever checked the blg for warnings or errors? – Ulrike Fischer Jul 26 '18 at 07:25
  • @Mico and David. There is no list of figures or list of tables. Reference 20 is the 4th reference in the entire text of the document, including the text of captions, table of contents, etc. It was correctly labelled 4 after my illogical fix was applied, which did not involve any changes to the main document or included files. Only the .bib file. – Ulysses Jul 26 '18 at 07:29
  • @Ulrike Fischer Can you clarify what you mean by the blg? There were no errors when I compiled the document. Is that what you meant? – Ulysses Jul 26 '18 at 07:30
  • 1
    The .blg-file is the "log" from bibtex. – Ulrike Fischer Jul 26 '18 at 07:33
  • I found the .blg file for the main document and the only errors are in reference to a couple of undefined citations I have much later in my document, so are likely not related. Could this document have been overwritten when I compiled it last? If so then it won't show any error messages for the original issue. – Ulysses Jul 26 '18 at 07:43
  • 1
    The .blg file gets re-written each time BibTeX is run. – Mico Jul 26 '18 at 07:45
  • In that case it's impossible to say either way since it now works fine. – Ulysses Jul 26 '18 at 07:49
  • Note that literally the only change made was to reorder the references within the .bib file. I just cut and pasted a reference from one place to another. The code for any individual reference wasn't altered. – Ulysses Jul 26 '18 at 07:51
  • Is it possible that the references aren't automatically compiled every time the main document is compiled, but by making a seemingly irrelevant change to the .bib file it simply forced them to be recompiled, and therefore fixed an error than was likely fixed in a previous edit, but simply not 'updated'? – Ulysses Jul 26 '18 at 08:15
  • 1
    @Ulysses latex itself never regenerates the bibliography, you need to re-run bibtex after any change, but of course your build system (make, latexmk, your editor build config or anything else you have not shown) may trigger bibtex to run under any conditions that may be programmed in to that system. – David Carlisle Jul 26 '18 at 08:21
  • That could be the issue then. I never manually run bibtex, and just rely on my editor to sort all that sort of stuff out. I'm using TeXstudio, but I don't know much about how it works, or where to find information about how it handles bibtex related stuff. – Ulysses Jul 26 '18 at 08:27
  • 1
    I've just dug through the program options and it appears a checkbox is ticked that means every time I compile the document it will first recompile the bibliography only if the .bib file was changed. Presumably if the .bib file isn't changed but I add a reference into the main document earlier than it was originally, then the bibliography won't update, or reorder references to match. This is likely the source of my error. If I can figure out how to manually run bibtex then I can ensure this issue doesn't reoccur. – Ulysses Jul 26 '18 at 08:36
  • 1
    since the issue is in editor config that is not shown. I think you need to self answer (if you have an answer that you think will help other texstudio users) or delete or something, I don't think anyone else can really answer. – David Carlisle Jul 26 '18 at 08:52
  • Sure. I'll put something together. – Ulysses Jul 26 '18 at 09:01
  • 1
    Mainly for the link, but also in case you didn't know it https://tex.stackexchange.com/q/63852/35864 explains what BibTeX does very nicely. If you then add that pdfLaTeX and BibTeX are independent programmes where normally neither calls the other, you can see why things went wrong in more detail. – moewe Jul 26 '18 at 09:29
  • Do you have \nocite somewhere? – egreg Jul 26 '18 at 09:32
  • @moewe Thanks! That will really help me to understand this better, and ensure I don't get any more issues like this one. – Ulysses Jul 26 '18 at 09:39
  • @egreg No, but thanks for the suggestion. I've now found the issue is due to the way things were being compiled, rather than anything in the code. I'm putting together an answer now that explains this. – Ulysses Jul 26 '18 at 09:40

1 Answers1

2

Just to summarise the discussion in the comments:

The issue was found to be due to the way things were (or rather weren't) being compiled, rather than any issues with the code itself. Regardless of the editor used, the order of references will only be updated when the bibliography is compiled, which is separate to the compiling of the main document. So if the document is edited such that the 20th reference is now the 4th one to be cited, it will still appear in the text as [20] when the document is compiled, until such time as the bibliography is compiled again. The solution is to simply force the editor to compile the bibliography, then compile the main document in the usual manner. It may be necessary to repeat this a few times if some issues with ordering remain, for reasons detailed in the main answer here.

In TeXstudio the compiler for the bibliography can be run manually by going to Tools --> Bibliography, or pressing F8, then the main document will show the correct references next time it is compiled, i.e. pressing Build, or F5. TeXstudio can also be set up so that the bibliography will also be automatically compiled if the .bib file is edited, which is why I saw the issue resolved when I made an irrelevant change to the .bib file. Simply changing the order things are cited in the text will not trigger it to recompile.

Ulysses
  • 1,933
  • 1
    Note that biblatex would warn you in cases like this and would ask for a re-run of Biber, so that the expected order can be restored. But of course then you need to read the warnings and act accordingly. – moewe Jul 26 '18 at 10:52
  • @moewe Are you sure? I just tested this and I was able to reproduce my issue, but there were no warnings or error messages suggesting anything like that. I checked the .blg log file, and the log feed in the editor, but there was nothing. – Ulysses Jul 27 '18 at 05:28
  • Yes, I am. But as far as I can see your are not using biblatex - you are using plain, ol' BibTeX (https://tex.stackexchange.com/q/25701/35864). I didn't say anything about BibTeX (or rather about LaTeX-side packages that work with it), because I wasn't sure whether or not they issue a warning. BTW: The warning would have to come from LaTeX (BibTeX could only say anything if it was run, but the whole point of the warning is to figure out whether or not to run BibTeX), so it would be in the .log not in the .blg. – moewe Jul 27 '18 at 05:37
  • @moewe My mistake, it is indeed Bibtex, not Biblatex. I didn't pick up on the difference. However I went through the log file and still did not find any warning or error suggesting Bibtex needed to be run, or that there was any problem with references even vaguely related to the above issue. – Ulysses Jul 27 '18 at 06:37
  • As I said, you use BibTeX (which in the way you use it is incompatible with biblatex) and I was saying that biblatex would warn you. So I didn't expect you to get a warning here. It was just meant as a tiny shred of information for people with a similar problem. And of course it also doubles as a convenient ad for biblatex in case people think that is a nice feature. – moewe Jul 27 '18 at 06:41
  • Sorry. I thought you were saying there'd be something in the .log file if bibtex wasn't run. I misunderstood. – Ulysses Jul 27 '18 at 06:51
  • I did, but I also said that this would be the case if you used biblatex. I did not make any claims about your setup which does not use biblatex if the example in the question is representative of your setup (because I didn't know if cite would warn you and because I didn't check that). – moewe Jul 27 '18 at 06:54
  • You said "The warning would have to come from LaTeX (BibTeX could only say anything if it was run, but the whole point of the warning is to figure out whether or not to run BibTeX), so it would be in the .log" so I assumed you were talking about Bibtex. Did you mean to say 'biblatex' instead? – Ulysses Jul 27 '18 at 06:58
  • Maybe the "LaTeX" at that point was a bit confusing. biblatex (a LaTeX package) would tell LaTeX (and in the end TeX, the programme) to print the warning in the .log file of the LaTeX run. That's what I meant by "from LaTeX" as opposed to "from BibTeX" after the BibTeX run (in the .blg). In that dichotomy there is no "from biblatex" since biblatex is not an independent programme. – moewe Jul 27 '18 at 07:01
  • Ah, I think I see now. From the discussion it sounded like bibtex and biblatex were just two different kinds of compilers, hence my confusion. Perhaps I should have clarified I'm a newbie, so explanations need to be clear and simple, with no or minimal assumed knowledge. – Ulysses Jul 27 '18 at 07:20
  • That's why I linked https://tex.stackexchange.com/q/25701/35864 which explains the difference between the terms that I flung around here. – moewe Jul 27 '18 at 08:18