ACMer 一键板子导出工具 cpps2md

这是我的个人开源项目，Github 自取 jamhus-tao/cpps2md，本来是给自己用的，当然也希望帮助更多人。

cpps2md @Jamhus Tao

简介

这是一个 cpp 转 markdown 脚本，主要用于 ACMer 整理板子。如果你不是 ACMer（参与大学生程序设计竞赛的人），这个项目或许对你没有什么帮助。众所周知，ACM 系列赛事允许赛时使用纸质资料，于是每到赛前都需要将之前的练习整理成册打印出来，这是一个繁琐的工作。

通过该工具，你只需要将所有待打印的练习，分门别类地整理到一个文件夹内，运行脚本就可以整理成单一的 Markdown 文件。然后使用你喜欢的方式打印该 Markdown 文件。

本工具为命令行工具，运行窗口简陋，但功能实用。同时支持 .cpp 和 .md 文件格式、支持板子增量式打印。也就是说工具会检测你相较于上一次更改了哪些文件并且只导出它们。

演示

原来的文件夹长这样，其中 .bin 放了我的工具，.out 放了工具导出的文件，其他几个可以无视。

运行脚本导出到 .out 文件夹。

然后我使用 Typora 将它转为 PDF。

很好，现在装订成册了。

快速开始

安装环境依赖

必须安装 Git 并且将其配置到环境变量，本工具使用 Git 管理你的代码。Git - Downloads
建议安装 Typora ，后面关于 PDF 导出推荐使用 Typora。Typora 官方中文站

构建目录结构

本工具必须运行在特定的目录结构下，这也是我出于更方便实用工具这样设计的。

如图是我们放置文件的根目录，而工具及其配置文件必须位于其 .bin 目录下，就是第一个，否则是无法运行的。

再次强调，注意上图示例中，工具及其配置文件与文件目录的路径关系。

另外，如果你使用默认配置，所有以 . 开头或包含英文 ! 的目录、文件都不会被识别。同时目前只识别 .cpp 和 .md 为后缀的文件。

运行工具

在确定目录结构正确后双击运行 cpps2md.exe 即可。

根据提示询问你是否需要只导出相对于上次后的更改内容，通常我们选择 y 表示增量导出，然后会显示哪些内容被检测到，并且准备打印。

回车确认导出，如果中间突然不想导出了直接关闭窗口即可。但回车之后请不要在提示完成前关闭窗口。

如果你进行了错误的操作，可以使用 git 进行回滚，但这首先要求你会使用 git，在开始时键入 Cmd 即可进入命令行模式，在这里直接键入你的 git 命令操作版本。如果在这方面你是小白，请备份好你的版本。不过需要声明，请放心本工具永远不会修改你的代码，只是进行增量导出时，它只会记住最近一个版本，但你可能想从两个版本前进行增量导出。

运行结束时程序会提示文件导出到 .out 文件夹，这时请返回到放置文件的目录，然后找到对应文件。如果你是使用增量导出，同时可能产生 .log 文件，它记录了相对于上次你做了哪些更新，你可以依此重新整理你的板子。

导出文件

直接导出的 .md 文件是不可打印的，你需要将其导出为 PDF，这不属于本工具的功能范围，但这里以 Typora 为例，简单强调几点：

务必打开 偏好设置 - 导出 - PDF - 分页 - 按一级标题分页，否则几篇代码放一页会很难受。
务必打开 偏好设置 - 导出 - PDF - 通用 - 允许 YAML front matters 覆盖当前设置。
建议打开 偏好设置 - Markdown - 代码块 - 显示行号。
文件最前面的 YAML 中 header 和 footer 会被 Typora 识别为页眉和页尾。

拓展工具

pdfOutlineOddPage

这是一个 PDF 小工具，将 PDF 的所有一级标题对齐到奇数页，这样导出的 PDF 可以直接用于双面打印，并且方便检索。本人很喜欢这样的页面设计，于是分离地实现了这个小工具。你可以看到演示中我的 PDF 所有一级标题都在奇数页。

