Skip to content

Refactor highlighting methods#11042

Merged
jgm merged 3 commits intojgm:mainfrom
tarleb:refactor-highlighting
Sep 2, 2025
Merged

Refactor highlighting methods#11042
jgm merged 3 commits intojgm:mainfrom
tarleb:refactor-highlighting

Conversation

@tarleb
Copy link
Collaborator

@tarleb tarleb commented Aug 11, 2025

No description provided.

@tarleb tarleb force-pushed the refactor-highlighting branch from 9b221f8 to 26c6c15 Compare August 11, 2025 17:14
@jgm
Copy link
Owner

jgm commented Aug 11, 2025

Can you describe more fully the motivation for the change?

Are there any formats besides LaTeX for which idiomatic makes sense? Typst?

Even for LaTeX, one might wonder about idiomatic; after all, listings is an external package, and it isn't the only external highlighting package for LaTeX: there is also pygments, for example, which calls out to the Python program.

@tarleb
Copy link
Collaborator Author

tarleb commented Aug 11, 2025

Sorry, I forgot to link to the relevant issue: #10525.

The motivation is indeed to allow users to choose between Typst's native highlighter and highlighting through Skylighting.

@tarleb tarleb force-pushed the refactor-highlighting branch 2 times, most recently from afc7b6b to db45066 Compare August 11, 2025 17:58
@tarleb tarleb marked this pull request as ready for review August 11, 2025 18:00
@jgm
Copy link
Owner

jgm commented Sep 2, 2025

Does doc/pandoc-server.md also need updating?

@tarleb
Copy link
Collaborator Author

tarleb commented Sep 2, 2025

Oh, I forgot about that. In fact, I even forgot to update the main manual. Fixing...

@tarleb
T.P.Highlighting: export defaultStyle [API Change]
efcadbb 
This allows to be more explicit about using a default style, and
providing a single point of truth for its value. The variable is an
alias for `pygments`.
@tarleb tarleb force-pushed the refactor-highlighting branch from db45066 to 67d6b95 Compare September 2, 2025 12:21
jgm
jgm reviewed Sep 2, 2025
View reviewed changes
MANUAL.txt Outdated
Comment on lines +1984 to +2014
| --no-highlight | highlight-style: null |
| --no-highlight | syntax-highlighting: null |
Copy link
Owner

@jgm jgm Sep 2, 2025

Choose a reason for hiding this comment

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

Curious about this: does "none" work too? If not, might this be an unexpected divergence between cli and defaults file behavior?

Copy link
Collaborator Author

@tarleb tarleb Sep 2, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

Oh, that was a typo; it was meant to say none. But yes, that works, too.

Copy link
Collaborator Author

@tarleb tarleb Sep 2, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

'none', null, and false all turn off syntax highlighting.

@tarleb
T.P.Options: add type HighlightMethod and patterns [API Change]
82840d0 
The Text.Pandoc.Options module exports the `HighlightMethod` data type
and it's constructors. Furthermore, three pattern synonyms are exported,
`NoHighlightingString`, `DefaultHighlightingString`, and
`IdiomaticHighlightingString`, which hold the string value that's used
for decoding and encoding of HighlightMethod values.
@tarleb tarleb force-pushed the refactor-highlighting branch from 67d6b95 to 68adff0 Compare September 2, 2025 14:57
@tarleb
Refactor highlighting options [API Change]
8ddd04f 
A new command line option `--syntax-highlighting` is provided; it takes
the values `none`, `default`, `idiomatic`, a style name, or a path to a
theme file. It replaces the `--no-highlighting`, `--highlighting-style`,
and `--listings` options.

The `writerListings` and `writerHighlightStyle` fields of the
`WriterOptions` type are replaced with `writerHighlightStyle`.

Closes: jgm#10525
@tarleb tarleb force-pushed the refactor-highlighting branch from 68adff0 to 8ddd04f Compare September 2, 2025 14:58
@jgm jgm merged commit e0acb24 into jgm:main Sep 2, 2025
11 of 14 checks passed
@tarleb tarleb deleted the refactor-highlighting branch September 2, 2025 17:14
@cderv cderv mentioned this pull request Sep 4, 2025
Closed
@hseg
Copy link
Contributor

hseg commented Sep 9, 2025

Is the commit message supposed to read

The writerListings and writerHighlightStyle fields of the WriterOptions type are replaced with writerHighlightMethod.

? This affects the changelog as well -- took a moment for me to figure out the
migration.

@hseg hseg mentioned this pull request Sep 9, 2025
Closed
1 task
@tarleb
Copy link
Collaborator Author

tarleb commented Sep 9, 2025

Yes, exactly. Sorry, my bad.

jgm added a commit that referenced this pull request Sep 10, 2025
@jgm
Changelog fix for #11042.
6d6ab8c 
See #11042 (comment)
@hseg
Copy link
Contributor

hseg commented Sep 10, 2025

Noting this here for future readers, given 6d6ab8c points here: the change to writerHighlightMethod also changes the type of the first argument (as is signalled by the change in name). In particular, we have the following rewrite:

writerHighlightStyle = writerHighlightMethod . maybe NoHighlighting Skylighting

(if you're consuming a highlight style, I can't give automatic advice, as this PR has added extra constructors to HighlightMethod)

@hseg
Copy link
Contributor

hseg commented Sep 10, 2025

Ah, and I missed the writerListings deprecation, which becomes

writerListings = writerHighlightMethod . IdiomaticHighlighting

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@jgm jgm jgm left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@tarleb @jgm @hseg