[src/trunk]: src/external/bsd/byacc/bin Improve PostScript output.

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

details:   https://anonhg.NetBSD.org/src/rev/286bed6b7c6c
branches:  trunk
changeset: 936445:286bed6b7c6c
user:      uwe <uwe%NetBSD.org@localhost>
date:      Mon Jul 27 00:34:56 2020 +0000

description:
Improve PostScript output.

Some highlights in no particular order:

%destructor was somehow lost from the list that follows, it should be
part of it.

Use .Ic for yacc directives when they are defined, .Ql otherwise.

Use explicit .Sq Li (instead of .Ql) in description of %destructor to
make sure the result is consistently quoted.  It more readable that
way.

Use .Va and .Vt where appropriate.

C preprocessor directives are marked up with .No (a nop), so that it's
easy to switch them to something else if need be.  For now just use
them as plain words.

diffstat:

 external/bsd/byacc/bin/yacc.1 |  239 +++++++++++++++++++++++------------------
 1 files changed, 131 insertions(+), 108 deletions(-)

diffs (truncated from 570 to 300 lines):

diff -r 8647b7228458 -r 286bed6b7c6c external/bsd/byacc/bin/yacc.1
--- a/external/bsd/byacc/bin/yacc.1     Sun Jul 26 23:18:06 2020 +0000
+++ b/external/bsd/byacc/bin/yacc.1     Mon Jul 27 00:34:56 2020 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: yacc.1,v 1.8 2020/07/26 23:18:06 uwe Exp $
+.\"    $NetBSD: yacc.1,v 1.9 2020/07/27 00:34:56 uwe Exp $
 .\"
 .\" Copyright (c) 1989, 1990 The Regents of the University of California.
 .\" All rights reserved.
@@ -32,7 +32,7 @@
 .\"
 .\"    from: @(#)yacc.1        5.7 (Berkeley) 7/30/91
 .\"    from: Id: yacc.1,v 1.24 2014/10/06 00:03:48 tom Exp
-.\"    $NetBSD: yacc.1,v 1.8 2020/07/26 23:18:06 uwe Exp $
+.\"    $NetBSD: yacc.1,v 1.9 2020/07/27 00:34:56 uwe Exp $
 .\"
 .Dd October 5, 2014
 .Dt YACC 1
@@ -40,7 +40,7 @@
 .Sh NAME
 .Nm yacc
 .Nd an
-.Tn LALR(1)
+.Tn LALR Ns (1)
 parser generator
 .Sh SYNOPSIS
 .Nm
@@ -54,10 +54,10 @@
 reads the grammar specification in the file
 .Ar filename
 and generates an
-.Tn LALR(1)
+.Tn LALR Ns (1)
 parser for it.
 The parsers consist of a set of
-.Tn LALR(1)
+.Tn LALR Ns (1)
 parsing tables and a driver routine
 written in the C programming language.
 .Nm
@@ -65,7 +65,7 @@
 .Pa y.tab.c .
 .Pp
 The following options are available:
-.Bl -tag -width symbol_prefixXXX
+.Bl -tag -width Fl
 .It Fl b Ar file_prefix
 The
 .Fl b
@@ -73,7 +73,7 @@
 the string denoted by
 .Ar file_prefix .
 The default prefix is the character
-.Ar y .
+.Ql y .
 .It Fl B
 Create a backtracking parser (compile-type configuration for
 .Nm ) .
@@ -83,12 +83,14 @@
 option causes the header file
 .Pa y.tab.h
 to be written.
-It contains #define's for the token identifiers.
+It contains
+.No #define Ns 's
+for the token identifiers.
 .It Fl g
 The
 .Fl g
 option causes a graphical description of the generated
-.Tn LALR(1)
+.Tn LALR Ns (1)
 parser to be written to the file
 .Pa y.dot
 in graphviz format, ready to be processed by
@@ -100,15 +102,19 @@
 .Pa y.tab.i
 to be written.
 It contains extern declarations
-and supplementary #define's as needed to map the conventional
+and supplementary
+.No #define Ns 's
+as needed to map the conventional
 .Nm
-yy-prefixed names to whatever the
+.Va yy Ns \&-prefixed
+names to whatever the
 .Fl p
 option may specify.
 The code file, e.g.,
 .Pa y.tab.c
-is modified to #include this file
-as well as the
+is modified to
+.No #include
+this file as well as the
 .Pa y.tab.h
 file, enforcing consistent usage of the symbols defined in those files.
 The supplementary header file makes it simpler to separate compilation
@@ -118,18 +124,25 @@
 .Fl l
 option is not specified,
 .Nm
