From f95d28d72ef0ed10f6ec80639246172edfe25fb8 Mon Sep 17 00:00:00 2001
From: Glenn <glenux@glenux.net>
Date: Fri, 5 Jan 2024 23:08:25 +0100
Subject: [PATCH] doc: improve README content

---
 README.md | 92 +++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 69 insertions(+), 23 deletions(-)

diff --git a/README.md b/README.md
index 6ab2e52..35d2887 100644
--- a/README.md
+++ b/README.md
@@ -1,60 +1,106 @@
+<!--
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#
+# SPDX-FileCopyrightText: 2023 Glenn Y. Rolland <glenux@glenux.net>
+# Copyright © 2023 Glenn Y. Rolland <glenux@glenux.net>
+-->
+
 # Makefiles Forever
 
 A drop-in collection of makefiles libraries for your projects
 
 ## Description
 
-* plantuml.makefile — Build [plantuml](https://plantuml.com/) diagrams
-* dot.mk — Build [graphviz](https://graphviz.org/) graph diagrams
-* mocodo.mk — Build [mocodo](http://mocodo.wingi.net/) entity-relation and logical diagrams
+* plantuml.makefile — Automate the building [plantuml](https://plantuml.com/) diagrams.
+* graphviz.mk — Streamline the creation of [graphviz](https://graphviz.org/) graph diagrams.
+* mocodo.mk — Facilitate the development of [mocodo](http://mocodo.wingi.net/) entity-relation and logical diagrams.
+* mypaint.mk - Automate the conversion of [mypaint](https://mypaint.app/) openraster images to usual image formats.
 
 ## Usage
 
-Add this repository as a GIT submodule of your project
+### Adding to your project
+
+To include 'Makefiles Forever' in your project, add this repository as a GIT
+submodule:
 
 ```shell-session
 $ git submodule add https://github.com/glenux/makefiles-forever .makefiles
 ```
 
-Include needed features in the end of your makefile
+### Configuring your makefiles
+
+In your project's makefile, include the necessary modules. __The `include` instructions must be located
+__before your existing targets__.
 
 ```makefile
-# [...]
+# [... variable definitions ...]
 
--include .makefiles/featureA.mk
--include .makefiles/featureB.mk  
+# Include as many Makefiles Forever features as your want
+include .makefiles/plantuml.mk
+include .makefiles/mocodo.mk
+include .makefiles/graphviz.mk
+
+# [... targets definitions ...]
 ```
 
 Declare API variables (ex: `*_SRC_DIR`, `*_DEST_DIR`) for each module
 
 ```makefile
-# Configuration for featureA from Makefiles Forever
-FEATUREA_SRC_DIR=/path/to/somewhere
-FEATUREA_DEST_DIR=/some/other/path
+# PlantUML Configuration
+PLANTUML_SRC_DIR=/path/to/plantuml/files
+PLANTUML_DEST_DIR=/path/to/output/directory
 
-# Configuration for featureB from Makefiles Forever
-FEATUREA_SRC_DIR=/another/path
-FEATUREB_DEST_DIR=/a/different/one
+# Mocodo Configuration
+MOCODO_SRC_DIR=/path/to/mocodo/files
+MOCODO_DEST_DIR=/path/to/output/directory
+
+# Graphviz Configuration
+GRAPHVIZ_SRC_DIR=/path/to/mocodo/files
+GRAPHVIZ_DEST_DIR=/path/to/output/directory
+
+# [ ... etc ...]
 ```
 
-Use pre-defined targets as dependencies of your targets:
+Use pre-defined targets in your build process, as dependencies of your existing
+targets:
 
 ```makefile
-build: featureA-build
-build: featureB-build
 
-clean: featureA-clean
-clean: featureB-clean
+build: plantuml-build mocodo-build graphviz-build
+
+clean: plantuml-clean mocodo-clean graphviz-clean
 ```
 
 Feature files usually define more targets than just build and clean, and you
 can use those too!
 
 
-## Good practices for coding .mk files
+## Best practices used in our .mk modules
 
-* Keep task parallelism in mind
-  * Make all targets available from root makefile 
-  * Do not descend in subdirectories
+* Parallel Execution: We ensure targets are available from the root makefile and avoid descending into subdirectories for parallel execution.
+* Modular Design: We keep our makefiles modular for easy maintenance and scalability.
+* Documentation: We comment our makefiles for clarity and ease of use by others.
+
+## Contributing
+
+Contributions are what make the open-source community such an amazing place to
+learn, inspire, and create. Any contributions you make are **greatly
+appreciated**.
+
+## Troubleshooting and Support
+
+If you encounter any issues or need support, please open an issue in 
+[the project's issue tracker](https://code.apps.glenux.net/glenux/makefiles-forever/issues). 
+We strive to be responsive and helpful.
+
+## License
+
+Distributed under the LGPL-3.0-or-later License. See `LICENSE` file for more
+information.
+
+## Acknowledgments
+
+* A special thanks to all contributors and users of this project for their
+  valuable feedback and support.