From 4517d0f55725c76de55ad477ab3fad2788032ec6 Mon Sep 17 00:00:00 2001
From: eclipse <eclipse@unterdemradar.de>
Date: Thu, 17 Jul 2025 21:23:18 +0200
Subject: [PATCH] added introductory section; improved Dependencies section

---
 README.md | 45 +++++++++++++++++++++++++++++++++------------
 1 file changed, 33 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 1c99dfc..24a7843 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,18 @@
-# The Works
+# the_works – a publication management tool for writers
+
+This software project  
+
+* supports managing texts and publications with multiple languages, pseudonyms, genres, publishers, series, editions, and more
+* supports storage of cover images
+* focuses on ease-of-use, safety, and speed
+* written and field-tested by an actual writer
+
+the_works also is
+
+* based on common technologies like Python, SQL, and HTML/JavaScript
+* underlying frameworks are Flask and SQLAlchemy
+* includes test coverage (using pytest)
+
 
 ## Configuration
 
@@ -21,7 +35,7 @@ Available commands:
 
 * `run`: Serve app (don't use for production).
 <!--* `init-db`: Create empty SQLite database `works.sqlite` in project root. BE CAREFUL: If a database already exists, it will be deleted with everything in it.  // 5/25: ich hab die Fkt. wieder rausgenommen, aber ich könnte sie eigentlich prima wieder einbauen … -->
-* `shell`: start a shell within the app context (I can i.e. import specific table models and test the data structures returned by ORM methods like select())
+* `shell`: start a shell within the app context (I can i.e. import specific table models and test ORM data structures)
 * 
 
 
@@ -31,18 +45,25 @@ Available commands:
 
 ### Python Packages
 
-flask
-flask-sqlalchemy
-python-dotenv
-Pillow
-pytest
-flask-debugtoolbar (optional)
-sqlacodegen (optional; only ever used from the command line during development)
+Required pip packages
 
-### CSS and Javascript
+* flask
+* flask-sqlalchemy
+* python-dotenv
+* Pillow
+* pytest
 
-PicoCSS (regular version) + SwitchColorMode.js (from Yohn's fork)
-DataTables.[js|css]
+Optional pip packages
+
+* flask-debugtoolbar (optional)
+* sqlacodegen (optional; only used from the command line during development)
+
+### CSS and Javascript resources
+
+* any regular (not classless) stylesheet from [PicoCSS](https://picocss.com) for general styling
+* `SwitchColorMode.js` from [Yohn's fork of PicoCSS](https://yohn.github.io/PicoCSS/) to enable color mode switching  
+* [DataTables](https://datatables.net/) (JS and CSS components) to enable ordering and filtering result tables 
+  * DataTables requires [jQuery](https://jquery.com/), which can either be bundled with DataTables itself or installed as a separate resource
 
 ### Icons