如何获取 AsciiDoc 中被 include 文件的最后修改时间?
数据小许
结论
使用 Asciidoctor 或 Asciidoctor PDF 时,{docdatetime} 的值不会因 include 而变成章节文件的修改时间。要显示各章的更新时间,可以在构建前读取章节文件的修改时间,为每章生成自定义属性,再在章节中引用。
Asciidoctor 的文档属性说明指出,docdatetime 默认反映入口源文件的最后修改时间,不考虑被包含文件的修改时间。
为什么章节中的值仍然来自 top.adoc?
include 会把目标文件的内容插入当前文档,章节文件不会因此成为单独转换、拥有独立文档属性的文档。因此,把 {docdatetime} 放在章节中,也不会让它重新读取该章节文件的时间。具体处理方式见 include 文档。
{localdatetime} 表示转换发生的时间,也不能用来显示章节文件的修改时间。
用构建脚本生成章节时间属性
下面以两个章节为例,文件名和属性名可以按实际项目调整。
1. 读取章节文件的修改时间
将以下脚本保存为文档目录中的 generate_dates.py,与 top.adoc 放在同一目录:
from datetime import datetime, timezone
from pathlib import Path
root = Path(__file__).resolve().parent
chapters = {
"chapter1-updated": root / "chapters" / "chapter1.adoc",
"chapter2-updated": root / "chapters" / "chapter2.adoc",
}
lines = []
for attribute, path in chapters.items():
updated = datetime.fromtimestamp(
path.stat().st_mtime,
tz=timezone.utc,
).strftime("%Y-%m-%d %H:%M:%S UTC")
lines.append(f":{attribute}: {updated}")
(root / "chapter-dates.adoc").write_text(
"\n".join(lines) + "\n",
encoding="utf-8",
)
脚本使用文件系统的修改时间,统一输出为 UTC。它只生成时间属性文件,不改写章节源文件。
2. 在 top.adoc 的文档头中引入属性
= 协作文档
:doctype: book
include::chapter-dates.adoc[]
include::chapters/chapter1.adoc[]
include::chapters/chapter2.adoc[]
生成的属性文件需要在章节内容之前引入。这里将它放在文档头中,与其他属性一起定义。
在 chapters/chapter1.adoc 中使用对应属性:
== 第一章
最后更新时间:{chapter1-updated}
章节正文。
第二章则使用 {chapter2-updated}。每个章节使用独立的属性名,可以避免共享同一个属性时发生覆盖。
3. 每次转换前重新生成
在文档目录中依次运行:
python3 generate_dates.py
asciidoctor-pdf top.adoc
以上命令假设环境已安装 Python 3 和 Asciidoctor PDF。应把生成步骤加入现有构建流程,否则显示的可能是上一次生成的时间。
使用时需要注意什么?
- 文件系统修改时间不一定等于内容最后一次修改或提交的时间。复制文件、检出仓库或重新生成文件都可能改变它。如果需要“最后一次 Git 提交时间”,应改为从 Git 历史读取,并明确是否计入未提交修改。
- 示例只读取每个章节文件自身的时间。如果章节内部还有
include,这些依赖文件的变化不会自动计入。若需要显示整个章节及其依赖的最后更新时间,需要收集相关文件后取最大时间。 - 独立转换某个章节时,也需要提供对应的时间属性;这里的示例按从
top.adoc统一构建设计。 - 如果构建环境设置了
SOURCE_DATE_EPOCH,内置日期属性可能使用该固定时间。上述脚本直接读取文件修改时间,不会自动遵循这个环境变量;有可复现构建要求时,应统一时间来源策略。相关属性说明
备注:内容仅供参考。
