Feature/conversion flag (#23)

* feature: --convert flag

* docs: changelog

CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to
 
 ## [Unreleased]
 
+### Added
+* `--convert` flag to simply convert `.map` files to `.yaml` files
+
 ## [0.3.0] - 2024-02-03
 
 ### Added

README.md

@@ -47,13 +47,33 @@ where:
 - First parameter specifies the path to the input file, where LinkerScope should get the data to represent from. It can come from a GNU Linker map file `.map` or from an already parsed or hand-crafted `.yaml` file. Check [Manually crafting input file](#Manually crafting input file) section for learning how to do this.
 - `-c, --config` [OPTIONAL] specifies the path to the configuration file. This file contains all the custom information to tell LinkerScope what to and how to draw the memory maps. While it is optional, the default parameters will most likely not apply to a given use case.
 - `-o, --output` [OPTIONAL] specifies the path to the output file, which will be a newly generated SVG.
-
+- `--convert` [OPTIONAL] tells LinkerScope to perform a conversion from a `.map` file to `.yaml` file containing memory information. After conversion, proqram will quit.
 
 
 ### Input files
 
 LinkerScope can use two types of input files: GNU linker map files (`.map`) or custom defined yaml files (`.yaml`).
 
+#### Using .map files
+
+Under the hood, LinkerScope will convert `.map` files to custom `.yaml` ones, and will work from there.
+Since this operation is time-consuming and makes no sense to do it multiple times, two strategies can be
+performed when using `.map` files:
+- Convert `.map` files to `.yaml` file and then use the `.yaml` file as an input to LinkerScope
+  > This is specially useful if you plan to execute LinkerScope multiple times, since this conversion is time-consuming. Therefore better doing the conversion step once, right? Execute the example below:
+  > ```shell
+  >  # Conversion step
+  > ./linkerscope.py examples/sample_map.map --convert 
+  > 
+  >  # Map diagram generation. You can execute multiple times without having to do the conversion again
+  > ./linkerscope.py map.yaml -c examples/sample_config.yaml -o sample_map.svg 
+  >```
+- Directly use the `.map` files to output a memory map diagram.
+  > Use this strategy when you already have a configuration file, and you know that LinkerScope will produce the expected result. Execute the example below:
+  > ```shell
+  > ./linkerscope.py examples/sample_map.map -c examples/sample_config.yaml -o sample_map.svg 
+  > ```
+
 #### Manually crafted memory map files
 
 Custom memory map files can be manually crafted and can run from a couple of memory sections up to very complex memory schemes with hundreds of sections.

examples/sample_config.yaml

@@ -0,0 +1,25 @@
+size: [500,1100]
+
+variables:
+  graphite: &graphite '#212b38'
+  cleargraphite: &cleargraphite '#37465b'
+  mydarkgreen: &mydarkgreen '#08c6ab'
+
+style:
+  text-fill: 'white'
+  background: *graphite
+  fill: *mydarkgreen
+  hide-address: false
+  stroke: *cleargraphite
+  stroke-width: 0.5
+  text-stroke-width: 0.1
+  font-size: 12
+  font_type: 'Helvetica'
+
+areas:
+- area:
+    title: ESP32 app space (extract)
+    range: [0x400d0000, 0x400da000]
+    section-size: [0x000010,0x0008000]
+    pos: [ 100, 50 ]
+    size: [200, 1000]