Some issues with code example coloring

[Aaron Meurer]

The code examples that use verbatim currently aren't colored. If we use minted, as is already done in the physics section, they are colored. There are some issues, though.

• Single quotes are rendered as ’ instead of '. This not only looks bad, but it makes it so that you can't copy and paste any code that has them. Double quotes appear to render correctly.

• The colors aren't very good. In particular, the output is formatted in gray. It should be formatted in black. Based on http://pygments.org/demo, none of the built in pygments styles do this, so we'll probably have to create a custom one. IMO the default colors are also way too colorful, putting a different color on every possible symbol and making things appear way too colorful and distracting.

• I'm sceptical whether the journal would be able to build the paper with minted correctly, and especially with minted and a custom pygments style (I'm a little unclear how to even do this. I see how to create a custom style, but is the only way to use it to literally require it to be installed first? Can we install a style by adding some directly to PYTHONPATH when building?).

  I think a better solution would be to generate the examples with pygments using its ability to output to tex (like pygmentize -f latex source.py). This way we would have pure tex to send to the journal, and the complexities of coloring the code would be up to us.

  As a side effect, all the examples would be in separate py files, which would make them more difficult to maintain, but also easier to doctest.

• It's a minor issue, but if you switch all the code examples from verbatim to minted the document takes much longer to build (over a minute for make to run).

Any other suggestions? Does anyone know how to fix the quote issue?

Another option would be to not syntax highlight at all, which I'm actually fine with.

[Aaron Meurer]

I guess another way would be to render the >>> parts using minted and the output using verbatim.

[Aaron Meurer]

Possible fix for quotes https://stackoverflow.com/questions/1662037/how-to-write-programming-code-containing-the-character-in-latex

[Aaron Meurer]

So upquote works for verbatim, but not for minted. I suggest removing minted support, unless we can figure out how to do it well.

[Jason K. Moore]

Some comments:

• The single quote are an outstanding issue. When I last looked into it I vaguely remember determining that it was a LaTeX issue (not minted) and did the same thing in verbatim and listings environments. I've just let this one go in the past in favor of having syntax highlighting because having syntax highlighting outweighs the fact that the quote looks a little odd. Here is a potential solution: http://tex.stackexchange.com/questions/46880/in-the-minted-package-how-do-i-enforce-straight-single-quotes, they also mention that XeTeX and LuaTex give the correct quote.
• Colors: we should be able to choose a color style.
• Journal building the paper: I've never had a journal ask to build the paper. Someone needs to ask the journal what the requirements are. Most journals (note I've never published in a CS journal) just accept pdfs and word docs. For example, PLoS converts LaTeX generated pdfs to word docs and then sends it through their word doc processing system. This isn't our problem. The journals cost money and editing/formatting are one of the things we are paying for. My opinion is to give them the result we want to present and let them figure it out. We don't have to spend time on worrying about if the journal can build the paper or not.
• Build time: what does it matter what the build time is if we get the result we want?

[Jason K. Moore]

I think a better solution would be to generate the examples with pygments using its ability to output to tex (like pygmentize -f latex source.py). This way we would have pure tex to send to the journal, and the complexities of coloring the code would be up to us.

This sounds reasonable.