docs: make bracketed inline code the default syntax

[mcanouil]

The commits in this pull request update the syntax for inline code in the documentation. The changes include using {r} primarily instead of `r` to denote inline R code. These updates improve consistency in the documentation.

Related to quarto-dev/quarto-cli#10805

[cderv]

Thanks.

Why do you think using {r} is more consistent ?

It has been asked already in

• Notation for inline code not consistent quarto-cli#10748

and I agreed with @cscheid on his answer

the previous syntax is historically very popular and this is an intentional choice.

Though looking into docs and its history, it seems your change in a follow up on

• Add Inline code page #953

where it seems to have been decided that using `{r}` is the prefered syntax, and the PR missed some place to change the syntax.

As reported in quarto-dev/quarto-cli#10805, the new syntax has a change in default behavior regarding string output compared to knitr and R Markdown context, a difference that could be surprising to existing R Markdown user. I did not know we wanted to push using `{r} instead of `r

I'll defer to @cwickham and @mine-cetinkaya-rundel for their advice on which one to document first for R documents. Especially as I guess a choice has been made for the Quarto book.

If we really go to new syntax as primary one to use, we should probably add an example in Get Started about outputting raw markdown without escaping.

[mcanouil]

As reported in quarto-dev/quarto-cli#10805, the new syntax has a change in default behavior regarding string output compared to knitr and R Markdown context, a difference that could be surprising to existing R Markdown user. I did not know we wanted to push using {r} instead of r

That is the question indeed as I really thought the brackets syntax was the one to advertise since the documentation states in several places to use brackets and that the syntax without is still supported.

Regarding the string/markdown, I think there is an issue or discussion about harmonising across engines behaviours.

[cderv]

Regarding the string/markdown, I think there is an issue or discussion about harmonising across engines behaviours.

Not sure to see which one is it. I am interesting to look at it if you find it;

With {lang} syntax for inline both Jupyter and Knitr engine behave the same, which is different for historical default `r behavior.

Knitr

---
format: html
engine: knitr
---

This will be bold `r "**hello**"`

This won't be bold `{r} "**hello**"`

But now this will `{r} I("**hello**")`

Jupyter

---
format: html
engine: jupyter
---

```{python}
from IPython.display import Markdown 
```


This won't be bold `{python} "**hello**"`

But now this will `{python} Markdown("**hello**")`

[cscheid]

I agree with @cderv's assessment here. I'm willing to eventually replace the "legacy" knitr syntax in our docs, but we need have a broader discussion about it that explains the situation to both knitr and jupyter users. This is not a change I want to make lightly.

[mcanouil]

Unfortunately, the change already took place in almost all corner of the documentation. This PR is really a follow up as Christophe highlighted.

[cderv]

but we need have a broader discussion about it that explains the situation to both knitr and jupyter users. This is not a change I want to make lightly.

Added as Team discussion item for next meeting.

[cwickham]

I'm picking this up after our team discussion on Sep 18.

• I've kept the changes to docs/get-started/computations/rstudio.qmd: we agreed we should be consistent and use {r}
• I reverted the changes to docs/manuscripts/authoring/_inline-computations in favor of https://github.com/quarto-dev/quarto-web/pull/1400/files
• I made some wording changes to docs/visual-editor/technical.qmd and made sure to link back to the primary Inline Code page.

[cwickham]

/deploy-preview

[github-actions]

🚀 Deployed on https://deploy-preview-1334.quarto.org

[github-actions]

Backport failed for prerelease, because it was unable to cherry-pick the commit(s).

Please cherry-pick the changes locally and resolve any conflicts.

git fetch origin prerelease
git worktree add -d .worktree/sync-1334-to-prerelease origin/prerelease
cd .worktree/sync-1334-to-prerelease
git switch --create sync-1334-to-prerelease
git cherry-pick -x 231e8f22088fcb81ef66e6d5a3b8c9cf5ddd276b 914386974aef0b474abd62c00afa19eea8c71efa 45d6d836fca6dcf9eba7cd8fdecf19a79426ca44

[cderv]

@cwickham I cherry picked the commit in pre-release: c776e84
So changes are there now.