Merge branch 'feat/SpecPress' into 'main'

#node_modules

node_modules

#public folder

public

# export folder

export

# log files

*.log

![](./figures/current_git_WoW.png)

## The trial

Interested delegates can login to the 3GPP forge and enter the repository to start playing around with the environment. We think the trial can be open in the sense that delegates can play around without restrictions, however there are a few things which we would highlight hereafter to take into account during the trial. Other options are available and thus this document does not limit what one can do but can give some direction for those new into the tools involved in this trial. For those that would want to get familiar with the git commands and how to perform the steps below via such commands, one can refer to the [Gitlab documentation](https://docs.gitlab.com/user/get_started/).

### Before you start

![](./figures/Change-user-ID.png)

## Provide comments to CRs

On the left side menu, you can click on the option “Merge requests” (or one can directly go to the [link for merge requests](https://forge.3gpp.org/rep/bergstromm/ran2_trial/-/merge_requests)). A list of all available CRs (here called “merge requests”) should appear.  

Click in one of the CRs, which should depict the CR overview as below.

![](./figures/comments.png)

Once the comment is done one can click on “Add comment now” to insert the comment.

## Create CRs

On the trial repository, in the top right, select the vertical ellipsis and select “Request Access”.

![](./figures/request_access.png)

After this step, on the bottom right of the screen it should appear an option to create a merge request “Create MR”. When clicked, this will lead to the merge request view where you can fill in details similar as done in [the first CR](https://forge.3gpp.org/rep/bergstromm/ran2_trial/-/merge_requests/3) (merge request) we provided as example (e.g. the “Description” field and “Labels” could be filled in).

Once done filling in the merge request details, click on “Create merge request” at bottom left.

## Approve/Reject CRs

On the left side menu, you can click on the option “Merge requests” (or one can directly go to the [link for merge requests](https://forge.3gpp.org/rep/bergstromm/ran2_trial/-/merge_requests)). A list of all available CRs (here called “merge requests”) should appear.  

Click in one of the CRs, which should depict the CR overview as below.

![](./figures/merge_request.png)

On the right side menu, note the “Labels” option can be edited. If “Edit” in “Labels” is clicked, the labels applicable to this merge request can be changed. One can look for the specific labels Agreed, Postponed or Rejected and add one of them to the merge request.

## Using SpecPress

SpecPress enables exxporting PDF and/or DOCX files from a subset of Markdown, ASN.1 and JSON files.

### System Requirements

SpecPress requires the following software to be installed on your system:

-   [Git](https://git-scm.com/)

-   [Node.js version 20+](https://nodejs.org/en)

-   [OpenJDK](https://openjdk.org/)

Additionally, if you eould like to use pandoc to convert mardown files into pdf or docx documents you need to install also:

-   [pandoc](https://pandoc.org/installing.html) by [John MacFarlane](https://johnmacfarlane.net/)

-   [MiKTeX](https://miktex.org/download) or [TeX Live](https://tug.org/texlive/) which include `pdflatex`

### Install specpress

To install specpress in your project, simply run the `npm install` command in the root folder of your repository:

```

# move into your project folder "ran2_trial"

cd ./ran2_trial

# install specpress

npm install

```

### Use specpress

Move now into your working directory which can be the source folder `specification` or a subfolder of `specification` folder.

You can define the name of your source folder by setting up the value of the `sourceFolderName` parameter in the `sp.config.json` configuration file.

```

#./sp.config.json

{

    "pathFiguresFolder": "/assets/figures",

    "sourceFolderName": "specification"

}

```

In the working folder you can use the following specpress commands in the terminal:

#### Export a .docx|.html|.pdf file

Specpress enables you to export a file which contains all the specification files from the working folder. The exported file will be saved in the `/ts101/export` folder.

```

# export a pdf file

npx sp_export pdf

# export a docx file

npx sp_export docx

# export a html file

npx sp_export html

# export a pdf file using pandoc

npx sp_export pdf pandoc

# export a docx file using pandoc

npx sp_export docx pandoc

# export a html file using

npx sp_export html pandoc

```

#### Generate UML diagrams from text files using PlantUML

Specpress enables you to automatically generate `.png` files containing UML diagrams using as an input a text file containing a textual description of the UML diagram as presented in the example below:

```

#/src/example.txt

@startuml

Alice -> Bob: Authentication Request

Boby --> Alice: Authentication Response

@enduml

```

The `.png` files are saved in the src subfolder indicated in the `sp.config.json` files.

```

# generale .png files for all the .txt files in the working folder

npx sp_generateUML

# generale .png file for a specific .txt file in the working folder

npx sp_generateUML-file ./example.txt

```

#### Display the specification as a web page

Execute the following commands to display your specification as a webpage on your local http server:

```

#create the /ts101/public/index.html file

npx sp_publish

# start the http server from the /ts101/public folder

# the server is accessible at http://lcalhost:8080

npx sp_serve

```

#### Watch for changes in your source files

```

npx sp_watch

```

The `sp_watch` command will:

-   watch for changes in your specification’s source files `[".asn", ".json", ".md"]` and update the `index.html` file according to your changes,

-   watch for changes in your UML sequence diagrams source files `[".puml", ".txt"]` and generate the corresponding PNG files in the `/ts101/src/assets/figures` folder

#### Start working on your specification

```

npx sp_start

```

The `sp_strat` command is equivalent to running the `sp_pubish`, `sp_watch` and `sp_serve` commands at once.

### About SpecPress

For more information about specpress please refer to:

-   GitHub: [https://github.com/Ericsson/specpres](https://github.com/Ericsson/specpress)

-   NPM: [https://www.npmjs.com/package/specpress](https://www.npmjs.com/package/specpress)

{

  "name": "ran2_trial",

  "version": "1.0.0",

  "description": "The intention of the plan is to try out CR handling. Namely preparing a CR, receiving comments, update the CR based on those comments and approve/reject/postpone a CR. The figure below depicts the main steps in way of working that can be different with Gitlab.",

  "main": "index.js",

  "scripts": {

    "test": "echo \"Error: no test specified\" && exit 1"

  },

  "repository": {

    "type": "git",

    "url": "https://forge.3gpp.org/rep/bergstromm/ran2_trial.git"

  },

  "author": "Mattias Bergstrom (Ericsson)",

  "license": "ISC",

  "devDependencies": {

    "specpress": "^1.1.0"

  }

}

{

	"pathFiguresFolder": "/assets/figures",

	"sourceFolderName": "specification"

}