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 (create vignette for optional modifications/protections #80)

BUG FIXES

• math with a single character will still be protected (thanks to @maelle, bug with one-character inline math #101)
• (filter out special control characters #112) filter out special control characters
• (preserve bare links in markdown #115) fixing bare links to return as <link> instead of [link](link)
• (do not issue warning for missing trailing newline #114) remove EOL warning from readLines()
• (make protect math exit early for money #122)
• (add recursive function to find currency dollars #123)

NEW FEATURES

Upstream Commonmark features

• formally support footnotes (footnote XML output contains <<unknown>> tags r-lib/commonmark#23)
• formally support subscripts (Require double-tilde for strikethrough r-lib/commonmark#33 (comment))

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 (create append_md and prepend_md methods #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

• the $show() method gains a new argument, lines which will subset the output by the lines in the document (Improve show method; add nodelist show functions #108)
• show_*() functions will be operate on nodes and/or nodesets, returning a character vector that contains the markdown of just those nodes (Improve show method; add nodelist show functions #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
• to_md_vec() will convert a node or nodelist to a character vector of the resulting markdown (Improve show method; add nodelist show functions #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.

• (add get_protected() #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 [Breaking Changes] attribute-based node protection #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.