[librsvg/rustification] tests/README.md: Improve the markup; describe 'crash' and 'styles' as well

[Federico Mena Quintero <federico src gnome org>]

commit f88130d9132d48aea4947728e083fae7bc5ee19c
Author: Federico Mena Quintero <federico gnome org>
Date:   Thu Nov 3 09:29:25 2016 -0600

    tests/README.md: Improve the markup; describe 'crash' and 'styles' as well

 tests/README.md |  131 ++++++++++++++++++++++++++++---------------------------
 1 files changed, 67 insertions(+), 64 deletions(-)
---
diff --git a/tests/README.md b/tests/README.md
index dd0289b..090a48c 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -27,80 +27,59 @@ Running the test suite
 ----------------------
 
 The easiest way to run all the tests is to go to librsvg's toplevel
-directory and run "make check".  This will run both the small unit
-tests and the black box tests in this librsvg/tests directory.
+directory and run `make check`.  This will run both the small unit
+tests and the black box tests in this `librsvg/tests` directory.
 
 If you want to run just the black box tests, go into this
-librsvg/tests directory and run "make check".
+`librsvg/tests` directory and run `make check`.
 
 Those commands will yield exit code 0 if all the tests pass, or
 nonzero if some tests fail.
 
-Running "make check" will produce a test/test-suite.log file.  You can
+Running `make check` will produce a `test/test-suite.log` file.  You can
 see this file for the details of failed tests.
 
 Additionally, all three sets of black box tests (crash, styles,
 rsvg-test) will produce a test report in a text file.  In the tests
-directory, you can see crash.log, styles.log, rsvg-test.log,
+directory, you can see `crash.log`, `styles.log`, `rsvg-test.log`,
 respectively.
 
 
-Tests and test fixtures
------------------------
+# Tests and test fixtures
 
-# Image-based reference tests for rsvg-test.c
+## Image-based reference tests for rsvg-test.c
 
 These will load, parse, and render an SVG, and compare the results
 against a reference PNG image.
 
-Each image-based reference test uses two files: foo.svg and
-foo-ref.png.  The test harness will render foo.svg and compare the
-results to foo-ref.png.  Currently we assume a pixel-perfect match.
+Each image-based reference test uses two files: `foo.svg` and
+`foo-ref.png`.  The test harness will render `foo.svg` and compare the
+results to `foo-ref.png`.  Currently we assume a pixel-perfect match.
 If there are differences in the output, the test will fail; see
-"Examining failed tests" below.
+"Examining failed reference tests" below.
 
-These files can go anywhere under the fixtures/reftests
-directory; the "rsvg-test" program will recursively look inside
-fixtures/reftests for all SVG files, render them, and compare them to
-the -ref.png reference images.
+These files can go anywhere under the `fixtures/reftests`
+directory; the `rsvg-test` program will recursively look inside
+`fixtures/reftests` for all SVG files, render them, and compare them to
+the `-ref.png` reference images.
 
 As of 2016/Nov/03 we have an informal organization of these files:
 
