Re: Multiline Subject as PDF metadata

[Deri]

On Monday, 31 January 2022 08:15:55 GMT Dave Kemper wrote:
> On 1/28/22, Deri <deri@chuzzlewit.myzen.co.uk> wrote:
> > If you are using -T pdf you
> > don't need to include -mpdfmark, this is documented in the gropdf man page
> > and the pdfmark.pdf is referenced.
> 
> True, but just barely.  It's mentioned in one entry in the list of \X
> escapes.  This is down in a level of detail that a lot of gropdf users
> won't necessarily need, whereas at least the .pdfinfo macro under
> discussion is a document-level control knob.  But users won't know it
> exists unless they read every entry of the \X list *and* follow the
> pointer to pdfmark.pdf.
> 
> And even for those users who do find it, the list item in question is
> less helpful than it could be:
>  * It directs users to pdfmark.pdf but gives no hint where to find this
> file. * It's vague about which pdfmark facilities are available by default
> in -Tpdf ("a subset" covering "most functionality," with no
> elaboration about what's included or excluded).
> 
> I feel like the tie between gropdf and pdfmark should be mentioned
> near the top of the Usage section.  If the man page doesn't list all
> the macros available, it should at least mention two or three
> important ones and what they do, so users have some idea of the
> functionality available to know they should move along to a separate
> PDF file (which is often a couple more steps than just looking at
> another man page, so it's worth giving some incentive).
> 
> That part could arguably come under the umbrella of
> http://savannah.gnu.org/bugs/?61958.

Pdfmark.pdf has been around longer than -T pdf, it is the best resource we have 
for producing 
pdfs with groff, and details the macros and how to use them. It is applicable 
to grops as well as 
gropdf if you process the postscript through a distiller.

PDFMARK is an extension to the postscript language, pdfmark.tmac is the groff 
api to use those 
extensions. Gropdf uses the same api because Keith did such a good job 
originally, but there are 
elements of a pdf which are not covered by the postscript extensions, so these 
are described in 
the gropdf man page.

Documentation can usually be improved and refined, as we have seen the 
contributions of you 
and Branden, and something which specifically documents how to produce pdfs 
from groff is a 
good idea. Of course the pdfmark extensions, and extras in pdf.tmac, are really 
low level 
commands, I suspect most groff pdf production is done either with -ms or -mom, 
so a lot of the 
information available is aimed at people who wish to integrate into their own 
macros.

You are correct that gropdf man page should have a more prominent reference to 
pdfmark.pdf 
and perhaps a reference to it in the Files section, and the same could be said 
for the grops man 
page since many still use grops to produce pdfs.