Commit 6e6dcb97 authored by Francisco-Javier Ramon Salguero's avatar Francisco-Javier Ramon Salguero
Browse files

- List of basic software: added download URLs 

- Removed OpenSSH from basic software, as it is installed by default
- Pandoc syntax is explained
parent f5f6e266

Workflow for documentation production in OSM.md

+30 −11
Original line number Diff line number Diff line
@@ -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