Skip to content

Commit 14123de

Browse files
zkamvarzkamvar
committed
add readme section
1 parent 72befbb commit 14123de

File tree

2 files changed

+102
-38
lines changed

2 files changed

+102
-38
lines changed

‎README.md

Lines changed: 83 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,9 @@ developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.re
1212
status](https://github.com/ropensci/tinkr/workflows/R-CMD-check/badge.svg)](https://github.com/ropensci/tinkr/actions)
1313
[![Coverage
1414
status](https://codecov.io/gh/ropensci/tinkr/branch/master/graph/badge.svg)](https://codecov.io/github/ropensci/tinkr?branch=master)
15+
[![R-CMD-check](https://github.com/ropensci/tinkr/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/ropensci/tinkr/actions/workflows/R-CMD-check.yaml)
16+
[![Codecov test
17+
coverage](https://codecov.io/gh/ropensci/tinkr/branch/main/graph/badge.svg)](https://app.codecov.io/gh/ropensci/tinkr?branch=main)
1518
<!-- badges: end -->
1619

1720
The goal of tinkr is to convert (R)Markdown files to XML and back to
@@ -23,16 +26,16 @@ regular expressions. If these words mean nothing to you, see our list of
2326

2427
Possible applications are R scripts using tinkr, and XPath via xml2 to:
2528

26-
- change levels of headers, cf [our `roweb2_headers.R`
27-
script](https://github.com/ropensci/tinkr/blob/main/inst/scripts/roweb2_headers.R)
28-
and [pull request \#279 to
29-
roweb2](https://github.com/ropensci-archive/roweb2/pull/279);
30-
- change chunk labels and options;
31-
- extract all runnable code (including inline code);
32-
- insert arbitrary Markdown elements;
33-
- modify link URLs;
34-
- your idea, please [report use
35-
cases](https://discuss.ropensci.org/c/usecases/10)!
29+
- change levels of headers, cf [our `roweb2_headers.R`
30+
script](https://github.com/ropensci/tinkr/blob/main/inst/scripts/roweb2_headers.R)
31+
and [pull request \#279 to
32+
roweb2](https://github.com/ropensci-archive/roweb2/pull/279);
33+
- change chunk labels and options;
34+
- extract all runnable code (including inline code);
35+
- insert arbitrary Markdown elements;
36+
- modify link URLs;
37+
- your idea, please [report use
38+
cases](https://discuss.ropensci.org/c/usecases/10)!
3639

3740
## Workflow
3841

@@ -175,6 +178,9 @@ rmd <- tinkr::yarn$new(path)
175178
xml2::xml_find_first(rmd$body, ".//md:code_block", rmd$ns)
176179
#| {xml_node}
177180
#| <code_block space="preserve" language="r" name="setup" include="FALSE" eval="TRUE">
181+
```
182+
183+
``` r
178184
new_code <- c(
179185
"```{r xml-block, message = TRUE}",
180186
"message(\"this is a new chunk from {tinkr}\")",
@@ -217,18 +223,18 @@ rmd$head(21)
217223
If you are not closely following one of the examples provided, what
218224
background knowledge do you need before using tinkr?
219225

220-
- That XPath, a language for querying XML & HTML, exists, and [some
221-
basics](https://www.w3schools.com/xml/xpath_intro.asp).
222-
- Basics of how [xml2
223-
works](https://blog.r-hub.io/2020/01/22/mutable-api/#exposing-the-c-api-in-xml2):
224-
how to find, replace, remove nodes etc.
225-
- How to use R6 classes… although reading the examples should help you
226-
get the gist.
227-
- If you are not happy with [our default
228-
stylesheet](#general-principles-and-solution), then understanding
229-
[XSLT](https://ropensci.org/blog/2017/01/10/xslt-release/) will help
230-
you create your own. Refer to this good resource on [XSLT for XML
231-
transformations](https://www.w3schools.com/xml/xsl_intro.asp).
226+
- That XPath, a language for querying XML & HTML, exists, and [some
227+
basics](https://www.w3schools.com/xml/xpath_intro.asp).
228+
- Basics of how [xml2
229+
works](https://blog.r-hub.io/2020/01/22/mutable-api/#exposing-the-c-api-in-xml2):
230+
how to find, replace, remove nodes etc.
231+
- How to use R6 classes… although reading the examples should help you
232+
get the gist.
233+
- If you are not happy with [our default
234+
stylesheet](#general-principles-and-solution), then understanding
235+
[XSLT](https://ropensci.org/blog/2017/01/10/xslt-release/) will help
236+
you create your own. Refer to this good resource on [XSLT for XML
237+
transformations](https://www.w3schools.com/xml/xsl_intro.asp).
232238

233239
## Loss of Markdown style
234240

@@ -238,21 +244,21 @@ The (R)md to XML to (R)md loop on which `tinkr` is based is slightly
238244
lossy because of Markdown syntax redundancy, so the loop from (R)md to
239245
R(md) via `to_xml` and `to_md` will be a bit lossy. For instance
240246

241-
- lists can be created with either “+”, “-” or “\*“. When using
242-
`tinkr`, the (R)md after editing will only use”-” for lists.
247+
- lists can be created with either “+”, “-” or “\*“. When using `tinkr`,
248+
the (R)md after editing will only use”-” for lists.
243249

244-
- Links built like `[word][smallref]` with a bottom anchor
245-
`[smallref]: URL` will have the anchor moved to the bottom of the
246-
document.
250+
- Links built like `[word][smallref]` with a bottom anchor
251+
`[smallref]: URL` will have the anchor moved to the bottom of the
252+
document.
247253

248-
- Characters are escaped (e.g. “\[” when not for a link).
254+
- Characters are escaped (e.g. “\[” when not for a link).
249255

250-
- [x] GitHub tickboxes are preserved (only for `yarn` objects)
256+
- [x] GitHub tickboxes are preserved (only for `yarn` objects)
251257

252-
- Block quotes lines all get “\>” whereas in the input only the first
253-
could have a “\>” at the beginning of the first line.
258+
- Block quotes lines all get “\>” whereas in the input only the first
259+
could have a “\>” at the beginning of the first line.
254260

255-
- For tables see the next subsection.
261+
- For tables see the next subsection.
256262

257263
Such losses make your (R)md different, and the git diff a bit harder to
258264
parse, but should *not* change the documents your (R)md is rendered to.
@@ -265,9 +271,9 @@ and provide its filepath as `stylesheet_path` argument to `to_md`.
265271

266272
### The special case of tables
267273

268-
- Tables are supposed to remain/become pretty after a full loop
269-
`to_xml` + `to_md`. If you notice something amiss, e.g. too much
270-
space compared to what you were expecting, please open an issue.
274+
- Tables are supposed to remain/become pretty after a full loop
275+
`to_xml` + `to_md`. If you notice something amiss, e.g. too much space
276+
compared to what you were expecting, please open an issue.
271277

272278
### LaTeX equations
273279

@@ -311,7 +317,7 @@ Note, however, that there are a few caveats for this:
311317
sure to either use punctuation after the trailing dollar sign OR
312318
format the text as code. (i.e. `` `INKEY$` `` is good, but `INKEY$`
313319
by itself is not good and will be interpreted as LaTeX code,
314-
throwing an error: ::: {.cell}
320+
throwing an error:
315321

316322
``` r
317323
path <- system.file("extdata", "basic-math.md", package = "tinkr")
@@ -335,7 +341,7 @@ Note, however, that there are a few caveats for this:
335341
#| Error: Inline math delimiters are not balanced.
336342
#|
337343
#| HINT: If you are writing BASIC code, make sure you wrap variable
338-
#| names and code in backtics like so: `INKEY$`.
344+
#| names and code in backtics like so: `INKEY$`.
339345
#|
340346
#| Below are the pairs that were found:
341347
#| start...end
@@ -345,7 +351,46 @@ Note, however, that there are a few caveats for this:
345351
#| We write $2 but ...
346352
```
347353

348-
:::
354+
4. **use of `$` as currency will still work**, but there is a caveat
355+
that mixing this inline math broken across lines will cause
356+
problems:
357+
358+
``` r
359+
# this will be mal-formed
360+
bad <- "It's 5:45 and I've got $5.45 in my pocket.\nThe __area of a circle__ is $A =\n \\pi r^2$, where\n$\\pi$ is irrational when it hasn't had its coffee."
361+
fails <- tinkr::yarn$new(textConnection(bad))
362+
fails$show()
363+
#| It's 5:45 and I've got $5.45 in my pocket.
364+
#| The **area of a circle** is $A =
365+
#| \\pi r^2$, where
366+
#| $\\pi$ is irrational when it hasn't had its coffee.
367+
fails$
368+
protect_math()$
369+
show()
370+
#| Error: Inline math delimiters are not balanced.
371+
#|
372+
#| HINT: If you are writing BASIC code, make sure you wrap variable
373+
#| names and code in backtics like so: `INKEY$`.
374+
#|
375+
#| Below are the pairs that were found:
376+
#| start...end
377+
#| -----...---
378+
#| It's 5:45 and I've got $5.45 in my pocket....\pi r^2$, where
379+
#| is $A =...
380+
# This works
381+
good <- "It's 5:45 and I've got $5.45 in my pocket.\nThe __area of a circle__ is $A = \\pi r^2$, where\n$\\pi$ is irrational when it hasn't had its coffee."
382+
works <- tinkr::yarn$new(textConnection(good))
383+
works$show()
384+
#| It's 5:45 and I've got $5.45 in my pocket.
385+
#| The **area of a circle** is $A = \\pi r^2$, where
386+
#| $\\pi$ is irrational when it hasn't had its coffee.
387+
works$
388+
protect_math()$
389+
show()
390+
#| It's 5:45 and I've got $5.45 in my pocket.
391+
#| The **area of a circle** is $A = \pi r^2$, where
392+
#| $\pi$ is irrational when it hasn't had its coffee.
393+
```
349394

350395
## Meta
351396

‎man/rmd-fragments/format-latex.Rmd

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,3 +28,22 @@ you must be sure to either use punctuation after the trailing dollar sign OR for
2828
math$head(15) # malformed
2929
math$protect_math() #error
3030
```
31+
4. **use of `$` as currency will still work**, but there is a caveat that mixing
32+
this inline math broken across lines will cause problems:
33+
```{r, split, error = TRUE}
34+
# this will be mal-formed
35+
bad <- "It's 5:45 and I've got $5.45 in my pocket.\nThe __area of a circle__ is $A =\n \\pi r^2$, where\n$\\pi$ is irrational when it hasn't had its coffee."
36+
fails <- tinkr::yarn$new(textConnection(bad))
37+
fails$show()
38+
fails$
39+
protect_math()$
40+
show()
41+
# This works
42+
good <- "It's 5:45 and I've got $5.45 in my pocket.\nThe __area of a circle__ is $A = \\pi r^2$, where\n$\\pi$ is irrational when it hasn't had its coffee."
43+
works <- tinkr::yarn$new(textConnection(good))
44+
works$show()
45+
works$
46+
protect_math()$
47+
show()
48+
49+
```

0 commit comments

Comments
 (0)