From aaeb95f73fd9e287c7a750e2a2b6d3a85842c278 Mon Sep 17 00:00:00 2001
From: Mars Liu <mars.liu@outlook.com>
Date: Tue, 9 Nov 2021 12:07:58 +0800
Subject: [PATCH] documents

---
 README.md | 136 +++++++++++++++++++++++++++++++-----------------------
 1 file changed, 78 insertions(+), 58 deletions(-)

diff --git a/README.md b/README.md
index 78c2f72..cd3679e 100644
--- a/README.md
+++ b/README.md
@@ -97,118 +97,138 @@ pip install -r requirement.txt
 
 ## `知识节点` 的导出习题选项配置编辑
 
-首先，在知识节点下增加一个习题代码，例如在 `data/1.C语言初阶/1.C语言概述/1.C语言发展史/` 下增加一个`helloworld.c`代码：
+目前我们支持使用 markdown 语法直接编辑习题和各选项。
 
-```c
-#include <stdio.h>
-int main(int argc, char** argv){
-    printf("Hello,Wrold!");
-    return 0;
+首先，编辑知识节点的配置，导出习题：
+
+
+```json
+{
+    // ...
+    "export": [
+        "hellowworld.json"
+    ]
 }
 ```
 
-其次，增加一个同名的选项配置文件`helloworld.json`，目前有两种配置规则
 
-**单行替换规则**：
+然后在 `data/1.C语言初阶/1.C语言概述/1.C语言发展史/` 下增加一个`helloworld.json`定义文件：
 
-* 配置由`one_line`字段指定的单行替换字典
-* 格式是：`"<源字符串>"`: [`"<替换字符串A>"`, `<替换字符串B>`,...],
-    * 其中每个 `"<源字符串>"` `/` `"<替换字符串A>"` 被生成为是一个替换选项
-    * 指定的配置应该能至少生成 `3+` 个替换选项
 
 ```json
 {
-    "one_line": {
-        "printf": ["print"],
-        "return 0;": ["return 0"],
-        "(\"Hello,Wrold!\")": [" \"Hello,Wrold!\""]
-    }
+    "type": "code_options",
+    "author": "刘鑫",
+    "source": "helloworld.md",
+    "notebook_enable": true
 }
 ```
 
-上面的替换规则会将代码替换成 3 个变种的代码：
+其中 type 字段目前都固定是 `code_options`，notebook_enable 字段决定这个习题是否生成对应的 notebook 。根据具体情况写好其它字段，注意这里 source 的文件名，我们指定了一个 markdwon 文件。现在我们新建一个 HelloWorld.md 并编辑为：
+
+
+````mardown
+# Hello World
+
+以下 `Hello World` 程序中，能够正确输出内容的是：
+
+## 答案
 
 ```c
-// 变种代码1
 #include <stdio.h>
 int main(int argc, char** argv){
-    print("Hello,Wrold!");
+    printf("Hello,Wrold!");
     return 0;
 }
 ```
 
+## 选项
+
+### main 函数定义错误
+
 ```c
-// 变种代码2
 #include <stdio.h>
-int main(int argc, char** argv){
-    print("Hello,Wrold!");
-    return 0
+void main(){
+    printf("Hello,Wrold!");
+    return 0;
 }
 ```
 
+### Print 函数调用错误
+
 ```c
-// 变种代码3
 #include <stdio.h>
 int main(int argc, char** argv){
-    print "Hello,Wrold!";
-    return 0
+    printf("Hello,Wrold!");
+    return 0;
 }
 ```
 
-这些变种代码将会作为技能树该知识点该代码选择题的选项。
-
-**多行替换规则**：
+### Java 风格的导入
 
-* 配置由`multiline`字段指定的多行替换数组
-* 数组的每个元素是一组替换规则，会整组被替换
-
-例如：
+```c
+import stdio;
 
-```json
-{
-    "multiline": [
-        {
-            "printf": "print"
-        },
-        {
-            "int main(int argc, char** argv){" : "int main(char** argv){",
-            "return 0;" : "return 0",
-        },
-        {
-            "#include <stdio.h>": ""
-        }
-    ]
+int main(int argc, char** argv){
+    stdio.printf("Hello,Wrold!");
+    return 0;
 }
 ```
 
-同样，该配置将支持将源代码生成3个变种代码
+### 函数错误
 
 ```c
-// 变种代码1
 #include <stdio.h>
 int main(int argc, char** argv){
     print("Hello,Wrold!");
     return 0;
 }
 ```
+````
+
+### 增强信息
+
+为了编写习题和生成 notebook 的需要，markdown 解释器支持两种模板能力，如果我们在答案之前，有一个名为 aop 的二级标题：
+
+````markdown
+
+## aop
+
+### before
 
 ```c
-// 变种代码2, 注意第2组替换规则，包含了两行替换
-#include <stdio.h>
-int main(char** argv){
-    print("Hello,Wrold!");
-    return 0
-}
+print("hello world");
 ```
 
+### after
+
 ```c
-// 变种代码3
+main(0, NULL);
+```
+````
+
+那么在创建notebook的时候，before 会插入到源代码前一个单元，after 则会插入到源代码后。aop 章节可以只包含 before 或 after 中的某一个，也可以两个都有。
+
+另一些情况下，我们可能需要把各个选项中重复的代码提取出来，建立一个模板，此时可以在答案之前建立一个名为 template 的二级标题，例如：
+
+````markdwon
+
+## template
+
+```c
+```c
+#include <stdio.h>
 int main(int argc, char** argv){
-    print("Hello,Wrold!");
+    $code
     return 0;
 }
+
 ```
 
+````
+
+注意这里的代码中，有一个 `$code` 占位符，它在管道程序处理过程中，会替换成答案和个选项内容中的代码
+
 ## 技能树合成
 
 在根目录下执行 `python main.py` 会合成技能树文件，合成的技能树文件: `data/tree.json`
-- 
GitLab