175 lines
6.3 KiB
Markdown
175 lines
6.3 KiB
Markdown
# 技术报告 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 文件。
|
||
|
||
## 说明
|
||
|
||
仓库中未提供许可证文件。使用或分发前，请根据实际归属补充许可证或内部使用说明。
|