[troff]: Implement new `pcolor` request.

* src/roff/troff/input.cpp (report_color): Add.
  (init_input_requests): Wire up `pcolor` request name to
  `report_color()`.

* doc/groff.texi (Colors, Debugging):
* man/groff.7.man (Request short reference, Debugging):
* man/groff_diff.7.man (New requests, Debugging):
* NEWS: Document it.

Also fix style nit in groff(7); where a list's items already use commas,
separate items with semicolons.

6 files changed, 82 insertions, 7 deletions

diff --git a/ChangeLog b/ChangeLog
index 0f8741a72..48184e93d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,16 @@
+2024-01-05  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+	[troff]: Implement new `pcolor` request.
+
+	* src/roff/troff/input.cpp (report_color): Add.
+	(init_input_requests): Wire up `pcolor` request name to
+	`report_color()`.
+
+	* doc/groff.texi (Colors, Debugging):
+	* man/groff.7.man (Request short reference, Debugging):
+	* man/groff_diff.7.man (New requests, Debugging):
+	* NEWS: Document it.
+
 2024-01-04  G. Branden Robinson <g.branden.robinson@gmail.com>
 
 	[troff]: Trivially refactor.
diff --git a/NEWS b/NEWS
index 79b7af268..2f219aa7f 100644
--- a/NEWS
+++ b/NEWS
@@ -26,6 +26,11 @@ o The device-independent output now reports unbreakable spaces (those
 o A new read-only, string-valued register, `.trap`, interpolates the
   name of the next vertical position trap that will be sprung.
 
+o A new request, `pcolor`, reports to the standard error stream the
+  current list of 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.)
+
 o A new request, `phw`, reports to the standard error stream the current
   list of hyphenation exceptions.
 
diff --git a/doc/groff.texi b/doc/groff.texi
index 1d9478d74..a956f1a6b 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -12337,6 +12337,9 @@ clamps it at 65,535).
 .defcolor gray50 rgb 0.5 0.5 0.5
 .defcolor darkgreen rgb 0.1f 0.5f 0.2f
 @endExample
+
+You can obtain a report of colors defined by @code{defcolor} on the
+standard error stream with the @code{pcolor} request.  @xref{Debugging}.
 @endDefreq
 
 @cindex default color
@@ -16868,8 +16871,8 @@ or for instrumentation while troubleshooting.  The @code{ex} and
 exit codes respectively, to halt further processing when continuing
 would be fruitless.  Examine the state of the formatter with requests
 that write lists of defined names (macros, strings, and diversions),
-environments, hyphenation exceptions, registers, and page location traps
-to the standard error stream.
+defined colors, environments, hyphenation exceptions, registers, and
+page location traps to the standard error stream.
 @c END Keep parallel with section "Debugging" of groff(7).
 
 @Defreq {lf, line [@Var{file}]}
@@ -16945,6 +16948,16 @@ 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, }
+@cindex dumping defined colors (@code{pcolor})
+@cindex defined colors, dumping (@code{pcolor})
+@cindex colors, defined, dumping (@code{pcolor})
+Report, to the standard error stream, the list of defined color names.
+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
+
 @Defreq {pev, }
 @cindex dumping environments (@code{pev})
 @cindex environments, dumping (@code{pev})
diff --git a/man/groff.7.man b/man/groff.7.man
index d2b5c178e..79d10884e 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -10,7 +10,7 @@ language reference
 .\" Legal Terms
 .\" ====================================================================
 .\"
-.\" Copyright (C) 2000-2023 Free Software Foundation, Inc.
+.\" Copyright (C) 2000-2024 Free Software Foundation, Inc.
 .\"
 .\" This file is part of groff, the GNU roff type-setting system.
 .\"
@@ -3839,6 +3839,17 @@ Change the page number character used in titles
 .RI to\~ c .
 .
 .TPx
+.REQ .pcolor
+Report,
+to the standard error stream,
+the list of defined color names.
+.
+A device's default stroke and/or fill colors,
+\[lq]default\[rq],
+are not listed since they are immutable and their details unknown to the
+formatter.
+.
+.TPx
 .REQ .pev
 Report the state of the current environment followed by that of all
 other environments to the standard error stream.
@@ -8037,12 +8048,14 @@ defined names\[em]macros,
 strings,
 and
 .RB diversions\[em]( .pm );
+defined colors
+.RB ( .pcolor );
 hyphenation exceptions
-.RB ( .phw ),
+.RB ( .phw );
 environments
-.RB ( .pev ),
+.RB ( .pev );
 registers
-.RB ( .pnr ),
+.RB ( .pnr );
 and page location traps
 .RB ( .ptr )
 to the standard error stream.
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 2eebe6146..0a38b41ac 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -11,7 +11,7 @@ and AT&T
 .\" Legal Terms
 .\" ====================================================================
 .\"
-.\" Copyright (C) 1989-2023 Free Software Foundation, Inc.
+.\" Copyright (C) 1989-2024 Free Software Foundation, Inc.
 .\"
 .\" This file is part of groff, the GNU roff type-setting system.
 .\"
@@ -3092,6 +3092,18 @@ other environments to the standard error stream.
 .
 .
 .TP
+.B .pcolor
+Report,
+to the standard error stream,
+the list of defined color names.
+.
+A device's default stroke and/or fill colors,
+\[lq]default\[rq],
+are not listed since they are immutable and their details unknown to the
+formatter.
+.
+.
+.TP
 .B .phw
 Report,
 to the standard error stream,
@@ -5203,6 +5215,8 @@ and
 .
 More aspects of formatter state can be examined with requests that write
 lists of
+defined colors
+.RB ( pcolor ),
 environments
 .RB ( pev ),
 hyphenation exceptions
diff --git a/src/roff/troff/input.cpp b/src/roff/troff/input.cpp
index 296d3b5d0..a0b987634 100644
--- a/src/roff/troff/input.cpp
+++ b/src/roff/troff/input.cpp
@@ -1539,6 +1539,22 @@ static void define_color()
   skip_line();
 }
 
+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 entry;
+  color *color_entry;
+  while(iter.get(&entry, reinterpret_cast<void **>(&color_entry))) {
+    assert(!entry.is_null());
+    assert(color_entry != 0 /* nullptr */);
+    const char *color_name = entry.contents();
+    errprint("%1\n", color_name);
+  }
+  skip_line();
+}
+
 node *do_overstrike()
 {
   overstrike_node *on = new overstrike_node;
@@ -8607,6 +8623,7 @@ void init_input_requests()
   init_request("opena", opena_request);
   init_request("output", output_request);
   init_request("pc", set_page_character);
+  init_request("pcolor", report_color);
   init_request("pi", pipe_output);
   init_request("pm", print_macros);
   init_request("psbb", ps_bbox_request);