Add new tmac file pdfpic.tmac and document this

1 files changed, 139 insertions, 0 deletions

diff --git a/tmac/pdfpic.tmac b/tmac/pdfpic.tmac
new file mode 100644
index 000000000..16ac9e181
--- /dev/null
+++ b/tmac/pdfpic.tmac
@@ -0,0 +1,139 @@
+.\" pdfpic.tmac
+.\"
+.\" Define the PDFPIC macro.
+.\"
+.\" When used other than with gropdf, the image is converted to .eps
+.\" and processing passed over to PSPIC.
+.\"
+.\" Usage:
+.\"
+.\"   .PDFPIC [-L|-R|-C|-I <indent>] <file> [<width> [<height>]]
+.\"
+.\" Requires the poppler-utils package (for pdfinfo and pdftops).
+.\" Requires running groff in unsafe mode.
+.
+.do if d PDFPIC .nx
+.
+.nr _C \n[.C]
+.cp 0
+.
+.de @abort
+.  ab [PDFPIC]: \\$* Aborting.
+..
+.de PDFPIC
+.  if !\\n[.U] \
+.    @abort Use of \\$0 requires giving groff the -U option.
+.
+.  nr convert-pdf 0
+.  if !'\\*[.T]'pdf' .nr convert-pdf 1
+.
+.  nr pdf-offset-mode 0
+.
+.  \" left-aligned?
+.  ie '\\$1'-L' \{\
+.    nr pdf-offset-mode 1
+.    if \\n[convert-pdf] .ds pspic-args \\$1 \"
+.    shift
+.  \}
+.  el \{\
+.    \" right-aligned?
+.    ie '\\$1'-R' \{\
+.      nr pdf-offset-mode 2
+.      if \\n[convert-pdf] .ds pspic-args \\$1 \"
+.      shift
+.    \}
+.    el \{\
+.      \" indented?
+.      ie '\\$1'-I' \{\
+.        nr pdf-offset-mode 3
+.        nr pdf-offset (m;\\$2)
+.        if \\n[convert-pdf] .ds pspic-args \\$1 \\$2 \"
+.        shift 2
+.      \}
+.      el \{\
+.        \" centered is the default
+.        ie '\\$1'-C' \{\
+.          if \\n[convert-pdf] .ds pspic-args \\$1 \"
+.          shift
+.        \}
+.        el .nr pdf-offset-mode 0
+.      \}
+.    \}
+.  \}
+.  br
+.
+.  ds is-pdf \\$1
+.  substring is-pdf -3
+.  if !'\\*[is-pdf]'pdf' \
+.    @abort \\$1 at line \\n[.c] is not a PDF file, or lacks a .pdf extension.
+.
+.\" if driver is not gropdf, convert image to .eps
+.  if \\n[convert-pdf] \{\
+.    ds img-file \\$1
+.    substring img-file 0 -5
+.
+.    sy pdftops -eps \\$1
+.    shift
+.
+.    as pspic-args \\*[img-file].eps \\$*
+.
+.    PSPIC \\*[pspic-args]
+.    return
+.  \}
+.
+.\" get image dimensions
+.  ec @
+.  sy pdfinfo @$1 | \
+grep "Page *size" | \
+sed -e 's/Page *size: *\\([[:digit:].]*\\) *x *\\([[:digit:].]*\\).*$/\
+.nr pdf-wid (p;\\1)\\n\
+.nr pdf-ht  (p;\\2)/' \
+> /tmp/pdfpic\n[$$]
+.  so /tmp/pdfpic\n[$$]
+.  sy rm /tmp/pdfpic\n[$$]
+.  ec
+.
+.  \" if we have a <width> parameter, use it as the final
+.  \" image width; otherwise we use the image's natural width
+.  \" or the current line length, whatever is smaller
+.  ie (\\n[.$] >= 2) \
+.    nr pdf-deswid (i;\\$2)
+.  el \
+.    nr pdf-deswid ((\\n[.l] - \\n[.i]) <? \\n[pdf-wid])
+.
+.  \" compute the final image height (with proper rounding),
+.  \" based on the image's aspect
+.  nr pdf-desht (\\n[pdf-deswid] * 1000 + (\\n[pdf-wid] / 2) \
+                / \\n[pdf-wid] * \\n[pdf-ht] \
+                + 500 / 1000)
+.
+.  \" if we have a <height> parameter, use it as the final
+.  \" image height in case it is smaller than the height
+.  \" value we have just computed
+.  if ((\\n[.$] >= 3) & (\\n[pdf-desht] > (i;0\\$3))) \{\
+.    nr pdf-desht (i;\\$3)
+.    \" recompute the final image width since we always
+.    \" keep the correct image aspect
+.    nr pdf-deswid (\\n[pdf-desht] * 1000 + (\\n[pdf-ht] / 2) \
+                   / \\n[pdf-ht] * \\n[pdf-wid] \
+                   + 500 / 1000)
+.  \}
+.
+.  \" reserve vertical space for image
+.  ne (\\n[pdf-desht]u + 1v)
+.
+.  \" compute image offset w.r.t. the current left margin
+.  if (\\n[pdf-offset-mode] == 0) \
+.    nr pdf-offset (\\n[.l] - \\n[.i] - \\n[pdf-deswid] / 2)
+.  if (\\n[pdf-offset-mode] == 1) \
+.    nr pdf-offset 0
+.  if (\\n[pdf-offset-mode] == 2) \
+.    nr pdf-offset (\\n[.l] - \\n[.i] - \\n[pdf-deswid])
+.
+\h'\\n[pdf-offset]u'\
+\X'pdf: pdfpic \\$1 -L \\n[pdf-deswid]z \\n[pdf-desht]z'
+..
+.
+.cp \n[_C]
+.
+.\" end of pdfpic.tmac