Skip to content

lib/gis: Fixes issues parsing YAML special characters in MkDocs #5907

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

Open
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

cwhite911
Copy link
Contributor

YAML 1.2 special characters are not getting escaped by parser_md.c. These characters are causing errors in the markdown documentation. You can look at r.regression.line as an example.

To address this I've enclosed the the text in quotes to resolve any issues with special characters.

@echoix
Copy link
Member

echoix commented Jun 17, 2025

See #5841 for the proper fix for the complete class of these issues, it was discussed there.

There might still be some problems with a colon followed by spaces. Even ruff's doc had to adapt to this.

@github-actions github-actions bot added C Related code is in C libraries labels Jun 17, 2025
@wenzeslaus
Copy link
Member

Maybe we can use parson to serialize the string and then write that to YAML. We have Python code which parses and then again writes this without a YAML dependency, so it might be good read and write it there with JSON too.

It is not clear to me what are the nuances of YAML double quotes strings and JSON strings, but they are close.

https://yaml.org/spec/1.2.2/#731-double-quoted-style

Nevertheless, in r.mask.status, I decided to write YAML manually and, if I recall correctly, the only way how to do it in a safe way is with the string on a new line as @echoix suggests.

@echoix
Copy link
Member

echoix commented Jun 21, 2025

Just a crazy idea just like that... If I remember the markdown standard correctly, the front matter (the metadata at the top) can be an arbitrary language, but we often see yaml.

Would mkdocs be able to understand and use json front-matter? If so, we could use parson directly to create our output and avoid this. At least for the generated pages
for the modules.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
C Related code is in C libraries
Projects
Status: In Progress
Development

Successfully merging this pull request may close these issues.

3 participants