Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix #4249 by overriding Pygments latex formatter error highlighting #4250

Merged
merged 1 commit into from
Dec 10, 2017

Conversation

jfbu
Copy link
Contributor

@jfbu jfbu commented Nov 20, 2017

Relates

If an option is provided for Sphinx not to use raiseonerror Pygments filter, then issue #4249 needs a fix. This PR provides it.

@jfbu jfbu added this to the 1.6.6 milestone Nov 20, 2017
@jfbu jfbu merged commit 0febbc5 into sphinx-doc:stable Dec 10, 2017
jfbu added a commit that referenced this pull request Dec 10, 2017
@jfbu jfbu deleted the 4249_errhighlight branch December 11, 2017 20:53
jfbu added a commit to jfbu/sphinx that referenced this pull request Dec 30, 2017
This goes for the quick solution, hence uses the pre-existing
architecture underlying the `\PYG` macro from the Pygments
highlighting code.

Each domain can add its own style to LaTeX by defining suitable macro
for supporting css styles.

For example, here we added

    \@namedef{PYG@tok@k-cpp}{%
         \def\PYG@tc##1{\textcolor[RGB]{0,0,"FF}{##1}}%
    }%

to sphinx.sty to emulate the CSS

    code.k-cpp {
        color: #0000FF;
    }

(previous commit uses `#0000AA` but I chose `#0000FF` for better seeing
things...)

For a fully developed example all the `\@namedef` would be in some
`sphinxcpp.sty` style file and either the document will do
`\usepackage{sphinxcpp.sty}` or `sphinx.sty` will do
`\RequirePackage{sphinxcpp.sty}`. The user could override this file via
`latex_additional_files`.

In absence of such file, the macro definitions will be lacking but this
will raise no error. For the example here (from last commit message) the
latex output contains

    \PYG{d+k+k-cpp}

and the `\PYG` macro nests "action of d(of k(of k-cpp...)))". Turns out
that Pygments already has some macro for "k", which uses bold face (as
can be seen in PDF output) and changes the text color, but has "k-cpp"
is deeper nested it is executed last and sets the good text color.

Thus it would perhaps be better if the latex writer produces something
like

    \PYG{cssd+cssk+cssk-cpp}

to avoid name clashes with Pygments pre-defined styles. Or here it is OK
that "k" is styled boldface by Pygments in LaTeX.

Important: class names must not contain the `+` character which is use
by Pygments LaTeX code as separator.

There are some issues in the Pygments code with the scope of some
changes; this is already corrected by Sphinx (refs: sphinx-doc#4250), but some
more scrutiny is perhaps needed because so far the Pygments code is
exercised only inside Verbatim environments where each code-line is a
scope in itself so border effects do not propagate, hence I have not
checked closely the Pygments LaTeX code, but perhaps sphinx-doc#4250 fixes already
all problems.
jfbu added a commit to jfbu/sphinx that referenced this pull request Dec 30, 2017
This goes for the quick solution, hence uses the pre-existing
architecture underlying the `\PYG` macro from the Pygments
highlighting code.

Each domain can add its own style to LaTeX by defining suitable macro
for supporting css styles.

For example, here we added

    \@namedef{PYG@tok@k-cpp}{%
         \def\PYG@tc##1{\textcolor[RGB]{0,0,"FF}{##1}}%
    }%

to sphinx.sty to emulate the CSS

    code.k-cpp {
        color: #0000FF;
    }

(previous commit uses `#0000AA` but I chose `#0000FF` for better seeing
things... also syntax `\textcolor[HTML]{0000FF}` is possible))

For a fully developed example all the `\@namedef` would be in some
`sphinxcpp.sty` style file and either the document will do
`\usepackage{sphinxcpp}` or `sphinx.sty` will do
`\RequirePackage{sphinxcpp}`. The user could override this file via
`latex_additional_files`.

In absence of such file, the macro definitions will be lacking but this
will raise no error. For the example here (from last commit message) the
latex output contains

    \PYG{d+k+k-cpp}

and the `\PYG` macro nests "action of d(of k(of k-cpp...)))". Turns out
that Pygments already has some macro for "k", which uses bold face (as
can be seen in PDF output) and changes the text color, but as "k-cpp"
is deeper nested it is executed last and sets the good text color.

Thus it would perhaps be better if the latex writer produced something
like

    \PYG{cssd+cssk+cssk-cpp}

to avoid name clashes with Pygments pre-defined styles. Or here it is OK
that "k" is styled boldface by Pygments in LaTeX.

Important: class names must not contain the `+` character which is used
by Pygments LaTeX code as separator.

There are some issues in the Pygments code with the scope of some
changes; this is already corrected by Sphinx (refs: sphinx-doc#4250), but some
more scrutiny is perhaps needed because so far the Pygments code is
exercised only inside Verbatim environments where each code-line is a
scope in itself so border effects do not propagate, hence I have not
checked closely the Pygments LaTeX code, but perhaps sphinx-doc#4250 fixes already
all problems.
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Sep 9, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant