Update README file

## Tools

## Tools

- [changemarks.py](https://git.onem2m.org/tools/scripts/generateCR/changemarks) is in charge of generating a set of markdown files (one file per modified clause) containing the changes (additions and deletions) being made by the Merge Request. Additions are marked as underlined text and deletions as striked text. 

- [changemarks.py](https://forge.etsi.org/rep/cti/tools/-/blob/master/generateCR/changemarks.py?ref_type=heads) is in charge of generating a set of markdown files (one file per modified clause) containing the changes (additions and deletions) being made by the Merge Request. Additions are marked as underlined text and deletions as striked text. 

- [addTrackedChanges.py](https://git.onem2m.org/tools/scripts/generateChangemarks/addTrackedChanges) is in charge of converting the underlined and striked text in Word documents to tracked changes insertions and deletions respectively. It uses the Merge Request information to set the author and date of the changes.  

- [addTrackedChanges.py](https://forge.etsi.org/rep/cti/tools/-/blob/master/generateCR/addTrackedChanges.py?ref_type=heads) is in charge of converting the underlined and striked text in Word documents to tracked changes insertions and deletions respectively. It uses the Merge Request information to set the author and date of the changes.  

All those scripts are dockerized into the same Docker image named [forge.etsi.org:5050/cti/tools/generatecr]

All those scripts are dockerized into the same Docker image named [forge.etsi.org:5050/cti/tools/generatecr:master](https://forge.etsi.org/rep/cti/tools/container_registry/15)

# Generation of baseline documents (generateBaseline)

# Generation of baseline documents (generateBaseline)

## Tools

## Tools

- [generateTOC.py](https://git.onem2m.org/tools/scripts/generateBaseline/generateTOC) is in charge of generating the Table of Content for a markdown file. 

- [generateTOC.py](https://forge.etsi.org/rep/cti/tools/-/blob/master/generateBaseline/generateTOC.py?ref_type=heads) is in charge of generating the Table of Content for a markdown file. 

- [pandocFilter.py](https://git.onem2m.org/tools/scripts/generateBaseline/pandocFilter) is in charge of adapting the markdown files (ToC references, figure captions, table captions, ...) as required by Pandoc to be used as input.

- [pandocFilter.py](https://forge.etsi.org/rep/cti/tools/-/blob/master/generateBaseline/pandocFilter.py?ref_type=heads) is in charge of adapting the markdown files (ToC references, figure captions, table captions, ...) as required by Pandoc to be used as input.

- [svg2png.py](https://git.onem2m.org/tools/scripts/generateBaseline/svg2png) is in charge of converting SVG images to PNG for easy Pandoc processing.  

- [svg2png.py](https://forge.etsi.org/rep/cti/tools/-/blob/master/generateBaseline/svg2png.py?ref_type=heads) is in charge of converting SVG images to PNG for easy Pandoc processing.  

All those scripts are dockerized into the same Docker image named [forge.etsi.org:5050/cti/tools/generatebaseline]

All those scripts are dockerized into the same Docker image named [forge.etsi.org:5050/cti/tools/generatebaseline](https://forge.etsi.org/rep/cti/tools/container_registry/17)

# Generation of specification web site (generateSpecWebSite)

# Generation of specification web site (generateSpecWebSite)

## Tools

## Tools

- [toMkdocs.py](https://git.onem2m.org/tools/scripts/generateSpecWebSite/toMkdocs) is in charge of generating the necessary set of files for Mkdocs from the markdown specification to be published on the web. 

- [toMkdocs.py](https://forge.etsi.org/rep/cti/tools/-/blob/master/generateSpecWebSite/toMkdocs.py?ref_type=heads) is in charge of generating the necessary set of files for Mkdocs from the markdown specification to be published on the web. 

- [mkdocs.yaml](https://git.onem2m.org/tools/scripts/generateSpecWebSite/mkdocs.yaml) is the Mkdocs config file.

- [spec_on_pages.sh](https://forge.etsi.org/rep/cti/tools/-/blob/master/generateSpecWebSite/spec_on_pages.sh?ref_type=heads) is in charge of publishing the specification on the web by using toMkdocs (to prepare input) and Mike (based on Mkdocs) for the publication. It deals with the multiversion handling for the specification web site.  

- [spec_on_pages.sh](https://git.onem2m.org/tools/scripts/generateSpecWebSite/spec_on_pages) is in charge of publishing the specification on the web by using toMkdocs (to prepare input) and Mike (based on Mkdocs) for the publication. It deals with the multiversion handling for the specification web site.  

- [gridTableFilter.py](https://forge.etsi.org/rep/cti/tools/-/blob/master/generateSpecWebSite/gridTableFilter.py?ref_type=heads) is a standalone script to replace grid tables in a markdown file to html tables. It can be used in Markdown Viewers which do not support grid tables as a pre-filter.  

- [gridTableFilter.py](https://git.onem2m.org/tools/scripts/generateSpecWebSite/gridTableFilter) is a standalone script to replace grid tables in a markdown file to html tables. It can be used in Markdown Viewers which do not support grid tables as a pre-filter.  

All those scripts are dockerized into the same Docker image named [forge.etsi.org:5050/cti/tools/generatespecwebsite](https://forge.etsi.org/rep/cti/tools/container_registry/18)

All those scripts are dockerized into the same Docker image named [forge.etsi.org:5050/cti/tools/generatespecwebsite]

# Other markdown tools (markdownTools)

# Other markdown tools (markdownTools)

## Tools

## Tools

- [processMDSpec.py](https://git.onem2m.org/tools/scripts/markdownTools/processMDSpec) is in charge of combining markdown documents into a single one when '''::include''' feature is used. It can also handle the front matter  

- [processMDSpec.py](https://forge.etsi.org/rep/cti/tools/-/blob/master/markdownTools/processMDSpec.py) is in charge of combining markdown documents into a single one when '''::include''' feature is used. It can also handle the front matter  

All those scripts are dockerized into the same Docker image named [forge.etsi.org:5050/cti/tools/markdowntools]

All those scripts are dockerized into the same Docker image named [forge.etsi.org:5050/cti/tools/markdowntools](https://forge.etsi.org/rep/cti/tools/container_registry/19)

# How it works

# How it works

The pipeline folder contains several scripts that deal with the generation of CR, baseline and web site specifications using the different feature sets mentioned aboved. These scripts are to be customized depending on the needs:

The pipeline project for a specific project should contain the following scripts to deal with the generation of CR, baseline/draft and web site specifications using the different feature sets mentioned aboved. These scripts are to be customized depending on the needs:

## Generation of CR

## Generation of CR

The generation of a Word Change Request document is launched upon creation of a Merge Request. The [generateChangemarks](https://git.onem2m.org/tools/scripts/pipeline/generateChangemarks) script implements the following steps:

The generation of a Word Change Request document is launched upon creation of a Merge Request. The [Example: generateChangemarks](https://git.onem2m.org/tools/scripts/-/blob/master/pipeline/generate_changemarks.sh?ref_type=heads) script implements the following steps:

- Step 1. Generation of the set of markdown files containing the changes being made by a Merge Request BY [forge.etsi.org:5050/cti/tools/generatecr changemarks.py](https://git.onem2m.org/tools/scripts/generateCR/changemarks). 

- Step 1. Generation of the set of markdown files containing the changes being made by a Merge Request BY [forge.etsi.org:5050/cti/tools/generatecr changemarks.py](https://forge.etsi.org/rep/cti/tools/container_registry/15). 

- Step 2. Preparation of the Change Request Word document BY [forgelib](forge.3gpp.org:5050/tools/3gpp-scripts/forgelib:v2.22.0) tool:

- Step 2. Preparation of the Change Request Word document BY [forgelib](https://forge.3gpp.org/rep/tools/3gpp-scripts/container_registry/5) tool. The forgelib tool can have the following parameters:

    - [onem2m-coversheet-template.docx](https://git.onem2m.org/tools/scripts/pipeline/onem2m-coversheet-template.docx) is used as template for the coversheet. It gets filled in by information from the Merge Request (Merge Request details and description)

    - Coversheet template: It is used as template for the coversheet. It gets filled in by information from the Merge Request (Merge Request details and description) [Example: onem2m-coversheet-template.docx](https://git.onem2m.org/tools/scripts/-/blob/master/pipeline/onem2m_coversheet_template.docx?ref_type=heads)

    - [onem2m-delimiter-start.docx](https://git.onem2m.org/tools/scripts/pipeline/onem2m-delimiter-start.docx) and [onem2m-delimiter-end.docx](https://git.onem2m.org/tools/scripts/pipeline/onem2m-delimiter-end.docx) are the change delimiter template to be insertion between changes.

    - Delimiter templates: These are the change delimiter template to be inserted between changes.[Example: onem2m-delimiter-start.docx](https://git.onem2m.org/tools/scripts/-/blob/master/pipeline/onem2m_delimiter_start.docx?ref_type=heads) and [Example: onem2m-delimiter-end.docx](https://git.onem2m.org/tools/scripts/-/blob/master/pipeline/onem2m_delimiter_end.docx?ref_type=heads) 

## Generation of baseline

## Generation of baseline

The generation of baseline is meant to produce a Word document for a specific version (baseline) from the markdown specification file, which is launched upon creation of a specific Merge Request (baseline contribution Merge Request, see [contribution procedure](https://git.onem2m.org/tools/contribution-procedure)). 

The generation of baseline is meant to produce a Word document for a specific version (baseline/draft) from the markdown specification file, which is launched upon creation of a specific Merge Request (baseline contribution Merge Request, see [contribution procedure](https://git.onem2m.org/tools/contribution-procedure)). It can also be launched upon creation of a tag, this is defined in the ```.gitlab-ci.yml``` file

The [publish_spec.sh](https://git.onem2m.org/tools/scripts/pipeline/publish_spec.sh) script implements the steps for the generation a specification baseline:

The [publish_spec.sh](https://git.onem2m.org/tools/scripts/-/blob/master/pipeline/publish_spec.sh?ref_type=heads) script implements the steps for the generation a specification baseline/draft:

- Step 1. Replacement of SVG images by PNG images for easy processing by Pandoc BY [forge.etsi.org:5050/cti/tools/generatebaseline svg2png.py](https://git.onem2m.org/tools/scripts/generateBaseline/svg2png).

- Step 1. Replacement of SVG images by PNG images for easy processing by Pandoc BY [forge.etsi.org:5050/cti/tools/generatebaseline svg2png.py](https://forge.etsi.org/rep/cti/tools/container_registry/17).

- Step 2. Addition of the Table of Content to the markdown file BY [forge.etsi.org:5050/cti/tools/generatebaseline generateTOC.py](https://git.onem2m.org/tools/scripts/generatebaseline/generateTOC).

- Step 2. Addition of the Table of Content to the markdown file BY [forge.etsi.org:5050/cti/tools/generatebaseline generateTOC.py](https://forge.etsi.org/rep/cti/tools/container_registry/17).

- Step 3. Conversion of the markdown file to Word document BY [Pandoc](https://hub.docker.com/r/pandoc/core). The Word document is downloadable as an artifact of the corresponding merge request.

- Step 3. Conversion of the markdown file to Word document BY [Pandoc](https://forge.etsi.org/rep/cti/tools/container_registry/20). The Word document is downloadable as an artifact of the corresponding merge request/tag. The process requires the following files to be provided:

    - [Spec-template.docx](https://git.onem2m.org/tools/scripts/pipeline/Spec-template.docx) is used as template for the conversion. It sets font style, headings styles, table and figure captions, etc...

    - Specification template: It is used as template for the conversion. It sets font style, headings styles, table and figure captions, etc... [Example: Spec-template.docx](https://git.onem2m.org/tools/scripts/-/blob/master/pipeline/Spec-template.docx?ref_type=heads) 

## Publication of specifications on Gitlab Pages

## Publication of specifications on Gitlab Pages

The publication of specifications on Gitlab Pages is meant to make the publish the markdown specifications on the web accesible at https://specifications.onem2m.org/PROJECT/ Gitlab Pages URL. Upon the creation of a tag, the tag version specification will be published on the Gitlab Pages.

The publication of specifications on Gitlab Pages is meant to publish the markdown specifications on the web accesible at https://<GROUP_NAME>.<GITLAB_DOMAIN>/PROJECT/ Gitlab Pages URL. Upon the creation of a tag (usually), the tag version specification will be published on the Gitlab Pages.

The [forge.etsi.org:5050/cti/tools/generatespecwebsite spec_on_pages.sh](https://git.onem2m.org/tools/scripts/generateSpecWebSite/spec_on_pages.sh) script implements this operation as explained above. 

The [forge.etsi.org:5050/cti/tools/generatespecwebsite spec_on_pages.sh](https://forge.etsi.org/rep/cti/tools/container_registry/18) script implements this operation as explained above. This process needs the following files:

- [mkdocs.yaml](https://git.onem2m.org/tools/scripts/-/blob/master/pipeline/mkdocs.yml?ref_type=heads) is the Mkdocs config file.

The CLEAN_WEB_PAGES variable can be used to clean up the Gitlab Pages site:

The CLEAN_WEB_PAGES variable can be used to clean up the Gitlab Pages site:

- CLEAN_WEB_PAGES = false (default), the specification web site will be published on Gitlab Pages normally

- CLEAN_WEB_PAGES = false (default), the specification web site will be published on Gitlab Pages normally

- CLEAN_WEB_PAGES = "TAG NAME", the specification version "TAG NAME" will be removed from Gitlab Pages. Note that no creation of tag is required in this case, a manual pipeline run is necessary with the CLEAN_WEB_PAGES variable properly set.

- CLEAN_WEB_PAGES = "TAG NAME", the specification version "TAG NAME" will be removed from Gitlab Pages. Note that no creation of tag is required in this case, a manual pipeline run is necessary with the CLEAN_WEB_PAGES variable properly set.

## .gitlab-ci.yml 

This is the pipeline definition that contains the required jobs for each specific project. [Example: .gitlab-ci.yml](https://git.onem2m.org/tools/scripts/-/blob/master/pipeline/.gitlab-ci.yml?ref_type=heads)