175 lines
7.0 KiB
Markdown
175 lines
7.0 KiB
Markdown
# 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.
|