RFC: doc: document api.*.file and the like

[Akim Demaille]

Hi all,

This is my proposal to document the new variables that provide
control over the file we use in C++.  I’m sure there are better
ways to document this, I’m not sure I’m the right person to do
it.  Contributions and critiques are most welcome.

commit 2a0072928e6e1ec567fea5c512c4cfc3dd798e3c
Author: Akim Demaille <address@hidden>
Date:   Mon Oct 8 08:24:34 2018 +0200

    doc: document api.*.file and the like
    
    * doc/bison.texi (Exposing the Location Classes): New.
    (%define Summary): Document api.location.file, api.location.include,
    api.stack.file and api.position.file.
    (C++ Bison Interface): stack.hh and position.hh are deprecated.

diff --git a/doc/bison.texi b/doc/bison.texi
index 5b6791f2..fbc4cc8e 100644
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@ -347,9 +347,11 @@ C++ Parsers
 
 C++ Location Values
 
-* C++ position::                One point in the source file
-* C++ location::                Two points in the source file
-* User Defined Location Type::  Required interface for locations
+* C++ position::                  One point in the source file
+* C++ location::                  Two points in the source file
+* Exposing the Location Classes:: Using the Bison location class in your
+                                  project
+* User Defined Location Type::    Required interface for locations
 
 A Complete C++ Example
 
@@ -5808,6 +5810,70 @@ The parser namespace is @code{foo} and @code{yylex} is 
referenced as
 @end deffn
 @c api.namespace
 
address@hidden ================================================== 
api.location.file
address@hidden {Directive} {%define api.location.file} "@var{file}"
address@hidden {Directive} {%define api.location.file} @code{none}
+
address@hidden @bullet
address@hidden Language(s): C++
+
address@hidden Purpose:
+Define the name of the file in which Bison's default location and position
+types are generated. @xref{Exposing the Location Classes}.
+
address@hidden Accepted Values:
address@hidden @asis
address@hidden @code{none}
+If locations are enabled, generate the definition of the @code{position} and
address@hidden classes in the header file if @code{%defines}, otherwise in
+the parser implementation.
+
address@hidden "@var{file}"
+Generate the definition of the @code{position} and @code{location} classes
+in @var{file}.  This file name can be relative (to where the parser file is
+output) or absolute.
address@hidden table
+
+Defining it imples @samp{%define api.position.file none} and @samp{%define
+api.stack.file none}.
+
address@hidden Default Value:
+Not applicable if locations are not enabled, or if a user location type is
+specified (see @code{api.location.type}).  Otherwise, Bison's
address@hidden is generated in @file{location.hh} (@pxref{C++ location}).
+
address@hidden History:
+Introduced in Bison 3.2.
address@hidden itemize
address@hidden deffn
+
address@hidden ================================================== 
api.location.file
address@hidden {Directive} {%define api.location.include} @{"@var{file}"@}
address@hidden {Directive} {%define api.location.include} @{<@var{file}>@}
+
address@hidden @bullet
address@hidden Language(s): C++
+
address@hidden Purpose:
+Specify how the generated file that defines the @code{position} and
address@hidden classes is included.  This makes sense when the
address@hidden class is exposed to the rest of your application/library in
+another directory.  @xref{Exposing the Location Classes}.
+
address@hidden Accepted Values: Argument for @code{#include}.
+
address@hidden Default Value:
address@hidden"@var{dir}/location.hh"} where @var{dir} is the directory part of 
the
+output.  For instance @file{src/parse} if
address@hidden/parse/parser.cc} was given.
+
address@hidden History:
+Introduced in Bison 3.2.
address@hidden itemize
+
address@hidden deffn
+
+
 @c ================================================== api.location.type
 @deffn {Directive} {%define api.location.type} @address@hidden@}
 
@@ -5827,6 +5893,28 @@ Introduced in Bison 2.7 for C, C++ and Java.  Introduced 
under the name
 @end itemize
 @end deffn
 
address@hidden ================================================== 
api.position.file
address@hidden {Directive} {%define api.position.file} @code{none}
+
address@hidden @bullet
address@hidden Language(s): C++
+
address@hidden Purpose:
+Disable the generation of the legacy file @file{position.hh}.  The class
address@hidden is now defined where the class @code{location} is.
+
address@hidden Accepted Values: @code{none}
+
address@hidden Default Value:
address@hidden if @code{api.location.file} is defined, otherwise a useless
address@hidden is generated for backward compatibility.
+
address@hidden History:
+Introduced in Bison 3.2.
address@hidden itemize
address@hidden deffn
+
+
 @c ================================================== api.prefix
 @deffn {Directive} {%define api.prefix} @address@hidden@}
 
@@ -5913,6 +6001,27 @@ the @code{full} value was introduced in Bison 2.7
 
 
 
