北京大学R语言教程（李东风）第22章： Quarto格式文件

---
title: "演示基本功能"
format: html
---

22.5.1 使用RStudio

Quarto格式可以生成HTML、Word、PDF等输出格式。
输出PDF格式需要安装TinyTeX软件，见§22.20。

只要在RStudio的文件编辑窗口点击“Render”快捷图标就可以转换为指定的输出文件。
如果使用Preview快捷图标，
则支持在修改文件后自动更新结果。

还可以在R中安装quarto扩展包，
并用如下R命令转换：

library(quarto)
quarto_render("index.qmd")

在quarto_render()中可以加选项output_format = "pdf"或output_format = "docx"转换为PDF或Word格式。

22.5.2 使用Quarto可执行程序

也可以不借助于RStudio，
而是单独安装Quarto的可执行程序，
在操作系统命令行使用如下命令转换某个文件：

quarto render index.qmd

这默认生成HTML结果，
在上述命令末尾空格并添加--to pdf转换为PDF格式（需要预先安装TinyTeX软件）:

quarto render index.qmd --to pdf

添加--to docx转换为MS Word格式:

quarto render index.qmd --to docx

Quarto可以使用R的knitr扩展包或者Jupyter软件执行qmd文件中的代码。
可以用YAML选项engine: knitr选用knitr,
engine: jupyter选用Jupyter。

22.5.3 Jupyter笔记本源文件的转换

Jupyter笔记本软件是Python系统生态的重要集成编辑、执行、报告环境，
也支持Julia等语言。
Jupyter笔记本软件本身也有保存为HTML、PDF、Word等的功能，
为什么还要使用Quarto？
这是因为科技论文常用的编号图表、公式、章节编号、章节引用、参考文献引用等功能在Jupyter笔记本中没有很好地被支持。

在操作系统中运行如下命令，
可以建立Jupyter笔记本对HTML格式输出结果的预览：

quarto preview mydoc.ipynb

这个预览会自动更新，
也就是说，
每次笔记本保存时，
预览会自动刷新。
如果要生成最后结果，
不想自动刷新，
可以用render命令，如：

quarto render mydoc.ipynb

为了生成其它格式的输出，
可以加--to选项，如：

quarto render mydoc.ipynb --to docx

生成Word格式，
--to pdf生成PDF格式。

Jupyter笔记本文件如果需要一些关于Quarto的设置，
仍可以在文件头部添加YAML选项，
办法是在文件头部添加一个单元格，
将其类型转换为raw(原样使用的单元格)，
并在其中添加需要的YAML内容，如：

---
title: 测试Python和Quarto
author: XXX
date: 2022-11-27
---

Jupyter笔记本不自动运行其中的程序(Python、Julia、R等)，
转换前应确保笔记本中的程序结果是最新的，
可以在转换前重新运行一遍笔记本，
还有一种办法是在quarto命令后面加--execute选项，
如：

quarto render mydoc.ipynb --execute

对于.qmd格式的文件，如mydoc.qmd，
在操作系统命令行界面中用如下命令转换为Jupyter笔记本：

quarto convert mydoc.qmd

有些程序计算运行时间很长，
可以安装Jupyter笔记本的缓存功能模块jupyter-cache，
使用缓存，
参见：

• https://quarto.org/docs/computations/python.html

22.7.1 标签

在代码段内用“#| label: mylabel”添加一个标签，
在RStudio中编辑时可以很容易地按标签导航到某个代码段，
代码段如果生成图形，可以按标签（图形标签以fig-开头）在别处交叉引用。
在使用缓存功能时，
可以按代码段标签表示代码段之间的依赖关系。

标签可以包含字母、数字、减号和下划线，
生成图形的代码段标签必须以fig-开头。
标签必须在文件中唯一，
如果是多个源文件的图书、网站项目，
标签在不同文件之间也必须唯一。

22.8.1 插图方法

可以用R程序生成图形，
Quarto会自动将该图形插入到结果文档中。

