本文主要介绍实验手册主体部分的语法。
插入实验名称
每一个实验都需要有一个实验名称。
语法
在实验手册的首行,用 Markdown 一级标题来插入实验名称:
# 实验名称
示例
# 云端搭建共享云盘
留意实验名称所在行:
插入实验任务
每一个实验都由若干个实验任务组成。
语法
在实验名称之后或者上一个任务的最后一个步骤之后,用 Markdown 二级标题来插入实验任务:
## 实验任务
示例
## 配置存储桶访问路径
留意实验任务与实验名称、实验步骤的相对位置:
插入实验步骤
每一个实验任务都由若干个实验步骤组成。
语法
在当前实验任务之后、下一个实验任务之前,用 Markdown 三级标题来插入实验步骤:
### 实验步骤
示例
### 登录 COS 控制台
留意实验步骤与实验任务的相对位置:
插入实验正文
正文可以写在实验任务或实验步骤之后。位于实验任务之后的正文,可以对实验任务进行概述;位于实验步骤之后的正文,可以对步骤的内容进行说明。正文的书写,要求工整、简洁、规范。
语法
中文字符和英文字符之间,要添加空格。例如:
登录 COS 控制台
。书籍名称、字句的引用,请用斜体表示。例如:
*引用内容*
。需要强调的概念或字句,请用粗体表示。例如:
**强调内容**
。不希望显示在手册中的内容,请以 > 开头。例如:
> 这一行不会在手册中显示
。不同段落之间、段落与实验任务/步骤之间,请间隔一行。
示例
## 创建 Maven 项目本次实验基于 Java 和 Maven 进行开发。所以,在这一步,我们要新建并配置好 Maven 项目,要根据系统预装的 JDK 版本配置 Maven 项目的编译器版本,以及引入程序所需要的外部依赖,并将依赖下载到本地。#### 新建 Maven 项目首先,在**终端模式**下执行以下命令,在当前目录新建一个 Maven 项目:
留意正文所处的位置、中英文字符间的空格,以及粗体强调内容:
插入检查器
检查器不会在实验手册中显示,但是会对当前实验步骤的完成情况进行检查。一份优质的实验,应该尽可能为每一个关键实验步骤都设置检查器。
语法
在需要检查的实验步骤的末尾,添加检查器:
> <checker type="output-contains" command="检查指令" hint="检查不通过时的提示内容">> <keyword regex="检查关键词" />> </checker>
注意:
一个实验步骤可以有多个检查器。检查顺序即检查器的编写顺序。
检查器会在用户单击下一步时,执行 command 属性中的检查指令。
如果检查指令的返回结果中,包含 regex 属性中的关键词,则检查通过;如果不包含关键词,则会提示 hint 属性中的提示内容。
type 属性有两种有效值:output-contains 表示在指令返回值中包含关键词时检查通过;output-contains-no 表示在指令返回值中不包含关键词时检查通过。
部分 Linux 命令的输出内容是在 stderr 输出的,如果检查器需要检查这部分的输出,需要重定向到 stdin。例如:
nginx -v 2>&1
。示例
> <checker type="output-contains" command="yum list installed git-core" hint="请安装 git 工具">> <keyword regex="git-core" />> </checker>
检查不通过时,实验会对用户进行提示: