update README and SYNTAX according to current practices

2 files changed, 82 insertions, 69 deletions

diff --git a/README b/README
index 410ce87..eb7508a 100644
--- a/README
+++ b/README
@@ -1,52 +1,49 @@
-# How to Blacklist a package - Parabola GNU/Linux-Libre Wiki
-From Parabola GNU/Linux-Libre Wiki
-
-If you find a package that is non-free or has non-free dependencies, it
-should be blacklisted until a way to free it is found.
-
-Preferred method
-
-  * If you don't have access to the [7]blacklist, ask for it.
-  * If you do:
-  * pull [8]blacklist.git from [9]projects
-  * add the package in a new line with the following syntax:
-
-package[:libre-replacement-package-name][:short description] [] is optional
-
-  * push the changes
-  * ssh into the repo server and run db-check-nonfree
-  * [10]report a bug if the package could be changed to be free
-
-Alternative method
-
-  * file a bug report on the [11]Parabola Issue Tracker
-
-See also
-
-  * Blacklist
-  * Creating_-libre_packages
-
-Retrieved from
-"[12]http://wiki.parabolagnulinux.org/How_to_Blacklist_a_package"
-
-Categories: FSDG | Hacking
-
-[14][GNU Free Documentation License 1.3]
-
- References:
-   1. https://parabolagnulinux.org
-   2. https://parabolagnulinux.org/packages
-   3. http://wiki.parabolagnulinux.org
-   4. http://bugs.parabolagnulinux.org
-   5. http://projects.parabolagnulinux.org
-   6. https://parabolagnulinux.org/download
-   7. http://repo.parabolagnulinux.org/docs/blacklist.txt
-   8. https://projects.parabolagnulinux.org/blacklist.git/
-   9. https://projects.parabolagnulinux.org/
-  10. http://bugs.parabolagnulinux.org/
-  11. http://bugs.parabolagnulinux.org/
-  12. http://wiki.parabolagnulinux.org/How_to_Blacklist_a_package
-  13. http://www.mediawiki.org/
-  14. http://www.gnu.org/copyleft/fdl.html
-  15. http://www.gnu.org/copyleft/fdl.html
-
+# How to Blacklist a package (adapted from [1]Parabola GNU/Linux-Libre Wiki)
+
+if you find a package that contains, uses or recommends nonfree
+software, it should be added to blacklist.txt until a way to free it
+is found. more generally, any package in violation to the [2]FSDG
+belongs in blacklist.txt
+
+other packages should be added to your-privacy-blacklist.txt,
+your-freedom_emu-blacklist.txt or both if they endanger privacy or
+only exist for the sake of using nonfree software; respectively. see
+[3] and [4] for more info.
+
+## Preferred method (blacklisting the package)
+
+  * if you don't have [5]git access:
+    * ask for it, or
+    * send a patch produced using `git format-patch` to dev@lists.parabola.nu
+  * if you do:
+    1. if possible, start by making a [6]replacement available for all
+       the affected architectures (packages in
+       your-freedom_emu-blacklist.txt are not meant to have a
+       replacement), or [7]report a bug if the package could be
+       changed to be free (read next section)
+    2. pull [8]blacklist.git
+    3. add package according to the SYNTAX file
+    4. push changes
+    5. ssh into repo.parabola.nu and run db-check-nonfree
+    7. pull [9]abslibre.git and make a new release of the
+       corresponding blacklist package (e.g. your-freedom)
+
+## Alternative method (reporting an issue)
+
+  * file a bug report on the [3]Parabola Issue Tracker
+  * choose the project responsible for it, nearly always "Packages"
+  * choose the "Freedom issue" type and priority
+  * report separate issues for appropriate projects if the package is
+    included with installation media.
+
+## References:
+
+[1]: https://wiki.parabola.nu/How_to_Blacklist_a_package
+[2]: https://www.gnu.org/distros/free-system-distribution-guidelines.html
+[3]: https://wiki.parabola.nu/Nonprism
+[4]: https://wiki.parabola.nu/Emulator_licensing_issues
+[5]: https://git.parabola.nu
+[6]: https://wiki.parabola.nu/Creating_-libre_packages
+[7]: https://labs.parabola.nu
+[8]: https://git.parabola.nu/blacklist.git
+[9]: https://git.parabola.nu/abslibre.git
diff --git a/SYNTAX b/SYNTAX
index 45c36a8..20b3855 100644
--- a/SYNTAX
+++ b/SYNTAX
@@ -1,12 +1,19 @@
 The *blacklist.txt files consist of lines in the following format:
 
-  original-package:libre-replacement:ref:id:description
+    original-package:[libre-replacement]:[ref]:[id]:short-description
 
-original-package is Arch binary package name, libre-replacement is the
--libre package that provides and replaces the original-package or
-empty if there is no compatible replacement.
+where something within [] is optional.
 
-ref is described by the following table:
+* original-package is the name of the binary package from Arch
+
+* libre-replacement is the name of the binary package that provides
+  and replaces the original-package, or empty if there is no
+  compatible replacement. The replacement must be compatible for use
+  by humans and scripts, e.g. fastjar is not a replacement for zip
+  although both solve the same problem. Packages in
+  your-freedom_emu-blacklist.txt are not meant to have a replacement.
+
+* ref is described by the following table:
 
     debian: &debian http://bugs.debian.org/
     fsf: &fsf http://libreplanet.org/wiki/List_of_software_that_does_not_respect_the_Free_System_Distribution_Guidelines#
@@ -14,17 +21,26 @@ ref is described by the following table:
     fedora: &fedora https://bugzilla.redhat.com/show_bug.cgi?id=
     parabola: &parabola https://labs.parabola.nu/issues/
 
-Use the value after & as the ref column value, the URL pointed by it and
-concatenated with the id field should point to an issue
-reporting/describing the reason for the package being blacklisted.
+  Use the value after & as the ref column value, the URL pointed by it and
+  concatenated with the id field should point to an issue
+  reporting/describing the reason for the package being blacklisted.
+
+  We should prefer FSF refs, since they are easily available for other
+  distros.  Hopefully some lines will move from parabola:X to fsf:Y with
+  the LibrePlanet wiki linking to the X issue on labs.parabola.nu.
+
+* short-description categorizes original-package with some tags,
+  followed by a short verbal explanation. Popular tags are:
 
-We should prefer fsf refs, since they are easily available for other
-distros.  Hopefully some lines will move from parabola:X to fsf:Y with
-the LibrePlanet wiki linking to the X issue on labs.parabola.nu.
+    [nonfree] for blatantly nonfree packages
+    [semifree] mostly free packages with some nonfree additions
+    [uses-nonfree] for depending upon, or recommending nonfree software
+    [branding] Arch instead of Parabola, Linux instead of GNU/Linux, etc.
+    [technical] patched to build from sources. various innocent circumstances
 
-To make reporting issues to gnu-linux-libre easier, we should explain
-in the description if the package is blacklisted due to an upstream FSDG
-issue, problem introduced by Arch (e.g. not including required license
-text, adding optional dependency on a nonfree package), or just
-branding, dependency or non-freedom-related issues which don't need
-reporting to other distros.
+  To make reporting issues to gnu-linux-libre easier, we should explain
+  in the description if the package is blacklisted due to an upstream FSDG
+  issue, problem introduced by Arch (e.g. not including required license
+  text, adding optional dependency on a nonfree package), or just
+  branding, dependency or non-freedom-related issues which don't need
+  reporting to other distros.