Hi Deri, At 2024-11-16T13:02:02+0000, Deri wrote: > On Thursday, 14 November 2024 17:44:55 GMT G. Branden Robinson wrote: > You did commit to adding relevent info from the attached pdf regarding > the significant changes to gropdf, is this still your intention? > > There is now also a gap in the documentation of adding pdf features to > groff documents (since you have removed pdfmark.ms from the groff > repository). This served a dual purpose of documenting the pdfmark API > used by both pdfroff and -Tpdf.
Well, sort of. I found the API to be inadequately documented in
contrib/pdfroff, too.
See, e.g., this commit:
commit 5058bc7ea64fbc88e534cbeaa3b85b2e0d2014d8
Author: G. Branden Robinson <g.branden.robin...@gmail.com>
Date: Sat Mar 16 10:48:21 2024 -0500
[pdf,man,mdoc]: Refactor a recent feature.
The "pdfhref pipe" feature recently added used in-band signaling to
indicate that a PDF mark hotspot should be left open by the `pdhref`
hyperlink management macro. I'm uneasy with this because it forecloses
the possibility of using the chosen in-band signal content as link text.
(Compounding the risk of user frustration is that there's no
documentation of any of this.) Replace it by adding a new `-S` flag to
the `pdfhref` macro, indicating the caller's desire to manage closing of
the hotspot themselves, as "tmac/an.tmac" does already.
See <https://savannah.gnu.org/bugs/?61434#comment5>.
[...]
...or the last 2 pages of the generated pdfmark.pdf document.
(Even if the in-band singaling was your invention, I have found that in
no situation where I was looking at pdf.tmac and failed to find
documentation I desired, did pdfmark.tmac or pdfmark.pdf leave me any
the wiser.)
[rearranged]
> are you expecting me to write something at extremely short notice?
No.
> What are your intentions regarding filling this gap,
Unclear. I can live with either of:
1. leaving the API as documented as it is in gropdf(1) (and
"internally" in pdf.tmac) for this release; or
2. writing documentation myself of whatever parts of the API you
identify to me as essential and don't want to overhaul for groff
1.25.
It looks to me like there is much less ground to cover in pdf.tmac:
$ wc -l tmac/pdf.tmac ~/groff-stable/share/groff/1.23.0/tmac/pdfmark.tmac
876 tmac/pdf.tmac
1953 /home/branden/groff-stable/share/groff/1.23.0/tmac/pdfmark.tmac
I also think that you not should feel yourself bound by Keith's design
choices.
Regards,
Branden
signature.asc
Description: PGP signature
