初始化仓库提交

2026-07-24 12:01:53 +08:00
commit 8851a2167b
15 changed files with 2093 additions and 0 deletions
@@ -0,0 +1,159 @@
+# Technical Report LaTeX Template
+
+[简体中文](README.md) | [English](README_en.md)
+
+This repository provides a LaTeX template for Chinese technical reports. It is suitable for documenting project design, implementation details, test results, troubleshooting records, FAQs, and future plans. A blank template and two complete examples are included for direct reuse.
+
+## Features
+
+- A4 paper, 12 pt text, 2.5 cm margins, and 1.5 line spacing
+- Cover page, automatic table of contents, headers, footers, and version information
+- Preset heading levels, hyperlinks, and color styles
+- Support for code listings, equations, tables, images, and lists
+- Reusable file-description and question-and-answer boxes
+- Preset syntax highlighting for Python and Bash
+
+## Directory Structure
+
+```text
+.
+├─ 模板/
+│  ├─ main.tex          # Blank template ready for editing
+│  └─ 模板.pdf           # Compiled preview of the template
+├─ example/
+│  ├─ 停车机器人example/
+│  │  ├─ main.tex       # Example troubleshooting report
+│  │  ├─ *.png          # Images used by the example
+│  │  └─ *.pdf          # Compiled example document
+│  └─ 旧版个人example/
+│     ├─ main.tex       # Longer personal technical report example
+│     ├─ *.png          # Images used by the example
+│     └─ *.pdf          # Compiled example document
+├─ README.md
+└─ README_en.md
+```
+
+## Requirements
+
+Install a LaTeX distribution that includes XeLaTeX, such as TeX Live or MiKTeX. The template uses `ctex` for Chinese typesetting and depends on the following packages:
+
+```text
+ctex, geometry, titlesec, titletoc, fancyhdr, listings,
+xcolor, graphicx, amsmath, amssymb, booktabs, enumitem,
+tcolorbox, fontawesome5, setspace, hyperref
+```
+
+A full TeX Live installation normally includes these packages. With a minimal installation, use the distribution's package manager to install any missing packages.
+
+## Quick Start
+
+1. Copy `模板/main.tex` to a new document directory.
+2. Edit the document metadata near the beginning of the file:
+
+   ```tex
+   \newcommand{\doctitle}{Technical Document Title}
+   \newcommand{\docsubtitle}{System Design and Implementation}
+   \newcommand{\projectname}{Project Name}
+   \newcommand{\docauthor}{Author}
+   \newcommand{\docversion}{v1.0}
+   \newcommand{\docdescription}{A short document description}
+   ```
+
+3. Edit, duplicate, or remove the sample sections as needed.
+4. Run XeLaTeX twice so that the table of contents and cross-references are updated:
+
+   ```powershell
+   xelatex main.tex
+   xelatex main.tex
+   ```
+
+   If `latexmk` is installed, you can instead run:
+
+   ```powershell
+   latexmk -xelatex main.tex
+   ```
+
+5. Open `main.pdf` in the current directory.
+
+## Common Elements
+
+### Images
+
+Place images next to the `.tex` file or in a subdirectory, then reference them as follows:
+
+```tex
+\begin{figure}[htbp]
+    \centering
+    \includegraphics[width=0.8\linewidth]{images/example.png}
+    \caption{Image description}
+    \label{fig:example}
+\end{figure}
+```
+
+Image paths are relative to the current `.tex` file. When copying an example document, copy its referenced images as well.
+
+### Code Listings
+
+The template defines `pythonstyle` and `bashstyle`:
+
+```tex
+\begin{lstlisting}[style=pythonstyle, caption={Python example}]
+def main():
+    print("Hello")
+\end{lstlisting}
+```
+
+Change the style to `bashstyle` for terminal commands. Other languages can be configured through the `language` option provided by `listings`.
+
+### Question-and-Answer Boxes
+
+```tex
+\begin{qabox}{Write the question here}
+\begin{answerbox}
+Describe the cause, investigation, and solution here.
+\end{answerbox}
+\end{qabox}
+```
+
+### Report Sections
+
+The blank template currently includes the following sections, all of which can be edited or removed:
+
+- Document overview
+- System design
+- Program file descriptions
+- Key methods and principles
+- Implementation details
+- Tests and results
+- Frequently asked questions
+- Future plans and version history
+
+## Examples
+
+- `example/停车机器人example` demonstrates problem descriptions, root-cause analysis, proposed solutions, code snippets, equations, test plans, and image layout.
+- `example/旧版个人example` demonstrates a longer technical report with process descriptions, algorithm details, tables, side-by-side images, Q&A records, and appendices.
+
+Both example directories include compiled PDF files, allowing the final layout to be reviewed without a local LaTeX installation.
+
+## Troubleshooting
+
+### Chinese text is not rendered correctly
+
+Make sure the document is compiled with XeLaTeX rather than the traditional LaTeX command, and verify that Chinese language support and `ctex` are installed.
+
+### A package cannot be found
+
+Install the package named in the error through the TeX Live or MiKTeX package manager. If icon commands are missing, check the `fontawesome5` package in particular.
+
+### The table of contents or references are outdated
+
+Compile the document twice, or run `latexmk -xelatex main.tex` to handle the required passes automatically.
+
+### An image cannot be found
+
+Check the file name, extension, and relative path. When moving or copying an example `main.tex`, include all referenced PNG files.
+
+## License Note
+
+No license file is currently included in this repository. Add an appropriate license or an internal-use notice before redistribution.
+