From c7958dafa1ccaeb6b05138c429d73b45a891b0e6 Mon Sep 17 00:00:00 2001
From: Glenn <glenux@glenux.net>
Date: Sun, 24 Dec 2023 17:01:57 +0100
Subject: [PATCH] doc: improve README

---
 README.md | 97 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 97 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f1073fc
--- /dev/null
+++ b/README.md
@@ -0,0 +1,97 @@
+# ReportSpam
+
+ReportSpam is a command-line tool that enables users to report spam emails to
+the SignalSpam platform. This tool serves as a bridge between individual users
+and the SignalSpam service, facilitating the process of submitting spam for
+investigation and action.
+
+## Introduction
+
+ReportSpam is a community-driven project developed independently from
+SignalSpam. It offers a convenient way for users to report spam emails directly
+from any email-piping capable mail client by leveraging the HTML forms on
+SignalSpam's web platform. The project is currently in beta but is mature
+enough for daily use.
+
+## Requirements
+
+To use the project:
+
+* An account on SignalSpam.
+
+To build the project from source:
+
+* GNU Make,
+* CrystalLang and Shards.
+
+## Installation
+
+To install ReportSpam, follow these steps:
+
+1. Ensure that CrystalLang is installed on your system.
+2. Clone the repository:
+
+   ```bash
+   git clone https://github.com/your-repo/reportspam.git
+   cd reportspam
+   ```
+
+3. Use the Makefile to build the project:
+
+   ```bash
+   make build
+   ```
+
+## Usage
+
+ReportSpam can be used in a few simple steps:
+
+```bash
+Usage: reportspam [options] [command]
+
+Commands:
+  configure        Initialize the configuration
+  send             Process and report spam email (default: from STDIN)
+
+Options:
+  -h, --help                       Show this help
+```
+
+- **Configure**: Set up your initial configuration for using ReportSpam.
+- **Report**: Pipe an email into the tool to report it as spam.
+- **Help**: Display the help message for more information.
+
+### Reporting Spam
+
+To report a spam email, you can use the `report` command:
+
+```bash
+cat spam_email.eml | reportspam send
+```
+
+## Configuration
+
+After installation, run `reportspam configure` to set up your user
+configuration, which may include credentials or preferences for interacting
+with the SignalSpam platform.
+
+## Issue Reporting
+
+Issues can be reported on ReportSpam's Issue Tracker.
+
+## License
+
+This project is licensed under the LGPL-3.0-or-later.
+
+## Acknowledgments and thanks
+
+* SignalSpam for their efforts in combating spam.
+* The CrystalLang community for support and resources.
+
+## Alternatives
+
+For alternative solutions or more information on SignalSpam, you can refer to:
+
+- [SignalSpam's Official Blog Post](https://signal.eu.org/blog/wp-content/uploads/2007/05/signalspam.txt)
+- [Bortzmeyer's Guide on Reporting to Signal Spam](https://www.bortzmeyer.org/signaler-a-signal-spam.html)
+