[src/trunk]: src/usr.bin/m4 Improve markup for better PostScript output.

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

details:   https://anonhg.NetBSD.org/src/rev/0e843fda486b
branches:  trunk
changeset: 973352:0e843fda486b
user:      uwe <uwe%NetBSD.org@localhost>
date:      Sat Jun 27 19:07:15 2020 +0000

description:
Improve markup for better PostScript output.
Make sure quotes are right and copy-pastable even in UTF-8 output.

diffstat:

 usr.bin/m4/m4.1 |  204 +++++++++++++++++++++++++++++++------------------------
 1 files changed, 114 insertions(+), 90 deletions(-)

diffs (truncated from 465 to 300 lines):

diff -r 7ef18480941a -r 0e843fda486b usr.bin/m4/m4.1
--- a/usr.bin/m4/m4.1   Sat Jun 27 18:52:24 2020 +0000
+++ b/usr.bin/m4/m4.1   Sat Jun 27 19:07:15 2020 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: m4.1,v 1.30 2020/06/25 02:59:20 uwe Exp $
+.\"    $NetBSD: m4.1,v 1.31 2020/06/27 19:07:15 uwe Exp $
 .\"    @(#) $OpenBSD: m4.1,v 1.56 2009/10/14 17:19:47 sthen Exp $
 .\"
 .\" Copyright (c) 1989, 1993
@@ -38,11 +38,11 @@
 .Nm m4
 .Nd macro language processor
 .Sh SYNOPSIS
-.Nm m4
+.Nm
 .Op Fl EGgiPQsv
 .Oo
 .Sm off
-.Fl D Ar name Op No = Ar value
+.Fl D Ar name Op Cm = Ar value
 .Sm on
 .Oc
 .Op Fl d Ar flags
@@ -56,42 +56,49 @@
 .Op Ar
 .Sh DESCRIPTION
 The
-.Nm m4
+.Nm
 utility is a macro processor that can be used as a front end to any
 language (e.g., C, ratfor, fortran, lex, and yacc).
 If no input files are given,
-.Nm m4
+.Nm
 reads from the standard input,
 otherwise files specified on the command line are
 processed in the given order.
-Input files can be regular files, files in the m4 include paths, or a
+Input files can be regular files, files in the
+.Nm
+include paths, or a
 single dash
-.Pq Sq - ,
+.Pq Sq Fl ,
 denoting standard input.
-.Nm m4
+.Nm
 writes
 the processed text to the standard output, unless told otherwise.
 .Pp
-Macro calls have the form name(argument1[, argument2, ..., argumentN]).
+Macro calls have the form
+.Fo name
+.Fa argument1\|
+.Bo \" should be Oo/Oc but mandoc chokes on it
+.Fa argument2
+.Fa \&...
+.Fa argumentN\|
+.Bc Ns Fc
 .Pp
 There cannot be any space following the macro name and the open
 parenthesis
