Commit 024c1989 authored by Daewon Lee's avatar Daewon Lee
Browse files

Update of the README file

parent 4db8e205
Loading
Loading
Loading
Loading
+95 −0
Original line number Diff line number Diff line
# Example LaTeX Implementation of TS38.201

[TOC]

## Introduction

This repository is an example implementation of TS 38.201 V19.0.0.

TS38.201 is a short specification that showcases basic specification drafting, including insertion of figures and tables, use of bullets, and mixture of mathematical expressions within table entries.

While the LaTeX version of the TS has been drafted to replicate all the formatting of the TS, not every single formatting may have been replicated perfectly. This does not imply limitation of LaTeX formatting but it is due to how the example was created.

## Basic Setup for Perquisites

### Git Setup 

Download and install git from [https://git-scm.com](https://git-scm.com).

Download this repository using command line git commands.

> git clone https://forge.3gpp.org/rep/fs_6gspecs_new/interdigital_latex_38201.git *destination-folder-name*

Alternatively, please use GUI application clients for git. List of graphical user interface (GUI) clients for Git is available [here](https://git-scm.com/tools/guis).

Most git GUI are intuitive to use. So method for cloning a git repository using a GUI is omitted here. Few suggested free git GUI are
- [GitExtensions](https://gitextensions.github.io/) (for Windows only),
- [SourceGit](https://sourcegit-scm.github.io/) (for Windows/Mac/Linux), and
- [SourceTree](https://www.sourcetreeapp.com/) (for Windows/Mac).

Please note git installation is required for GUI clients to work properly as they only provide GUI.

### LaTex Setup

In order to use LaTeX compiling and view generated PDF locally, you will need to first install TeX. There are two recommended choices for TeX installation.

- [MikTeX](https://miktex.org/) (available for Windows/Max/Linux)
- [TeXLive](https://www.tug.org/texlive/) (available for Windows/Max/Linux)

The main differences between MikTeX and TeXLive is that MikTeX only installs basic packages for LaTeX and installs any additional packages on the fly (from the internet), whereas TeXLive stores all packages locally and does not require internet connection after installation. For MikTeX, the package installation is one-time event for each packet. After the packages are downloaded locally, no further internet connection would be necessary.

It is also recommended to use a LaTeX editor. There are a number of free/commercial LaTeX editors available. You can find a non-comprehensive list [here](https://en.wikipedia.org/wiki/Comparison_of_TeX_editors). The following are some recommended choices for LaTeX editors:

- [TeXStudio](https://www.texstudio.org/) - Windows only application client, supports side-by-side view of generated PDF, and inverse search\*
- [TeXShop](https://pages.uoregon.edu/koch/texshop/) - Mac only application client, supports side-by-side view of generated PDF, and inverse search\*
- [LyX](https://www.lyx.org/) - Windows/Mac/Linux application client, supports What You See Is What You Mean (WYSIWYM), and inverse search\*
- [LaTex Workshop - Visual Studio Extension](https://marketplace.visualstudio.com/items?itemName=James-Yu.latex-workshop) - VScode extension that allows compiling and viewing of LaTeX code in VScode. When used with MikTeX, it requires a separate installation of perl on your local computer.

Note \*: Inverse search means that one can locate the relevant part of the source code from the viewer (e.g., double-clicking in dvi or pdf file brings up the appropriate line/paragraph in the latex code).

### Perl Setup

Perl installation is not strictly required for LaTeX compilation. However, `latexdiff` which is suggested to be used for reviewing the differences between updates of LaTeX results in user friendly manner, is written in perl.

To use `latexdiff` scripts, Perl installation is required.

For Windows, [strawberry Perl](https://strawberryperl.com/) is recommended.
- Once installed, please add the perl binary folder to the `PATH` environmental variable. Just search for *edit path environment variable on windows* and you should be able to find many articles explaining how to edit the `PATH` environmental variable on windows.

For Mac, perl should be pre-installed with Mac OS X. 
- Open a Terminal application (in the Utilities folder of your Applications folder) and run `perl -v` to find out which version.

## Compiling LaTeX to PDF

Compiling LaTeX to PDF largely depends on which LaTeX processor application being used. The following example shows an example of LaTeX compile to view and edit source TeX file and view the compiled PDF based on **TeXStudio** on Windows.

In **TeXStudio**, PDF can be compiled and viewed side-by-side by click on fast-forward button on the top.

![TexStudio compile button](media\texstudio-pdf.png)

### Configuration of default LaTeX Compiler

There are several methods of compiling LaTeX. Most commonly used LaTeX compiler is `pdfLaTeX`, which is the one of the fastest PDF compilers for LaTeX and has great compatibility with most packages. `pdfLaTeX` unfortunately lacks support for modern fonts and unicode characters.

Alternative suggested default compiler is `LuaLaTeX`. `LuaLaTeX` supports advanced scripting using Lua, native unicode (UTF-8), and native (OpenType/TrueType) system fonts. It has the disadvantage of taking longer to compile the PDF.

The initial implementation of the TS was drafted to be compiled with either `pdfLaTeX` or `LuaLaTeX`. The latter will have slight better support for certain font formatting such as italic-bold faced san serif font formatting.

In **TeXStudio**, default compiler can be changed from `options` menu -> `Build` tab -> `default compiler` option.

![TexStudio default compiler configuration](media\texstudio-configuration.png)

### Getting Diff View of two LaTeX files

GitLab can show the diff results between files for each commit, as well as any pull requests made for a branch.

A new LaTeX file that shows the change marks of two LaTeX files can be generated using `latexdiff` perl script as follows.

> **perl** .\scripts\latexdiff.pl *old-latex-file.tex* *new-latex-file.tex* > *diff-latex-file.tex*

- You may replace 'diff-latex-file.tex' with any file name. 
- **Note :** the generated diff tex file may not be encoded using UTF-8, which may result in LaTeX compile error. In case, diff tex file does not compile correctly, please open the diff tex file and `save as` using `UTF-8` encoding. This can be done using any number of text editing tools, such as **Notepad++**, **VScode**, or even Windows pre-installed **notepad**.

Example of results of `latexdiff`:

![Example of latexdiff perl script results](media\latexdiff-example.png)
+78.8 KiB
Loading image diff...
+74.7 KiB
Loading image diff...
+171 KiB
Loading image diff...