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

Clarifying some documentation #1928

Merged
merged 4 commits into from
Dec 6, 2021
Merged

Conversation

Arthur-Milchior
Copy link
Contributor

While reading Pygments documentation, there were parts that confused me. That
required that I read the code to understand them. I hope that this contribution
will help clarify for future readers.

I do not know pygments usage. I have chosen to do atomic commits so that if you agree that some commits are an improvement and others need more work, we can cherry pick the good one.

@simplefilter is great, but also not very intuitive. Indeeds, the syntax seems
to indicate that you define a function with four arguments while in reality you
define a class whose constructor takes arbitrary keyword arguments. I believe in
this case an example to show how to instantiate this filter is really necessary.

Regarding simplefilter, I also believe that it could be improved in two simple
ways:
* accepting any method which takes lexer and stream as a filter. That would be
  sufficient as long as there is no option
* the @simplefilter decorator could deal with `self` so that the user do not
  have to add it themselves. Probably not worth doing it no, as it would break
  compatibility with current version, but would be even simpler to use
get_bool_opt's documentation seems to indicate that the key is interpreted as a
Boolean. While a quick look at the code shows clearly that the value associated
to the key is what is interpreted as a Boolean. I hope I made the code clearer
to any people who know python by indicating that it is essentially `.get` but
with extra features
`filter` has already a specific behavior in general python, or for any people
used to functional programing (and even if some dom processor). So indicating
that a filter is not something that remove some tokens seems really useful to
try to explain what is going on.
I found the state explanation confusing. I do know what a state machine
is. However, reading the code, I first thought that there were two distinct
variables:
* the current state
* the stack

that are somehow related but distinct. Explaining that the current state is the
top of the stack was lacking in my opinion. That also help explain #push. In
particular that if you define in state "s" an operation whose new state is
"#push", the behavior can be quite different than if the new state was "s".
@Anteru Anteru changed the title Clarifying somme documentation Clarifying some documentation Nov 6, 2021
@Anteru Anteru self-assigned this Nov 6, 2021
@Anteru Anteru merged commit 73b77d5 into pygments:master Dec 6, 2021
@Anteru
Copy link
Collaborator

Anteru commented Dec 6, 2021

Merged, thanks!

@Anteru Anteru added this to the 2.11.0 milestone Dec 6, 2021
@Arthur-Milchior Arthur-Milchior deleted the comments branch December 8, 2021 21:43
Copy link

@00251911391303 00251911391303 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Muhamed

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants