Fixing :emphasized-lines: in PDF output

[David H]

Hi all -

I posted this first on sphinx-users, but now realized I should have posted it here on sphinx-dev instead.

I am writing (actually re-writing) a beginning Python programming textbook using Sphinx. It is important to me to have highlighted lines of code in both HTML and PDF output format.

Apparently :emphasized-lines: has been broken in PDF output for quite some time, there is a ticket for it here: https://github.com/sphinx-doc/sphinx/issues/1238

This is important enough to me that I'd like to help fix it. I'm an experienced Python developer, new to Sphinx, and not comfortable with latex.

Questions:

Is anyone else working on this, or thinking of working on this?

What help or at least advice can you give me to get started on this?

Thanks,
David H

[Bram Geron]

On Friday, 18 December 2015 14:49:04 UTC+1, David H wrote:

This is important enough to me that I'd like to help fix it. I'm an experienced Python developer, new to Sphinx, and not comfortable with latex.

Great! 

 

Questions:

Is anyone else working on this, or thinking of working on this?

I expect not.

 

What help or at least advice can you give me to get started on this?

I've looked around a bit, and it seems that Sphinx calls[1][2] Pygments for both parsing and formatting to HTML and LaTeX. The Pygments HtmlFormatter checks[3] if the hl_lines attribute is set (in which case it should be a list of line numbers); if it is, the HTML output is postprocessed[4]. There is a similar writer for LaTeX but the highlight wrapper is missing, as is duly noted in the source[6]. Wikipedia gives an example of how to add a background color in LaTeX[5]. I have hand-patched the output of Sphinx using colorbox, and the result looks decent, although there is a bit of a shift to the right, which you can compensate for with a negative-width space (\!). I have given an example in [7]. 

Hope that helps; let us know if you get stuck!

Cheers, Bram

[1]: https://github.com/sphinx-doc/sphinx/blob/4234c88f21f7f2a120a8d3df8aea1244ee8e2986/sphinx/writers/latex.py#L1712

[2]: https://github.com/sphinx-doc/sphinx/blob/4234c88f21f7f2a120a8d3df8aea1244ee8e2986/sphinx/highlighting.py#L185

[3]: https://bitbucket.org/birkenfeld/pygments-main/src/142a870bf0f1822414649ae26f433b112a5c92d5/pygments/formatters/html.py?at=2.0.2&fileviewer=file-view-default#html.py-823

[4]: https://bitbucket.org/birkenfeld/pygments-main/src/142a870bf0f1822414649ae26f433b112a5c92d5/pygments/formatters/html.py?at=2.0.2&fileviewer=file-view-default#html.py-778

[5]: https://en.wikibooks.org/wiki/LaTeX/Colors#Entering_colored_background_for_the_text 

[6]: https://bitbucket.org/birkenfeld/pygments-main/src/142a870bf0f1822414649ae26f433b112a5c92d5/pygments/formatters/latex.py?at=2.0.2&fileviewer=file-view-default#latex.py-332

[7]: https://gist.github.com/bgeron/6b0fd37124ab91843fee

[David H]

Thank you Bram for the good advice to get me started.

Since this appears to be a pygments enhancement, I went ahead and filed pygments ticket for this: https://bitbucket.org/birkenfeld/pygments-main/issues/1187/add-line-highlighting-to-latex-formatter

If all goes well, I'll follow up with a pygments pull request.

Thanks again,
David H

[Bram Geron]

Thanks, and good luck :)

Cheers, Bram