We’ve all read the TeX FAQ and know that commands and environments for verbatim text are LaTeX’s revenge for being free and still give you the top-notch typography you get with it. Like not to use them in the definition of new commands or environments blindly.
But recently I discovered another pitfall with verbatim text, this time in packages that want to improve the vanilla LaTeX verbatim functionality, namely fancyvrb and listings. But let me give the story how it all happened.
One stormy night, I sat at home fearing for my life and with the grim reaper on my doorstep (so I thought), it seemed like a noble last deed to do something that would last. Something that would spark spontaneous outbursts of devotion in future generations whenever they see what one of their herculean ancestors had achieved – me.
So that night I decided to improve the LaTeX-backend of AsciiDoc, after a very frustrating experience with the toolchain of DocBook. I know what you think now. Something along the line of „after all those years with MS Word around him, the poor lad still hasn’t realized that no good ever comes from anything DOC“. And you’re right, I should have known, but I didn’t.
So, in my panic-induced hubris (remember the storm outside my home?) I started to dig into AsciiDoc’s latex.conf that drives the backend with templates and macros. But soon my initial verve was cooled down, as I came to see that there is no obvious way to get newlines directly in front or after the text that comes from the template match on the AsciiDoc input. Well, what’s bad about that? Who needs human-readable .tex files as long as LaTeX can handle it, right? Right. And that’s the problem here.
The verbatim extensions I tried first (fancyvrb and listings; in that order) might save you from some of the shortcomings of plain verbatim. But they don’t save you from the following two when using the environments they provide:
- You can’t have the verbatim text begin on the same line as the \begin{environment} command.
- You have to start the next paragraph after the environment with a blank line. Just \par on the next line (or the same; makes no difference) won’t work.
I’m still not certain which of the two cost me more nerves, but my guess is that it was the first one (as the verbatim text is ignored and nothing appears in the typeset output). The second one by contrast is quite visible, as the entire paragraph following the verbatim environment is set in the monospaced font of the environment. Still weird enough.
The second one was also the easy one to cure, you can always cram an empty line into the output, (ab)using a LaTeX comment. Mail me if you want to know the gory details 🙂
But the first one was quite a challenge. Figuring out what the problem really was took quite a while. And then how to search for it on the web? „LaTeX begin verbatim same line“ – too unspecific, I thought. But I gave it a go, and one of the first results was the documentation of the verbatim package. It said something about text on the same line as \end{verbatim}. Although that was the problem already solved, I checked the package out. Don’t ask me why I didn’t try it earlier. I just didn’t.
I was in for a surprise. Text on the same line as \begin{verbatim} comes out as verbatim text using the verbatim package! I don’t know if this is a bug or a feature (but you never know); as long as it works – fine with me.
What have I learned?
- If you think you know LaTeX in and out, you’re most likely wrong.
- Read all the documentation you can get, even if it seems only remotely related to your problem.
- Don’t let storms drive you to noble deeds. They just want to test you.
Andreas Hermann Bramls Blog 