11

biber complains about "junk" in what should be seen rather as commented-out lines in a BibTeX file. I was wondering if comments are discouraged in BibTeX at all.

\documentclass {article}

\usepackage {filecontents}

\begin {filecontents} {ref.bib}
 @book {book1,
 author={author 1},
 title={title 1}}

 book {book2,
 author={author 2},
 title={title 2}}

 @book {book3,
 author={author 3},
 title={title 3}}
\end{filecontents}

\usepackage [backend=biber] {biblatex}
\addbibresource {ref.bib}

\begin {document} 
 \nocite{*}
 \printbibliography
\end {document}

Here is biber's output:

INFO - This is Biber 2.1
INFO - Logfile is 'mwe.blg'
INFO - Reading 'mwe.bcf'
INFO - Using all citekeys in bib section 0
INFO - Processing section 0
INFO - Looking for bibtex format file 'ref.bib' for section 0
INFO - Decoding LaTeX character macros into UTF-8
INFO - Found BibTeX data source 'ref.bib'
WARN - BibTeX subsystem: /tmp/No7MbpTruX/ref.bib_31209.utf8, line 13, warning: 43 characters of junk seen at toplevel
INFO - Overriding locale 'en-US' defaults 'variable = shifted' with 'variable = non-ignorable'
INFO - Overriding locale 'en-US' defaults 'normalization = NFD' with 'normalization = prenormalized'
INFO - Sorting list 'nty' of type 'entry' with scheme 'nty' and locale 'en-US'
INFO - No sort tailoring available for locale 'en-US'
INFO - Writing 'mwe.bbl' with encoding 'ascii'
INFO - Output to mwe.bbl
INFO - WARNINGS: 1
n.r.
  • 4,942
  • You can ignore the warnings. You can use tex comments (%) to comment an entry if you don't like them. Imho is is rather useful that biber reports things like this, as the "junk" is often due to some faulty brace. – Ulrike Fischer Aug 13 '15 at 15:35
  • Are TeX comments % in BibTeX files a biber's extension or does it belong to the BibTeX format originally? – n.r. Aug 13 '15 at 15:41
  • Try it out. You can also look at some of the older bib files in your texmf. xampl.bib e.g. starts with % Copyright (C) 1988, 2010 Oren Patashnik.. – Ulrike Fischer Aug 13 '15 at 16:07
  • @UlrikeFischer Commenting them out won't avoid the warnings, though, will it? At least, it doesn't for me. – cfr Aug 13 '15 at 16:18
  • It's missing on purpose. – n.r. Aug 13 '15 at 17:26
  • And what should that purpose be? – MaxNoe Aug 14 '15 at 06:40
  • It's a comment. See this. – n.r. Aug 14 '15 at 10:35
  • 1
    Technically you are right, according to btxdoc, p. 13: "BibTeX allows in the database files any comment that’s not within an entry. If you want to comment out an entry, simply remove the @ character preceding the entry type." Which seems to quite clearly indicate that everything that is not a proper entry starting with @ has to be seen as comment. Remember, though, that Biber does not give you an error, but only a warning. See it as a solicitous service by Biber. ... – moewe Aug 14 '15 at 11:41
  • ... If you for the life of you cannot live with that warning, ask the maintainers for a switch to turn it off (in the Biber issue tracker over at github). Interestingly though, % is treated as a comment character by Biber, while btxdoc says: "LaTeX's comment character % is not a comment character in the database files.", point 14, p. 14. But even Oren Patashnik seems to have succumbed to using % as a comment character in the .bib file, as UlrikeFischer points out above, though one could argue that the use of % was merely superfluous. – moewe Aug 14 '15 at 11:42
  • This is not about the warning but what exactly a BibTeX comment is supposed to be, and more important, as stated in the OP, whether comments are discouraged in a BibTeX database, as seems to be the case with how biber reacts to it. Suppose I'd like to have an annotated BibTeX database. What would be the proper or recommended way of doing it? – n.r. Aug 14 '15 at 13:07
  • Well, as I said above, the "standard" says that everything that is not an entry has to be taken as a comment, i.e. is a comment in the eyes of the law. What you have in your file then is de jure a comment. It is generally considered acceptable to sprinkle your files with comments as you seem fit. Who would discourage the use of comments - and who would have the right to do so? Now, in this case indeed Biber issues a warning (and might lead people to think it were to discourage comments). You can interpret this warning as a wholehearted rejection of comments. ... – moewe Aug 14 '15 at 14:00
  • ... Or you can interpret this message as a mere word of warning (maybe not even warning, just a short reminder to not let your guard down) that you might have missed a @ or that your automatic .bib exporter messed up, or your downloaded source is malformed etc... If you are sure what you have there is no mistake or oversight on your part, but that we deal with a mere comment, you are of course free to disregard the warning entirely, thank Biber for kindly reminding you, and move on. – moewe Aug 14 '15 at 14:02
  • Now if you just want an annotated database you need to think about what exactly it is you need. You can try one of those reference management softwares. You can just go on putting a comment in front of your entry as you used to. You can put a % in front so Biber ignores it. You can add the comment into a special field in the proper entry, so it can be printed if you wished. There is really a lot you can do.... – moewe Aug 14 '15 at 14:07
  • My point is this: You seem to have discovered that Biber does not seem not parse a .bib file 100% by the book, it issues a warning where the book, i.e. btxdoc speaks of a comment, which we normally expect not to trigger a warning. Now your question seems to be: Do I ignore the warning because technically (i.e. de jure) I'm in the right. Or do I placate Biber by changing the format of my comments and thus concede your right to use comments in exactly that way. – moewe Aug 14 '15 at 14:22
  • 4
    You could also annotate the entry in the entry itself. Both Biber and BibTeX ignore entry fields for which they have received no instructions, so you can simply add a field like specann = {} and fill it up with whatever you like. I often, though not systematically, add library call numbers to my entries for this reason. – jon Aug 14 '15 at 14:54
  • If you want to annotate special entries, keep the annotatin within the entry, as @jon pointed out. If you want to structure the database in parts, use keywords in the entries. – Johannes_B Aug 14 '15 at 15:39
  • @nicolai.rostov Are you OK with the comments, or are you missing anything? I'm thinking of compiling the comments into a CW answer so we can get this answered. – moewe Aug 19 '15 at 07:44
  • Sure. Maybe we should change the question to reflect a more interesting answer. – n.r. Aug 19 '15 at 12:01
  • @UlrikeFischer I have added a CW answer, feel free to contribute or start a competing answer. – moewe Aug 20 '15 at 07:57
  • @jon I have added a CW answer, feel free to contribute or start a competing answer. – moewe Aug 20 '15 at 07:57
  • @Johannes_B I have added a CW answer, feel free to contribute or start a competing answer. – moewe Aug 20 '15 at 07:57
  • @moewe -- Looks good to me. – jon Aug 20 '15 at 16:47

