Byron / Byron/pulldown-cmark-to-cmark

Simplify backslash escapes where possible

Open
#60 2 comments 0 reactions 0 assignees View on GitHub
enhancement help wanted
Dominant language
Rust
Stars
63
Forks
46
PR merge metrics
No merged PRs in 30d

Description

Hi @Byron!

An issue was opened in the mdbook-i18n-helpers crate about how we treat backslashes in the translations: https://github.com/google/mdbook-i18n-helpers/issues/105.

As you might recall, the tooling there works by

- parsing Markdown text -> Markdown AST
- find translatable text in the AST
- turn the AST nodes into Markdown text (using this crate)
- translate this text and turn it into Markdown AST again

The third step here turns a Markdown file with

```markdown
\x
```

into

```markdown
\\x
```

This is completely valid! According to [Backslash escapes](https://spec.commonmark.org/0.30/#backslash-escapes), `\\x` and `\x` both mean backslash-x (2 bytes).

However, I can see how it could be confusing to people and tools which rely on a lot of backslashes, e.g., for LaTeX math like `$\sqrt{\frac{1}{x}}$`. Here, the translator will end up seeing the escaped backslashes: `$\\sqrt{\\frac{1}{x}}$` because that is what we get back when we serialize the Markdown AST into Markdown text. It would be easier to work with the unescaped backslashes in this case.

So I'm proposint that pulldown-cmark-to-cmark would emit the simplest escaped form for an escaped character.

Contributor guide

Open the contributing guide

Research direction

Start by tracing the Markdown serialization path that handles backslash escapes, then reproduce the issue with `\x` and the LaTeX example from the report. Done means escaped characters are emitted in the simplest valid form while preserving the parsed Markdown meaning.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
tooling
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.