Always use explicit anchors

[eliocamp]

In reviewing the Spanish translation I've found this instance of a section without explicit anchor. An earlier section links to this one using the implicit anchor created by rmarkdown/quarto, but the link broke in the Spanish version because the name of the implicit anchor is now different.

dev_guide/softwarereview_intro.Rmd

Line 52 in 6bee2f7

## Editors and reviewers

Before sending a PR to address this particular case, perhaps it might be better to do a holistic revision to add explicit anchors to every section in one single PR.

[mpadge]

Even better would be a workflow file that ensured that every section and sub-section had an explicit anchor. That could be integrated as part of the general PR workflow. @maelle How about i write a script for that, let you know when that's done, and you can plug it in to the workflow?

[maelle]

Oh good catch @eliocamp!

@mpadge Yep but first I'll make a bigger PR ensuring current content has such explicit references.

For my own reference: https://quarto.org/docs/authoring/cross-references.html#sections

[maelle]

I've done some work on this, right now I have one (last?) blocker which is that titles à la Ajustar la fecha límite de la revisión {.unnumbered} {#tweak-review-due-date} don't work, even if I change the order of the curly braces thingies. The second one is rendered as is, not used.

[maelle]

https://community.rstudio.com/t/quarto-how-to-cross-reference-unnumbered-book-chapter/136279

[maelle]

this is only a problem for the bot cheatsheet. Maybe we don't need explicit cross-references for it, or maybe it wouldn't be horrible to have numbers there.

[maelle]

1. Add explicit anchors
2. Check existing internal links
3. PR workflow

[maelle]

@mpadge note that I need to be working on a PR workflow anyway.
For each PR,

• if change in a doc in a language,
• transform to XML and translate the same node in the other languages.

this works if all languages have the same XML structure (header, paragraphs) -- which this work on anchors helped check.

[mpadge]

Code to quickly find missing anchors:

y <- yaml::read_yaml ("_quarto.yml")
chapters <- y$book$chapters
for (ch in chapters) {
    ch <- grep ("\\.Rmd$", unlist (ch), value = TRUE)
    lapply (ch, function (i) {
        ch_i <- readr::read_lines (i, progress = FALSE)
        secs <- grep ("^#", ch_i)
        chk <- grepl ("\\s\\{.*\\}$", ch_i [secs])
        secs_fail <- secs [which (!chk)]
        if (length (secs_fail) > 0L) {
            cli::cli_alert_warning ("Lines {secs_fail} of {i}")
        }
    })
}