-.Sq \&( .
+.Ql \&( .
 If the macro name is not followed by an open
 parenthesis it is processed with no arguments.
 .Pp
 Macro names consist of a leading alphabetic or underscore
-possibly followed by alphanumeric or underscore characters, e.g.,
-valid macro names match the pattern
-.Dq [a-zA-Z_][a-zA-Z0-9_]* .
+possibly followed by alphanumeric or underscore characters,
+i.e. valid macro names match the pattern
+.Dq Li [a-zA-Z_][a-zA-Z0-9_]*\| .
 .Pp
 In arguments to macros, leading unquoted space, tab, and newline
 .Pq Sq \en
 characters are ignored.
-To quote strings, use left and right single quotes
-.Po e.g.,\ \&
-.Sq "\ this is a string with a leading space"
-.Pc .
+To quote strings, use left and right single quotes, e.g.\&
+.Li "\` this is a string with a leading space\(aq" .
 You can change the quote characters with the
 .Ic changequote
 built-in macro.
@@ -100,39 +107,41 @@
 recognized as special when not followed by an open parenthesis.
 .Pp
 The options are as follows:
-.Bl -tag -width Ds
-.It Fl D , Fl Fl define Ar name Ns Op Pf = Ns Ar value
+.Bl -tag -width Fl
+.It Fl D , Fl Fl define Ar name Ns Op Ns Cm = Ns Ar value
 Define the symbol
 .Ar name
-to have some value (or
-.Dv NULL ) .
+to have
+.Ar value
+or to be a null string.
 .It Fl d , Fl Fl debug Ar "flags"
 Set trace flags.
 .Ar flags
 may hold the following:
-.Bl -tag -width Ds
-.It Ar a
+.Pp
+.Bl -tag -width ".Li XX" -compact
+.It Cm a
 print macro arguments.
-.It Ar c
+.It Cm c
 print macro expansion over several lines.
-.It Ar e
+.It Cm e
 print result of macro expansion.
-.It Ar f
+.It Cm f
 print filename location.
-.It Ar l
+.It Cm l
 print line number.
-.It Ar q
+.It Cm q
 quote arguments and expansion with the current quotes.
-.It Ar t
+.It Cm t
 start with all macros traced.
-.It Ar x
+.It Cm x
 number macro expansions.
-.It Ar V
-turn on all options.
+.It Cm V
+turn on all trace flags.
 .El
 .Pp
 By default, trace is set to
-.Qq eq .
+.Ql eq .
 .It Fl E , Fl Fl fatal-warnings
 Warnings make
 .Nm
@@ -141,16 +150,24 @@
 Save the input state to
 .Ar filename .
 .It Fl G , Fl Fl traditional
-Disable GNU-m4 extensions.
+Disable GNU\~m4 extensions.
 .It Fl g , Fl Fl gnu
-Activate GNU-m4 compatibility mode.
-In this mode, translit handles simple character
-ranges (e.g., a-z), regular expressions mimic emacs behavior,
-multiple m4wrap calls are handled as a stack,
+Activate GNU\~m4 compatibility mode.
+In this mode
+.Ic translit
+handles simple character
+ranges (e.g., 
+.Sq Li a-z ) ,
+regular expressions mimic emacs behavior,
+multiple
+.Ic m4wrap
+calls are handled as a stack,
 the number of diversions is unlimited,
 empty names for macro definitions are allowed,
-and eval understands
-.Sq 0rbase:value
+and
+.Ic eval
+understands
+.Sq Ic 0r Ns Ar base Ns Cm \&: Ns Ar value
 numbers.
 .It Fl Fl help
 Print help message and exit.
@@ -168,7 +185,7 @@
 .Ar filename .
 .It Fl P , Fl Fl prefix-builtins
 Prefix all built-in macros with
-.Sq m4_ .
+.Sq Li m4_ .
 For example, instead of writing
 .Ic define ,
 use
@@ -191,7 +208,7 @@
 Print the version and exit.
 .El
 .Sh SYNTAX
-.Nm m4
+.Nm
 provides the following built-in macros.
 They may be redefined, losing their original meaning.
 Return values are null unless otherwise stated.
@@ -205,9 +222,8 @@
 Comment sequences may be up to five characters long.
 The default values are the hash sign
 and the newline character.
-.Bd -literal -offset indent
-# This is a comment
-.Ed
+.Pp
+.Dl # This is a comment
 .Pp
 With no arguments, comments are turned off.
 With one single argument, the end comment sequence is set
@@ -217,9 +233,8 @@
 Quote sequences may be up to five characters long.
 The default values are the backquote character and the quote
 character.
-.Bd -literal -offset indent
-`Here is a quoted string'
-.Ed
+.Pp
+.Dl \&\`Here is a quoted string\(aq
 .Pp
 With no arguments, the default quotes are restored.
 With one single argument, the close quote sequence is set
@@ -238,22 +253,22 @@
 value of the second argument
 .Fa value .
 Each occurrence of
-.Sq $n
+.Sq Li \&$ Ns Ar n
 (where
 .Ar n
 is 0 through 9) is replaced by the
 .Ar n Ns 'th
 argument.
-.Sq $0
+.Sq Li $0
 is the name of the calling macro.
 Undefined arguments are replaced by a null string.
-.Sq $#
+.Sq Li $#
 is replaced by the number of arguments;
-.Sq $*
+.Sq Li $*\|
 is replaced by all arguments comma separated;
-.Sq $@
+.Sq Li $@
 is the same as
-.Sq $*
+.Sq Li $*\|
 but all arguments are quoted against further expansion.
 .It Fn defn name ...
 Returns the quoted definition for each argument.
@@ -262,7 +277,7 @@
 .It Fn divert num
 There are 10 output queues (numbered 0-9).
 At the end of processing
-.Nm m4
+.Nm
 concatenates all the queues in numerical order to produce the
 final output.
 Initially the output queue is 0.
@@ -277,12 +292,12 @@
 Prints the names and definitions for the named items, or for everything
 if no arguments are passed.
 .It Fn errprint msg
-Prints the first argument on the standard error output stream.
+Prints the first argument on the standard error stream.
 .It Fn esyscmd cmd
 Passes its first argument to a shell and returns the shell's standard output.
 Note that the shell shares its standard input and standard error with
-.Nm m4 .
-.It Fn eval expr[,radix[,minimum]]
+.Nm .
+.It Fn eval expr radix minimum
 Computes the first argument as an arithmetic expression using 32-bit
 arithmetic.
 Operators are the standard C ternary, arithmetic, logical,
@@ -304,17 +319,21 @@
 .Fa arg1
 and following arguments, in a way similar to
 .Xr printf 3 .
-This built-in is only available in GNU-m4 compatibility mode, and the only
+This built-in is only available in GNU\~m4 compatibility mode, and the only
 parameters implemented are there for autoconf compatibility:
 left-padding flag, an optional field width, a maximum field width,
-*-specified field widths, and the %s and %c data type.
+.So Li \&*\| Sc Ns -specified
+field widths, and the
+.Ql %s
+and
+.Ql %c
+data type.
 .It Fn ifdef name yes no
 If the macro named by the first argument is defined then return the second
 argument, otherwise the third.
-If there is no third argument, the value is
-.Dv NULL .
+If there is no third argument, the value is null.
 The word
-.Qq unix
+.Sq Li unix
 is predefined.
 .It Fn ifelse a b yes ...
 If the first argument