dmake，一个文档编译工具

工作中被反复修改的文档搞破防了。这些文档有一个特点，就是同一段文字会多次出现在一个或者多个.docx文件中。于是在破防之余，开发了这个dmake工具，用于从Markdown文件编译生成需要的.docx文件。

1. 什么是dmake

dmake( document-make) 是一个用于编译包含有较多重复文档部件且分布在多个文档或一个文档的多处的命令行工具。其设计初衷为避免人工编写时出现的错误和遗漏。该软件受到了hexo博客系统、makefile等项目的启发，你可以在使用中发现上述项目的影子。

2. 安装dmake

1 2	dmake install dmake unsinstall

注：该命令作用仅为添加环境变量，dmake文件需要手动删除。

2. 快速入门

mkdir TestProject    REM 在当前位置新建TestProject目录
cd TestProject       REM 进入TestProject目录
dmake init c4t2      REM 初始化一个c4t2项目（IV级风险二票）
dmake                REM 编译项目，生成文档

注：项目目录中存在一个d-makefile，文件名为makefile.yaml（或makefile.yml）。

3. makefile.yaml文件概述

# makefile.yaml

# 定义需编译生成的目标文档
filename: 
  - test.docx
  - foo.docx

# 定义生成上述文档所用到的模板文档，与生成文档为一一对应关系
template: 
  - template1.docx
  - template2.docx

# 文档源文件，重复、可变的文档部件均定义在下列.md文件中
source:
  - abstract.md
  - safety_measure.md

4. dmake项目支持的Markdown语法

语法	描述
三级标题	用于字段定义, 值应紧随在下面的行中
列表	支持有序列表（含多级列表）
图片	支持jpg, png, gif, bmp, vsd, vsdx图片的插入
引用	从其他字段定义的值中引用到本字段，或从外部导入Word文档
表格	支持单列单元格文本插入
注释	同HTML注释，<!– 注释内容 –> ，可跨行，不支持嵌套注释

5. md源文件示例

### IMG_TEST
![image-title](../img/test.jpg) 
![image-title](../img/test2.vsd#2)   <!--将img/test2.vsd文件的第2页转换为jpeg并插入到文档中（vsd文件首页编号为1） -->
![image-title](../img/test3.vsd)     <!-- 将img/test3.vsd文件的第1页转换为jpeg并插入到文档中-->
<!-- 注意，图片的插入必须使用IMG_前缀 -->


### CL_LIST
<!-- 单列单元格列表，以下列表将被插入到MergedField所在列，并自动插入新的行 -->
- Item 1
- **Item 2**
- Item 3
<!-- 列表项目以 - 为前缀，并支持加粗格式符 -->


<!--三级标题中的[ ]内为备注描述文本，可选项 -->
### SURVEY_DATE[查勘日期]
2022-04-01 12:00


### LOCATION[地点]
Somewhere

### TEST_FIELD
[](#LOCATION)是一个测试引用，它引用自###LOCATION块
[](#LIST[2])引用了一个列表中的第2子项（从1开始）

### FILE_IMPORT
[$IMPORT](../assets/src.docx)     <!-- 注意，当从外部导入文档时，必须使用$IMPORT关键字 -->

6. 约定优于配置

我们约定dmake项目有如下目录结构，请勿修改目录名或文件名：

工作目录
  ├─img
  ├─md
  ├─template
  └─makefile.yaml

目录	描述
img	图片存放目录
md	Markdown源文件存放目录
template	模板文件存放目录
makefile.yaml	自动化生成文件

此外，在md文件中引用图片、文件时，以md目录为起点

7. dmake 命令行用法

# 初始化dmake工作目录
dmake init c3t1

# 编译并生成文档
dmake
dmake make

# 向项目工作目录中添加已安装的模板
dmake add template test_template

# 列出本机已安装的模板
dmake list template 

# 安装dmake（将dmake目录添加到PATH环境变量，需在dmake目录下执行）
dmake install

# 卸载dmake（仅将dmake目录从PATH环境变量中移除）
dmake uninstall

注：当dmake遇到错误命令时会显示帮助信息，可供查看