rmd迁移qmd

总结从rmd迁移到qmd的若干转换技巧。
R
Code
Quarto
Author

胡华平

Published

November 11, 2023

R包管理

基本包列表+辅助包列表相组合

使用openxlsx::read.xlsx()读取xlsx文件

交叉引用

引用标签

{#simple-regression}替换为{#sec-simple-regression}

表格交叉引用

在Rstudio界面下进行查找替换。

regex语法:(表\\@ref\(tab:)(.*?)(\)) 替换为 @tbl-$2。其中(.*?)表示非贪婪匹配(non-greedy),也即一旦匹配即停止搜索。$2Rstudio特定的组模式(group)用法(参看)。

例如,表\@ref(tab:data-mess-wide-q)将被替换为@tbl-data-mess-wide-q

图交叉引用

在Rstudio界面下进行查找替换。

regex语法:(图\\@ref\(fig:)(.*?)(\)) 替换为 @fig-$2

例如,图\@ref(fig:new-workfile)将被替换为@fig-new-workfile

公式

环境说明

  • 只使用两类公式环境:\begin{aligned} ... \end{aligned} 以及\begin{alignedat}{999} ... \end{alignedat}

  • 保持使用双美元符号对$$ ... $$

Latex数学模式下(Latex math mode)不允许出现空行1

Empty lines are not allowed in Latex math mode.

pdf输出时,公式环境\begin{aligned} ... \end{aligned} 需要以某种数学模式进行囊括(例如双美元符号对$$ ... $$)。

如果有空白行,则pdf渲染时会报错:

Package amsmath Error: \begin{aligned} allowed only in math mode.

环境替换

在Rstudio界面下进行查找替换alignequation

regex语法:

  • 开始:^(\$\$\\begin{)(align)(}) 替换为 $1aligned$3

  • 结束:^(\\end{)(align)(}\$\$) 替换为 $1aligned$3

例如,$$\begin{align}将被替换为$$\begin{aligned}\end{align}$$将被替换为\end{aligned}$$

公式环境内索引

在Rstudio界面下进行查找替换。

regex语法:\(\\#eq:(.*?)\) 替换为 {#eq-$1}

例如,(\#eq:var-b2)将被替换为{#eq-var-b2}

交叉引用

在Rstudio界面下进行查找替换。

regex语法:(\\@ref\(eq:)(.*?)(\)) 替换为 @eq-$2

例如,\@ref(eq:demon-SRM)将被替换为@eq-demon-SRM

定理定义

引用标签

  • 有序号定义:TheoremLemmaCorollaryPropositionConjectureDefinitionExampleExercise。直接使用::: {#thm-}类型的div块。 、
  • 无序号定义:proof, remark, and solution。直接使用::: {.proof}的div块。因此也不存在引用标签。

交叉引用

在Rstudio界面下进行查找替换。

  • 定义definition:regex语法(\\@ref\(def:)(.*?)(\)) 替换为 @def-$2。例如,\@ref(def:fitness)将被替换为@def-fitness

节交叉引用

在Rstudio界面下进行查找替换。

regex语法:(节\\@ref\()(.*?)(\)) 替换为 @sec-$2

例如,\@ref(workfile-create)将被替换为@sec-workfile-create

数学符号处理

图表标题包含数学符号

使用如下的语法:

fig-cap: !expr sprintf( "通过命令视窗计算得到理论$t$值$t_{1-\\alpha/2}(f)=t_{0.975}(125)$ ")

knitr::kable()渲染下tibble表格包含数学符号

tibble表格包含数学符号,且使用knitr::kable()进行渲染,那么需要设定2

  • tibble表格里的希腊符号使用单美元对符号$\\beta$,并且希腊字母要额外使用一个逃逸符(escape)\。(如果表格内容是存放在.xlsx文件里,则不需要额外使用一个逃逸符3
  • knitr::kable(escape = FALSE)需要设定escape = FALSE(默认设置为escape = FALSE
```{r}
#| label: tibble-math
#| tbl-cap: "escape and special character"
tibble(
  "$\\alpha$" = letters[1:2],
  "$\\Delta$T" = 1:2,
  "$\\beta$" = c("\u0394F~0-100~", "\u0394F~100-200~")
) %>%
  knitr::kable(escape = FALSE)
```
escape and special character
\(\alpha\) \(\Delta\)T \(\beta\)
a 1 ΔF0-100
b 2 ΔF100-200

图表布局

多图布局

```{r}
#| label: fig-5-scatter-comparison1
#| fig-cap: "辅助回归方程A1-A3"
#| fig-subcap:
#|   - "a1"
#|   - "a2"
#|   - "a3"
#| layout-ncol: 3

include_graphics(
  c("image/3-A1.png",
    "image/3-A2.png",
    "image/3-A3.png")
  )
```
(a) a1
(b) a2
(c) a3
图 1: 辅助回归方程A1-A3

渲染输出

html输出

基本上大部分website的风格样式定义都可以用于book项目。

每章的节目录标题动态显示各不相同

节目录标题的全局设定很容易实现(参看官方文档):

---
format:
  html:
    toc-depth: 4
    toc-title: "章节目录"
---

每章的节目录标题动态显示各不相同,例如第7章-节目录。只需要给对应章的.qmd源文件(例如chpt07-your-file.qmd)里添加yaml定义(参看GitHub问答):

---
toc-title: '第7章-节目录'
---

pdf输出

渲染工作流

两种渲染链条:

(1)通过render book按钮进行渲染。会发生如下过程:

  • 各种LaTeX中间产物文件(.tex.log等)会直接产生在根目录文件夹下。如果渲染顺利完成,则这些中间文件会自动被删除。但是如果渲染失败,则这些中间文件会残留下来。在检查纠正完渲染报错原因后,再次渲染之前一定要记得手动删除这些中间文件!!

  • 渲染得到的pdf文件最后会存放在_site/文件夹下。但是如果下次再重新渲染,则原来的文件会被自动清除替换。

(2)通过命令行渲染。具体可以参看官方文档。其作用和过程如下:

  • 主要作用:方便进行LaTeX源代码的测试和风格调整修改。

  • 命令行执行:quarto render --to latex

  • 渲染结束后会在_site/book-latex/下存放LaTeX源文件,包括.tex以及picture/文件夹等。

提升LaTex渲染速度

当图书项目较大,章节内容较多时,LaTex渲染pdf的耗时会特别长。

例如,在Rstudio的Background Jobs界面下会显示如下信息:

running xelatex - 1
  This is XeTeX, Version 3.141592653-2.6-0.999994 (TeX Live 2022) (preloaded format=xelatex)
   restricted \write18 enabled.
  entering extended mode
  
running xelatex - 2
  This is XeTeX, Version 3.141592653-2.6-0.999994 (TeX Live 2022) (preloaded format=xelatex)
   restricted \write18 enabled.
  entering extended mode
  
running xelatex - 3
  This is XeTeX, Version 3.141592653-2.6-0.999994 (TeX Live 2022) (preloaded format=xelatex)
   restricted \write18 enabled.
  entering extended mode

一个提升渲染速度的办法是给出两个渲染引擎(ps:目前已经失效),并把xelatex引擎作为备选4

---
format:
  pdf:
    pdf-engine: latexmk
    pdf-engine-opt: -xelatex
---

待处理问题

速度与报错

从这两个维度来衡量,初步的结果是:html > docx > pdf

章节前缀和后缀

例如 第1章 或者第1.5节

如何管理多格式输出

  • How do I build my Quarto book as both HTML and PDF? 参看

  • Book – keep both pdf and html outputs in _book directory 参看

内容的条件输出(不同格式下)

  • How to PDF render Quarto books with dynamic content? 参看

相对路径转为绝对路径

相对路径语法一般为:"../pic/logo/nwafu-logo-circle-wb.png"

绝对路径则需要改语法为:here("pic/logo/nwafu-logo-circle-wb.png")

具体操作可以在Rstudio中进行regex匹配替换:

也即,将\"\.\./(.*?)" 替换为here("$1")

某些脚本文件可能需要特殊处理:

(1)Xaringan文件.Rmd可能存在其他的相对路径,建议是还是保持相对路径语法。

  • 一是插件:xaringanExtra::use_logo(image_url = “../pic/logo/nwafu-logo-circle-wb.png”)

  • 二是属性:

layout: false
class: middle,right, hide_logo
background-size: contain
background-image: url("../pic/chpt02-search-google.png")

Footnotes

  1. Package amsmath Error 参看↩︎

  2. 参看cderv的问答↩︎

  3. 例如.xlsx的单元格内容输入为$\alpha +\beta$↩︎

  4. (参看队长问答,Quarto rendering pdf (running xelatex) faster in Rstudio 链接);以及github问答Quarto rendering pdf, running xelatex 10 times 链接↩︎