1 Answers1

23

It is in no way discouraged to comment any files you might have written. What you came across is a slight discrepancy in the handling of comments, or if you will a disagreement about what constitutes a comment.

According to btxdoc, §4, item 7, p. 13

BibTeX allows in the database files any comment that's not within an entry. If you want to comment out an entry, simply remove the @ character preceding the entry type.

That means that anything that is not within a @<entrytype>{...} entry block has to be considered a comment by the parser.

Furthermore, in §4, item 14, p. 14, we find

LaTeX's comment character % is not a comment character in the database files.

So technically (and legally, if you will) your block with book2 is indeed a comment.

Still, Biber warns about it mentioning "characters of junk". You can safely ignore this warning just as Biber ignores these characters. Instead you can see these warning as an additional service by Biber to warn you that something might be wrong. Sometimes people genuinely forget a @ or have some real junk in their files.

Contrary to the excerpt quoted above, Biber considers lines starting with % to be real comments and does not issue junk character warnings in these cases. So if you are OK with using % at the beginnings of comments in your .bib file, Biber will not bother you about them again, even though technically the lines outside a @ block should be considered comments without the % as well.

As biber considers % a real comment sign, it handles commented entries differently to BibTeX. An entry starting with

%@article{A,

will be ignored by biber (and the rest will junk), while bibtex will still see it.

Since the % is not considered a comment character by BibTeX, but is passed through verbatim to LaTeX (where it will be recognized as a comment with possibly catastrophic results), you should better not use the % inside an entry. (Outside it doesn't matter as it is ignored along with all the rest).

The entry

@ARTICLE{auchunbekannt,
  title = {Beispielaufsatz},
  journal = {Zeitschrift},
  year = {2001},
  %volume = {7},
  pages = {1--35, 99--291},
  annotation = {lorem},
}

will compile just fine with Biber (you will not get a volume field in the output of course), but BibTeX will throw an error. So a safer way to exclude a field is to rename it:

 xxxvolume = {7},

Similarly,

@article{B,
    author  = {Uthor, A.}, % her full name is Anne Uthor
    journal = {Journal 1},
    title   = {Title},
    year    = {2015},
}

will compile fine with Biber, but will throw the error

You're missing a field name---line 6 of file biblio.bib
 :         author  = {Uthor, A.}, 
 :                                % her full name is Anne Uthor
I'm skipping whatever remains of this entry

with BibTeX.

On the other hand

@article{A,
    author = {Author, A.},
    journal = {Journal 1},
    title = {Title %1
            },
    year = {2014},
}

can work with BibTeX, but with biber you would get this in the bbl:

\field{title}{Title %1}

and this leads to a runaway argument.

If your aim is an annotated bibliography, you can also annotate an entry inside the entry in a field unknown to Biber/BibTeX, this leaves the option of – if need be – allowing an output in the document. biblatex even has an annotation field that is optionally shown by the reading style, all other standard styles ignore it, it is passed to the .bbl file, though. A new field such as myann will be completely ignored by Biber and BibTeX and thus can be filled with your comments as well.

moewe
  • 175,683