# 技术报告 LaTeX 模板

[简体中文](README.md) | [English](README_en.md)

这是一个面向中文技术报告的 LaTeX 模板，适合整理项目设计、实现说明、测试结果、问题排查、常见问题和后续规划等内容。仓库同时提供空白模板与两个完整示例，可直接复制后修改。

如果不想在本地安装和配置 LaTeX 环境，推荐直接使用 [Overleaf](https://www.overleaf.com/) 在线编辑和编译。Overleaf 提供免费版，无需安装软件，注册后上传模板即可使用。

## 模板特点

- 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
```

## 推荐方式：Overleaf 在线编译

对于初次使用 LaTeX 或不方便配置本地环境的用户，Overleaf 免费版通常足以编辑和编译本模板。

1. 将 `模板` 目录中的 `main.tex` 压缩为 ZIP 文件。请让 `main.tex` 位于压缩包根目录。
2. 登录 Overleaf，选择 **New Project → Upload Project**，上传 ZIP 文件。
3. 打开项目左上角的 **Menu**，将 **Compiler** 设置为 **XeLaTeX**。
4. 修改 `main.tex`，然后点击 **Recompile** 生成 PDF。
5. 需要本地保存时，在 Overleaf 中下载生成的 PDF 或整个项目源码。

使用示例文档时，应将对应目录下的 `main.tex` 和 PNG 图片一起压缩上传，否则图片无法显示。具体上传方法可参考 [Overleaf 官方上传指南](https://www.overleaf.com/learn/latex/Kb/Uploading_a_project)。

> Overleaf 免费版存在编译时长等资源限制，但对本仓库中的普通技术报告通常已经够用。较大的图片、复杂内容或较长文档如果触发限制，可以压缩图片或改用本地编译。

## 本地编译环境

只有需要离线编译时，才需要安装带有 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. 将文档上传至 Overleaf，并将编译器设置为 XeLaTeX；或者在本地使用 XeLaTeX 编译两次，以正确生成目录和交叉引用：

   ```powershell
   xelatex main.tex
   xelatex main.tex
   ```

   如果已安装 `latexmk`，也可以使用：

   ```powershell
   latexmk -xelatex main.tex
   ```

5. 编译完成后，在 Overleaf 的 PDF 预览区查看或下载结果；本地编译时可在当前目录查看 `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 环境时先查看最终排版效果。

## 常见问题

### 中文无法正常显示

在 Overleaf 项目菜单或本地编译命令中确认使用的是 XeLaTeX，而不是传统 LaTeX 编译器。本地编译时还需确认 TeX 发行版已安装中文支持和 `ctex`。

### 提示找不到宏包

根据错误信息，通过 TeX Live 或 MiKTeX 的包管理器安装对应宏包。若缺少图标相关命令，请重点检查 `fontawesome5`。

### 目录或引用没有更新

连续编译两次，或使用 `latexmk -xelatex main.tex` 自动处理多轮编译。

### 图片无法找到

检查文件名、扩展名和相对路径是否一致。移动或复制示例的 `main.tex` 时，也需要带上它引用的 PNG 文件。

## 说明

仓库中未提供许可证文件。使用或分发前，请根据实际归属补充许可证或内部使用说明。