latex output: description lists and `lstinline'

[ft]

When writing description lists in markdown such as this:

`--foo` **BAR**

:   Enables the foo feature with **BAR** as its flavour.

...and you use the latex (or pdf) writer backends with the --listings option, you'll get \lstlinline within \item[...] which doesn't work without additional workarounds (i.e. the part within \item[...] disappears or sometimes appears in an entirely different place).

Hence, I'd propose to use \texttt{...} instead of \lstinline within \item[...] even if the --listings option is used.

To reproduce the issue, use the document body from above and call pandoc like this:

% pandoc --listings -o foo.pdf foo.mdwn

This is with pandoc 1.10 (actually a build from git, that is a week or two old) and pdfTeX 3.1415926-2.4-1.40.13 (TeX Live 2012/Debian).

[jgm]

I'm not keen on the idea of adding lots of complexity to the writer to specially handle lstinline in all of the various contexts in which it blows up. (And why not just use pandoc's own highlighting capabilities, which can be customized as you like by redefining the macros highlighting-kate uses?) It's probably better to handle the problem with solutions like this: http://tex.stackexchange.com/questions/93944/using-lstinline-inside-a-item

[jwr]

Instead of opening another issue I will add a comment here.

There are many reasons why one might not want to use \lstinline. Some have been shown here — my reason is different. It sometimes makes sense to use different fonts for code listings and for code strings that are inline with the text. As an example, code listings usually need to be monospaced, while inline code strings do not. You can get very good results using a font like "Input Mono" for code listings and "Input Sans" for inline code strings.

Also, one sometimes needs the listings to be set in slightly smaller font. As it is now, doing this will cause the inline code strings to be awkwardly different from the rest of the text they are in line with. I am at a point right now where I can either have listings that look bad (are too large), or paragraphs that look bad (inline code strings will be too small).

So, there are many reasons for an option to use \texttt{} even when one uses --listings.

[jwr]

Actually (responding to myself here) — this is a much more important issue than I previously thought. The problem with \lstinline is that is does not support UTF-8. The whole listings package is limited to 8-bit data.

The (rather disastrous) result is that you get --images-directory ś[żcieka] instead of --images-directory [ścieżka] in your text and there is no workaround other than manually removing all non-ASCII characters.

For non-english documents this is a significant problem. While it is workable within code listings, replacing \texttt{} with \lstinline is a bigger problem than it might seem.

[jwr]

I'm not sure if this issue is understood. I think it deserves more attention than it currently gets. To rephrase: currently Pandoc produces corrupted output if --listings is used. Not just in code listings, in document text.

\lstinline should not be used, because it breaks with UTF-8.

[jgm]

@jwr If, as you say, the whole listings package is limited to 8-bit data, then I don't see how avoiding \lstinline in favor of \texttt would really help -- we'd still have problems with code blocks. Why shouldn't we just add the following advice to the README: If your code is non-ASCII, don't use --listings?

[jwr]

@jgm well, that's throwing out the baby with the bathwater. If you have UTF-8 in your text, you likely write in a language other than English, and yet most (if not all) code gets written in English. That is a pattern I see in all companies I know of.

Hence, --listings is still very useful, as it produces beautifully formatted code listings. It's just the forced use of \lstinline that is the problem.

[jgm]

+++ Jan Rychter [May 19 15 09:55 ]:

@jgm well, that's throwing out the baby with the bathwater. If you have UTF-8 in your text, you likely write in a language other than English, and yet most (if not all) code gets written in English. That is a pattern I see in all companies I know of.

Hence, --listings is still very useful, as it produces beautifully formatted code listings. It's just the forced use of \lstinline that is the problem.

So, then, your objection to \lstinline has nothing to do with UTF-8?
(Because that objection extends to code blocks as well.)
Is it just about code size and styling?

[jwr]

@jgm My objection to \lstinline is exactly (and only) because of UTF-8.

I also point out a frequent use case (which happens to be my case, too): documentation with UTF-8 and code without UTF-8. My code listings only contain ASCII, as they are in English, but the rest of my document is in Polish. So I do want --listings, just without the forced use of \lstinline.

You seem to think that if one uses UTF-8 in documents, one also has code blocks with UTF-8, which is actually not necessarily the case.

[nkalvi]

@jwr I'm familiar neither Polish nor LaTex, but just trying to understand the issue - so please pardon me if I'm completely off.

I used your example, --images-directory [ścieżka], which is output by Pandoc as --images-directory ś[żcieka] with pandoc --listings --latex-engine=xelatex.

After seeing a similar issue here
http://stackoverflow.com/questions/1116266/listings-in-latex-with-utf-8-or-at-least-german-umlauts
I tried the one of the suggestions (by GDR for Polish language) there and it seems to work:

foo.txt

\lstset{literate={ą}{{\k{a}}}1 {ł}{{\l{}}}1 {ń}{{\'n}}1 {ę}{{\k{e}}}1 {ś}{{\'s}}1 {ż}{{\.z}}1 {ó}{{\'o}}1 {ź}{{\'z}}1 {Ą}{{\k{A}}}1 {Ł}{{\L{}}}1 {Ń}{{\'N}}1 {Ę}{{\k{E}}}1 {Ś}{{\'S}}1 {Ż}{{\.Z}}1 {Ó}{{\'O}}1 {Ź}{{\'Z}}1 }

`--images-directory [ścieżka]`

Output with pandoc --listings -o foo.pdf foo.txt:

Would something similar be a viable solution for you?

[jgm]

I don't ever use --listings, so the proposed change -- using \texttt instead of \lstinline -- wouldn't affect me. But I'm reluctant to make the change, since some users who do use --listings may want \lstinline. @jwr I recommend you ask on pandoc-discuss whether anyone would object if --listings didn't use \lstinline for inline code. If nobody objects, I'd be willing to make the change. But it does still seem to me that it's going to be a fairly rare case where you have non-ASCII in code spans, but not in code blocks.

[jgm]

I don't think this discussion ever occurred, and I'm not going to make the change without it, so closing for now.

[jgm]

Reopening, not for the unicode issue, but for the disappearing stuff issue.
We can fix that by using texttt if in an \item[...] context.

[lamyergeier]

I concur that this modification would be useful as can be seen here:

# Temp.md
Edit Configuration: `sudo nano /etc/default/grub`

pandoc Temp.md -s -o Temp.tex
pandoc Temp.md -o Temp.pdf
pandoc Temp.md --listings -s -o TempListing.tex
pandoc Temp.md --listings -o TempListing.pdf

[lamyergeier]

@jgm Please support \texttt{...} instead of \lstinline as no one in the pandoc-discuss objected.

[jgm]

Anish Mittal <notifications@github.com> writes:

@jgm Please support `\texttt{...}` instead of `\lstinline` as no one in the `pandoc-discuss` objected.

I'm not sure your message was clear enough for people to know what the proposal was. Also, I would like to hear more about your motivations. Is it because you have non-ascii characters in your inline code spans, but not in code blocks? As I point out above, this seems quite an unusual case to optimize for.

[Agarwal-Nikhil]

I don't have a strong motivation. But we can observe (in the following) that in the --listings case the monospace fonts are not getting rendered.

# Temp.md
Edit Configuration: `sudo nano /etc/default/grub`

pandoc Temp.md -o Temp.pdf
pandoc Temp.md --listings -o TempListing.pdf

[jgm]

LaTeX listings doesn't use monospace fonts generally, unless you tell it to. Why are you using --listings in the first place? Just don't use it, and you'll get a monospaced font.

[mbanck]

So I decided to use a smaller font for codeblocks via \lstset{basicstyle=\footnotesize\ttfamily in order to get more of them on a page.

Now as soon as I use --listings, all my inline texttt snippets are suddently rendered in a smaller font. Is there at least a way to override/work around this, if it is not considered a bug?

[DanielGibson]

When I convert Markdown to Tex or PDF, I'd like it to use \texttt for `inline code` and listings for full code blocks (enclosed in ```).