Fudan Logic History

This repository contains the history and documentation for the Fudan Logic Group.

网页数据同步 (Website Data Synchronization)

本仓库将复旦逻辑学官方网站（LogicFudanWebsite）作为子模块（Submodule）引入，并放置在 .website_pages 文件夹中。 为了节省磁盘空间并保持项目整洁，我们对该子模块使用了 浅克隆（Shallow Clone） 与 稀疏检出（Sparse Checkout），仅提取了网站仓库下的 fudanlogic/data/pages 目录。

1. 日常更新网页数据（在已配置好的机器上）

当远端网页仓库有更新时，你只需要在主仓库根目录下运行以下命令，即可拉取网页仓库的最新内容（它会自动维持稀疏检出的状态，只下载 pages 的变动）：

git submodule update --remote .website_pages

更新完成后，如果有新的提交，记得在主仓库中执行 git add .website_pages 并 commit 以保存子模块的版本号变更。

2. 在新电脑上重新配置本项目

如果未来你在其他机器上 git clone 了本仓库，.website_pages 文件夹默认会是空的。 由于该仓库是私有仓库，且我们只需要它的一小部分文件，请在新机器上不要直接运行 git submodule update --init（这会下载网站所有的图片和前端代码，大概几百兆），而是执行以下特定的初始化流程：

# 1. 注册子模块变量（不会立即下载文件）
git submodule init .website_pages

# 2. 使用带有你 Token 的链接，进行极速浅克隆（仅克隆元数据，不检出文件）
# 注意：请将 <YOUR_TOKEN> 替换为你在 Forgejo 上生成的 Access Token
git clone --no-checkout --depth 1 https://ganganray:<YOUR_TOKEN>@git.yangruizhi.cyou/FudanLogicGroup/LogicFudanWebsite.git .website_pages

# 3. 进入子模块，开启并设置稀疏检出（只提取所需文件夹）
cd .website_pages
git sparse-checkout init --cone
git sparse-checkout set fudanlogic/data/pages

# 4. 正式检出文件（此时只会看到 fudanlogic 文件夹）
git checkout main

# 5. 回到主目录，重置 URL（擦除明文密码以防泄漏）并让主仓库接管该子模块
cd ..
git remote set-url origin https://git.yangruizhi.cyou/FudanLogicGroup/LogicFudanWebsite.git
git submodule absorbgitdirs

完成以上步骤后，这台新机器就配置好了完美的只读“稀疏”子模块了。

原始素材转换 Markdown 操作流程 (Source Conversion Workflow)

本仓库将一些原始素材（如 .docx, .pdf）集中放置在 orignal_sources 目录下。我们使用开源的解析工具 markitdown 自动将这些原始文件提取并转换为便于查阅的 .md 格式。

1. 环境准备

为了不污染系统环境，我们在 orignal_sources 目录下建立了一个专属的 Python 虚拟环境（Virtual Environment），你需要先激活它：

cd orignal_sources
source .venv/bin/activate

(注意：由于 .venv 是被 Git 忽略的，如果你在一台新电脑上克隆了本仓库，你需要先重新创建并安装工具：)

cd orignal_sources
python3 -m venv .venv
source .venv/bin/activate
pip install "markitdown[all]"

2. 执行转换

激活环境后（终端前面会带有 (.venv) 提示符），直接使用 markitdown 命令进行转换，并将结果重定向输出为 .md 文件：

# 示例：将 docx 转为 md
markitdown "逻辑学科史.docx" > "逻辑学科史.md"

# 示例：将 pdf 转为 md
markitdown "数理逻辑学程简介202601.pdf" > "数理逻辑学程简介202601.md"

如果你在转换某种新格式（如 PDF、Excel 等）时遇到 MissingDependencyException 的报错，说明你的 markitdown 缺少相应格式的插件，直接补充安装即可（例如执行 pip install "markitdown[pdf]"）。

编写与编译工作流 (Drafting and Compilation Workflow)

我们通过将《学科史》按历史阶段拆分为多个 Markdown 草稿（存放在 draft/ 目录），实现了文档的模块化管理。在定稿时，我们需要将这些草稿拼合，并生成用于正式提交或排版的 .docx 文件。

为了方便自动化处理合并、修复相对路径以及保留空格编码，我们提供了一键编译脚本 build.py。

自动拼合与生成

在项目根目录下，直接运行以下命令：

python3 build.py

该脚本会自动执行以下步骤：

1. 按顺序读取 draft/ 下的所有分章草稿。
2. 自动调整相对路径：将草稿中的 ../orignal_sources/ 自动更正为相对于根目录的 ./orignal_sources/，确保 Fudan_Logic_History.md 可以在任何 Markdown 渲染器中正常显示图片。
3. 生成带内嵌图片的 Word：自动处理文本中的 URL 编码 %20，并调用 pandoc 无损生成内嵌所有高清图片的 Fudan_Logic_History.docx。

(前提：需提前通过 sudo apt install pandoc 安装环境依赖。)

版本发布指南 (Release Guide)

当形成了一个重要版本的终稿后，建议通过 Forgejo 的 Release 功能将最终的 .md 与 .docx 固定为里程碑式的历史存档，便于后续回溯、分享和直接下载。

1. 推送代码与打标签（Tag）： 在本地将你的最新改动提交并推送至远端。

   git add .
   git commit -m "docs: 完成复旦逻辑学学科史最终定稿"
   git push
   git tag v1.0.0
   git push origin v1.0.0
   

2. 在网页端创建 Release： 登录你的 Forgejo 服务器，进入该仓库主页，点击 Tags 或 Releases，找到刚刚推送的 v1.0.0，点击 New Release（发布新版本）。
3. 上传最终交付物： 在 Release 编辑页面中，填写发布说明（如总结字数扩充情况、新章节和附录的增加等）。 将根目录下生成的 Fudan_Logic_History.md 和 Fudan_Logic_History.docx 文件拖拽上传到最下方的 附件 (Attachments) 区域。
4. 点击 Publish release，协作者即可在这个版本页直接下载包含了完整图片的最终排版稿，无需再在本地克隆庞大（包含高清图片素材）的源码库！