fix: preserve qdocco block comments as code

README.md

@@ -2,7 +2,7 @@
 
 QuickCoffee 是一台以 Rust 编写、受 CoffeeScript 启发的字节码脚本引擎。它保留紧凑、可读的表达式语法，却不兼容 JavaScript：没有原型链、`this`、`eval` 或嵌入 JavaScript。
 
-当前实现遵循 [RFCs/0000-project-scope.md](RFCs/0000-project-scope.md) 至 [RFCs/0103-qbench-schema-version.md](RFCs/0103-qbench-schema-version.md)。
+当前实现遵循 [RFCs/0000-project-scope.md](RFCs/0000-project-scope.md) 至 [RFCs/0104-qdocco-block-comments.md](RFCs/0104-qdocco-block-comments.md)。
 
 ```coffee
 square = (x) -> x * x

RFCs/0000-project-scope.md

@@ -20,4 +20,4 @@ QuickCoffee 是一个 Rust 实现的、受 CoffeeScript 2016 启发的脚本引
 
 本仓库中的测试即 0.1 的语义基线。对语法或运行时的新增特性必须先以 RFC 补充定义，并至少添加：成功测试、错误测试及字节码验证测试。
 
-当前已实现的后续语义与工具 RFC 延伸至 RFC 0103；其中 RFC 0077 定义 JSON 输出、RFC 0079 定义 TAP 输出、RFC 0080 定义 CLI 字节码指纹、RFC 0081 定义可机器读取的基准输出、RFC 0082 规范化指纹编码、RFC 0083 定义 Markdown 文学编程产物、RFC 0084 定义嵌入上下文 fuel 控制、RFC 0085 定义可执行 Rust 嵌入示例、RFC 0086 定义 crate 发布元数据、RFC 0094 定义 qdocco 最终值门禁、RFC 0095 定义字符串步进迭代、RFC 0096 定义其性能基准、RFC 0097 定义 `do` 参数转发、RFC 0098 定义 RFC 索引门禁、RFC 0099 定义 `!` 否定别名、RFC 0100 定义有符号 `by` 步长、RFC 0101 定义 qdocco 原子输出、RFC 0102 定义 qtest 规范文件去重、RFC 0103 定义 qbench schema 版本，均不改变脚本语言值模型的原型无关约束。
+当前已实现的后续语义与工具 RFC 延伸至 RFC 0104；其中 RFC 0077 定义 JSON 输出、RFC 0079 定义 TAP 输出、RFC 0080 定义 CLI 字节码指纹、RFC 0081 定义可机器读取的基准输出、RFC 0082 规范化指纹编码、RFC 0083 定义 Markdown 文学编程产物、RFC 0084 定义嵌入上下文 fuel 控制、RFC 0085 定义可执行 Rust 嵌入示例、RFC 0086 定义 crate 发布元数据、RFC 0094 定义 qdocco 最终值门禁、RFC 0095 定义字符串步进迭代、RFC 0096 定义其性能基准、RFC 0097 定义 `do` 参数转发、RFC 0098 定义 RFC 索引门禁、RFC 0099 定义 `!` 否定别名、RFC 0100 定义有符号 `by` 步长、RFC 0101 定义 qdocco 原子输出、RFC 0102 定义 qtest 规范文件去重、RFC 0103 定义 qbench schema 版本、RFC 0104 定义 qdocco 块注释代码保留，均不改变脚本语言值模型的原型无关约束。

RFCs/0104-qdocco-block-comments.md

@@ -0,0 +1,8 @@
+# RFC 0104：qdocco 保留块注释代码
+
+- 状态：已采纳
+- 依赖：RFC 0032、RFC 0083
+
+qdocco 文学 prose 行必须以恰好两个 `#` 开始（可有前导空格）；以三个或更多 `#` 开始的行属于 QuickCoffee 块注释或其内容，必须保留在生成文档的代码区。这样 `### ... ###` 不会被误渲染成说明文字，也不会从可复制代码中消失。
+
+HTML 与 Markdown 输出采用同一分类规则。块注释仍由 QuickCoffee 编译器执行并从运行语义中移除，RFC 0104 只规定文学文档的代码/prose 分区。

src/bin/qdocco.rs

@@ -50,11 +50,16 @@ fn escape(input: &str) -> String {
         .replace('>', ">")
         .replace('"', """)
 }
+fn prose_text(line: &str) -> Option<&str> {
+    let trimmed = line.trim_start();
+    let text = trimmed.strip_prefix("##")?;
+    (!text.starts_with('#')).then_some(text)
+}
 fn render(source: &str, result: &str) -> String {
     let mut prose = String::new();
     let mut code = String::new();
     for line in source.lines() {
-        if let Some(text) = line.trim_start().strip_prefix("##") {
+        if let Some(text) = prose_text(line) {
             prose.push_str(&format!("<p>{}</p>\n", escape(text.trim())))
         } else {
             code.push_str(line);
@@ -71,7 +76,7 @@ fn render_markdown(source: &str, result: &str) -> String {
     let mut prose = String::new();
     let mut code = String::new();
     for line in source.lines() {
-        if let Some(text) = line.trim_start().strip_prefix("##") {
+        if let Some(text) = prose_text(line) {
             let text = text.trim();
             if !text.is_empty() {
                 prose.push_str(text);

tests/cli_tools.rs

@@ -72,6 +72,37 @@ fn qdocco_renders_escaped_source_and_checks() {
     );
     let fenced_document = fs::read_to_string(&fenced_output).unwrap();
     assert!(fenced_document.contains("`````quickcoffee\n# ````\ntrue\n`````"));
+    let block_input = temp.join("block-comment.qc");
+    let block_output = temp.join("block-comment.html");
+    fs::write(&block_input, "### hidden code ###\ntrue\n").unwrap();
+    assert!(
+        Command::new(bin("qdocco"))
+            .args([
+                block_input.to_str().unwrap(),
+                "-o",
+                block_output.to_str().unwrap()
+            ])
+            .status()
+            .unwrap()
+            .success()
+    );
+    let block_document = fs::read_to_string(&block_output).unwrap();
+    assert!(block_document.contains("<pre><code>### hidden code ###\ntrue\n</code></pre>"));
+    let block_markdown = temp.join("block-comment.md");
+    assert!(
+        Command::new(bin("qdocco"))
+            .args([
+                "--markdown",
+                block_input.to_str().unwrap(),
+                "-o",
+                block_markdown.to_str().unwrap(),
+            ])
+            .status()
+            .unwrap()
+            .success()
+    );
+    let block_markdown_document = fs::read_to_string(&block_markdown).unwrap();
+    assert!(block_markdown_document.contains("````quickcoffee\n### hidden code ###\ntrue\n````"));
     let overwrite = Command::new(bin("qdocco"))
         .args([input.to_str().unwrap(), "-o", input.to_str().unwrap()])
         .output()