syntax.md: mention headers supersede horizontal rules

Add a note to the syntax document mentioning that when using
a line of solid hyphens (`-`s) for a horizontal rule, it will
actually be treated as an H2 Setext-style header if the preceding
line is not blank.

Signed-off-by: Kyle J. McKay <mackyle@gmail.com>

syntax.md

@@ -817,6 +817,12 @@ following lines will produce a horizontal rule:
 
       ---------------------------------------
 
+Note that when using a line of three or more solid hyphens, if the
+preceding line is not empty, then it will be treated as part of one of
+the H2 Setext-style [headers].  Add at least one space between the
+hyphens to prevent that (or use asterisks or make sure the preceding
+line is blank).
+
 
 - - - - -