[src/trunk]: src/external/bsd/byacc/bin Sync mdoc page with the one provided ...

[christos <christos%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/6ab55668e729
branches:  trunk
changeset: 345722:6ab55668e729
user:      christos <christos%NetBSD.org@localhost>
date:      Sun Jun 05 16:24:34 2016 +0000

description:
Sync mdoc page with the one provided from upstream.

diffstat:

 external/bsd/byacc/bin/yacc.1 |  348 +++++++++++++++++++++++++++++++++++++++--
 1 files changed, 329 insertions(+), 19 deletions(-)

diffs (truncated from 422 to 300 lines):

diff -r a24e0ffdf425 -r 6ab55668e729 external/bsd/byacc/bin/yacc.1
--- a/external/bsd/byacc/bin/yacc.1     Sun Jun 05 15:05:49 2016 +0000
+++ b/external/bsd/byacc/bin/yacc.1     Sun Jun 05 16:24:34 2016 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: yacc.1,v 1.4 2011/09/10 21:38:59 christos Exp $
+.\"    $NetBSD: yacc.1,v 1.5 2016/06/05 16:24:34 christos Exp $
 .\"
 .\" Copyright (c) 1989, 1990 The Regents of the University of California.
 .\" All rights reserved.
@@ -31,10 +31,10 @@
 .\" SUCH DAMAGE.
 .\"
 .\"    from: @(#)yacc.1        5.7 (Berkeley) 7/30/91
-.\"    from: Id: yacc.1,v 1.12 2011/09/08 00:40:44 tom Exp
-.\"    $NetBSD: yacc.1,v 1.4 2011/09/10 21:38:59 christos Exp $
+.\"    from: Id: yacc.1,v 1.24 2014/10/06 00:03:48 tom Exp 
+.\"    $NetBSD: yacc.1,v 1.5 2016/06/05 16:24:34 christos Exp $
 .\"
-.Dd September 7, 2011
+.Dd October 5, 2014
 .Dt YACC 1
 .Os
 .Sh NAME
@@ -44,9 +44,9 @@
 parser generator
 .Sh SYNOPSIS
 .Nm
-.Op Fl dgilPrtVv
-.Op Fl b Ar prefix
-.Op Fl o Ar outputfile
+.Op Fl BdgilLPrtvVy
+.Op Fl b Ar file_prefix
+.Op Fl o Ar output_file
 .Op Fl p Ar symbol_prefix
 .Ar filename
 .Sh DESCRIPTION
@@ -65,15 +65,18 @@
 .Pa y.tab.c .
 .Pp
 The following options are available:
-.Bl -tag -width Ar
-.It Fl b Ar prefix
+.Bl -tag -width symbol_prefixXXX
+.It Fl b Ar file_prefix
 The
 .Fl b
 option changes the prefix prepended to the output file names to
 the string denoted by
-.Ar prefix .
+.Ar file_prefix .
 The default prefix is the character
 .Ar y .
+.It Fl B
+Create a backtracking parser (compile-type configuration for
+.Nm ) .
 .It Fl d
 The
 .Fl d
@@ -124,11 +127,19 @@
 .Nm
 will not insert the #line directives.
 #line directives specified by the user will be retained.
-.It Fl o Ar outputfile
-The
-.Fl o
-option specifies an explicit output file name should be used instead
-of the default.
+.It Fl L
+Enable position processing, e.g., 
+.Dq %locations
+(compile-type configuration for
+.Nm ) .
+.It Fl o Ar output_file
+Specify the filename for the parser file.
+If this option is not given, the output filename is
+the file prefix concatenated with the file suffix, e.g.
+.Pa y.tab.c .
+This overrides the
+.Fl b
+option. 
 .It Fl P
 The
 .Fl P
@@ -155,6 +166,53 @@
 .Pa y.code.c ,
 and the tables file is named
 .Pa y.tab.c .
+The prefix 
+.Dq y.
+can be overridden using the
+.Fl b
+option.
+.It Fl s
+Suppress 
+.Dq #define
+statements generated for string literals in a
+.Dq %token
+statement, to more closely match original
+.Nm 
+behavior.
+.Pp
+Normally when
+.Nm 
+sees a line such as
+.Dq %token OP_ADD "ADD"
+it notices that the quoted
+.Dq ADD
+is a valid C identifier, and generates a #define not only for 
+.Dv OP_ADD ,
+but for 
+.Dv ADD
+as well,
+e.g.,
+.Bd -literal -offset indent
+#define OP_ADD 257
+#define ADD 258
+.Ed
+The original
+.Nm
+does not generate the second
+.Dq #define .
+The 
+.Fl s
+option suppresses this
+.Dq #define .
+.Pp
+.St -p1003.1
+documents only names and numbers for
+.Dq %token ,
+though the original
+.Nm 
+and
+.Xr bison 1
+also accept string literals.
 .It Fl t
 The
 .Fl t
@@ -171,14 +229,87 @@
 option causes a human-readable description of the generated parser to
 be written to the file
 .Pa y.output .
+.It Fl y
+.Nm
+ignores this option,
+which
+.Xr bison 1
+supports for ostensible POSIX compatibility.
 .El
 .Sh EXTENSIONS
 .Nm
-provides some extensions for compatibility with 
+provides some extensions for
+compatibility with
 .Xr bison 1
-and other implementations
-of 
-.Nm :
+and other implementations of yacc.
+The 
+.Dq %destructor
+and 
+.Dq %locations
+features are available only if 
+.Nm yacc
+has been configured and compiled to support the back-tracking functionality.
+The remaining features are always available:
+.Pp
+.Dv %destructor {
+.Dv code }
+.Dv symbol+
+.Pp
+Defines code that is invoked when a symbol is automatically
+discarded during error recovery.
+This code can be used to
+reclaim dynamically allocated memory associated with the corresponding
+semantic value for cases where user actions cannot manage the memory
+explicitly.
+.Pp
+On encountering a parse error, the generated parser
+discards symbols on the stack and input tokens until it reaches a state
+that will allow parsing to continue.
+This error recovery approach results in a memory leak
+if the
+.Dq YYSTYPE
+value is, or contains, pointers to dynamically allocated memory.
+.Pp
+The bracketed 
+.Dv code
+is invoked whenever the parser discards one of the symbols.
+Within
+.Dv  code , 
+.Dq $$
+or
+.Dq $\*[Lt]tag\*[Gt]$
+designates the semantic value associated with the discarded symbol, and
+.Dq @$
+designates its location (see
+.Dq %locations
+directive).
+.Pp
+A per-symbol destructor is defined by listing a grammar symbol
+in 
+.Dv symbol+ .
+A per-type destructor is defined  by listing a semantic type tag (e.g.,
+.Dq \*[Lt]some_tag\*[Gt] )
+in
+.Dv symbol+ ;
+in this case, the parser will invoke
+.Dv code
+whenever it discards any grammar symbol that has that semantic type tag,
+unless that symbol has its own per-symbol destructor.
+.Pp
+Two categories of default destructor are supported that are
+invoked when discarding any grammar symbol that has no per-symbol and no
+per-type destructor:
+.Pp
+The code for
+.Dq \*[Lt]*\*[Gt]
+is used
+for grammar symbols that have an explicitly declared semantic type tag
+(via 
+.Dq %type ) ;
+.Pp
+the code for 
+.Dq \*[Lt]\*[Gt]
+is used for grammar symbols that have no declared semantic type tag.
 .Pp
 .Bl -tag -width "%expect-rr number" -compact
 .It Dv %expect Ar number
@@ -196,6 +327,71 @@
 allowable in
 .Tn LALR(1)
 parsers.
+.It Dv %locations
+Tell
+.Nm 
+to enable  management of position information associated with each token, 
+provided by the lexer in the global variable
+.Dv yylloc ,
+similar to management of semantic value information provided in
+.Dv yylval .
+.Pp
+As for semantic values, locations can be referenced within actions using
+.Dv @$
+to refer to the location of the left hand side symbol, and
+.Dv @N (
+.Dv N
+an integer) to refer to the location of one of the right hand side
+symbols.
+Also as for semantic values, when a rule is matched, a default
+action is used the compute the location represented by
+.Dv @$
+as the beginning of the first symbol and the end of the last symbol
+in the right hand side of the rule.
+This default computation can be overridden by
+explicit assignment to
+.Dv @$
+in a rule action.
+.Pp
+The type of
+.Dv yylloc
+is 
+.Dv YYLTYPE ,
+which is defined by default as:
+.Bd -literal -offset indent
+typedef struct YYLTYPE {
+    int first_line;
+    int first_column;
+    int last_line;
+    int last_column;
+} YYLTYPE;
+.Ed
+.Pp
+.Dv YYLTYPE
+can be redefined by the user (
+.Dv YYLTYPE_IS_DEFINED
+must be defined, to inhibit the default)
+in the declarations section of the specification file.
+As in
+.Xr bison 1 ,
+the macro
+.Dv YYLLOC_DEFAULT
+is invoked each time a rule is matched to calculate a position for the
+left hand side of the rule, before the associated action is executed;
+this macro can be redefined by the user.
+.Pp
+This directive adds a
+.Dv YYLTYPE
+parameter to
+.Fn yyerror .
+If the 
+.Dq %pure-parser
+directive is present,
+a 
+.Dv YYLTYPE
+parameter is added to 
+.Fn yylex
+calls.
 .It Dv %lex-param Ar { Ar argument-declaration Ar }
 By default, the lexer accepts no parameters, e.g.,