address@hidden ================================================== api.stack.file
address@hidden {Directive} {%define api.stack.file} @code{none}
+
address@hidden @bullet
address@hidden Language(s): C++
+
address@hidden Purpose:
+Disable the generation of the legacy file @file{stack.hh}.
+
address@hidden Accepted Values: @code{none}
+
address@hidden Default Value:
address@hidden if @code{api.location.file} is defined, otherwise a useless
address@hidden is generated for backward compatibility.
+
address@hidden History:
+Introduced in Bison 3.2.
address@hidden itemize
address@hidden deffn
+
+
 @c ================================================== api.token.constructor
 @deffn Directive {%define api.token.constructor}
 
@@ -10559,15 +10668,11 @@ see @ref{%define Summary,,api.namespace}.  The 
various classes are generated
 in the following files:
 
 @table @file
address@hidden position.hh
address@hidden location.hh
address@hidden location.hh
 The definition of the classes @code{position} and @code{location}, used for
-location tracking when enabled.  These files are not generated if the
address@hidden variable @code{api.location.type} is defined.  @xref{C++
-Location Values}.
-
address@hidden stack.hh
-An auxiliary class @code{stack} used by the parser.
+location tracking when enabled.  This file is not generated if user defined
+locations are used, i.e., if the @code{%define} variable
address@hidden is defined.  @xref{C++ Location Values}.
 
 @item @var{file}.hh
 @itemx @var{file}.cc
@@ -10575,6 +10680,14 @@ An auxiliary class @code{stack} used by the parser.
 declaration and implementation of the C++ parser class.  The basename and
 extension of these two files follow the same rules as with regular C parsers
 (@pxref{Invocation}).
+
address@hidden position.hh
+A useless legacy file.  To get rid of it, use @samp{%define api.stack.file
+none}, or define @code{api.location.file}.
+
address@hidden stack.hh
+A useless legacy file.  To get rid of it, use @samp{%define
+api.position.file none}, or define @code{api.location.file}.
 @end table
 
 All these files are documented using Doxygen; run @command{doxygen} for a
@@ -10728,7 +10841,9 @@ classes will not be generated, and the user defined 
type will be used.
 @menu
 * C++ position::         One point in the source file
 * C++ location::         Two points in the source file
-* User Defined Location Type::  Required interface for locations
+* Exposing the Location Classes:: Using the Bison location class in your
+                                  project
+* User Defined Location Type::    Required interface for locations
 @end menu
 
 @node C++ position
@@ -10841,6 +10956,55 @@ Report @var{p} on @var{o}, taking care of special 
cases such as: no
 @code{filename} defined, or equal filename/line or column.
 @end deftypefun
 
address@hidden Exposing the Location Classes
address@hidden Exposing the Location Classes
+
+When both @code{%defines} and @code{%locations} are enabled, Bison generates
+an additional file: @file{location.hh}.  If you don't use locations outside
+of the parser, you may avoid its creation with @samp{%define
+api.location.file none}.
+
+However this file is useful if, for instance, your parser builds an abstract
+syntax tree decorated with locations: you may use Bison's @code{location}
+type independently of Bison's parser.  You may name the file differently,
+e.g., @samp{%define api.location.file "include/ast/location.hh"}: this name
+can have directory components, or even be absolute.  The way the location
+file is included is controlled by @code{api.location.include}.
+
+This way it is possible to have several parsers share the same location
+file.
+
+For instance, in @file{src/foo/parser.yy}, generate the
address@hidden/ast/loc.hh} file:
+
address@hidden
+// src/foo/parser.yy
+%locations
+%define api.namespace @address@hidden
+%define api.location.file "include/ast/loc.hh"
+%define api.location.include @{<ast/loc.hh>@}
address@hidden example
+
address@hidden
+and use it in @file{src/bar/parser.yy}:
+
address@hidden
+// src/bar/parser.yy
+%locations
+%define api.namespace @address@hidden
+%code requires @{#include <ast/loc.hh>@}
+%define api.location.type @{bar::address@hidden
address@hidden example
+
+Absolute file names are supported; it is safe in your @file{Makefile} to
+pass the flag
address@hidden'"$(top_srcdir)/include/ast/loc.hh"'} to
address@hidden for @file{src/foo/parser.yy}.  The generated file will not
+have references to this absolute path, thanks to @samp{%define
+api.location.include @{<ast/loc.hh>@}}.  Adding @samp{-I
+$(top_srcdir)/include} to your @code{CPPFLAGS} will suffice for the compiler
+to find @file{ast/loc.hh}.
+
 @node User Defined Location Type
 @subsubsection User Defined Location Type
 @findex %define api.location.type
@@ -10898,6 +11062,7 @@ files, reused by other parsers as follows:
 %code requires @{ #include <master/location.hh> @}
 @end example
 
+
 @node C++ Parser Interface
 @subsection C++ Parser Interface
 @c - define parser_class_name