Skip to content

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