tinkr 0.3.0 roadmap

[zkamvar]

I am planning to do a major version component update to {tinkr} in the next few weeks with some new features and bug fixes. This describes my ambitions for it.

DOCUMENTATION

• [ ] vignette to demonstrate applying all possible protections (#80)

BUG FIXES

• [x] math with a single character will still be protected (thanks to @maelle, #101)
• [x] (#112) filter out special control characters
• [x] (#115) fixing bare links to return as <link> instead of [link](link)
• [x] (#114) remove EOL warning from readLines()
• [x] (#122)
• [ ] (#123)

NEW FEATURES

Upstream Commonmark features

• [ ] formally support footnotes (https://github.com/r-lib/commonmark/issues/23)
• [ ] formally support subscripts (https://github.com/r-lib/commonmark/pull/33#issuecomment-2418137911)

misc

• find_between_nodes() will return a set of nodes that exist between two nodes in the same block. This will be most useful for finding the content between braces.
• [ ] new methods to add markdown to specific places in the document (#119)

xml to markdown conversion/display

As of {tinkr} 0.2.0, it's not easy to convert a single XML node or set of nodes to markdown without converting the entire document. The following new features will help with that

• [x] the $show() method gains a new argument, lines which will subset the output by the lines in the document (#108)
• [x] show_*() functions will be operate on nodes and/or nodesets, returning a character vector that contains the markdown of just those nodes (#108)
  • show_censor() will show the nodes in context of the rest of the document, with the rest of the content censored.
  • show_list() will show the nodes individually in separate paragraphs
  • show_block() will show the nodes in the context of the markdown block structure
• [x] to_md_vec() will convert a node or nodelist to a character vector of the resulting markdown (#108)

Safeguards against upcoming changes to "asis" nodes

Version 1.0.0 will subtly break the way both {babeldown} and {pegboard} have been operating by using attributes to protect nodes instead of splitting them into "asis" nodes (see #105 and #107).

On the one hand, the "asis" nodes were useful because it allows patterns to find and protect nodes for translation:

  ## protect content inside curly braces and math ----
  woolish$body <- tinkr::protect_math(woolish$body)
  woolish$body <- tinkr::protect_curly(woolish$body)
  curlies <- xml2::xml_find_all(woolish$body, "//*[@curly]")
  purrr::walk(curlies, protect_curly)
  maths <- xml2::xml_find_all(woolish$body, "//*[@asis='true']")
  purrr::walk(maths, protect_math)

On the downside, it creates a bit of chaos because it does split up the nodes, as shown in the documentation for pegboard's internal fix_links():

However, if a link uses liquid templating for a variable such as: 
`[Home]({{ page.root }}/index.html) and other text`, it will appear in XML as

```xml
...
<text asis="true">[</text>
<text>Home</text>
<text asis="true">]</text>
<text>({{ page.root }}/index.html) and other text</text>
...

**I want to add an accessor for protected nodes from the yarn object to help prepare for the change.** 

 - [x] (#111) `$get_protected()` will return the protected nodes, which currently include curly, math, and square braces. The type and content of these nodes should not change when #107 is merged.
   - this will have an argument of `type`, which will allow one or more of `"curly"`, `"math"`, and `"square"` to select the type of protected node to find. It defaults to `NULL`.