〇、概述

0.1 BaLaRe工具简介

LaTeX工具作为批量制作报告的手段具有先天优势：

• 使用UTF8纯文本
• 简单的指令结构
• 丰富的包支持

BaLaRe工具针对批量报告生成情况开发，基于目录结构的tex文件管理工具。

BaLaRe 名称取义“批处理latex报告”，简称BLR。

其简要工作流程为：

1. 选择一个目录作为报告的工作目录，程序自动在此目录下创建一套默认的模板（tex文件、样式或文档类）。模板分为主目录报告模板和子目录报告模板：主目录模板即对所有要生成的报告公用的模板，而子目录模板是在每个报告的独立文件夹下。这些模板都可以进行编辑。
2. 导入批量报告变量表。变量表是一张保存有所有待出报告信息的CSV表单，在表单中包含一些报告的属性值，例如编号、接受人、报告内容等，这些属性被赋予一个变量名，可以在编辑时使用。
3. 定义需要的编译条件。可以在用户界面修改一些条件符号的真值，用于配合if指令，有条件地进行排版输出。
4. 定义多选变量。多选变量可以在任何时刻设置，程序将记录下曾经设置的值，使用时从下拉表中选择。这些变量在编译时生成到特定的文件，在主模板中有对此文件的引用。
5. 编辑报告内容。在报告的列表中选择要编辑的子报告，使用之前定义的变量及符号，完成内容编写。
6. 生成PDF文件。在列表中使用鼠标操作，进行xelatex编译生成报告，并进行查看。

需要注意：BLR本身提供管理和自动生成功能，文件内容编辑必须要搭配xelatex和合适的编辑器（如notepad++）。

BLR工具的管理模式不影响版本管理软件（如git）的使用。

0.2 版本更新

• 2.0.4 记录窗口状态
• 2.0.3 从文件夹构建模板项列表
• 2.0.2 远程模板项
• 2.0 程序拓展为基于文件夹的项目管理程序
• 1.0 基于分散文件的批量latex文档生成程序

0.3 获取

点击此处下载最新发布
通过邮件获取最新的运行版本。

一、项目

BLR基于文件夹进行管理，若一个 文件夹a 内包含名为 .balare 的子文件夹，则该 文件夹a 可被BLR识别为一个项目。

• 新建项目：即在用户指定文件夹中生成.balare子文件夹，并使用默认模板生成必要配置文件。
• 打开项目：浏览到用户指定的文件夹，若其为BLR项目文件夹，则可打开，BLR对配置文件加载解释，随后可以操作。
• 删除项目：BLR不提供删除项目功能，您可根据需要删除.balare子文件夹以取消BLR支持。

在程序菜单“项目”中，可进行新建和打开项目的操作。程序会记录最近5次打开的项目以供快速操作。生配置改动的项目，在关闭或打开其它项目时会提示保存。已经失效的项目（如目录已不存在）可在启动界面上点击红色X按钮移除。

项目的批变量、映射、条件、用户变量、模板复制定义、本地模板、以及其它必要配置均保存在项目文件夹中。

二、批变量表

BLR围绕批变量表进行操作。一个BLR项目应有一个批变量表及其变量映射文件构成基本的项目列表，列表中的每一项可单独生成一份子报告。每个项由指定的主键作为唯一标识，在执行操作时，BLR以该主键的值创建子文件夹。

2.1 批变量表及映射文件格式

批变量表和映射均是以utf-8格式保存的csv文件，您可以在excel等电子表格软件中创建。

批变量表文件本质为一份关系型数据表，首行为列名称，其余行为数据；映射文件的每一行为 数据表列名 与 BLR变量名 的字符串对。

如图所示，在电子表格工具中编辑并保存成为csv文件，映射文件将列表中的首行列名对应成为BLR变量名。在格式上，有如下约定：

• 设置主键列：批变量表应设置一列作为主键列，用于唯一标识数据行。上例中以“名称”作为主键列。主键列宜使用数字，以避免创建子文件夹时的命名冲突。
• 非强制映射：在上例中，映射文件包含了表格中所有的三个列，但您可以根据需要，仅映射指定的几个列。需要注意，主键列必须设置映射；未被映射的列将不会在BLR程序中显示，也不会参与生成。
• csv格式：建议使用utf-8编码，但也可使用ANSI编码，只是不利于版本管理时的预览。
• 关于变量名：BLR变量名用于在xelatex中使用，因此应符合其要求，即仅使用大小写英文字母，不可使用中文及符号。为避免与引用tex包定义的变量冲突，建议采用 BlrVarXxx 的格式。

2.2 在项目中设置批变量表

通过BLR程序菜单“编辑” – “导入批变量表” 及 “导入批变量映射”，分别浏览到文件所在位置进行加载。此加载过程将复制指定文件到项目.balare目录下，并替换现有文件。

在设置新建项目时，建议先导入映射，再导入批变量表，以使程序正确显示表格内容。若界面内容未能如预期显示，请重新启动程序打开项目即可。

在程序界面的“批变量表”tab页上，选择主键列的变量名，如下图所示。

三、模板

3.1 基本tex文件结构

BLR用于管理latex文件，对文件的编译过程需要latex文件满足一定的组织结构。能够支持BLR正确运行的结构（或称基本tex结构）为：

