create append_md and prepend_md methods

[zkamvar]

This creates two new methods for yarn objects:

$append_md() and $prepend_md() which allows users to use XPath or nodes
to choose where to insert markdown.

library("tinkr")
path <- system.file("extdata", "example2.Rmd", package = "tinkr")
ex <- tinkr::yarn$new(path)

With prepend_md(), you can add elements you forgot such as table captions:

ex$prepend_md("Table: BIRDS, NERDS", ".//md:table")$tail(20)
#> 
#> Note that the `echo = FALSE` parameter was added to the code chunk to prevent printing of the R code that generated the plot.
#> 
#> Table: BIRDS, NERDS
#> 
#> | scientific\_name            | common\_name         | n   | 
#> | :------------------------- | :------------------ | --: |
#> | Corvus corone              | Carrion Crow        | 288 | 
#> | Turdus merula              | Eurasian Blackbird  | 285 | 
#> | Anas platyrhynchos         | Mallard             | 273 | 
#> | Fulica atra                | Eurasian Coot       | 268 | 
#> | Parus major                | Great Tit           | 266 | 
#> | Podiceps cristatus         | Great Crested Grebe | 254 | 
#> | Ardea cinerea              | Gray Heron          | 236 | 
#> | Cygnus olor                | Mute Swan           | 234 | 
#> | Cyanistes caeruleus        | Eurasian Blue Tit   | 233 | 
#> | Chroicocephalus ridibundus | Black-headed Gull   | 223 | 
#> 
#> blabla

With append_md() you can add more context, such as adding a note after all
the headings

txt <- c("> Hello from *tinkr*!", ">", ">  :heart: R")
ex$append_md(txt, ".//md:heading")$show(10:30)

#> ```
#> 
#> ## R Markdown
#> 
#> > Hello from *tinkr*!
#> > 
#> > :heart: R
#> 
#> This is an ~~R Markdown document~~. Markdown is a simple formatting syntax for authoring HTML, PDF, and MS Word documents. For more details on using R Markdown see <http://rmarkdown.rstudio.com>.
#> 
#> When you click the **Knit** button a document will be generated that includes both content as well as the output of any embedded R code chunks within the document. You can embed an R code chunk like this:
#> 
#> ```{r, eval=TRUE, echo=TRUE}
#> summary(cars)
#> ```
#> 
#> ## Including Plots
#> 
#> > Hello from *tinkr*!
#> > 
#> > :heart: R

We can also make the heading text more exciting with exclamation points!

ex$append_md("!!!", ".//md:heading/*", space = FALSE)$show(10:30)

#> ```
#> 
#> ## R Markdown!!!
#> 
#> > Hello from *tinkr*!
#> > 
#> > :heart: R
#> 
#> This is an ~~R Markdown document~~. Markdown is a simple formatting syntax for authoring HTML, PDF, and MS Word documents. For more details on using R Markdown see <http://rmarkdown.rstudio.com>.
#> 
#> When you click the **Knit** button a document will be generated that includes both content as well as the output of any embedded R code chunks within the document. You can embed an R code chunk like this:
#> 
#> ```{r, eval=TRUE, echo=TRUE}
#> summary(cars)
#> ```
#> 
#> ## Including Plots!!!
#> 
#> > Hello from *tinkr*!
#> > 
#> > :heart: R

^{Created on 2024-06-21 with reprex v2.1.0}

One huge benefit of this is that markdown can be inserted on a broad spectrum.

[zkamvar]

I just tried this in a real-world situation, and the $prepend_md() method has a bug where it will insert the markdown blocks in reverse order.

[maelle]

🚀

[maelle]

nice! curious to hear what your use case was?

[zkamvar]

I wanted to try to modify the installation section of hubverse packages to have "On the R Universe" and "Development" subsections, and this the previous method of needing to know the exact position of the node in the document was frustrating.

[maelle]

error if none found?

[maelle]

because the error that's right after might be too mysterious

[zkamvar]

That's a good point. I'll try it out.

[zkamvar]

oh yeah, especially given that there is xml_missing

[maelle]

do you want to start using devtag for documenting internal functions? https://github.com/moodymudskipper/devtag

[zkamvar]

Ohhh I think I should!

[maelle]

why an explicit return()?

[zkamvar]

I think I was burned about this with JavaScript and vowed to always use the explicit return, but I know that it's against the standard R style.

[maelle]

should there be a @family tag in both manual pages?

[zkamvar]

Oh yes!

[maelle]

Not sure why it took me THREE MONTHS to have a look 🙈

[zkamvar]

Not sure why it took me THREE MONTHS to have a look 🙈

It's been a busy three months!