为了在.qmd文件中插入已有图形文件，
若使用本地文件，
仍可以用markdown语法，
即“![代替显示文字](图片地址)”，
如“![百度](figs/baidu01.png)”

在使用RStudio编辑文件时，
可以打开可视化编辑模式(Visual模式)，
选快捷图标Figure/Image，
选择要插入的图片，
并选择一些选项。
也可以将本项目目录或子目录内的图形文件直接拖曳到要插入的位置。
还可以复制图片，
然后在可视化编辑模式中的文档中粘贴图片，
这会在项目文件夹中生成图片的副本。

可以使用R程序插图，如：

```{r}
#| label: fig-mytestimg
#| fig-cap: "百度图标"
#| echo: false
knitr::include_graphics("figs/baidu01.png")
```

22.10.1 在Markdown中输入数学公式

原始的Markdown格式并不支持数学公式。
Pandoc扩展的markdown格式提供了对数学公式的支持，
可以在Markdown文件中插入LaTeX格式的数学公式。
虽然不能提供所有的LaTeX公式能力，
但是常用的数学公式还是能做得很好，
转换到HTML、docx都可以得到正常显示的公式。

用RStudio软件编译Markdown文件，
可以在其中插入LaTeX格式的数学公式，
数学公式可以在编辑器内部显示预览，
编译成HTML或者docx格式后都可以正常显示数学公式,
HTML结果可以直接利用RStudio内部的浏览器预览，
在另外安装的LaTeX编译器的支持下也可以将.qmd格式编译LaTeX格式然后再转换为PDF格式，
这种基于LaTeX的方法对数学公式的支持会更完善。

.qmd和.ipynb文件在Quarto软件支持下都可以使用LaTeX数学公式。

22.10.2 数学公式类别

数学公式公式分为行内公式和独立公式。
行内公式和段落的文字混排，
写在两个美元符号$中间，或者\(和\)之间。
例如$f(x)=\frac{1}{2} \int_0^1 \sin^2 (t x) dt$变成
f(x)=12∫10sin2(tx)dt。
开头的$后面不能紧跟着空格，
结尾的$不能紧跟在空格后面。

独立公式写在成对的美元符号中间，或者\[和\]之间。
例如：

$
  f(x) = \frac{1}{2} \sum_{j=1}^\infty \int_0^1 \sin^2(j t x) dt .
$

显示为

f(x)=12∑j=1∞∫10sin2(jtx)dt.

22.10.3 基本功能

在数学公式中，
用下划线表示下标，
比如$x_1$结果为x1。
用^表示上标，
如$x^2$结果为x2。
上下标都有，如$x_1^2$结果为x21。

公式中用大括号表示一个整体，
比如$x^(1)$不能得到x(1)，
需要用$x^{(1)}$。

公式中用反斜杠开始一个命令，
命令仅包含字母而不能包含数字，
数字只能作为参数。
如$\frac{1}{2}$和$\frac12$都可以生成12。
类似的命令如$\sqrt{2}$为2‾√。

希腊字母都有对应的命令，
如$\alpha$为α，
$\Sigma$为Σ。

常用数学函数有自己的命令，
如$\sin x$变成sinx，
$\exp (x)$为exp(x)。

注意，在公式中使用单词、缩写时，
要写在\text{}内，
使其显示为正体，
而非表示数学符号的斜体。
比如，变量ht表示以厘米为单位的身高，
转换为以米为单位的变量y，正确的做法为：

$
  y = \text{ht} / 100 .
$

显示为：

y=ht/100.

如果不使用\text{}保护，
则会显示为：

y=ht/100.

这在数学公式解释上，一般会解释为

y=h×t/100.

圆括号与方括号可以直接使用，
绝对值符号用|，
如$|x|$变成|x|。
但是，大括号必须写成\{和\}的形式，
如$\exp\{-\frac12 x^2\}$变成exp{−12×2}。

