updated readmeHEADmaster

1 files changed, 57 insertions, 17 deletions

diff --git a/README.org b/README.org
index 8d9eb12..b029195 100644
--- a/README.org
+++ b/README.org
@@ -2,30 +2,70 @@
 
 *WIP - it does not work yet*.
 
-The program should return librejs report for a given page.  It should
-return a JSON for a given url:
+The program should return librejs report for free javascript on a
+given webpage.  It should return a JSON for a given url:
 
 http://localhost:5678/https://fsf.org
 
 This should return a JSON report of the compliance of https://fsf.org.
 
-A more advanced version of this program should take user input url
-(url to a webpage, not a javascript file), run librejs compliance, and
-return the report to user.  If the user is ok for the report to be
-shared, it will also be added to a database.  The server can then
-serve a filtered / sorted list of urls by compliance, popularity etc.
-This can help users discover sites that are librejs-compliant.
+A proper version of this program should take user input of a url with
+all free javascript (url to a webpage, not a javascript file), run
+librejs compliance script on the url, and return the report to user.
+If the user is ok for the report to be shared, it will also be added
+to a database.  The server can then serve a filtered / sorted list of
+urls by compliance, popularity etc.  This can help users discover
+sites that are librejs-compliant.
 
-An even more advanced version of this program should list reasons for
-non-compliance of free javascript, and librejs devs can use this data
-and statistics to determine how to update the compliance check to
-cover more free javascript.  A more advanced librejs can download the
-database, and add javascript to whitelist depending on some threshold
-from the data.
+** Purpose of the program
 
-Problem:
+LibreJS does not recognise all free javascript. That is, every
+javascript code or file falls under one of the three catogories:
 
-1. This is an SaaSS
-2. Without moderation or approval, user will submit nonfree javascript
+1. Free and librejs-compliant - these scripts will be accepted by
+   librejs and excuted.  Example: JS on most FSF/GNU pages.
+2. Free and librejs-noncompliant - these scripts will be blocked by
+   librejs.  Example: peertube instances
+3. Nonfree javascript.  Example: YouTube web client.
+
+To improve LibreJS coverage means to make it recognise more free
+javascript so that the number of scripts in the first category
+increase and that of the second category decreases.
+
+To that end, we design a server program that maintain a database of
+free scripts, that come from webpages whose urls are submitted by
+users of this server.
+
+Initially users should only submit webpages they believe contains only
+free javascript, LibreJS-compliant or not. Ideally the user should be
+able to explain why they think all the js on the page is free, e.g. it
+is an instance of a free software web application.
+
+With this, librejs devs can use this data and statistics to determine
+how to update the compliance check to cover more free javascript. On
+the other hand, LibreJS can include a functionality to download the
+database from the librejserver, and add javascript to whitelist
+depending on some threshold from the data (e.g. popularity of the
+script based on user submission counts or upvotes).
+
+** Possible problems
+
+This sounds like an SaaSS. Users will let the server run the librejs
+compliance script, which they can do on their own computer. However,
+the main functionality of this server program is crowd-sourcing
+LibreJS compliance info, similar to a wiki. Therefore, the compliance
+script run on the server can be considered as a computation done by
+the project which the user is part of.
+
+Another possible problem is that without moderation or approval, user
+may submit pages with nonfree javascript, intentionally or
+unintentionally. This requires moderation or approval. Something
+similar would be the FSD review process, but that would be too slow or
+heavy. Perhaps the moderation can be done automatically using an
+upvote / downvote functionality.
 
 see also https://lists.gnu.org/archive/html/bug-librejs/2022-11/msg00003.html
+
+** Acknowledgement
+
+This document is improved thanks to conversations with iank.