探索Literate Markdown Tangle：代码与文档的新融合

2024-06-15 20:31:55作者：范靓好Udolf

Literate Markdown Tangle（LMT）是一个创新的工具，它将Markdown与编程风格相结合，使程序员能够在文档中以清晰易读的方式编写代码。这种** literate programming** 的理念让开发者可以在保持代码可读性的同时，增强文档的完整性。

安装LMT

LMT是一个基于Go语言开发的自包含程序，源码和这个README文件一起存储在GitHub仓库中，用于自我构建。首先确保你的环境中已经安装了Go语言，然后执行以下命令：

git clone https://github.com/driusan/lmt
cd lmt
go build

这将在当前目录下创建名为lmt的二进制文件，你可以通过-o $path参数来指定不同的输出位置。

对于Nix(OS)用户，项目还提供了一个shell.nix文件，可以用来编译项目。

功能演示

为了体验LMT的工作原理，请将此README文件复制到一个空目录，并运行lmt README.md。你会看到从Markdown文件中的代码块中提取出来的文件出现在当前目录。这种过程在literate编程中被称为“tangling”。

LMT是语言无关的，下面的示例使用非常基础的C++来展示其他语言的应用。

文件定向与追加

比如这段带有cpp hello.cpp +=前缀的代码块：

<<<copyright>>>
<<<includes>>>

int main() {
    <<<body of main>>>
}

cpp 表示该代码块为C++，在Markdown渲染时会有相应的语法高亮，在LMT中则会添加语言特定的预处理指令。
hello.cpp 指定了代码块将会被写入到hello.cpp文件中。
+= 表示如果文件已存在，则追加内容到文件末尾，如果不存在则新建。

宏引用

像<<<...>>>这样的序列称为“宏参考”。LMT的“宏”是一个可以从代码块中提取并插入到其他地方的变量。如上例中的<<<body of main>>>，未定义时会有警告，但定义后会被替换。

宏内容

以下代码块定义了body of main的值：

std::cout << "Hello, werld!" << std::endl;

双引号表示这是一个宏，而没有+=意味着会覆盖之前的定义。

追加到宏

使用+=，我们可以向宏添加新的内容，例如在includes宏后面添加更多头文件：

#include <numeric>

隐藏内容

隐藏内容如注释中的版权信息不会显示在最终文档中，但仍会被提取出来：

// Copyright 2020 Me, myself, and I

可选的Tangle与不可选的

LMT允许你对任意语言字符串和文件名进行编码，以实现不同需求。不指定语言或目标，代码块就不会被打包到任何地方。

应用场景

LMT特别适用于：

文档驱动的开发，它可以轻松地将代码解释与实现结合在一起。
教程编写，读者可以直接查看和理解代码细节。
开源项目，提供清晰的、有注解的代码以提高代码透明度。
快速原型设计，代码与说明文档可以同时修改，减少切换成本。

项目特点

语言无关：LMT支持所有语言的代码块，只需指定语言名称。
扩展性：通过宏引用，可以在多个代码块之间传递和组合代码。
隐藏内容：在不影响文档展示的情况下，隐藏需要tangle的内容。
灵活的代码组织：追加内容、定义新宏等操作，让代码结构更自由。

LMT不仅是一个工具，更是一种编程哲学。它将代码和文档紧密集成，让开发变得更直观，更易于理解和维护。立即尝试LMT，提升您的代码写作体验吧！

登录后查看全文

项目优选

收起

kernel

deepin linux kernel

kernel

openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。

Ascend Extension for PyTorch

本项目是CANN提供的transformer类大模型算子库，实现网络在NPU上加速计算。

本项目是CANN提供的神经网络类计算算子库，实现网络在NPU上加速计算。

本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。

本仓库是 Flutter SDK 与 Flutter Engine 的 OpenHarmony 适配版本，由 CPF-Flutter 团队维护。开发者可使用熟悉的 Flutter 技术栈开发 OpenHarmony 应用，3.35.7 及以后的适配版本可基于本仓库源码构建支持 OpenHarmony 的 Flutter Engine。