From 0cab5f55230f1c47b76c3a177750388c1cff02f1 Mon Sep 17 00:00:00 2001
From: Torsten <torsten@rubydesign.fi>
Date: Fri, 30 Dec 2022 14:25:21 +0200
Subject: [PATCH] update readme

---
 README.md | 86 +++++++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 68 insertions(+), 18 deletions(-)

diff --git a/README.md b/README.md
index 8d9c7a8..7a214c5 100644
--- a/README.md
+++ b/README.md
@@ -47,28 +47,33 @@ Like a Page, a Section may have options.
 
 ### Cards
 
-Cards, as in general css lingo, are usually smaller html snippets,
-usually contained in a grid (defined by the Section).
+Cards, as in general css lingo, are usually smaller html boxes,
+usually contained in a grid (defined by the Section). But they may
+be form fields, or features (svg).
 
 Cards have data and options like the other elements.
 
 ### Image
 
-Merged also manages images, adding deleting, renaming, which are
-stored in the assets folder. With the Pages (and their data) they
+Merged also manages images, adding deleting, renaming, even a small editor.
+Images are stored in the assets folder. With the Pages, Sections and Cards they
 define the content that users can change.
 
 Images merge into the upstream in the same way as the pages, through
 git actions (partially done by Merged)
 
-## Change (-sets)
+### Change (-sets)
 
 As data is in files, all change happens by git.
 Merged partially manages this, by making changes visible to the
 users, ie what Pages and Images were added/removed or edited.
 Merged can commit and in the future maybe even push.
 
-### Basic setup
+Merged requires a user to be logged in and will log all changes, meaning
+change times and the email of the editor. The last change is displayed in
+the ui for auditing purposes.
+
+## Basic setup
 
 A developer set up a machine on a intranet/lan. Ie access is
 restricted by physical access.
@@ -78,12 +83,12 @@ A User may use the machine to edit and commit and push (the branch).
 
 The developer reviews, merges changes and deploys.
 
-
 ## Installation
+
 Add this line to your application's Gemfile:
 
 ```ruby
-gem "merged"
+gem "merged" , git: "https://github.com/HubFeenixMakers/merged"
 ```
 
 And then execute:
@@ -91,7 +96,8 @@ And then execute:
 $ bundle
 ```
 
-Mount engine in routes for editing.
+Mount engine in routes for editing (possibly not in production).
+
 ```ruby
 mount Merged::Engine => "/merged"
 ```
@@ -106,25 +112,69 @@ If Merged served the root:
 root "merged/view#view" , id: 'index'
 ```
 
-Include merged stylesheet to your layout (NOT asset
-pipeline).
+### Stylesheets
+
+#### Apps not using tailwind
+
+Include merged stylesheet to your layout or asset
+pipeline.
 
 ```
 = stylesheet_link_tag "application"
 = stylesheet_link_tag "merged/merged"
-= stylesheet_link_tag "tailwind" , "inter-font", "data-turbo-track": "reload"
 ```
 
-If you use tailwind with the basic install, add it _before_ tailwind,
-and switch preflight off in the apps tailwind config file (config/tailwind.config.js). Otherwise tailwind will reset the styles from merged
-or the other way around.
+#### Apps using tailwind
+
+If you use tailwind with the basic install, you need to edit the tailwind config.
+
+Basically it is impossible to have two tailwind generated stylesheets, so your app needs to pick
+up the merged styles. This can be configured like so:
 
 ```
-corePlugins: {
-  preflight: false,
-}
+const output = execSync('bundle show merged', { encoding: 'utf-8' });
+const fullname = output.trim() + '/app/**/*.{haml,html,rb}' ;
+
+
+module.exports = {
+  content: [
+    fullname ,
+    .... as before
+  ]
 ```
 
+## Developers
+
+### Styles
+
+Developers should look at the predefined styles. These are found in
+merged gem /config/merged/**style.yml
+
+And on a running app http://localhost:3000/merged/styles/index
+
+### Section Views
+
+These are under app/views/merged/views/sections/*haml
+and the name of the file matches the section_style entry
+
+Developers may define more section styles, but must provide the partials to render them.
+
+### Card Views
+
+These are under app/views/merged/views/cards/*haml
+and the name of the file matches the card entry.
+
+Developers may define more card styles, but must provide the partials to render them.
+
+### Options
+
+Option definitions (also found under style dir) are common between elements.
+Options may be added and then used in the view partials. Many common ones (background,
+color) and many more are already defined.
+
+To make the partials more dry, Helpers are defined in OptionsHelper
+
+
 ## Contributing
 Ask first.