diff options
| -rw-r--r-- | content/_drafts/60.md | 2 | ||||
| -rw-r--r-- | content/_drafts/关于一切的纯文本解决方案指南.md | 148 |
2 files changed, 148 insertions, 2 deletions
diff --git a/content/_drafts/60.md b/content/_drafts/60.md index 52680ee9..f2bfb207 100644 --- a/content/_drafts/60.md +++ b/content/_drafts/60.md @@ -43,7 +43,7 @@ toc: true 这个插件在前端开发者工具中添加了一个 Atomic CSS 标签页，会把选中元素的样式全部列出来，在右侧显示是哪个类提供了这个样式。 - + 访问：[GitHub - astahmer/atomic-css-devtools](https://github.com/astahmer/atomic-css-devtools) diff --git a/content/_drafts/关于一切的纯文本解决方案指南.md b/content/_drafts/关于一切的纯文本解决方案指南.md index 0c5faba2..e75c05b6 100644 --- a/content/_drafts/关于一切的纯文本解决方案指南.md +++ b/content/_drafts/关于一切的纯文本解决方案指南.md @@ -137,9 +137,155 @@ Word 简直是世界上最反人类的文本编辑器，还有与之相关的 Pa \end{document} ``` +不过，我并没有高强度的写论文需求，所以接触 LaTeX 比较少，用的比较多的场景应该是在 Markdown 中嵌入公式，许多 Markdown 编辑器都支持用 `$$` 包裹 LaTeX 块以渲染数学公式。以下是一个二分类问题的对数损失函数，用做示例。 + +```latex +$$ +\mathcal{L}(\theta) += -\sum_{i=1}^{n} \left[ +y_i \log f_\theta(x_i) ++ (1 - y_i)\log\bigl(1 - f_\theta(x_i)\bigr) +\right] +$$ +``` + + + +总而言之，LaTeX 是一个功能强大的文档标记语言，有了它就可以把注意力放在编写内容上，而无需过多关注页面排版。不过，也有人认为 LaTeX 的语法太啰嗦，所以会寻求其他的解决方案。 + ### Typst -### 万能的 Markdown +你可以把 Typst 理解为一个更像 Markdown 的 LaTeX，它的功能和 LaTeX 一样强大，却有着 Markdown 一样简洁的语法。 + + + +Typst 支持各种类型的可视化、图表、数学公式、代码高亮等，还可以用来做幻灯片。不过，我并不了解 Typst，我对它的印象是，Typst 似乎更商业化，提供 Pro 版本，订阅制，每个月 $7.99。 + +### Markdown 和 Pandoc + +Markdown 最常用的使用场景是被渲染为 HTML，用在博客平台、论坛和一些即时通讯软件里（据我所知，Discord 就支持 Markdown 语法）。Markdown 的最大特点是可读性，即便没有被渲染，阅读纯文本的 Markdown 文档也没有任何问题。 + +尽管 Markdown 本身的语法比较局限，缺乏 LaTeX 和 Typst 的排版能力，但借助一些拓展语法和外部工具，就能让 Markdown 变得几乎万能。 + +本文要介绍的是一个非常强大的命令行工具——[Pandoc](https://pandoc.org/)，他几乎可以把任何文档格式转换为另一种文档格式（官网列出了详细的支持列表），它可以在 Markdown、Emacs Org-Mode、AsciiDoc、Typst、LaTeX、Microsoft Word 等格式之间相互转换，还可以把上述格式轻松转换为 PDF。如果有不支持的小众格式，还可以自己用 Lua 语言编写 Reader 和 Writer。 + +有了 Pandoc，你就可以安心地用 Markdown 编写文档，写完之后再转换为需要的格式，比如 Word 和 PDF。 + +你还可以编写 Filter 来拓展 Pandoc 的功能。Pandoc 转换文档的过程是这样的：使用相应的 Reader 把以原始格式编写的文档读取为 AST（抽象语法树，一个中间层）；再由 Writer 把 AST 写为用户指定的文档格式。编写自定义的 Reader 和 Writer 可以让 Pandoc 读取或写出更多的文档格式，编写 Filter 可以改变中间的抽象语法树。以下是 Pandoc 从输入到输出的过程： + +```text +INPUT --reader--> AST --filter--> AST --writer--> OUTPUT +``` + +举个例子，如果你想要把 Markdown 文档里的二级标题全部替换为斜体正文内容，这就涉及到了更改中间层 AST，因为 `## 二级标题` 被 Reader 读取时，依然是二级标题，如果 AST 没有改变，被 Writer 写出的时候就转换为了另一个格式的二级标题（比如 HTML 的 `<h2>二级标题</h2>`）。如果要从二级标题改为斜体正文内容，就要在内容被 Writer 写出之前改变 AST 的内容。 + +记得前文提到的 PlantUML 吗？GitHub 上有一个现成的 [pandoc-plantuml-filter](https://github.com/timofurrer/pandoc-plantuml-filter)，他会把编程语言被标记为 `plantuml` 的代码块，用 PlantUML 渲染为对应的 UML 图——Reader 读取到了 `plantuml` 的代码块；Filter 把抽象语法树中的代码块变成了图片；Writer 把图片写入了输出文件。 + +配置好了对应的 Filter，就可以直接在 Markdown 文件里这样嵌入 UML 图： + +~~~ +```plantuml +Alice -> Bob: Authentication Request +Bob --> Alice: Authentication Response + +Alice -> Bob: Another authentication Request +Alice <-- Bob: Another authentication Response +``` +~~~ + +将 PDF 引擎设置为 `xelatex`，Pandoc 也能将被标记为 LaTeX 的代码块渲染为嵌入式的 LaTeX 文档，可以用这个特性来实现多图排版。 + +~~~ +```{=latex} +\begin{figure}[H] +\centering +\begin{subfigure}[b]{0.3\textwidth} + \centering + \includegraphics[width=\textwidth]{img/1.jpeg} + \caption{图 1} + \label{fig:img1} +\end{subfigure}% +\hfill +\begin{subfigure}[b]{0.3\textwidth} + \centering + \includegraphics[width=\textwidth]{img/2.jpeg} + \caption{图 2} + \label{fig:img2} +\end{subfigure}% +\hfill +\begin{subfigure}[b]{0.3\textwidth} + \centering + \includegraphics[width=\textwidth]{img/3.jpeg} + \caption{图 3} + \label{fig:img3} +\end{subfigure} +\caption{三张图} +\end{figure} +``` +~~~ + +有了上述工具，你就能以一种**工程化**的方式编写文档。我的建议是，把图片、参考资料、Markdown 源文件和其他资源放在同一个目录下，然后在这个目录下再创建一个 `pandoc.sh`，示例内容如下： + +```sh +#!/bin/bash + +pandoc "input.md" \ + --from=markdown+yaml_metadata_block \ + --pdf-engine=xelatex \ + --filter=pandoc-plantuml \ + -V geometry:margin=2cm \ + -V fontsize=12pt \ + -V mainfont="Songti SC" \ + -V CJKmainfont="Songti SC" \ + -o output.pdf +``` + +编写文档的过程中可能需要多次运行 Pandoc 来测试结果，或者在更新后生成更新版本的 PDF 文件，把命令放在 Shell 文件里更方便运行。这些设置项也可以放在 Markdown 文件的 frontmatter 里，具体放在哪里就看自己的喜好了。 + +```markdown +--- +title: 文档标题 +subtitle: 副标题 +author: Eltrac +date: "2025-12-13" +geometry: margin=2cm +fontsize: 12pt +mainfont: "Songti SC" +CJKmainfont: "Songti SC" +header-includes: + - \usepackage{xeCJK} + - \setCJKmainfont{Songti SC} + - \setCJKfamilyfont{hei}{Heiti SC} + - ... +--- +``` + +Pandoc 还可以一次性接收多个 Markdown 文件作为参数，文档也可以用模块化的方式编写。 + +```sh +pandoc intro.md chapter1.md chapter2.md appendix.md \ + -o output.pdf +``` + +如此一来，你就可以像开发软件系统一样编写文档，维护一个这样的目录： + +```text +document/ +├── intro.md +├── chapter1.md +├── chapter2.md +├── ... +├── appendix.md +├── pandoc.sh <-- 编译时运行 +├── img/ +│ ├── figure1.png +│ └── ... +└── output.pdf <-- 编译结果 +``` + +把文档发送给别人的时候，提交 `output.pdf` 就好了。 + +## [^1]: SaaS：Software as a Service（软件即服务），可以简单理解为商业软件，一般以订阅制为商业模式。 |