# Listings, Literate Programming, and Beautiful Typography

Now that I'm procrastinating with tweaking LaTeX, instead of finishing my Ph.D. thesis, I'm wondering what's the most beautiful way to typeset source code (C#, C++, LISP, XML, BNF) in LaTeX. Currently, I'm using the listings package, and the literate option, to search&replace some characters with mathematical equivalent symbols, such as:

\lstset{ %
...
literate= {+}{{$+$}}1 {*}{{$*$}}1 {=}{{$\gets$}}1
{<=}{{$\leq$}}1 {>=}{{$\geq$}}1 {!=}{{$\neq$}}1
{==}{{$\equiv$}}1 {=>}{{$\leadsto$}}1
}


Although one can find some inspiration for symbols in CWEB, I'm wondering if there exists any standard symbology for common programming (and domain specific) languages. Or maybe more appropriate packages (btw, I'm not looking for fancy syntax coloring, which would ruin my two-colored document).

Since there was some users concerned if this should be regarded as a good practice, I think this question deserves some further explanation. Overall, I have to both agree and disagree them (and I think a lot of the literate programming community too). Here's when:

1. I absolutely would agree in cases one is writing a book on the language, a tutorial, a recipe, patterns, something where it is intended the reader to try that code on the computer. This can provoke confusion on the reader (where is that <- sign?), and hinder their reading pattern (you know, when you glance at hundreds of lines of code very quickly).
2. But in thesis, papers, and other scientific publications, most of the snippets are illustrative; almost as if they were pseudo-code. Readability is improved, especially because lots of two/three character symbols (which can vary depending on the language) are compressed to a more symbolic notation. Now, it is true that most of you will suggest: "then why don't you you pseudo-code?" Well... First, because the pseudo-code provided by the algorithmic environment is nice for simplifying imperative languages, but it fails for things like LISP, XML and BNF. Second, because it takes a lot of time converting them, and it quickly falls out of sync.

Still, I maintain my original question: "examples of beautiful typography of source code".

-
I am not sure if that is a good idea for the reader. If I see C code with \equiv symbol, I will not be sure what that means. I am not convinced that such conversions add to readability. Regarding syntax highlighting, you can use basic syntax highlighting like bold, italic, underline, and reverse video all in monospaced font....something like the print_bw color scheme for vim. – Aditya Sep 1 '10 at 5:09
Aditya, I've commented upon your concerns in the original post. – Hugo S Ferreira Sep 1 '10 at 13:06
Seriously don't! Look at how code is typeset in academic journals & periodicals and copy that style. In the end of the day you are not writing a typography show-case. In a Ph.D. thesis typography should not distract the reader, instead it should facilitate the reader to crearly see your thought process and methods described in the code snippers. You should not aadd any ambiguity with fancy new symbols you come up with. Experiment with different monospace fonts is all I can suggest in improving your listings. – Dima Sep 3 '10 at 2:09
As a programmer, I'd be distracted if the listing has unfamiliar characters. When I read code, I switch my mind into "code reading mode" and anything alien will disrupt the act of reading the code and I'll start wondering "why is this character here"? Worse, it may give a (false) impression the code is typed as text, instead of being pasted from real, working code. – wishihadabettername Sep 6 '10 at 18:07

When typesetting C code in non-monospaced fonts, I've certainly found the "literate programming" options useful.

What I've used them for is specifying typography for symbol pairs that aren't very readable in the standard non-monospaced font -- not replacing them with a different symbol, but adjusting to make the same symbols more readable. For instance, "--" doesn't look right in Times, so I've used literate={--}{{\texttt{--}} to make that look better.

Meanwhile, when one's using illustrative pseudocode in discussions of algorithms that are detached from details of programming language syntax, I do think it's useful to use non-programming symbols. For one thing, it helps make it clear that what you are writing is not compilable C code -- even if it has a C-like syntax, and is really just C with irrelevant bits removed. (Or Lisp, or whatever.) And, since the "irrelevant bits" are going to vary from discussion to discussion, I haven't found that one specific pseudocode format applies to everything.

-

For the logical operators, it is quite natural to use \not, \and, and \lor.

But in general, I agree with Aditya: the more the used symbol deviates from the actual input, the more likely it is to create confusion. For example, Pascal WEB uses a leftward pointing arrow for assignment (:= in Pascal) and I find that quite confusing, even after years of exposure to it.

-
+1; the only symbol I would find reasonable to replace thus in C would be -> but that's all. – Arthur Reutenauer Sep 3 '10 at 8:46

Sorry to dig this topic, but, meanwhile, I've found a similar thing was done in Emacs for live editing programming languages such as Haskell. Sequences of symbols are replaced by unicode characters, greatly improving readability. The same principle can be applied to LaTeX documents. Here's a link describing how to configure such technique, and here's a screenshot taken from this blog:

Another typical usage is in Literate Haskell, by the lhs2tex tool.

-
Personally, I find it impossible to read code generated by lhs2tex (while I am comfortable reading raw Haskell code). It is almost like a new language with a different syntax. For example, on page 20 of the lhs2tex manual, I understand what <| from Data.Seq, but when I see a typeset \lhd, I need to imagine what it might mean (and it is impossible to search). – Aditya Jun 6 '12 at 15:37
symbolhound.com – Hugo S Ferreira Jun 6 '12 at 16:03
How do I type the typeset output of \lhd in it? For regular Haskell code, Hoogle works fine. – Aditya Jun 6 '12 at 17:32
@Aditya: Confusion is easily averted by including a short symbol table. After that you get both; better typography and clarity. – morbusg Jun 6 '12 at 18:50