• 位于项目根目录下的主报告入口文件（记为 main）
• 位于项目根目录下的子报告入口文件（记为 sub）
• 位于单项子目录下的汇总引用代理文件 （记为 agent）

您也可以在main中对其它文件进行引用，形成更为复杂的结构。默认情况下，BLR程序指定的项目文件夹内不包含这些文件，您可以自行创建这些文件，并在程序的“配置属性”tab页中指定这些文件的名称（可修改默认值）。

如上图所示，程序默认的基本文件架构为：

• main：AggregateMain.tex，即执行汇总编译时，在项目根目录下寻找此文件名，作为主文件；
• sub：SeparateMain.tex，即执行单项编译时，在项目根目录下寻找此文件名，作为主文件；
• agent：Agent.tex，即执行汇总编译时，在单项子目录下寻找此文件名，并在临时引用文件中引用。

3.2 模板

为重用复杂的tex文件结构，可以利用预先制作的tex等文件，当需要创建编译文件时，从特定目录进行复制即可。在BLR中提供这种支持，称为模板。模板包含主文档模板和子文档模板，分别为：

• 主文档模板：定义要复制到项目文档根目录的文件。
• 子文档模板：定义要复制到单项子目录下的文件。

复制时支持文件夹创建和深度迭代。

BLR支持 本地 和 远程 两种模板复制方案。

3.2.1 本地模板

在项目的.balare文件夹下，有temp子文件夹，该文件夹为本地模板根目录，模板文件均存放在此。

在BLR程序的菜单“模板” – “打开模板目录” 可以打开本地模板目录；“重置模板” 将删除项目本地模板所有文件；“在文档目录套用模板” 根据 “模板复制项”tab页的配置进行模板复制。

在菜单“编辑”中，“导入模板” 和 “导出模板” 可以将本地模板导出/导入（以.bzip压缩文件格式）。

在程序的“模板复制项” – “主文档复制项”/ “子文档复制项” tab页的 “项目源” 部分，可设置要从本地模板复制的文件。可执行的操作包括：新建/编辑/移除复制项、执行单个文件复制（>>按键，仅对主文档复制项可用）、列表排序、及从文件夹构建列表。从文件夹构建列表是指：浏览到指定文件夹，遍历文件夹中的文件，每个文件生成一个复制项。

3.2.2 远程模板

指定一个远程地址（网址），以及对应的本地位置，执行复制时下载。

在BLR程序的“模板复制项” – “主文档复制项”/“子文档复制项” tab页的 “远程源” 部分，可以设置要从远程复制的文件。可执行的操作包括：新建/移除复制项、执行单个文件复制（>>按键，仅对主文档复制项可用）、列表排序（以本地名称）、及从文件夹构建列表。从文件夹构建列表是指：浏览到指定文件夹，遍历文件夹中的文件，每个文件生成一个复制项。

如上图所示，每一条远程模板复制项由源（左侧）和目标（右侧）构成。

四、条件与用户变量

批变量保存的是项目文档目标的参数信息，例如，需要为n家企业出具报告，则批变量中每一条对应每一家企业。除批变量外，还可以定义编译条件、一般变量和随机变量，分别在程序相应tab页中设置。

1. 编译条件：定义tex中if符号，通过勾选/取消将该值设置为true或false。条件符号可以在编辑文件时使用。
2. 一般变量：定义tex变量（文本指令），变量的取值可保持在记忆下拉列表中，从列表中选取的值作为编译时的变量取值。
3. 随机变量：定义tex变量（文本指令），在记忆下拉列表中定义若干个可选的值，在编译时，变量的实际取值从列表中随机选取。

条件和变量符号仅使用大小写英文字母，不可使用中文及符号。为避免与引用tex包定义的变量冲突，建议采用有明确区别的前缀格式。

五、编辑和编译

5.1 配置环境

根据以上描述加载需要的批变量和模板，定义条件和参数。

在程序 “批变量表” tab页中表格中，在特定行处通过 单击鼠标左键/双击鼠标右键/选定后敲击回车键 可唤出单项上下文菜单，执行针对子文件的操作。

在程序“批变量表” 单击右上角 “汇总操作” 打开汇总上下文菜单，执行汇总文档操作。

5.2 编译子文档（单项编译）

首先通过上下文菜单 “创建子目录”，该操作生成以指定标记主键为名称的文件夹，并根据复制项配置复制模板文件到子文件夹。

在上下文菜单的 “编辑内容文件” 中选择子文件夹下需要编辑的文件打开，编辑文件需要使用第三方编辑器。

在上下文菜单的 “编译选中” 执行xelatex编译，一般应执行此操作两次，以正确构建PDF文件。

编译完成后在上下文菜单的 “查看PDF”，用第三方工具打开文件查看。

5.3 编译汇总文档（汇总编译）

汇总文档操作的编译执行过程与子文档类似，但可以选择参与编译的单项、并可以按照界面排序顺序引用。

在“汇总操作”菜单中，可以全选/全不选单项；在单项上下文菜单中，可以选择或取消选择当前单项。汇总编译仅对已经选中的单项有效。

通过点击批变量界面列表列头，可实现依据特定列的排序。例如，您可以在定义批变量表时专门设置一个用于排序的列（不同于主键），以避免需要重新排序时更改主键列的取值（更改主键取值将导致子文件管理混乱）。