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

console lexer (BashSessionLexer) fails with quotes inside comments #1598

Closed
j1elo opened this issue Nov 10, 2020 · 3 comments
Closed

console lexer (BashSessionLexer) fails with quotes inside comments #1598

j1elo opened this issue Nov 10, 2020 · 3 comments
Milestone

Comments

@j1elo
Copy link

@j1elo j1elo commented Nov 10, 2020

Hi, I'm facing failures from Pygments while trying to build my project's documentation with Sphinx; after some analysis I discovered that the issue comes from single quotes (') being used within comments.

A block such as this one causes the issue:

.. code-block:: console

   # My project's build script
   echo "Hello World"

the code-block will try to parse its contents with the console lexer from Pygments, which fails:

WARNING: Could not lex literal_block as "console". Highlighting skipped.

Removing the single quote solves the issue:

.. code-block:: console

   # My projects build script
   echo "Hello World"

Pygments and Sphinx versions:

$ pip3 freeze | grep -i -e sphinx -e pygments
Pygments==2.7.2
Sphinx==3.3.0

I searched for "console" and "console quote" and couldn't find an already existing bug so I'm opening this one. Sorry if this is a duplicate (I somehow believe this bug must have been reported already, using a single quote in simple-form English comments seems too much of a common use case to have this bug unnoticed... but I haven't found anything)

j1elo added a commit to Kurento/doc-kurento that referenced this issue Nov 10, 2020
This is needed because the Pygments lexer (used by Sphinx) has a bug and
fails to parse the code blocks that use quotes, it doesn't matter if
they arejust in comments.

Pygments issue: pygments/pygments#1598
@j1elo
Copy link
Author

@j1elo j1elo commented Nov 10, 2020

The linked commit (d368202) shows the real situation where I hit this issue.

Loading

@birkenfeld
Copy link
Contributor

@birkenfeld birkenfeld commented Nov 11, 2020

Hey @j1elo, the console lexer is meant for cases where you include shell prompt, command and output, e.g.

# ls -l
total 128
-rw-r--r-- 1 gbr gbr  8816 Oct 24 21:54 AUTHORS
-rw-r--r-- 1 gbr gbr 40808 Oct 24 21:54 CHANGES

The # at the start of a line here is recognized as a common prompt (for the root user), not as a comment sign.

If you're presenting pure shell code, you should use one of the shell lexers, usually bash.

Loading

@j1elo
Copy link
Author

@j1elo j1elo commented Nov 11, 2020

Hey @j1elo, the console lexer is meant for cases where you include shell prompt, command and output, e.g.

# ls -l
total 128
-rw-r--r-- 1 gbr gbr  8816 Oct 24 21:54 AUTHORS
-rw-r--r-- 1 gbr gbr 40808 Oct 24 21:54 CHANGES

The # at the start of a line here is recognized as a common prompt (for the root user), not as a comment sign.

If you're presenting pure shell code, you should use one of the shell lexers, usually bash.

Oh my, that means I was very wrong about the intended use case of console! (I've been using it all across the docs for everything related to a console... both command samples and shell code).

The way I see it, this grants then a "documentation" bug in the sense that the docs are really too bare and somewhat confusing. I'll open a couple new issues wrt. to this topic, and close this one in a couple of days (just in case some more insightful comments happen to arrive).

Loading

@j1elo j1elo closed this Nov 12, 2020
j1elo added a commit to Kurento/doc-kurento that referenced this issue Nov 12, 2020
Folloup from d368202

We learn from pygments/pygments#1598 that the
"console" lexer is actually meant for blocks that present a shell
prompt, a command, and some result:

$ command
result

However we were using this block type as general purpose command
descriptions, which should instead be changed to "shell" type.

For symmetry, those blocks which actually contained prompt + command +
output are renamed from "console" to the equivalent "shell-session".
@Anteru Anteru added this to the 2.7.3 milestone Nov 13, 2020
j1elo added a commit to Kurento/doc-kurento that referenced this issue Nov 13, 2020
Folloup from d368202

We learn from pygments/pygments#1598 that the
"console" lexer is actually meant for blocks that present a shell
prompt, a command, and some result:

$ command
result

However we were using this block type as general purpose command
descriptions, which should instead be changed to "shell" type.

For symmetry, those blocks which actually contained prompt + command +
output are renamed from "console" to the equivalent "shell-session".
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
3 participants