https://github.com/duckymomo20012/latex-template
Latex template
https://github.com/duckymomo20012/latex-template
dev-container latex latex-template
Last synced: about 1 year ago
JSON representation
Latex template
- Host: GitHub
- URL: https://github.com/duckymomo20012/latex-template
- Owner: DuckyMomo20012
- Created: 2025-01-21T02:19:54.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-03-11T13:34:39.000Z (about 1 year ago)
- Last Synced: 2025-03-11T13:42:12.063Z (about 1 year ago)
- Topics: dev-container, latex, latex-template
- Language: TeX
- Homepage:
- Size: 927 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# :notebook_with_decorative_cover: Table of Contents
- [Getting Started](#toolbox-getting-started)
- [Prerequisites](#bangbang-prerequisites)
- [Run Locally](#running-run-locally)
- [Usage](#eyes-usage)
- [Makefile](#package-makefile)
- [Compile](#computer-compile)
- [Cleanup](#wastebasket-cleanup)
- [Format Code](#sparkles-format-code)
- [Remote Development](#whale-remote-development)
- [FAQ](#grey_question-faq)
- [Contact](#handshake-contact)
- [Acknowledgements](#gem-acknowledgements)
## :toolbox: Getting Started
### :bangbang: Prerequisites
This project requires the following prerequisites:
- Local Development:
- make:
```bash
sudo apt-get update
sudo apt-get -y install make
```
- [TexLive](https://www.tug.org/texlive/): A TeX distribution for Linux,
macOS, and Windows. Required about ~5GB of disk space.
- Remote Development (**recommended**):
- [Docker](https://www.docker.com/) installed locally:
```bash
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
```
### :running: Run Locally
Clone the project:
```bash
git clone https://github.com/DuckyMomo20012/latex-template.git
```
Go to the project directory:
```bash
cd latex-template
```
Compile `all` targets:
```bash
make all
```
Compile `main` (Bachelor thesis):
```bash
make main
```
The generated pdf file will be located at `dist/main.pdf`.
Compile `proposal` (Thesis proposal):
```bash
make proposal
```
The generated pdf file will be located at `dist/proposal.pdf`.
## :eyes: Usage
### :package: Makefile
There are two targets in the `Makefile`:
- `main`: Compile the `main.tex` file, which is the **Bachelor thesis**.
- Usage:
```bash
make main
```
- `proposal`: Compile the `proposal.tex` file, which is the **Thesis proposal**.
- Usage:
```bash
make proposal
```
- `all`: Compile both `main` and `proposal` targets.
- Usage:
```bash
make all
```
- `pretty`: Format the code using `latexindent`.
- Usage:
```bash
make pretty
```
- `clean`: Remove the `dist` directory.
- Usage:
```bash
make clean
```
### :computer: Compile
The compilation process is described in the following steps:
1. Clone the directory tree:
In the next step, we want to output the compiled files to the `dist`
directory, using the option `-output-directory`; however, the `pdflatex` may
write some auxiliary files to the dependency directories (required files by
the main latex file) and it **can't write without those directories created
in the `dist` directory**.
2. Compile the `tex` file:
The `pdflatex` will compile the `tex` file and write the output to the `dist`
directory.
Compile order:
- `main.tex`: `pdflatex` -> `bibtex` -> `pdflatex` -> `pdflatex`.
- `proposal.tex`: `pdflatex` -> `bibtex` -> `pdflatex` -> `pdflatex`.
> **Note**: The pdf files will be **generated with different checksums** on
> each run.
3. Clean up the directory tree:
Sometimes, the `tex` file doesn't have any dependencies, so the cloned
directory tree will have an empty directory. In this case, we should clean up
empty directories.
### :wastebasket: Cleanup
Clean up the `dist` directory:
```bash
make clean
```
### :sparkles: Format Code
The tool `latexindent` is used to format the code, this
[should be shipped with the `TeXLive` distribution](https://latexindentpl.readthedocs.io/en/latest/sec-how-to-use.html#how-to-use-the-script).
To format the code, run the following command:
```bash
make pretty
```
- When running the command, the backup directory `dist/backup` will be created
to store the backup files.
- All the `tex` files will be formatted.
- The `latexindent` will be used to format the code:
- `cruft`: Backup directory stored in `dist/backup`.
- `local`: Configuration file defined in `latexindent.yaml`.
- `overwrite`: Overwrite the original file.
- `silent`: Silent mode.
- `modifylinebreaks`: Modify line breaks.
- Or, you can run the full command:
```bash
latexindent --local=./latexindent.yaml --cruft=./dist/backup --overwrite --silent --modifylinebreaks main.tex
```
Read more about `latexindent` in the
[documentation](https://ctan.org/pkg/latexindent) or on
[Read the Docs](https://latexindentpl.readthedocs.io/en/latest/).
### :whale: Remote Development
#### Introduction
This is the **recommended** way to develop this project. Using Docker provides a
consistent environment for development, quick setup, and teardown. Moreover,
developers don't have to install the `TexLive` distribution on their local
machine, which is quite large.
For remote development, we can use the `Dev Container` feature of the `VS Code`,
which will create a docker container for us and mount the project folder.
#### Setup
Install the extension
[`Dev Containers`](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
in the `VS Code`:
```bash
code --install-extension ms-vscode-remote.remote-containers
```
After the installation, the extension will immediately detect the file
`devcontainer.json` in the project root directory and prompt you to reopen the
project in a container.
#### Configuration
The `devcontainer.json` file is used to configure the development container.
## :grey_question: FAQ
- Can I develop this project on Overleaf?
- Yes, you can. You can use it as an editor, but you still need to commit
those changes to the repository.
- You can find the `Overleaf` template here:
https://www.overleaf.com/read/jwrxbcrmkgfh. You can read more about the
template instructions
[here](https://www.fit.hcmus.edu.vn/vn/LinkClick.aspx?fileticket=uQfVVVLFuE0%3D&tabid=1064&mid=3747).
- Can't remove the `dist` directory?
- If you develop this project in the container, hence the `dist` is created by
the container, you can't remove it without changing the owner of the `dist`.
- To remove the `dist` directory, you have to change the owner:
```bash
sudo chown -R $USER:$USER dist
```
- Then you can remove the `dist` directory:
```bash
rm -rf dist
```
Or you can use the `make` command:
```bash
make clean
```
## :handshake: Contact
Duong Vinh - [@duckymomo20012](https://twitter.com/duckymomo20012) -
tienvinh.duong4@gmail.com
Project Link:
[https://github.com/DuckyMomo20012/latex-template](https://github.com/DuckyMomo20012/latex-template).
## :gem: Acknowledgements
Here are useful resources and libraries that we have used in our projects:
- [Development Containers](https://containers.dev/): An open specification for
enriching containers with development specific content and settings.
- [TexLive](https://www.tug.org/texlive/): A comprehensive TeX system including
all the major TeX-related programs, macro packages, and fonts that are free
software.
- [latexindent](https://github.com/cmhughes/latexindent.pl): latexindent.pl is a
perl script to beautify/tidy/format/indent (add horizontal leading space to)
code within environments, commands, after headings and within special code
blocks.