-* fixtures/reftests/*.svg - Tests for special situations
+* `fixtures/reftests/*.svg` - Tests for special situations
   that arose during development.
 
-* fixtures/reftests/bugs/*.svg - Tests for particular bug numbers.
+* `fixtures/reftests/bugs/*.svg` - Tests for particular bug numbers.
   Please use the bug number from Bugzilla, like 123456.svg, and the
   corresponding 123456-ref.png for the known-good reference image.
 
-* fixtures/reftests/svg1.1 - Tests from the W3C's SVG test suite.
+* `fixtures/reftests/svg1.1` - Tests from the W3C's SVG test suite.
   These are supposed to test all of SVG's features; we'll add them one
   by one as librsvg starts implementing the features.
 
+### Examining failed reference tests
 
-# Crash tests for crash.c
-
-These load and parse an SVG, and ensure that there are no errors in
-the process.  Note that this does *not* render the images.
-
-The SVG images live in the fixtures/crash directory.  The "crash"
-program will look recursively look inside fixtures/crash for all SVG
-files, load them, and ensure that no GError was produced while loading
-each file.
-
-
-# Style tests for styles.c
-
-These load and parse an SVG, ask librsvg to fetch an SVG object by its
-id, and ensure that the object has certain style properties with
-particular values.
-
-
-Examining failed reference tests
---------------------------------
-
-Let's say you run "make check" and see that one of the tests fails.
-For example, rsvg-test.log may have lines that look like
+Let's say you run `make check` and see that one of the tests fails.
+For example, `rsvg-test.log` may have lines that look like
 
 ```
 # Storing test result image at /tmp/paths-data-18-f-out.png
@@ -112,60 +91,84 @@ FAIL: rsvg-test 29 /rsvg-test/reftests/svg1.1/paths-data-18-f.svg
 ```
 
 This means that the test named
-"/rsvg-test/reftests/svg1.1/paths-data-18-f.svg" failed:  those are
+`/rsvg-test/reftests/svg1.1/paths-data-18-f.svg` failed:  those are
 autogenerated test names from GTest.  In this case, it means that the
-test file fixtures/reftests/svg1.1/paths-data-18-f.svg got rendered,
+test file `fixtures/reftests/svg1.1/paths-data-18-f.svg` got rendered,
 and produced incorrect output when compared to
-fixtures/reftests/svg1.1/paths-data-18-f-out.png.
+`fixtures/reftests/svg1.1/paths-data-18-f-out.png`.
 
-When a test fails, rsvg-test creates two images:
+When a test fails, rsvg-test creates two images in `/tmp`:
 
 ```
 /tmp/foo-out.png
 /tmp/foo-diff.png
 ```
 
-In this case, foo-out.png is the actual rendered output, which is presumed to
-be incorrect, since it differs from the foo-ref.png reference image.
-The foo-diff.png is a "visual diff" that you can see in an image
+In this case, `foo-out.png` is the actual rendered output, which is presumed to
+be incorrect, since it differs from the `foo-ref.png` reference image.
+The `foo-diff.png` is a "visual diff" that you can see in an image
 viewer; pixels that differ are highlighted.
 
 It is up to you to decide what to do next:
 
-* If the foo-out.png image looks correct, and the only difference with
-  respect to the foo-ref.png reference image is that antialiased edges
-  look different, or font rendering is slightly different due to
-  system-specific changes, you can just regenerate the test image.
-  See "Regenerating reference images" below.
+* If the `foo-out.png` image looks correct, and the only difference
+  with respect to the `foo-ref.png` reference image is that
+  antialiased edges look different, or font rendering is slightly
+  different due to the font-rendering machinery in your system, you
+  can just regenerate the test image.  See "Regenerating reference
+  images" below.
 
-* If the foo-out.png image is obviously wrong when compared to the
-  foo-ref.png reference, you can file a bug in bugzilla.gnome.org.  You can wait
-  until someone fixes it, or try to fix the bug yourself!
+* If the `foo-out.png` image is obviously wrong when compared to the
+  `foo-ref.png` reference, you can file a bug in
+  https://bugzilla.gnome.org.  You can wait until someone fixes it, or
+  try to fix the bug yourself!
 
 * Any other situation of course deserves attention.  Feel free to ask
   the maintainers about it; even if you figure out the problem
   yourself, a failed test almost always indicates a problem that is
-  not just on your end.
+  not just on your end.  See the `librsvg/MAINTAINERS` file for where
+  to reach them.
 
 
-Regenerating reference images
------------------------------
+### Regenerating reference images
 
 Let's continue with the example above, where the test
-/rsvg-test/reftests/svg1.1/paths-data-18-f.svg failed.  Let's say you
+`/rsvg-test/reftests/svg1.1/paths-data-18-f.svg` failed.  Let's say you
 fix the bug, or determine that the output image is in fact correct,
 and just differs from the reference image due to antialiasing
 artifacts.  In this case, you'll want to regenerate the reference
 image so the test passes again.
 
 If you want to regenerate the reference image
-fixtures/reftests/foo/bar.png, you can run
+`fixtures/reftests/foo/bar-ref.png` from the corresponding `bar.svg`, you can run
 
 ```
-rsvg-convert -o fixtures/reftests/foo/bar.png fixtures/reftests/foo/bar.svg
+rsvg-convert -o fixtures/reftests/foo/bar-ref.png fixtures/reftests/foo/bar.svg
 ```
 
 This is just the normal rsvg-convert program doing its job; it will
 just render the SVG image and output it to the specified PNG file.
 
-You can then run "make check" again and ensure that the tests pass.
+You can then run `make check` again and ensure that the tests pass.
+
+
+## Crash tests for crash.c
+
+These load and parse an SVG, and ensure that there are no errors in
+the process.  Note that this does *not* render the images.
+
+The SVG images live in the `fixtures/crash` directory.  The `crash`
+program will look recursively look inside `fixtures/crash` for all SVG
+files, load them, and ensure that no GError was produced while loading
+each file.
+
+
+## Style tests for styles.c
+
+These load and parse an SVG, ask librsvg to fetch an SVG object by its
+id, and ensure that the object has certain style properties with
+particular values.
+
+The SVG images live in the `fixtures/styles` directory.  The
+corresponding object IDs and values to be tested for are in the
+`styles.c` source code.