style: fix includes

* src/fixits.c: Follow our usual pattern.
* src/scan-code.l, src/scan-gram.l, src/scan-skel.l: Prefer "" to
include src/ headers.
* README-hacking.md: Document the pattern.

README-hacking.md

@@ -62,6 +62,30 @@ Don't reinvent the wheel: we use gnulib, which features many components.
 Actually, Bison has legacy code that we should replace with gnulib modules
 (e.g., many ad hoc implementations of lists).
 
+#### Includes
+The `#include` directives follow an order:
+- first section for *.c files is `<config.h>`.  Don't include it in header
+  files
+- then, for *.c files, the corresponding *.h file
+- then possibly the `"system.h"` header
+- then the system headers.
+  Consider headers from `lib/` like system headers (i.e., `#include
+  <verify.h>`, not `#include "verify.h"`).
+- then headers from src/ with double quotes (`#include "getargs.h"`).
+
+Keep headers sorted alphabetically in each section.
+
+See also the [Header
+files](https://www.gnu.org/software/gnulib/manual/html_node/Header-files.html)
+and the [Implementation
+files](https://www.gnu.org/software/gnulib/manual/html_node/Implementation-files.html#Implementation-files)
+nodes of the gnulib documentation.
+
+Some source files are in the build tree (e.g., `src/scan-gram.c` made from
+`src/scan-gram.l`).  For them to find the headers from `src/`, we actually
+use `#include "src/getargs.h"` instead of `#include "getargs.h"`---that
+saves us from additional `-I` flags.
+
 ### Skeletons
 We try to use the "typical" coding style for each language.
 

src/AnnotationList.h

@@ -21,6 +21,7 @@
 # define ANNOTATION_LIST_H_
 
 # include <bitsetv.h>
+
 # include "Sbitset.h"
 # include "InadequacyList.h"
 # include "state.h"

src/fixits.c

@@ -21,19 +21,19 @@
 
 #include "fixits.h"
 
+#include <error.h>
+#include <get-errno.h>
+#include <gl_array_list.h>
+#include <gl_xlist.h>
+#include <progname.h>
+#include <quote.h>
+#include <quotearg.h>
+#include <vasnprintf.h>
+
 #include "system.h"
 
-#include "error.h"
-#include "get-errno.h"
-#include "getargs.h"
-#include "gl_array_list.h"
-#include "gl_xlist.h"
-#include "progname.h"
-#include "quote.h"
-#include "quotearg.h"
-#include "vasnprintf.h"
-
 #include "files.h"
+#include "getargs.h"
 
 typedef struct
 {

src/print-xml.h

@@ -21,8 +21,6 @@
 #ifndef PRINT_XML_H_
 # define PRINT_XML_H_
 
-# include <config.h>
-
 # include <stdio.h>
 
 void xml_indent (FILE *out, int level);

src/scan-code.l

@@ -25,15 +25,15 @@
 #include <get-errno.h>
 #include <quote.h>
 
-#include <src/complain.h>
+#include "src/complain.h"
-#include <src/getargs.h>
+#include "src/getargs.h"
-#include <src/muscle-tab.h>
+#include "src/muscle-tab.h"
-#include <src/reader.h>
+#include "src/reader.h"
-#include <src/scan-code.h>
+#include "src/scan-code.h"
-#include <src/symlist.h>
+#include "src/symlist.h"
 
 #define FLEX_PREFIX(Id) code_ ## Id
-#include <src/flex-scanner.h>
+#include "src/flex-scanner.h"
 
 /* Work around a bug in flex 2.5.31.  See Debian bug 333231
    <http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=333231>.  */

src/scan-gram.l

@@ -28,16 +28,16 @@
 #include <quote.h>
 #include <quotearg.h>
 
-#include <src/complain.h>
+#include "src/complain.h"
-#include <src/files.h>
+#include "src/files.h"
-#include <src/getargs.h>
+#include "src/getargs.h"
-#include <src/gram.h>
+#include "src/gram.h"
-#include <src/reader.h>
+#include "src/reader.h"
-#include <src/scan-gram.h>
+#include "src/scan-gram.h"
-#include <src/uniqstr.h>
+#include "src/uniqstr.h"
 
 #define FLEX_PREFIX(Id) gram_ ## Id
-#include <src/flex-scanner.h>
+#include "src/flex-scanner.h"
 
 /* Work around a bug in flex 2.5.31.  See Debian bug 333231
    <http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=333231>.  */

src/scan-skel.l

@@ -26,13 +26,13 @@
 #include <path-join.h>
 #include <quotearg.h>
 
-#include <src/complain.h>
+#include "src/complain.h"
-#include <src/files.h>
+#include "src/files.h"
-#include <src/getargs.h>
+#include "src/getargs.h"
-#include <src/scan-skel.h>
+#include "src/scan-skel.h"
 
 #define FLEX_PREFIX(Id) skel_ ## Id
-#include <src/flex-scanner.h>
+#include "src/flex-scanner.h"
 
 /* Work around a bug in flex 2.5.31.  See Debian bug 333231
    <http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=333231>.  */