扩充README

README.md

@@ -9,34 +9,69 @@
 
 ——问题是我想要批量生成的东西，系统里生成不了啊！！！例如什么成绩排名证明，还有什么在读证明，以及学生毕业设计的封面贴纸……
 
-网上好像没有现成的个人用户app可以达成“根据模板填空”这样的目的。好在已经有能达成类似目的的[库](https://docxtpl.readthedocs.io/en/latest)了，自己写一个难度没那么大了。 ~~ 这就是给python-docx=template写的一个图形用户界面 ~~
+网上好像没有现成的个人用户app可以达成“根据模板填空”这样的目的。好在已经有能达成类似目的的[python-docx-template](https://docxtpl.readthedocs.io/en/latest)了。
 
-## 配置使用环境
+~~你可以认为这个项目给python-docx-template写了（图形）用户界面~~
+
+## 基本用法
 ```shell
+# 配置环境
+git clone https://github.com/y0umu/TTVDUW.git
+cd TTVDUW
 pip install -r requirements.txt
+# 运行
+python app_main.py
 ```
-我的Python版本是3.8。不过Python 3.9、3.10应该也能使用
+我的Python版本是3.8。不过Python 3.9、3.10应该也能使用。
 
-## 基本用法
-这个app的入口是`app_main.py`。有图形用户界面和命令行两种接口。如果不带任何命令行参数执行app_main.py，就会启动图形界面。
+这个app的入口是`app_main.py`，提供图形用户界面和命令行界面。如果不带任何命令行参数执行`app_main.py`，就会启动图形界面。
+
+Windows用户也可以直接[下载](https://github.com/y0umu/TTVDUW/releases/)使用Pyinstaller打包的二进制程序，而不必配置环境。在这种情况下，解压TTVDUW.zip后，运行TTVDUW.exe即可看到用户界面。
+
+无论使用图形界面还是命令行，都需要准备**模板**和**键值数据表**。
 
-无论使用图形界面还是命令行，都需要准备模板和键值数据表
-- 用户配置模板（docx格式），在模板中设置占位符1、占位符2…… 占位符的语法是所谓的[Jinja语法](https://jinja.palletsprojects.com/en/3.0.x/templates/)，占位符两侧要用`{{  }}`包裹起来。观看examples目录中的示例文件就能大致明白该怎么书写
-- 用户提供键值数据表（xlsx等），每一列为占位符1、占位符2……以及它们对应的值
+用户配置模板（docx格式）：在模板中设置占位符1、占位符2…… 占位符的语法是所谓的[Jinja语法](https://jinja.palletsprojects.com/en/3.0.x/templates/)，占位符两侧要用`{{  }}`包裹起来。这个文件既可以用MS Word书像撰写普通文档那样书写，也可以用python-docx这样的工具生成。**但是必须保证格式是docx格式，不能是doc格式**
+
+如果你看不明白“Jinja语法”到底说了什么事情，请打开`examples/成绩排名证明（推免）模板_tpl.docx`。这是一个样例模板文件。这个文件中，你会看到`{{ stu_name }}`、`{{ stu_colledge }}`这样的文本。这些在Word里面都是**普通**文本。这些文本经过程序处理后将会被**替换**，所以我把它们称为“占位符”。
+
+- 注：“`{{`”之后需要空一格，“`}}`”之前也需要空一格。
+
+占位符被替换成什么，则是由用户提供的**键值数据表**决定的。这个表提供了占位符名称（称为**键**，**key**，有时也称**字段**）与替换内容（称为**值**，**value**）之间的关系。示例文件`examples/2022级智能建造学生成绩排名_datafeed.xlsx`是一个键值数据表，其格式可供参考。
+
+- 注：键值数据表中字段名应该是唯一的。程序在处理含有重名字段键值数据表时未必会报错，但输出文件的结果会变得不可靠。
 
 ### 图形用户界面
-![gui](screenshots/ttvduw_gui.png)
+初上手本项目的用户可能更倾向于使用更为直观的图形用户界面。
+
+![gui_main](screenshots/ttvduw_gui.png)
 
-图形用户界面展现了所有的可配置项。
+**模板**（`-t, --template`）区域用来选择输入模板文件的位置。
 
-需要解释的可能是“选择输出文件名”（`ttvduw_gui.TtvduwGui.btn_custom_outname`）这个按钮。默认情况下，图形界面程序的输出文件名由键值数据表中的全部字段的值组成。如果你希望输出文件名只包括部分字段的值，就可点击这个按钮。点击此按钮后会弹出图中右侧的窗口，将输出文件命名时希望保留的字段保持勾选，其余取消勾选即可生效。
+**键值数据表**区域用来选择（`-f, --data-feeder-file`）键值数据表文件的位置。这个区域还有两个可配置参数“从表格第?行（列）开始取数数据”（`--tab-start-from-row`、 `--tab-start-from-col`），这两个参数是为了表格区域不是从左上角顶格的开始的xlsx文件准备的。例如你的表格有个标题把第1行占用了，那么你应该从第2行开始取数据。
 
+**输出文件夹配置**区域用来选择输出目录的位置。如果不选，就会根据模板文件的文件名自动生成一个输出目录。
+
+**操作说明**区域是给从来不看说明书的人准备的。
+
+![gui_选取输出文件名](screenshots/ttvduw_gui_2.png)
+
+关于**选取输出文件名**按钮（`ttvduw_gui.TtvduwGui.btn_custom_outname`）：默认情况下，输出文件名是一串辨识度不太高的[Unix时间](https://time.is/zh/Unix_time_now)。这个按钮允许你将键值数据表中的部分字段的值作为文件名。
+
+- 注1：如果你选了半天最后还是决定什么都不选，那么程序仍然会把Unix时间作为输出文件名。
+- 注2：目前程序图形界面限制了最多显示20个字段（`ttvduw_gui.TtvduwGui.custom_outname_window`）。如果20个字段已经满足不了你的要求了，请用命令行（参数`--custom-out-names-with-keys`）。
+- 注3（Bug？）：对于那些数据区域挨着一行被合并单元格的excel表格，本app使用的openpyxl在读取表格行的时候，会读出一行有16384个数据。虽然大部分情况感觉不到这一点，但是在这个选择输出文件名的模块会有体现：不对应实际表格区域的单元格被当作字段名收了进来，字段名显示为“None”。
+
+关于**生成我需要的文档**按钮：这个不得了的按钮就像是奇迹的见证者。
 
 ### 命令行
+命令行界面适合经常使用固定参数操作，或者需要编写脚本的用户。对此感到陌生的人应该直接去看[图形用户界面](#图形用户界面)这一节。
+
+如下为命令行帮助。
 ```
-usage: app_main.py [-h] -t TEMPLATE -f DATA_FEEDER_FILE [-o OUT_PATH] [--tab-start-from-row TAB_START_FROM_ROW]
-                 [--tab-start-from-col TAB_START_FROM_COL]
-                 [--custom-out-names-with-keys CUSTOM_OUT_NAMES_WITH_KEYS [CUSTOM_OUT_NAMES_WITH_KEYS ...]]
+usage: app_main.py [-h] -t TEMPLATE -f DATA_FEEDER_FILE [-o OUT_PATH]
+                   [--tab-start-from-row TAB_START_FROM_ROW]
+                   [--tab-start-from-col TAB_START_FROM_COL]
+                   [--custom-out-names-with-keys CUSTOM_OUT_NAMES_WITH_KEYS [CUSTOM_OUT_NAMES_WITH_KEYS ...]]
 
 optional arguments:
   -h, --help            show this help message and exit
@@ -52,30 +87,38 @@ optional arguments:
                         键值数据表文件从第几列开始有数据(default: 1)
   --custom-out-names-with-keys CUSTOM_OUT_NAMES_WITH_KEYS [CUSTOM_OUT_NAMES_WITH_KEYS ...]
                         使用哪些键的值作为输出文件名
+
 ```
 
 通过一个例子描述会更为清楚：
 ```shell
 python app_main.py -t "examples/成绩排名证明/成绩排名证明（推免）模板_tpl.docx" -f "examples/成绩排名证明/2022级智能建造学生成绩排名_datafeed.xlsx" --tab-start-from-row 2 --custom-out-names-with-keys stu_id stu_name
 ```
 
-
 ## 其他文件的说明
 `ttvduw.py`: 底层实现
 `ttvduw_gui.py`: 图形用户界面代码
 `test_ttvduw.py`: 测试代码
 
+## 构建Windows的二进制包
+```powershell
+# 构建
+pip install -r requirements_with_pyinstaller.txt
+pyinstaller -n TTVDUW app_main.py
+# 运行构建的二进制包
+.\dist\TTVDUW\TTVDUW.exe
+```
+
 ## 功能完善路线图
 目前app只有命令行界面，这对广大不熟悉命令行的职员们来说简直就是灾难。考虑实现
 - [x] 一个简单的图形用户界面（使用Python自带的tkinter包）
 
 让职员们去配置Python环境也是对大家的折磨。考虑使用[PyInstaller](https://www.pyinstaller.org/)
-- [ ] 打包
+- [x] 打包
 
-目前键值数据表只实现了xlsx的支持，后续还希望实现对
+目前键值数据表只实现了xlsx的支持，后续还希望实现csv、xls支持。（看起来没多少事实际上界面各种逻辑估计涉及不少重写）
 - [ ] csv （通过Python自带的csv包）
 - [ ] xls （通过[xlrd](https://xlrd.readthedocs.io/en/latest/)包）
-的支持。
 
 ## Credits & References
 开发工作还受到下面的资料的启发