Using bibleref inside a section title

Question

The bibleref package does not work when a reference is called inside the title of a section. The following error is raised:

Argument of \@sect has an extra }

Same inside a caption. Does anyone knows how to overcome this?

Here is a MWE:

\documentclass[a4paper]{article}
\usepackage[T1]{fontenc} 
\usepackage[utf8]{inputenc}

\usepackage{bibleref}

\begin{document}

Here a reference in the text which works: \bibleverse{Gn}(1:1-3)

\section{Here a reference within a title: \bibleverse{Gn}(1:1-3) } % Don't work

\begin{table}
\caption{Here a reference within a caption: \bibleverse{Gn}(1:1-3) } % Don't work
\end{table}

\end{document}

Answer 1

You can \protect those "special" references:

\documentclass[a4paper]{article}
\usepackage[T1]{fontenc} 
\usepackage[utf8]{inputenc}

\usepackage{bibleref}

\begin{document}

Here a reference in the text which works: \bibleverse{Gn}(1:1-3)

\section{Here a reference within a title: \protect\bibleverse{Gn}(1:1-3) }

\begin{table}
\caption{Here a reference within a caption: \protect\bibleverse{Gn}(1:1-3) }
\end{table}

\end{document}

---

Explanation

As there is already a great and very detailed answer here (What is the difference between Fragile and Robust commands?) by @mpg, I'll try my luck with a not-so-detailed, but hopefully still helpful explanation. In this answer I try to look at it by example rather than the full details. If you want to know more in detail, read the linked answer, or feel free to ask.

The issue is kind of easily addressed (if you can track it down), but the origin is a little technical. The problem can be more easily looked at by observing the auxiliary file that is produced while compiling. It contains, e.g., the section names and captions. This is needed, because you might want to print, e.g., a table of contents (or a table of tables), and the section names (or caption names) have to be displayed in there as well. So, these sections and captions can occur twice in the same document, in different places. This is why one calls them "moving" commands. The text is copied/"moved" to another place in your document.

Assuming your document is called doc.tex, latex writes a file called doc.aux. When latex writes to this file, it usually expands the macros. If you observe the content of doc.aux, you will see what happens:

Without \protecting the macro, it contains

\relax 
\@writefile{lot}{\contentsline {table}{\numberline {1}{\ignorespaces Here a reference within a caption: \let \@bv@restore \relax \def {}Genesis\let \let \let  \let \def  {\BRbookof }\def \BRbooknumberstyle  \def {\BRepistletothe }\def \BRepistlenumberstyle  \let \@@protect \let \@unexpandable@protect \afterassignment \let \@@protect \edef \BRbooktitlestyle {\BRbookof Genesis}{\BRbooktitlestyle {Genesis}}\let \let \let  \let \let \reserved@d = (\def \par }}{1}}
\@writefile{toc}{\contentsline {section}{\numberline {1}Here a reference within a title: \let \@bv@restore \relax \def {}Genesis\let \let \let  \let \def  {\BRbookof }\def \BRbooknumberstyle  \def {\BRepistletothe }\def \BRepistlenumberstyle  \let \@@protect \let \@unexpandable@protect \afterassignment \let \@@protect \edef \BRbooktitlestyle {\BRbookof Genesis}{\BRbooktitlestyle {Genesis}}\let \let \let  \let \let \reserved@d = (\def \par }{1}}

This "gibberish" you see here is the expanded \bibleverse macro, i.e., how it is defined. In contrast to the \protected version:

\relax 
\@writefile{lot}{\contentsline {table}{\numberline {1}{\ignorespaces Here a reference within a caption: \bibleverse {Gn}(1:1-3) }}{1}}
\@writefile{toc}{\contentsline {section}{\numberline {1}Here a reference within a title: \bibleverse {Gn}(1:1-3) }{1}}

You might notice that the \protect actually does what it's named after. It protects the following macro from expansion. This is needed, as this auxiliary file is read in again to display, e.g., the toc.

In short, you need to preserve the original macro without expansion in order to make it work.

Robust commands

Instead of protecting every \bibleverse in a moving command, as @Mico pointed out, you can follow a different path: Making the macro "robust". This actually makes the macro "self-protecting", so you don't need to take care of it manually.

To make a macro robust, you can use \robustify{\macro} provided by the etoolbox package:

\documentclass[a4paper]{article}
\usepackage[T1]{fontenc} 
\usepackage[utf8]{inputenc}
\usepackage{etoolbox} % provides the \robustify command

\usepackage{bibleref}
\robustify{\bibleverse} % makes \bibleverse work in sections and captions

\begin{document}

Here a reference in the text which works: \bibleverse{Gn}(1:1-3)

\section{Here a reference within a title: \bibleverse{Gn}(1:1-3) }

\begin{table}
\caption{Here a reference within a caption: \bibleverse{Gn}(1:1-3) }
\end{table}

\end{document}

This works as well, and you don't have to take care of every occurence in a caption or section. Whether you should cite (frequently) in a section title or not... Well that's another topic, but by "robustifying" the \bibleverse macro, you're free to do it without having to \protect it manually.

Thanks @Mico for that nice and helpful comment :)