Technical-Report-LaTeX-Template/README_en.md

# 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.