[PATCH 3/4] style: fix includes

[Akim Demaille]

* 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    | 24 ++++++++++++++++++++++++
 src/AnnotationList.h |  1 +
 src/fixits.c         | 20 ++++++++++----------
 src/print-xml.h      |  2 --
 src/scan-code.l      | 14 +++++++-------
 src/scan-gram.l      | 16 ++++++++--------
 src/scan-skel.l      | 10 +++++-----
 7 files changed, 55 insertions(+), 32 deletions(-)

diff --git a/README-hacking.md b/README-hacking.md
index af14dbf0..d596c7e3 100644
--- a/README-hacking.md
+++ b/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 sort 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.
 
diff --git a/src/AnnotationList.h b/src/AnnotationList.h
index d5258a57..a9f808c5 100644
--- a/src/AnnotationList.h
+++ b/src/AnnotationList.h
@@ -21,6 +21,7 @@
 # define ANNOTATION_LIST_H_
 
 # include <bitsetv.h>
+
 # include "Sbitset.h"
 # include "InadequacyList.h"
 # include "state.h"
diff --git a/src/fixits.c b/src/fixits.c
index 2c900254..701d2ad4 100644
--- a/src/fixits.c
+++ b/src/fixits.c
@@ -21,19 +21,19 @@
 
 #include "fixits.h"
 
-#include "system.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 "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 "system.h"
 
 #include "files.h"
+#include "getargs.h"
 
 typedef struct
 {
diff --git a/src/print-xml.h b/src/print-xml.h
index c057780b..51d3c15c 100644
--- a/src/print-xml.h
+++ b/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);
diff --git a/src/scan-code.l b/src/scan-code.l
index 8259bfd3..1aaecd4e 100644
--- a/src/scan-code.l
+++ b/src/scan-code.l
@@ -25,15 +25,15 @@
 #include <get-errno.h>
 #include <quote.h>
 
-#include <src/complain.h>
-#include <src/getargs.h>
-#include <src/muscle-tab.h>
-#include <src/reader.h>
-#include <src/scan-code.h>
-#include <src/symlist.h>
+#include "src/complain.h"
+#include "src/getargs.h"
+#include "src/muscle-tab.h"
+#include "src/reader.h"
+#include "src/scan-code.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>.  */
diff --git a/src/scan-gram.l b/src/scan-gram.l
index 763432d8..e3d96f24 100644
--- a/src/scan-gram.l
+++ b/src/scan-gram.l
@@ -28,16 +28,16 @@
 #include <quote.h>
 #include <quotearg.h>
 
-#include <src/complain.h>
-#include <src/files.h>
-#include <src/getargs.h>
-#include <src/gram.h>
-#include <src/reader.h>
-#include <src/scan-gram.h>
-#include <src/uniqstr.h>
+#include "src/complain.h"
+#include "src/files.h"
+#include "src/getargs.h"
+#include "src/gram.h"
+#include "src/reader.h"
+#include "src/scan-gram.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>.  */
diff --git a/src/scan-skel.l b/src/scan-skel.l
index 703c56f5..d7e334d5 100644
--- a/src/scan-skel.l
+++ b/src/scan-skel.l
@@ -26,13 +26,13 @@
 #include <path-join.h>
 #include <quotearg.h>
 
-#include <src/complain.h>
-#include <src/files.h>
-#include <src/getargs.h>
-#include <src/scan-skel.h>
+#include "src/complain.h"
+#include "src/files.h"
+#include "src/getargs.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>.  */
-- 
2.26.2