updated documentation and made it shorter and more precise

README.md

@@ -1,5 +1,7 @@
 # Welcome to ThreadR
-This is the source code for the ThreadR Forum Engine. It originated as a school project with the goal of developing a mix between a forum engine and a social media platform. When school was over, we left the project up for some time with the general intention to continue working on it until I took it down after an extended period of inactivity to host my own website on my server.
+This is the source code for the ThreadR Forum Engine.
+
+The project originated as a school project with the goal of developing a mix between a forum engine and a social media platform. When school was over, we left the project up for some time with the general intention to continue working on it until I took it down after an extended period of inactivity to host my own website on my server.
 
 Now, that it is being revived, the original scope of the project doesn’t really make sense anymore (at least to me) so it needs to shift slightly. Below is a list of goals that I would like to see achieved, feel free to discuss this in the issues or commit comments.
 
@@ -20,11 +22,6 @@ Once these two are given, here are some additional goals both from the original
 
 \- BodgeMaster
 
-# WARNING
-~~All information below is only relevant for documentation purposes.~~ This is a backup of the ThreadR project. A backup of the databases has been saved to `ThreadR.sql` and `web.sql`.
-
-Update: This project will (hopefully) be brought back to life in its now home - here. This warning will be removed once the new box is set up with ThreadR in its current state.
-
 # Git based automatic web deployment system
 This repository will be automagically pulled by the web server each time something is pushed by a user.
 
@@ -32,47 +29,34 @@ Dear Developers, Please use pushes sparingly because it takes a while for the se
 
 ## Symlinks
 The following files and directories are linked to areas where they can be accessed by the web server:
-  * `threadr/` → `threadr.lostcave.ddnss.de/threadr/` (all files acessible by the web server)
+  * `threadr/` → `threadr.lostcave.ddnss.de/threadr/` (all files acessible by the web server, READMEs get deleted on deployment)
   * `default.html` → `threadr.lostcave.ddnss.de/index.html` (http redirect)
 
-## Variables handled by the deployment script
-~~Here is the place for variables that will be replaced automatically on the server. Using them is encouraged. Using the paths is DISCOURAGED.
-This way, it is possible to change folder names around and fix the URLs in one place for all files simultaneously.~~
-
-This section has moved. Look in the files or their documentation below.
-
-## Some server variables that might turn out to be useful (example):
-```
-{
-  "HTTP_USER_AGENT":"Mozilla\/5.0 (X11; Ubuntu; Linux x86_64; rv:73.0) Gecko\/20100101 Firefox\/73.0",
-  "REMOTE_ADDR":"10.1.1.3"
-}
-```
-
 # Individual documentation for each file
 ### [[DIR] threadr](./threadr)
 This folder contains all the files that are parts of ThreadR directly
 ### [[DIR] config](./config)
 A place to store the configuation for a specific ThreadR instance (contains official instance config for now, will be moved elsewhere eventually)
 ### [[DIR] macros](./macros)
-files for variable_grabbler.py
+files for use with variable_grabbler.py
 ### [admin.php](./admin.php)
-This is the file that is shown on the internal admin page. It will contain a list of users, forums, threads, etc.
+~~This is the file that is shown on the internal admin page. It will contain a list of users, forums, threads, etc.
 At the moment, it is just a convenient way to access the other internal administration tools.
-This is not directly a part of ThreadR.
+This is not directly a part of ThreadR.~~
+
+This is part of the server management tools and therefore will be gone from this repository soon.
 ### [default.html](./default.html)
 The main index.html on the server. It redirects to ThreadR.
 ### [deployment_script.sh](./deployment_script.sh)
-This script is executed each time (well... if Gitea decides to actually run the WebHook) the repository gets pushed.
+This script is executed each time (or most of the time) the repository gets pushed.
 It contains the commands to execute the code variable replcement system and some other useful tasks.
-It’s working directory is the root of the git repository.
+Its working directory is the root of the git repository.
-If you want to know more: It is commented. Just look at it.
 ### [strassenkind.php](./strassenkind.php), [internal.css](./internal.css), [commands_status.conf](./commands_status.conf), [commands_ondemand.conf](./commands_ondemand.conf), [commands_git.conf](./commands_git.conf)
-The internal status page. strassenkind.php is the index, internal.css is the stylesheet strassenkind.php uses
+~~The internal status page. strassenkind.php is the index, internal.css is the stylesheet strassenkind.php uses
 and the .conf files are lists of commands to be executed by the status page. The status page auto-refreshes to display up-to-date information on the commands in commands_status.conf.
 It is advised to put commands that have a high disk usage or start/stop/restart/reload system services etc. on the commands_ondemand.conf file as the ondemand status page does not auto-refresh.
 The file commands_git.conf contains the commands that would be executed by the deployment WebHook. These are there to provide a fast and simple backup solution.
-The alternative to foce-updating ThreadR via the status page would be:
+The alternative to foce-updating ThreadR via the status page would be:~~
 ```
 ssh <user>@<threadr.ip|no public access set up currently>
 cd /var/www/git
@@ -84,14 +68,22 @@ cd web-deployment
 exit
 logout
 ```
-DEPRECATED: The administration framework will be turned into its own project.
+DEPRECATED: The administration framework will be turned into its own project and completely overhauled.
+### [LICENSE.md](./LICENSE.md)
+A copy of the Apache 2.0 license, the license this project is under
+### [NOTICE](./NOTICE)
+Copyright notice in plain text format
 ### [README.md](./README.md)
 this file
 ### [variable_grabbler.py](./variable_grabbler.py)
-This is the code variable replacer. It takes two arguments: The configuration file to be used and the file to be worked on.
+Custom macro processor, takes two arguments: macro declaration file and the file to be processed
-The configuration file contains a json which defines replacement string for each code variable in the format `"<VARNAME>":"<String>"`. Code variables are preceeded and followed by a % sign in code but this is not the case in the configuration.
-Also, they must be capitalized in code.
-An alternative option to providing a string in the config is to add arrays defining files or commands (Commands are not implemented yet.). Format: `"<VARNAME>":["<file|exec>","<filepath|command>"]
-Read the source code for further information.
 
-NOTICE: This file (or rather a more up-to-date version of it) will be moved to a new repository containing the deployment system.
+Macros in code are strings of capitalized characters prefixed and suffixed with %.
+
+Macro definition format: JSON
+"<MACRO>":"<text>" → direct replacement
+"<MACRO>":["file","<file path>"] → insert file
+"<MACRO>":["exec","<command>"] → run command and insert its output from stdout
+
+~~NOTICE: This file (or rather a more up-to-date version of it) will be moved to a new repository containing the deployment system.~~
+I haven’t exactly figured out how to handle this in the future. It is absolutely necessary to deploy a ThreadR instance because it is used to configure ThreadR so we need a copy of it here.