-will insert #line directives in the generated code.
-The #line directives let the C compiler relate errors in the
+will insert
+.No #line
+directives in the generated code.
+The
+.No #line
+directives let the C compiler relate errors in the
 generated code to the user's original code.
 If the
 .Fl l
 option is specified,
 .Nm
-will not insert the #line directives.
-#line directives specified by the user will be retained.
+will not insert the
+.No #line
+directives.
+.No #line
+directives specified by the user will be retained.
 .It Fl L
 Enable position processing, e.g.,
-.Dq %locations
+.Ql %locations
 (compile-type configuration for
 .Nm ) .
 .It Fl o Ar output_file
@@ -146,7 +159,7 @@
 options instructs
 .Nm
 to create a reentrant parser, like
-.Dq %pure-parser
+.Ql %pure-parser
 does.
 .It Fl p Ar symbol_prefix
 The
@@ -155,7 +168,7 @@
 the string denoted by
 .Ar symbol_prefix .
 The default prefix is the string
-.Ar yy .
+.Ql yy .
 .It Fl r
 The
 .Fl r
@@ -167,15 +180,15 @@
 and the tables file is named
 .Pa y.tab.c .
 The prefix
-.Dq y .
+.Ql y
 can be overridden using the
 .Fl b
 option.
 .It Fl s
 Suppress
-.Dq #define
+.No #define
 statements generated for string literals in a
-.Dq %token
+.Ql %token
 statement, to more closely match original
 .Nm
 behavior.
@@ -183,10 +196,14 @@
 Normally when
 .Nm
 sees a line such as
-.Dq %token OP_ADD "ADD"
+.Pp
+.Dl %token OP_ADD \*qADD\*q
+.Pp
 it notices that the quoted
 .Dq ADD
-is a valid C identifier, and generates a #define not only for
+is a valid C identifier, and generates a
+.No #define
+not only for
 .Dv OP_ADD ,
 but for
 .Dv ADD
@@ -196,18 +213,19 @@
 #define OP_ADD 257
 #define ADD 258
 .Ed
+.Pp
 The original
 .Nm
 does not generate the second
-.Dq #define .
+.No #define .
 The
 .Fl s
 option suppresses this
-.Dq #define .
+.No #define .
 .Pp
 .St -p1003.1
 documents only names and numbers for
-.Dq %token ,
+.Ql %token ,
 though the original
 .Nm
 and
@@ -243,18 +261,15 @@
 .Xr bison 1
 and other implementations of yacc.
 The
-.Dq %destructor
+.Ql %destructor
 and
-.Dq %locations
+.Ql %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
+.Bl -tag -width Ic
+.It Ic %destructor { Ar code Ic } Ar symbol Ns +
 Defines code that is invoked when a symbol is automatically
 discarded during error recovery.
 This code can be used to
@@ -267,32 +282,31 @@
 that will allow parsing to continue.
 This error recovery approach results in a memory leak
 if the
-.Dq YYSTYPE
+.Vt YYSTYPE
 value is, or contains, pointers to dynamically allocated memory.
 .Pp
 The bracketed
-.Dv code
+.Ar code
 is invoked whenever the parser discards one of the symbols.
-Within
-.Dv  code ,
-.Dq $$
+Within it
+.Sq Li $$
 or
-.Dq $\*[Lt]tag\*[Gt]$
+.Sq Li $\*[Lt] Ns Ar tag Ns Li \*[Gt]$
 designates the semantic value associated with the discarded symbol, and
-.Dq @$
+.Sq Li @$
 designates its location (see
-.Dq %locations
+.Ql %locations
 directive).
 .Pp
 A per-symbol destructor is defined by listing a grammar symbol
 in
-.Dv symbol+ .
+.Ar symbol Ns + .
 A per-type destructor is defined  by listing a semantic type tag (e.g.,
-.Dq \*[Lt]some_tag\*[Gt] )
+.Sq Li \*[Lt] Ns Ar some_tag Ns Li \*[Gt] )
 in
-.Dv symbol+ ;
+.Ar symbol Ns + ;
 in this case, the parser will invoke
-.Dv code
+.Ar code
 whenever it discards any grammar symbol that has that semantic type tag,
 unless that symbol has its own per-symbol destructor.
 .Pp
@@ -301,62 +315,60 @@
 per-type destructor:
 .Pp
 The code for
-.Dq \*[Lt]*\*[Gt]
+.Sq Li \*[Lt]*\*[Gt]
 is used
 for grammar symbols that have an explicitly declared semantic type tag
 (via
-.Dq %type ) ;
+.Ql %type ) ;
 .Pp
-the code for
-.Dq \*[Lt]\*[Gt]
+The code for
+.Sq Li \*[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
+.It Ic %expect Ar number
 Tell
 .Nm
 the expected number of shift/reduce conflicts.
 That makes it only report the number if it differs.
-.It Dv %expect-rr Ar number