[groff] 07/17: [troff]: Make pcolor request accept color id args.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit b889983a88928ccab84cdbb550e373393ebde944
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Oct 29 21:25:31 2024 -0500

    [troff]: Make pcolor request accept color id args.
    
    * src/roff/troff/input.cpp (report_color): Do it.
    
    * doc/groff.texi.in (Debugging) <pcolor>:
    * man/groff.7.man (Request short reference) <pcolor>:
    * man/groff_diff.7.man (New requests) <pcolor>: Document it.
    
    * NEWS: Update item.
---
 ChangeLog                | 13 +++++++++++++
 NEWS                     | 11 ++++++-----
 doc/groff.texi.in        |  7 ++++---
 man/groff.7.man          | 12 +++++++++++-
 man/groff_diff.7.man     | 14 ++++++++++----
 src/roff/troff/input.cpp | 22 +++++++++++++++-------
 6 files changed, 59 insertions(+), 20 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 909625a86..7f4729352 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,16 @@
+2024-10-29  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       [troff]: The `pcolor` request now accepts color identifiers as
+       arguments.
+
+       * src/roff/troff/input.cpp (report_color): Do it.
+
+       * doc/groff.texi.in (Debugging) <pcolor>:
+       * man/groff.7.man (Request short reference) <pcolor>:
+       * man/groff_diff.7.man (New requests) <pcolor>: Document it.
+
+       * NEWS: Update item.
+
 2024-10-29  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * tmac/de.tmac:
diff --git a/NEWS b/NEWS
index 8f16e6239..e578dc8a7 100644
--- a/NEWS
+++ b/NEWS
@@ -102,11 +102,12 @@ troff
    line continuation (cf. the `it` and `itc` requests), and the name of
    the macro associated with the pending input trap, respectively.
 
-*  A new request, `pcolor`, reports to the standard error stream each
-   defined color name, its color space identifier, and channel value
-   assignments.  (A device's default stroke and/or fill colors,
-   "default", are not listed since they are immutable and their details
-   unknown to the formatter.)
+*  A new request, `pcolor`, reports to the standard error stream details
+   of each color name specified as an argument, including its color
+   space identifier and channel value assignments.  Without arguments,
+   all defined colors are listed.  (A device's default stroke and/or
+   fill colors, "default", are not listed since they are immutable and
+   their details unknown to the formatter.)
 
 *  A new request, `pcomposite`, reports to the standard error stream the
    list of defined composite characters.
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 0f0c9ac1b..7f4b8f440 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -17180,12 +17180,13 @@ If you know in advance that there are many errors and 
no useful output,
 or are interested @emph{only} in diagnostic output, you can suppress GNU
 @code{troff}'s formatted output with its @option{-z} option.
 
-@Defreq {pcolor, }
+@Defreq {pcolor, [@Var{col} @r{@dots{}}]}
 @cindex dumping defined colors (@code{pcolor})
 @cindex defined colors, dumping (@code{pcolor})
 @cindex colors, defined, dumping (@code{pcolor})
-Report, to the standard error stream, each defined color name, its color
-space identifier, and channel value assignments.  A device's default
+Report, to the standard error stream, each defined color named
+@var{col}, its color space identifier, and channel value assignments,
+or, without arguments, those of all defined colors.  A device's default
 stroke and/or fill colors, ``default'', are not listed since they are
 immutable and their details unknown to the formatter.
 @endDefreq
diff --git a/man/groff.7.man b/man/groff.7.man
index 59b5e4c73..1f213e1f1 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -3960,7 +3960,8 @@ Change the page number character used in titles
 .
 .TPx
 .REQ .pcolor
-Report, to the standard error stream,
+Report,
+to the standard error stream,
 each defined color name,
 its color space identifier,
 and channel value assignments.
@@ -3971,6 +3972,15 @@ are not listed since they are immutable and their 
details unknown to the
 formatter.
 .
 .TPx
+.REQ .pcolor "col \fR\&.\|.\|.\&\fP"
+Report,
+to the standard error stream,
+the name,
+color space identifier,
+and channel value assignments of each color
+.IR col .
+.
+.TPx
 .REQ .pcomposite
 Report,
 to the standard error stream,
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 1fbd01b37..c18ef3952 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -3256,11 +3256,17 @@ in the top-level diversion.
 .
 .
 .TP
-.B .pcolor
-Report, to the standard error stream,
-each defined color name,
+.BR .pcolor \~[\c
+.IR col \~\&.\|.\|.]
+Report,
+to the standard error stream,
+each defined color named
+.IR col ,
 its color space identifier,
-and channel value assignments.
+and channel value assignments,
+or,
+without arguments,
+those of all defined colors.
 .
 A device's default stroke and/or fill colors,
 \[lq]default\[rq],
diff --git a/src/roff/troff/input.cpp b/src/roff/troff/input.cpp
index cdfeb2f77..71a56c3a3 100644
--- a/src/roff/troff/input.cpp
+++ b/src/roff/troff/input.cpp
@@ -1558,15 +1558,23 @@ static void define_color()
 
 static void report_color()
 {
-  // TODO: Accept an argument to look up a color by name and dump its
-  // info (name, color space, channel values).
-  dictionary_iterator iter(color_dictionary);
   symbol key;
   color *value;
-  while (iter.get(&key, reinterpret_cast<void **>(&value))) {
-    assert(!key.is_null());
-    assert(value != 0 /* nullptr */);
-    errprint("%1\t%2\n", key.contents(), value->print_color());
+  if (has_arg()) {
+    do {
+      key = get_name();
+      value = static_cast<color *>(color_dictionary.lookup(key));
+      if (value != 0 /* nullptr */)
+       errprint("%1\t%2\n", key.contents(), value->print_color());
+    } while (has_arg());
+  }
+  else {
+    dictionary_iterator iter(color_dictionary);
+    while (iter.get(&key, reinterpret_cast<void **>(&value))) {
+      assert(!key.is_null());
+      assert(value != 0 /* nullptr */);
+      errprint("%1\t%2\n", key.contents(), value->print_color());
+    }
   }
   fflush(stderr);
   skip_line();