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

If you prefer not to install and configure LaTeX locally, use [Overleaf](https://www.overleaf.com/) to edit and compile the template online. Overleaf offers a free plan and requires no local installation: create an account, upload the template, and start editing.

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

## Recommended: Compile Online with Overleaf

For new LaTeX users or anyone who does not want to configure a local toolchain, the Overleaf free plan is generally sufficient for editing and compiling this template.

1. Create a ZIP archive containing `main.tex` from the `模板` directory. Keep `main.tex` at the root of the archive.
2. Sign in to Overleaf and select **New Project → Upload Project** to upload the ZIP file.
3. Open **Menu** in the upper-left corner and set **Compiler** to **XeLaTeX**.
4. Edit `main.tex`, then click **Recompile** to generate the PDF.
5. Download the generated PDF or the complete project source when a local copy is needed.

When using an example document, include its `main.tex` and PNG images in the same ZIP archive; otherwise, the images will be missing. See the [official Overleaf upload guide](https://www.overleaf.com/learn/latex/Kb/Uploading_a_project) for details.

> The Overleaf free plan has resource limits such as a compile timeout, but it is normally sufficient for the technical reports in this repository. If a long document, complex content, or large images reach those limits, optimize the images or compile locally.

## Local Compilation Requirements

Install a LaTeX distribution only if offline compilation is required. Use a 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. Upload the document to Overleaf and select XeLaTeX as the compiler, or run XeLaTeX locally 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. View or download the result from Overleaf's PDF preview. For local compilation, 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 XeLaTeX is selected in the Overleaf project menu or used by the local compile command. For local compilation, also 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.