为了使得括号能够与括号内部的内容等高，
可以用\left和\right命令进行修饰，
如

$
\phi(x) = \frac{1}{\sqrt{2\pi}} \exp\left\{ \frac{1}{2} x^2 \right\}
$

变成

ϕ(x)=12π‾‾‾√exp{12×2}

注意\left与\right必须成对使用，否则出错。

求和如$\sum_{i=1}^n x_i$变成∑ni=1xi。
乘积如$\prod_{i=1}^n x_i$变成∏ni=1xi。
积分如$\int_0^1 f(x) dx$变成∫10f(x)dx。

22.10.4 修饰符

$f'(x)$显示为f′(x)，
表示导数；
$f''(x)$显示为f″(x)，
表示二阶导数。
顺便说一句，
偏导数写法如$\frac{\partial f(x,t)}{\partial x}$，
显示为∂f(x,t)∂x。

x¯的写法是$\bar{x}$。
span⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯的写法是$\overline{\text{span}}$。
x̂ 的写法是$\hat{x}$。
x̃ 的写法是$\tilde{x}$。
x⃗ 的写法是$\vec{x}$。

22.10.5 对齐与矩阵

为了产生对齐的公式，
在独立公式中使用aligned环境。
公式中的环境以\begin{环境名}开始，
以\end{环境名}结束，
用\\表示换行，用&表示一个上下对齐位置。
如

$\begin{aligned}
  f(x) =& \sum_{k=0}^\infty \frac{1}{k!} x^k \\
  =& e^x
\end{aligned}$

转化成

f(x)==∑k=0∞1k!xkex

可以用pmatrix环境制作写在圆括号中的矩阵，
用bmatrix环境制作写在方括号中的矩阵，
用vmatrix制作写在绝对值号中的矩阵，如

$
\begin{pmatrix}
x_{11} & x_{12} \\
x_{21} & x_{22}
\end{pmatrix}
$

变成

(x11x21x12x22)

列向量、行向量也可以用这种办法制作。

矩阵A的转置可以写成$A^T$，显示为AT；
也可以写成$A^\top$，显示为A⊤。

22.10.6 特殊字体

有些教材用粗体表示向量或者矩阵，
办法是用\boldsymbol{...}说明。如

$
  \boldsymbol{v} = (v_1, v_2)^T .
$

变成

v=(v1,v2)T.

美术体英文字母用\mathcal{...}，
如,,写法为$\mathcal{A}, \mathcal{B}, \mathcal{C}$。
数学中常用来表示集合类。

手写花体字母用\mathscr{...}，
如ℬ,𝒞,ℱ,𝒢写法为$\mathscr{B}, \mathscr{C}, \mathscr{F}, \mathscr{G}$。
在测度论、概率论中经常用来表示σ代数。

空心字体用\mathbb{...}，
如ℝ,ℂ写法为$\mathbb{R}, \mathbb{C}$
数学中经常用来表示整数集、实数域、复数域等。

22.10.7 数学公式引用

使用LaTeX制作科技论文时，
一个重要的功能是给数学公式贴上标签，
并使用标签引用公式，
编译时自动生成公式编号并引用编号。
Quarto支持这样的功能。

