- Screenshots added to editor's guide

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

- [Pandoc](https://pandoc.org/)

  - In Windows, you might want to install MiKTeX in addition to support conversion to PDF.

  - In Windows, you might want to optionally install [MiKTeX](https://miktex.org/) to support conversion to PDF from Pandoc.

- Markdown editor(s). Recommended (both):

  - Integrated: [Visual Studio Code](https://code.visualstudio.com/)

    - The integrated editor supports version control operations graphically, so that usual operations do not require CLI commands necessarily.

To install extensions in VSCode you can follow any of the procedures described in: https://code.visualstudio.com/docs/editor/extension-gallery

This document provides the description of all the procedures based on Git as CLI command to minimize any potential ambiguity. However, it must be noted that all actions required for contributors and the most common actions of the editor can be conveniently performed from the integrated editor, following the same steps but in a more visual manner. Once you have read this document, it is highly recommended checking this [visual guide](https://code.visualstudio.com/docs/editor/versioncontrol), which shows how to perform all the operations in a visual manner.

Beware that the required steps for each of the procedures of this document will be exactly the same, and should happen in the same order, both for the integrated editor and the CLI. Furthermore, there is total interchangeability between both means, so that you can combine steps performed from the editor with steps performed from the CLI at your total discretion with no risk of confusing Git (in the end of the day, the editor also invokes the own `git` command behind the scenes).

## Markdown conversion basics

The basic syntax of Pandoc is rather simple. In the simplest cases, it just requires an input file and an output file name, and it will determine the formats based on the extensions.

### Edition and processing of open merge requests

The editor can view all the pending merge requests within a project by navigating to **Project > Merge Requests** in the Gitlab web of the project for the document. That merge request would be associated to a new branch, which can be also be checked navigating to **Repository > Branches**.

The editor can view all the pending merge requests within a project by navigating to **Project > Merge Requests** in the Gitlab web of the project for the document:

![merge-requests-in-gitlab](assets/merge-requests-in-gitlab.png)

That merge request would be associated to a new branch, which can be also be checked navigating to **Repository > Branches**:

![branches-in-gitlab](assets/branches-in-gitlab.png)

For instance, for a group of committers (Group) called `osm-doc` and a project called `documentation-how-to`:

- The list of pending Merge Requests would be at `https://osm.etsi.org/gitlab/osm-doc/documentation-how-to/merge_requests`

- The list of branches would be available at `https://osm.etsi.org/gitlab/osm-doc/documentation-how-to/branches`

TODO: Include some screenshots

First online review and, if needs to be rejected, include comments where applicable.

If the contribution is acceptable for a merge, the merge process can be conducted either in the website (particularly if it is a simple review) or in the editor's local repo. The following steps describe the most generic case of using the local repo, although the process would be analogous in the web interface.

In order to minimize potential issues due to ambiguity of format among contributors, in case of doubt, **GitHub Flavored Markdown (GFM)** is highly recommended, given its prevalent popularity and support by most major editors, renderers and viewers.

#### File structure

#### File structure and document build

It is highly advisable that the editor provides a base file structure for the document. There are some best practices that apply:

- Different chapters (i.e. level-1 titles) of the document should be in different markdown files. Likewise, no more than one level-1 title should be placed in the same file.

- Different chapters (i.e. level-1 titles, with a single dash, **`#`**) of the document should be in different markdown files. Likewise, no more than one level-1 title should be placed in the same file.

  - Use **`TODO:`** as tag (including the colon, **`:`**) to indicate (in free text) the content expected for a specific section or any pending refinements to be added at later stages. This text will be visible by readers and will be rendered to output formats, so editors should use it wisely to provide sufficient context about the missing content without adding excessive noise to the reader.

- Images should be placed in a dedicated folder. The recommendation is using the `./assets` folder.

- Likewise, DOCX templates, auxiliary files, output files, etc. should be placed in dedicated folders

- File and folder names should not contain spaces or any other kind of special characters to maximize portability and minimize rendering or reading errors in various auxiliary tools. To improve readability, an useful convention is using dashes (`-`) to replace spaces.

- The editor should add to the base folder a simple **script to build the document**, so there is no ambiguity to test the results.

TODO: Include example with all recommendations above, so that it can be easily used as template for new editors.

TODO: Create a sample template with all recommendations above, so that it can be easily reused by new editors. Meanwhile, the [EUAG whitepaper on OSM scope](https://osm.etsi.org/images/OSM_EUAG_White_Paper_OSM_Scope_and_Functionality.pdf) can be used as reference and adapted with no much effort. Source files can be obtained by cloning the repository:

```bash

git clone https://osm.etsi.org/gerrit/osm/DOC.git

```

If you plan to adapt it over the same directory, **remember to change the remote URL to point the appropriate repo** to avoid pushing commits to the wrong location. In our example:

```bash

git remote set-url origin ssh://git@osm.etsi.org:29419/osm-doc/test.git

```

### Line length limitation and minimization of conflicts