[bug #64576] [pdf.tmac] pdf*href option handling insufficiently flexible

[Deri James]

Follow-up Comment #6, bug #64576 (project groff):

I've just lost half a days typing, my fault, closed the wrong firefox window!
Not all is lost, phew, found snippets in my clipboard history as I copied text
from Dasher to the savannah page, but it has not got everything, because some
I typed directly. I have attached an example pdf and its source which
illustrates the fix.

The information below was going to be a reply to Branden & Alex, regarding a
fourth parameter to the .MR macro, which seemed to be misunderstood, but it
never got finished. Some of it may be useful information in this bug report,
but it was written before I had implemented the interim fix for this bug
report.

----

> I expect man page authors would violently protest if they were told they
> had to type all those quotes and, worse, repeat the name of the page.

The fourth parameter is never required by the man page author, and definitely

should not be used.

There is a fundamental difference between .MR used in a terminal viewer, where

it becomes an external reference to another man page (man://...), and pdf 
output where it is an internal reference to a man entry in the same document,

but only if the man entry exists, otherwise it is just treated as text rather

than a clickable. So if you produce a single man page as a pdf it will have no

clickables within it, unless it references itself as a "See also"!

It only becomes more useful when dealing with a collection of man entries 
within a single pdf, since then references between entries become clickable. 
To make this clear: with pdf output, .MR does nothing unless it is being used
to create a collated collection of man pages.

Talking about internal links (i.e. .pdfhref L).

The basic problem goes back to the design of the pdfmark macros. The concept 
is simple, one macro call marks a particular location in a document (.pdfhref

M) which accept two strings, a name and a descriptive text, either of which 
can be omitted, and a further macro which creates a link to a named 
destination (.pdfhref L) which again accepts the same two strings, either of 
which can be omitted.

When name is omitted the first word of descriptive text is used as the "name".

Here's the first issue "descriptive text" is intended to become part of the 
text flow of the document, so may contain typographic elements, so the first 
"word" (including typographic elements) would become the name. The second 
issue is that if descriptive text is missing from the link (.pdfhref L), the 
descriptive text from the matching .pdfhref M is used. Note also that the link

may appear before the mark within the document, which is why pdfroff and 
pdfmom do multiple runs of groff, the first run creates a string variable 
based on the mark’s given name containing it's descriptive text and outputs
a 
.ds line via a .tm which is then fed back into the next groff run before the 
actual document. This is where the problem lies. If the computed string 
variable name contains anything other than straight text this may be an 
illegal name for a string variable.

So .MR is the equivalent of calling .pdfhref L without a separate "name" 
provided, the 4th parameter rectifies this by separating name and descriptive

text. Given .MR is only active with man page collections, and a collection 
will probably require a make file or some other script it is this which can 
add the 4th parameter, not the man page author.

Hopefully, Branden's new "for" command will solve the issue, but I will wait 
to see what it returns if the whole string is made of special characters, such

as when the document is written in a different language and run through 
preconv.

----

Now to turn to external links, such as Branden's experiment with .pdfhref W.
This again has been fixed to stop groff complaining, however, his example will
not work using the special characters from the SS fonts. It is much more
likely that an IDN will come from a UTF-8  document written in greek. The
example shows this "working". The browser fails to locate the domain, but the
address looks correct in the browser window.


(file #55085, file #55086)

    _______________________________________________________

Additional Item Attachment:

File name: t.trf                          Size:2 KB
    <https://file.savannah.gnu.org/file/t.trf?file_id=55085>

File name: t.pdf                          Size:68 KB
    <https://file.savannah.gnu.org/file/t.pdf?file_id=55086>



    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?64576>

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/