在独立公式的$$后面，
用{#eq-mylabel}的方式加公式标签，
引用时用“(@eq-mylabel)”格式引用。

需要的情况下可以在YAML中加选项：

crossref:
  eq-prefix: ""

使得公式引用仅包含编号，
如(2.1)，
否则可能会变成(方程式2.1)。
也将引用写成如“(-@eq-mylabel)”。

目前不支持多行公式中的多个编号。

22.10.8 数学公式的显示设置

当Quarto的转换目标为HTML时，
数学公式默认使用MathJax库显示。
这是一个Javascript函数库，
从远程访问使用，
有很强的数学公式显示能力，
但断网时会无法显示。

另一种HTML格式的数学公式显示方式是用KATEX显示，
显示效果也很优秀。
为了使用KATEX，
可以在YAML的format--html设置部分，
增加如下设置：

format:
  html:
    html-math-method: katex

22.11.1 使用单个源文件

只有一个源文件时，
所有的设置都放在文件头部的YAML块中，
如：

---
title: "作业框架"
author: "李东风"
date: "2023-07-27"
lang: zh
format:
  html:
    toc: true
    toc-location: body
    toc-depth: 3
    number-sections: true
    html-math-method: katex
  docx:
    toc: true
    toc-depth: 3
    number-sections: true
  pdf:
    documentclass: article
    toc: true
    toc-depth: 3
    include-in-header: 
      text: |
        \usepackage{ctex}
        \usepackage{amsthm,mathrsfs}
---

在设置中，number-sections: true表示自动生成章节的编号并显示编号。
toc: true表示要自动生成目录，
toc-depth: 3表示目录内容包含到小节级别。

在format下的pdf部分是先转换为.tex文件，
再用单独安装的TinyTeX软件转换为PDF的运行设置。
设置中调用了ctex包，
这时中文内容所需要的，
如果没有这个设置，
产生的PDF可能无法显示中文内容。

22.11.2 生成图书

如果用多个源文件同时构成一本书或网站，
应该在项目目录中添加一个“_quarto.yml”文件，
将关于书（网站）的设置都放在这个文件中。

为了用Quarto格式写书，
应该在RStudio中用新建项目方式自动生成新文件夹，
并选择Quarto book格式。
这会自动生成文件夹和主要文件框架，
其中index.qmd是主控文件，
_quarto.yml是主要的设置文件。
_quarto.yml中会包括如下设置：

这说明整个项目的目标是生成一本书，
书的输出结果一般包括网站形式和PDF形式。

仍用title, author, date给出书名、作者、日期，
如：

title: "统计计算"
author: "李东风"
date: "2022-11-28"

其中日期如果想动态填入编译时的日期，
可以用：

title: "统计计算"
author: "李东风"
date: !r lubridate::today()

22.11.3 图书章节结构

章节结构最简单的情况是仅有若干章，
这时在_quarto.qml中，
写在book:下面如下的内容：

book:
  chapters:
    - index.qmd
    - intro.qmd
    - summary.qmd
    - references.qmd

如果有部分，
有附录，结构如：

book:
  chapters:
    - index.qmd
    - preface.qmd
    - part: "基础知识"
      chapters:
        - elem.qmd
        - linear.qmd
    - part: "进阶知识"
      chapters:
        - nonlin.qmd
        - solve.qmd
    - appendices
      - summary.qmd
      - references.qmd

注意“部分”下面的章需要用chapters作为父节点，
而appendices下面则直接列出各个附录文件。

22.11.4 多种输出格式

在单个源文件或者图书的_quarto.yml文件中，
可以设置format项，
在其下层列出要生成的输出格式类型，
以及专用于该输出格式的选项。
比如在_quarto.yml中：

format:
  html:
    toc-float: true
    html-math-method: katex
  pdf:
    documentclass: scrbook
  docx: default

其中default表示使用默认设置，
但是不能仅列出输出格式而没有任何设置。

22.11.5 目录

在_quarto.qml中用toc: true指定对所有输出格式都自动生成目录。
用toc-depth: 3指定目录中显示内容的层级，3是显示到小节层次。
对于HTML输出，
用toc-location: right指定目录单独放在正文右侧，
用toc-location: body指定目录单独放在正文内部开头处。

在_quarto.qml中用number-sections: true使得所有输出格式都有章节编号数字。
不需要编号的章节，在章节标题内容后面空格后写{.unnumbered}。

22.11.6 中文支持

中文内容，需要指定在_quarto.qml的顶级设置中指定lang: zh。
默认的中文翻译有些不尽合理，
可以从https://github.com/quarto-dev/quarto-cli/tree/main/src/resources/language/下载_language-zh.yml，
修改成需要的样子，
改名为_language.yml，
放在自己的项目目录中。
这时不需要使用lang: zh选项。

为了使得LaTeX输出的PDF支持中文，
必须在YAML的format--pdf--include-in-header中指定\usepakage{ctex}，
如：

format:
  pdf:
    documentclass: scrbook
    include-in-header: 
      text: |
        \usepackage{ctex}
        \usepackage{amsthm,mathrsfs}

注意其中的text:项，这用来指定具体的插入内容，而不是插入文件。
也可以将这些LaTeX头文件中需要的内容写在一个preamble.tex文件中，
这时就可以写成include-in-header: preamble.tex。

另外一种办法是直接指定使用的中文字体，
这种方法因为仅指定一种字体，
效果不太美观。
在安装了LaTeX软件如TinyTeX后，
在Windows的命令行窗口(cmd)，
运行如下命令：

fc-list :lang=zh > tmp.txt

则产生一个tmp.txt文件，
其中包含了可用字体的列表，
比如NSimSun代表“新宋体”。
在YAML中设置format -- pdf -- mainfont: "NSimSun"可以使得通过LaTeX生成的PDF支持中文内容。

22.11.7 参考文献数据库设置

在在_quarto.yml中可以设置一个或多个文献数据库，
会自动生成参考文献列表，如：

bibliography: ["myref1.bib", "myref2.bib"]

这些.bib文件目前需要放在项目目录中，
不支持用绝对路径或相对路径。

可以用Jabref软件管理文献数据库。
这是一个Java程序，
可以很容易地编辑文献数据库。

如果使用RStudio对Quarto源文件的可视化编辑模式，
还支持利用DOI等方法加入参考文献引用，
这时RStudio自动添加一个名为“bibliography.bib”，
将这些引用保存在里面。

关于.bib文件的格式，
可以参考一些讲LaTeX用法的书。
一个典型的.bib文件如：

@Book{MWP06-HighStat,
  author    = {茆诗松 and 王静龙 and 濮晓龙},
  title     = {高等数理统计},
  year      = {2006},
  edition   = {第二版},
  publisher = {高等教育出版社}
}
@ARTICLE{Ansley90,
  author = {Ansley, C.F. and Kohn, R.},
  title = {Filtering and smoothing in state space 
  models with partially diffuse
    initial conditions},
  journal = {J. Time Series Analysis},
  year = {1990},
  volume = {11},
  pages = {275--93}
}

引用方法如“[@Ansley90]”。
多个文献引用如“[参见 @Ansly90; @MWP06-HighStat pp 101-103]”。
注意“@文献标签”前后不允许直接使用汉字和中文标点。

22.11.8 其它选项

format:
  html:
    embed-resources: true

:::{#thm-lebesgue01 name="勒贝格定理"}
一元函数黎曼可积，
当且仅当其不连续点的集合为零测集。
:::

引用如：见[@thm-lebesgue01]。

22.13.1 引用章节

为了引用章节，
在章节标题空格后写{#sec-label}，
其中label是全书都唯一的标签。
引用如“参见[@sec-label]”。
如果仅希望生成引用数字，
可用如“参见第[-@sec-label]章”。

22.13.2 可引用插图和表格

可引用插图示例：

#| label: fig-test-fig01
#| fig-cap: "测试图形编号"

plot(1:10)

参见[@fig-test-fig01]。

注意代码开始注释不要忘记#号后面的竖线符号|。
label的内容必须以fig-开头。
后面的选项是fig-cap而不是fig-caption。

22.13.3 图、表、交叉引用定制

在引用图、表、公式、章节时，
默认的引用格式不一定合适，
可以用上述修改_language.yml的方法，
也可以在_quarto.yml中进行设置，如：

crossref:
  eq-prefix: ""
  sec-prefix: "§"

这里eq-prefix设置了在引用公式时，
(@eq-mylabel)的编译结果如(1.1)，
而不是(公式1.1)。
sec-prefix使得在引用某一节时，
使用适当的格式如“§1.1”。

22.15.1 增量转换

用quarto命令转换时，
可以仅指定一个文件或一个子目录进行转换。
这时，
项目中的其它文件使用原来已经转换过的结果。

在RStudio中，
可以用Preview Book打开一个动态更新的预览窗口，
这样，
在用Render重新转换单个文件时可以自动显示新的结果。
如果选择了“Knit on Save”也可以在保存文件时自动显示新的结果。

22.15.2 冻结版本

可以使用YAML选项execute -- freeze: true要求在编译整个项目时，
不运行文件中的源程序。
将true改为auto，
则意味着仅在源文件改变时才运行其中的源程序。
而编译单个文件或单个子目录时还是会运行文件中的源程序。

使用冻结功能要谨慎，
这个功能与使用缓存类似，
可能会使得输出结果使用旧版本的数据或程序。
这些冻结结果保存在_freeze子目录中，
可以删除这个子目录，
强迫重新计算结果。

---
title: "Quarto revealjs演示文稿样例"
author: "李东风"
date: "2022-12-31"
format: revealjs
---

# 用Quarto的revealjs格式输出制作演示

## 幻灯片结构

- 用二级标题标志一个页面开始
- 用一级标题制作单独的分节页面
- 用三个或三个以上减号标志没有标题的页面开始
- 每个页面一般用markdown列表显示若干个项目

## 幻灯片编辑和编译

- 用RStudio编辑内容
- 用RStudio的Render按钮生成结果

-----

![一个演示画面](figs/bd_logo.png)


## 数学公式

$\begin{aligned}
  \sum_{k=1}^n k^2 =& \frac{1}{6} n (n+1) (2n+1) , \\
  \sum_{k=1}^n k^3 =& \left(\frac{1}{2} n (n+1) \right)^2 .
\end{aligned}$


## 代码段和结果

```{r}
x <- 1:10
y <- x^2
plot(x, y)
```

## 幻灯片结构

::: {.incremental}

- 用二级标题标志一个页面开始
- 用一级标题制作单独的分节页面
- 用三个或三个以上减号标志没有标题的页面开始
- 每个页面一般用markdown列表显示若干个项目

:::

format:
  revealjs:
    incremental: true

format:
  revealjs: default
  pptx: default

22.20.1 基于Quarto可执行程序

如果不使用Rmarkdown、bookdown，
仅使用Quarto格式，
而且安装了单独的Quarto可执行程序，
可以在操作系统命令行运行如下安装TinyTeX的命令：

quarto install tool tinytex

这种安装方式不更新操作系统的PATH环境变量，
仅供Quarto本身使用，
从而不会影响到操作系统中已经安装的其它LaTeX编译环境。
Quarto在编译PDF时遇到缺少的格式文件可以自动下载安装。

22.20.2 基于RStudio

如果要在rmarkdown、bookdown中使用PDF输出功能，
可以在在R中安装tinytex扩展包并安装TinyTeX编译软件：

install.packages('tinytex')
tinytex::tlmgr_repo('http://mirrors.tuna.tsinghua.edu.cn/CTAN/')
tinytex::install_tinytex()

其中上面第一行命令安装R的tinytex扩展包，
第二行将下载LaTeX编译程序的服务器设置为清华大学tuna镜像站，
第三行安装LaTeX编译程序。

如果安装成功，
TinyTeX软件包在MS Windows系统中一般会安装在
C:\Users\用户名\AppData\Roaming\TinyTeX目录中，
其中“用户名”应替换成系统当前用户名。
如果需要删除TinyTeX软件包，
只要直接删除那个子目录就可以。

为了判断TinyTeX是否安装成功，
在RStudio中运行

结果应为TRUE,
出错或者结果为FALSE都说明安装不成功。

当用户使用RMarkdown和tinytex包转换latex并编译为PDF时，
如果缺少某些latex宏包，
tinytex会自动安装缺少的宏包。