Add explanation of pdf_ignored_tests with links to upstream poppler bug reports

boilerplate/cairo-boilerplate-pdf.c

@@ -43,7 +43,36 @@ typedef struct _pdf_target_closure
 } pdf_target_closure_t;
 
 #define ARRAY_LENGTH(__array) ((int) (sizeof (__array) / sizeof (__array[0])))
+
+/* We currently ignore tests that generate valid PDF output, but which
+ * poppler currently misrenders. This lets us avoid false negatives in
+ * the test suite, (at the significant cost that we won't notice any
+ * regressions in the PDF output of these tests).
+ *
+ * So obviously, we have an interest in ensuring that the poppler bugs
+ * get fixed sooner rather than later, so that we can re-enable these
+ * tests. As such, we're trying to be good citizens by reporting all
+ * such poppler bugs that we identify to the poppler bugzilla.
+ *
+ * Here's a tracking bug explaining the situation:
+ *
+ *	Poppler does not yet handle everything in the cairo test suite
+ *	https://bugs.freedesktop.org/show_bug.cgi?id=12143
+ *
+ * Here's the rule: To add any test to this list (based on a poppler
+ * bug), you must first create a new bug report against poppler,
+ * marked as blocking 12143, and list that bug here in a comment for
+ * the ignored test(s).
+ *
+ * And when this list shrinks to nothing, we can close bug 12143.
+ */
 static const char *pdf_ignored_tests[] = {
+  /* These first four failures are caused by poppler mis-handling
+   * transparency in gradients. See here:
+   *
+   *	Poppler doesn't correctly handle gradients with transparency
+   *	https://bugs.freedesktop.org/show_bug.cgi?id=12144
+   */
     "gradient-alpha",
     "linear-gradient",
     "text-pattern",