Re: Fwd: [docutils:bugs] Re: #477 Generated man page leads to groff warning "TE macro called with TW register undefined"

"G. Branden Robinson" <[email protected]> Tue, 13 Feb 2024 10:52:20 -0600

Newsgroups	gmane.text.docutils.devel
Message-ID	<20240213165220.kzdw3g74hpak2mfb@illithid>

Hi Engelbert,

I managed to miss this 3 months ago.

[regarding the ' and . control characters in *roff]

At 2023-11-15T13:32:00+0000, engelbert gruber wrote:
> > They are not the same, as noted in the first URL above. However, a
> > portable man(7) document is unlikely to ever rely on the distinction
> > between them
> 
> you mean i should not use it in the manpage-writer ... for example
> inline UR/UE is easy with ' ...

It makes no difference because the UR and UE macros don't break the line
anyway, and that is all the no-break control character ' is for.  Long
story short, you never need to call a man(7) macro with the no-break
control character, and groff man(7) will never do anything different if
you do.  I don't think any other man(7) implementation will either, but
I won't guarantee that.  (For a macro to even know which control
character was used to call it requires a GNU extension.)

Let me illustrate.  Here's a sample document.

$ cat ATTIC/UR-and-UE-demo.man
.TH foo 1 2024-02-13 "groff test suite"
.SH Name
foo \- frobnicate a bar
.SH Description
For demonstration purposes,
the topic of discussion is
.UR https://\:sourceforge\:.net/\:p/\:docutils/\:bugs/\:477/
python-docutils bug #477
.UE .
Once again,
the topic of discussion is
'UR https://\:sourceforge\:.net/\:p/\:docutils/\:bugs/\:477/
python-docutils bug #477
'UE .

Now let's render it with and without explicit rendering of the URL
(groff man(7) will mark up the link text with OSC 8 escape sequences[1]
to make hyperlink text, but like font style changes, that won't show up
copy-and-pasted into an email).

$ nroff -man -Tascii ATTIC/UR-and-UE-demo.man
foo(1)                       General Commands Manual                      foo(1)

Name
     foo - frobnicate a bar

Description
     For  demonstration purposes, the topic of discussion is python-docutils bug
     #477.  Once again, the topic of discussion is python-docutils bug #477.

groff test suite                   2024-02-13                             foo(1)

$ nroff -rU0 -man -Tascii ATTIC/UR-and-UE-demo.man
foo(1)                       General Commands Manual                      foo(1)

Name
     foo - frobnicate a bar

Description
     For  demonstration purposes, the topic of discussion is python-docutils bug
     #477 <https://sourceforge.net/p/docutils/bugs/477/>.  Once again, the topic
     of  discussion  is  python-docutils  bug  #477  <https://sourceforge.net/p/
     docutils/bugs/477/>.

groff test suite                   2024-02-13                             foo(1)

Regards,
Branden

[1] https://github.com/Alhadis/OSC8-Adoption

signature.asc (application/pgp-signature, 833 B)