[groff] 05/13: [man]: Deprecate `OP` macro.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit feb204b70c207f34bbcb768abe7a32931561e50a
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Sep 11 01:19:16 2021 +1000

    [man]: Deprecate `OP` macro.
    
    * tmac/an-ext.tmac (OP): Move implementation from here...
    * tmac/an.tmac (OP): ...to here.  Throw deprecation warning.  Throw
      style warning if wrong number of arguments given.
    
    * tmac/groff_man.7.man.in (Description): Drop from introductory macro
      summary.
    
      (Description/Command synopsis macros): Move discussion from here...
    
      (Description/Deprecated features): ...to here.  Explain why it's
      deprecated.
---
 ChangeLog               | 15 ++++++++++
 tmac/an-ext.tmac        |  9 ------
 tmac/an.tmac            | 13 +++++++++
 tmac/groff_man.7.man.in | 76 ++++++++++++++++++++++++++-----------------------
 4 files changed, 68 insertions(+), 45 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 361d9da..495b99e 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,18 @@
+2021-09-11  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       [man]: Deprecate `OP` macro.
+
+       * tmac/an-ext.tmac (OP): Move implementation from here...
+       * tmac/an.tmac (OP): ...to here.  Throw deprecation warning.
+       Throw style warning if wrong number of arguments given.
+
+       * tmac/groff_man.7.man.in (Description): Drop from introductory
+       macro summary.
+       (Description/Command synopsis macros): Move discussion from
+       here...
+       (Description/Deprecated features): ...to here.  Explain why it's
+       deprecated.
+
 2021-09-07  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        [troff]: Make `ab` request quiet if given no arguments.  The
diff --git a/tmac/an-ext.tmac b/tmac/an-ext.tmac
index 4ac2faf..956d288 100644
--- a/tmac/an-ext.tmac
+++ b/tmac/an-ext.tmac
@@ -85,15 +85,6 @@
 ..
 .
 .
-.\" Declare optional option.
-.de OP
-.  ie \\n(.$-1 \
-.    RI "[\fB\\$1\fP" "\ \\$2" "]"
-.  el \
-.    RB "[" "\\$1" "]"
-..
-.
-.
 .\" Start URL.
 .de UR
 .  ds m1 \\$1\"
diff --git a/tmac/an.tmac b/tmac/an.tmac
index 6d0530f..4cab17d 100644
--- a/tmac/an.tmac
+++ b/tmac/an.tmac
@@ -786,6 +786,19 @@
 .  in \\n[an-margin]u
 ..
 .
+.\" Deprecated: Style an option with an argument (mandatory if
+.\" specified) for a command synopsis.
+.\" .OP flag [option-parameter]
+.de1 OP
+\\*[an-deprecation-warn]\\
+.  if ((\\n[.$] < 1) : (\\n[.$] > 2)) \
+.    an-style-warn .\\$0 expects 1 or 2 arguments, got \\n[.$]
+.  ie \\n[.$]>1 \
+.    RI "[\fB\\$1\fP" "\ \\$2" "]"
+.  el \
+.    RB "[" "\\$1" "]"
+..
+.
 .\" tbl(1) table support
 .
 .\" Start table.
diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in
index d0e1a90..e008cff 100644
--- a/tmac/groff_man.7.man.in
+++ b/tmac/groff_man.7.man.in
@@ -155,7 +155,6 @@ _
 \&.LP  (Left) paragraph        Paragraph macros
 \&.ME  Mail-to end     Hyperlink and email macros
 \&.MT  Mail-to start   Hyperlink and email macros
-\&.OP  (Command-line) option   Command synopsis macros
 \&.P   Paragraph       Paragraph macros
 \&.PP  Paragraph       Paragraph macros
 \&.RB  Roman, bold alternating Font style macros
@@ -854,21 +853,11 @@ appearance.
 .
 A command synopsis is wrapped in
 .BR .SY / .YS
-calls,
-with command-line options of some formats indicated by
-.BR .OP .
+calls.
 .
 .
 .P
-These macros are extensions
-.RB ( .OP
-from Documenter's Workbench
-.IR troff ,
-.B .SY
-and
-.B .YS
-from GNU)
-not defined on systems running
+These macros are GNU extensions not defined on systems running
 AT&T,
 Plan\~9,
 or
@@ -909,27 +898,6 @@ plus a space.
 .
 .
 .TP
-.BI .OP " option-name"\/\c
-.RI " [" option-argument ]
-Indicate an optional command parameter called
-.IR option-name ,
-which is set in bold.
-.
-If the option takes an argument,
-specify
-.I option-argument
-using a noun,
-abbreviation,
-or hyphenated noun phrase.
-.
-If present,
-.I option-argument
-is preceded by a space and set in italics.
-.
-Square brackets in roman surround both arguments.
-.
-.
-.TP
 .B .YS
 End synopsis.
 .
@@ -2186,7 +2154,7 @@ which should be avoided).
 .
 The macros we have described as extensions
 .RB ( .EX / .EE ,
-.BR .SY / .OP / .YS ,
+.BR .SY / .YS ,
 .BR .TQ ,
 .BR .UR / .UE ,
 and
@@ -2768,6 +2736,43 @@ may be lost.
 .
 .
 .TP
+.BI .OP " option-name"\/\c
+.RI " [" option-argument ]
+Indicate an optional command parameter called
+.IR option-name ,
+which is set in bold.
+.
+If the option takes an argument,
+specify
+.I option-argument
+using a noun,
+abbreviation,
+or hyphenated noun phrase.
+.
+If present,
+.I option-argument
+is preceded by a space and set in italics.
+.
+Square brackets in roman surround both arguments.
+.
+.
+.IP
+Use of this quasi-semantic macro,
+.\" https://github.com/n-t-roff/DWB3.3/blob/master/macros/man/an.sr#L37
+originating in Documenter's Workbench
+.IR troff ,\" DWB
+is deprecated.
+.
+It cannot easily be used to annotate options that take optional
+arguments or options whose arguments have internal structure
+(such as a mixture of literal and variable components).
+.
+One could work around these limitations with font escape sequences,
+but it is preferable to use font style alternation macros,
+which afford greater flexibility.
+.
+.
+.TP
 .BR .PD " ["\c
 .IR vertical-space ]
 Define the vertical space between paragraphs or (sub)sections.
@@ -3225,7 +3230,6 @@ reloads each macro package as necessary.
 .I \%@MACRODIR@/\:an\-ext\:.tmac
 The extension macro definitions for
 .BR .SY ,
-.BR .OP ,
 .BR .YS ,
 .BR .TQ ,
 .BR .EX / .EE ,