Describe the new syntax.

1 files changed, 30 insertions, 0 deletions

diff --git a/SYNTAX b/SYNTAX
new file mode 100644
index 0000000..45c36a8
--- /dev/null
+++ b/SYNTAX
@@ -0,0 +1,30 @@
+The *blacklist.txt files consist of lines in the following format:
+
+  original-package:libre-replacement:ref:id: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.
+
+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#
+    savannah: &sv https://savannah.nongnu.org/bugs/?
+    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.
+
+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.
+
+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.