本工具支持拖拽运行，也支持双击打开选择文件。导出文件位于源目录。

全部功能

全目录打印

启动程序时询问 Check the modification? ，回复 N 进入全目录打印。
全目录打印会搜索并打印全部模板，并在 Markdown 头部生成目录。

增量式打印

启动程序时询问 Check the modification? ，回复 Y 进入增量式打印。
增量式打印基于 Git ，仅打印新建、修改的内容，并提示已删除的内容。
查看同时生成的 .log 文件查看更新细节。

命令行模式（首先你需要会使用 Git）

启动程序时输入特殊命令 CMD 进入命令行模式。
命令行模式支持使用 Git 命令行直接对你的仓库进行管理，同时提供了全目录打印 / 增量式打印的快捷命令。
Git 仓库的存储位置是工作目录下的隐藏文件 .git.jamhus 。
在启动命令中添加 -c 开关，启动时自动进入命令行模式。或者运行提供的 cpps2md-c.bat 批处理文件。

拖拽启动

将要打印的文件同时选中，全部拖拽到脚本上，脚本将以参数模式启动。
拖拽的文件尚不支持是文件夹。
拖拽启动不会干扰增量式管理系统，与工作目录无关。

配置选项

配置文件为 config.json。

{
  // Markdown YAML Front Matter，视编辑器而定，为空忽略
  "front_matter": {
    "title": "ACM Code Template",  // PDF 标题
    "author": "Jamhus Tao",        // PDF 作者
    "header": "Jamhus Tao / GreatLiangpi ${today}",  // Typora 页眉
    "footer": "ACM Code Template"                    // Typora 页尾
  },
  // 去除开头文本，如果你的代码以这段文本开始，将在导出时过滤，为空忽略
  "ignore_head": "// Jamhus Tao / GreatLiangpi\n// Start at 2022/10/6\n// Please using int32_t and int64_t to replace the int and long long.\n#include <bits/stdc++.h>\n#define int int64_t\n#define endl '\\n'\n#pragma GCC optimize(3, \"Ofast\", \"inline\")\nusing namespace std;\n",
  // 文件/目录过滤选项，被列表匹配的文件将不导出、目录将不搜索
  "skip": {
    "regex": true,  // 是否使用正则表达式过滤
    "list": [  // 一切以 . 开头的文件/目录被过滤，不可配置
      "^README.md$",
      "^test",
      "^!"     // 你可以在暂时不想打印的文件前加上 ! 标记
    ]
  },
  // 支持文件类型，null 表示直接复制到正文，否则复制到代码块并标注语言
  "file_type": {
    ".c": "cpp",
    ".cc": "cpp",
    ".cpp": "cpp",  // 支持为 cpp 代码块, 如果同时支持多语言, ignore_head 可能对其他语言无效
    ".h": "cpp",
    ".hpp": "cpp",
    ".md": null     // 直接复制到正文，注意 Markdown 不能包含一级标题
  }
}

版本更新

V0.0.0: 初始版本，仅支持对单一文件的打印，不支持目录打印。
V0.1.0: 开始支持多文件打印，并将内容输出到多个文件。
V2.0.0: 重写代码，实现了全目录打印到单一文件。
V2.1.0: 重写代码，基于 git 实现全目录增量式打印，提供相关配置文件，基本确定了 V2.x 原型。
V2.1.7: 性能调优，优化目录搜索方式；修复一些已知问题。
V2.2.0: 增加命令行模式，支持直接使用 git 管理。
V2.2.1: 修改输出排序方式，目录顺序可能与原先不一致。
V2.3.0: 增加拖拽启动，拖拽模式只支持打印多个文件，不可为目录。
pdfOutlineOddPage: 新增拓展工具 pdf outline odd page，与主程序完全分离。
V3.0.0: 重构配置文件为 config.json，增强配置选项。