[groff] 03/23: groff_tmac(5),gropdf(1): Revise `PDFPIC` docs.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit b2e407c55d7470751caef57156f790b6e0fddd23
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Oct 14 14:08:06 2024 -0500

    groff_tmac(5),gropdf(1): Revise `PDFPIC` docs.
    
    Fix content and style nits.
    
    Content:
    * Convert column headings in tables to style them like man page cross
      references to clue in the user.  (If we converted them to text blocks
      we could make them full-on hyperlinks.)
    
    Style:
    * Capitalize proper nouns more idiomatically and in line with their
      vendors' branding.
    * Protect `PDFPIC` from hyphenation.
    * Recast.
---
 man/groff_tmac.5.man            | 70 +++++++++++++++++++++++++++--------------
 src/devices/gropdf/gropdf.1.man | 29 ++++++++++++-----
 2 files changed, 67 insertions(+), 32 deletions(-)

diff --git a/man/groff_tmac.5.man b/man/groff_tmac.5.man
index 61162c963..f7df3eb67 100644
--- a/man/groff_tmac.5.man
+++ b/man/groff_tmac.5.man
@@ -649,49 +649,71 @@ file when formatting for a typesetter
 .TP
 .I pdfpic
 provides a single macro,
-.BR PDFPIC ,
-it operates in two modes.
-If it is not used with the pdf output driver -T
-.IR pdf ,
+.BR \%PDFPIC ,
+that operates in two modes.
+.
+If it is not used with
+.IR gropdf ,
 the given
 .I file
-must be a pdf and it relies on the external program
+must be a PDF;
+.B \%PDFPIC
+then relies on the external program
 .MR pdftops 1
-to convert the pdf to an encapsulated postscript file
+to convert the PDF to an encapsulated PostScript (EPS) file
 and calls the
 .B PSPIC
 macro with which it shares an interface.
-If output is to a pdf it calls
-.BR "\[rs]X\[aq]pdf: pdfpic" \~.\|.\|. \[aq]
+.
+If output is to a PDF,
+.B \%PDFPIC
+uses the
+.RB \[lq] "pdf: \%pdfpic" \[rq]
+device extension command
 (see
-.MR gropdf @MAN1EXT@ )
-and the given
+.MR gropdf @MAN1EXT@ );
+the given
 .I file
-can be a pdf or any graphic format supported by
+can then be a PDF or any graphic file format supported by
 .IR gropdf .
+.
+.
+.IP
+Since
+.B \%PDFPIC
+needs to discover the width and height of the image
+(to check if sufficient room exists to place it on the page),
+it has dependencies on external programs as shown below.
+.
+.
 .IP
-Since this macro needs to discover the actual width and
-height of the image (in order to check if there is sufficient
-room on the page) there are dependencies on external programs
-shown in this table:-
 .TS
-allbox  centre;
-Cb Cb Cb Cb
-L C C C.
-       pdfinfo file    identify
+allbox center;
+Cb Ci Ci Ci
+L  C  C  C.
+\&     pdfinfo\fR(1)   file\fR(1)      identify\fR(1)
 \&.pdf \[OK]   \[OK]   \[OK]
 \&.jpg \[u2717]        \[OK]   \[OK]
 \&.jp2 \[u2717]        \[u2717]        \[OK]
 other  \[u2717]        \[u2717]        \[OK]
 .TE
+.
+.
 .IP
-To include \[oq]other\[cq] (e.g. png/pam/gif) image formats the
-perlmagick modules must be installed as well, they are used by
+To include image formats such as PNG,
+PAM,
+and GIF,
 .I gropdf
-to embed the graphic. They are not needed for the other 3 types.
+relies upon PerlMagick modules to embed the graphic.
+.
+They are not needed for the types listed in the table above.
+.
+.
 .IP
-If the required programs are not available, the file is treated as
-a pdf, so will likely fail if it is not a pdf.
+If the required programs are not available,
+.I file
+is treated as a PDF;
+failure is likely if it is not one.
 .
 .
 .TP
diff --git a/src/devices/gropdf/gropdf.1.man b/src/devices/gropdf/gropdf.1.man
index ac85a5871..f9b6329fc 100644
--- a/src/devices/gropdf/gropdf.1.man
+++ b/src/devices/gropdf/gropdf.1.man
@@ -972,25 +972,38 @@ and
 .I height
 are non-zero the image is scaled to \[oq]best fit\[cq].
 .
+.
+.IP
+The availability of other software on the system,
+such as
+.IR PerlMagick ,
+influences the types of image files
+.I gropdf
+can embed in its output.
+.
+.
 .IP
-Three elements control which type of image files you can now embed into a -T 
pdf produced file. If you have perlmagick installed, if you have the program 
"identify" installed (part of ImageMagick), if you have the program "file" 
installed, or if you have none of these. Here's a table showing the different 
possibilities:-
 .TS
-allbox  centre;
-Cb Cb Cb Cb Cb
-L C C C C.
-       none    file    identify        perlmagick
+allbox center;
+Cb Ci Ci Ci Ci
+L  C  C  C  C.
+\&     none    file\fR(1)      identify\fR(1)  Image::Magick\fR(3pm)
 \&.pdf \[OK]   \[OK]   \[OK]   \[OK]
 \&.jpg \[u2717]        \[OK]   \[OK]   \[OK]
 \&.jp2 \[u2717]        \[u2717]        \[OK]   \[OK]
 other  \[u2717]        \[u2717]        \[u2717]        \[OK]
 .TE
+.
+.
 .IP
 See
 .MR groff_tmac @MAN5EXT@
 for a description of the
-.B PDFPIC
-macro which provides a convenient high-level interface for inclusion
-of various graphics files.
+.B \%PDFPIC
+macro,
+which provides a convenient high-level interface for inclusion of
+various graphic file formats.
+.
 .
 .TP
 .B \[rs]X\[aq]pdf: xrev\[aq]