初始化仓库提交

2026-07-24 12:01:53 +08:00
commit 8851a2167b
15 changed files with 2093 additions and 0 deletions
@@ -0,0 +1,159 @@
+# 技术报告 LaTeX 模板
+
+[简体中文](README.md) | [English](README_en.md)
+
+这是一个面向中文技术报告的 LaTeX 模板，适合整理项目设计、实现说明、测试结果、问题排查、常见问题和后续规划等内容。仓库同时提供空白模板与两个完整示例，可直接复制后修改。
+
+## 模板特点
+
+- A4 纸张、12 pt 字号、2.5 cm 页边距和 1.5 倍行距
+- 包含封面、自动目录、页眉页脚和版本信息
+- 预设多级章节标题、超链接和配色
+- 支持代码块、数学公式、表格、图片和列表
+- 提供文件说明框、问答框等技术文档常用样式
+- 已配置 Python 与 Bash 代码高亮样式
+
+## 目录结构
+
+```text
+.
+├─ 模板/
+│  ├─ main.tex          # 可直接修改的空白模板
+│  └─ 模板.pdf           # 模板编译效果
+├─ example/
+│  ├─ 停车机器人example/
+│  │  ├─ main.tex       # 技术问题排查类报告示例
+│  │  ├─ *.png          # 示例使用的图片
+│  │  └─ *.pdf          # 已编译的示例文档
+│  └─ 旧版个人example/
+│     ├─ main.tex       # 较完整的个人技术报告示例
+│     ├─ *.png          # 示例使用的图片
+│     └─ *.pdf          # 已编译的示例文档
+├─ README.md
+└─ README_en.md
+```
+
+## 环境要求
+
+请安装带有 XeLaTeX 的 LaTeX 发行版，例如 TeX Live 或 MiKTeX。模板使用 `ctex` 处理中文，并依赖以下宏包：
+
+```text
+ctex, geometry, titlesec, titletoc, fancyhdr, listings,
+xcolor, graphicx, amsmath, amssymb, booktabs, enumitem,
+tcolorbox, fontawesome5, setspace, hyperref
+```
+
+完整安装的 TeX Live 通常已包含这些宏包；使用精简安装时，可能需要通过发行版的包管理器补充安装。
+
+## 快速开始
+
+1. 复制 `模板/main.tex` 到新的文档目录。
+2. 修改文件开头“可修改的文档信息”区域：
+
+   ```tex
+   \newcommand{\doctitle}{XXXX技术文档}
+   \newcommand{\docsubtitle}{XXXX系统设计与实现}
+   \newcommand{\projectname}{XXXX项目}
+   \newcommand{\docauthor}{XXXX}
+   \newcommand{\docversion}{v1.0}
+   \newcommand{\docdescription}{文档简介}
+   ```
+
+3. 按需修改、复制或删除正文中的示例章节。
+4. 使用 XeLaTeX 编译两次，以正确生成目录和交叉引用：
+
+   ```powershell
+   xelatex main.tex
+   xelatex main.tex
+   ```
+
+   如果已安装 `latexmk`，也可以使用：
+
+   ```powershell
+   latexmk -xelatex main.tex
+   ```
+
+5. 编译完成后，在当前目录查看 `main.pdf`。
+
+## 常用内容
+
+### 插入图片
+
+将图片放在 `.tex` 文件所在目录或其子目录中，然后使用：
+
+```tex
+\begin{figure}[htbp]
+    \centering
+    \includegraphics[width=0.8\linewidth]{images/example.png}
+    \caption{图片说明}
+    \label{fig:example}
+\end{figure}
+```
+
+图片路径相对于当前 `.tex` 文件。复制示例文档时，请同时复制其引用的图片。
+
+### 插入代码
+
+模板预设了 `pythonstyle` 和 `bashstyle`：
+
+```tex
+\begin{lstlisting}[style=pythonstyle, caption={Python 示例}]
+def main():
+    print("Hello")
+\end{lstlisting}
+```
+
+将 `style` 改为 `bashstyle` 可展示终端命令。其他语言可以通过 `listings` 的 `language` 参数自行配置。
+
+### 插入问答框
+
+```tex
+\begin{qabox}{这里填写问题}
+\begin{answerbox}
+这里填写原因、排查过程和解决方法。
+\end{answerbox}
+\end{qabox}
+```
+
+### 调整章节
+
+空白模板目前包含以下内容，可根据实际报告自由删改：
+
+- 文档概述
+- 系统设计
+- 程序文件说明
+- 关键方法与原理
+- 实现说明
+- 测试与结果
+- 常见问题
+- 后续规划与版本记录
+
+## 示例说明
+
+- `example/停车机器人example`：展示问题描述、原因分析、解决思路、代码片段、公式、测试计划和图片排版。
+- `example/旧版个人example`：展示篇幅较长的技术报告，包括流程说明、算法原理、表格、双图排版、问答记录和附录。
+
+两个示例目录均保留了已编译 PDF，可在未安装 LaTeX 环境时先查看最终排版效果。
+
+## 常见问题
+
+### 中文无法正常显示
+
+优先确认使用的是 XeLaTeX，而不是直接使用传统 LaTeX 命令；同时确认 TeX 发行版已安装中文支持和 `ctex`。
+
+### 提示找不到宏包
+
+根据错误信息，通过 TeX Live 或 MiKTeX 的包管理器安装对应宏包。若缺少图标相关命令，请重点检查 `fontawesome5`。
+
+### 目录或引用没有更新
+
+连续编译两次，或使用 `latexmk -xelatex main.tex` 自动处理多轮编译。
+
+### 图片无法找到
+
+检查文件名、扩展名和相对路径是否一致。移动或复制示例的 `main.tex` 时，也需要带上它引用的 PNG 文件。
+
+## 说明
+
+仓库中未提供许可证文件。使用或分发前，请根据实际归属补充许可证或内部使用说明。
+