From 6e6dcb97fb91b108ddc4e65e4e7656b68bfcb91d Mon Sep 17 00:00:00 2001
From: ramonsalguer <javier.ramon@telefonica.com>
Date: Thu, 14 Mar 2019 13:11:39 +0100
Subject: [PATCH] - List of basic software: added download URLs - Removed
 OpenSSH from basic software, as it is installed by default - Pandoc syntax is
 explained

---
 ...low for documentation production in OSM.md | 41 ++++++++++++++-----
 1 file changed, 30 insertions(+), 11 deletions(-)

diff --git a/Workflow for documentation production in OSM.md b/Workflow for documentation production in OSM.md
index 7069c64..c5b9453 100644
--- a/Workflow for documentation production in OSM.md	
+++ b/Workflow for documentation production in OSM.md	
@@ -19,13 +19,12 @@ In the edition process there are two roles:
 
 Basic Software:
 
-- Git
-- Pandoc
-- OpenSSH
+- [Git](https://git-scm.com/)
+- [Pandoc](https://pandoc.org/)
 - Markdown editor(s). Recommended (both):
-  - Integrated: Visual Studio Code
-    - The integrated editor would support version control operations graphically, so that usual operations do not require a command line.
-  - WYSIWYG: Typora
+  - 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.
+  - WYSIWYG: [Typora](https://typora.io/)
 
 ### Some recommended extensions for Visual Studio Code
 
@@ -55,13 +54,33 @@ To install extensions in VSCode you can follow any of the procedures described i
 
 ## Markdown conversion basics
 
-The basic syntax of Pandoc is rather 
+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.
 
-pandoc MyDocument.md -o MyDocument.html
+For instance, this command converts from Markdown to MS-Word format:
 
+```bash
 pandoc MyDocument.md -o MyDocument.docx
+```
+
+It is also possible to merge several input files into one output file:
+
+```bash
+pandoc MyDocument1.md MyDocument2.md -o MyDocument.docx
+```
 
+For some target formats, such as HTML, you would need to specify whether you want to produce a fragment (default) or a complete standalone document (using the `-s` switch):
+
+```bash
+pandoc -s MyDocument.md -o MyDocument.html
+```
+
+In the case of MS-Word target format, a highly useful feature is specifying an existing document (usually based on a specific format template) as reference, so that Pandoc can produce the output document based on the same template:
+
+```bash
 pandoc MyDocument.md --reference-doc=referenceDocument.docx -o MyDocument.docx
+```
+
+Please note that the reference must be a valid standalone DOC/DOCX document, not an MS-Word template (i.e. DOT/DOTX files are not valid references for Pandoc).
 
 ## Git settings
 
@@ -84,7 +103,7 @@ It is also highly advisable adding an SSH key to https://osm.etsi.org/gitlab/pro
 git clone git@osm.etsi.org:osm-doc/test.git
 ```
 
-**TEMPORARY**:
+**TEMPORARY URL**:
 
 ```bash
 git clone https://osm.etsi.org/gitlab/osm-doc/test.git
@@ -120,8 +139,8 @@ Note that **this procedure needs to be followed exactly as it is described** or
 
 - You are **rewriting** your Git history and, therefore, might delete wrong entries if you make any mistake. Please read these steps carefully and follow them accurately.
 - Any changes not committed before starting this procedure. If they are relevant for your, you should commit them (to `master`) as well.
- 
- As said, you can follow this procedure (assuming that you start in your `master` branch):
+
+As said, you can follow this procedure (assuming that you start in your `master` branch):
 
 ```bash
 git branch newbranch              # Create a new branch, saving the desired commits
-- 
GitLab