develooper Front page | perl.perl5.porters | Postings from December 2019

Re: [perl #134093] Pod::Perldoc 3.2801 no longer includes the 'term'formatter class by default

Thread Previous | Thread Next
Zefram via perl5-porters
December 2, 2019 12:53
Re: [perl #134093] Pod::Perldoc 3.2801 no longer includes the 'term'formatter class by default
Message ID:
(I note that the message I'm replying to doesn't appear in the GitHub
instance of this ticket.  Problem with the RT->GitHub transition?)

Timothe Litt wrote:
>That seems like a draconian solution.

It's a conservative solution.  It's the simple way to ensure that everyone
gets legible output.  It's the appropriate thing to do until someone
implements the more sophisticated logic that gets most people highlighting
by default while still ensuring that everyone gets legible output.

>                                       It breaks all my scripts that use
>Pod::Usage (which runs perldoc under
>the covers).

By "breaks", presumably you mean that you get legible output that just
lacks highlighting.  This is a vastly preferable degraded mode to the
various forms of illegible output or total output failure that the
conservative patch protects against.  If you mean some stronger kind of
breakage than I'm supposing, then by all means report that as a bug in
its own right, with explicit detail.

>don't see an obvious way to pass -oterm
>through Pod::Usage to restore the expected behavior.

It would be wrong in any case for you to force the use of "-oterm"
on users.  You, as the invoker of Pod::Usage, don't know any better than
perldoc(1) whether the ToTerm formatter combined with the user's pager
can actually produce legible output for the present user.  However,
a user who knows that ToTerm works for em can stick "PERLDOC=-oterm" in
eir environment, and I think that'll influence Pod::Usage's invocation
of perldoc just as it influences direct invocations.

>However, with the old code, the work-around for the case that you tried
>to address is setting
>TERM=dumb -- which has the same effect as the new code -

No.  Setting a false $TERM interferes with the operation of the pager,
which is quite likely to make use of terminal capabilities that
termcap/terminfo knows about.  Even if the effect of "TERM=dumb" on
perldoc(1) were desirable, having it automatically take effect would
involve setting that in the user's normal environment, where it would
interfere with the operation of *every* program that wants to use an
addressable cursor or other terminal facilities.

>As for the escape sequences being "unportable" - (a) the ANSI sequences
>date back to the VT100, which
>was introduced in 1978.

They're old, but at no point became universal.  You don't get to dictate
which kind of terminal the user is allowed to have.

>(b) more importantly, if
>you happen to have a device/emulation that still doesn't support them -
>there's Termcap.

termcap is a wonderful system, and it would be nice to have a perldoc
output toolchain that was capable of using it to get highlighting on all
terminals that are capable of it.  That would be infinitely superior to
making the assumption that every terminal is a VT100.

However, we don't currently have such a toolchain.  Pagers in general do
use termcap or terminfo, in order to portably perform cursor addressing,
and it's a great blessing to perldoc that it can delegate that tricky
issue.  However, pagers are less likely to use their termcap skills to
render highlighting.  Generally, pagers expect their input to be plain
text, and they use termcap to portably provide the ability to page plain
text.  So long as perldoc delegates the paging job to an external program
(which due to user choice of pager is not something it's really desirable
to change), we are at the mercy of specific pagers with respect to what
highlighting it is possible to render, and in what form that highlighting
should be expressed in their input.

less(1) is one of the rare pagers that can portably render some
highlighting.  It still expects its input to be plain text, but, from
the old days of printer output, there is a way to portably represent some
highlighting via overstriking.  Specifically, less(1) interprets "a\ba" as
a request for a bold "a", and "_\ba" as a request for an underlined "a",
and renders both using sequences from terminfo if the terminal is capable
of these kinds of highlighting.  Note that this kind of overstriking
input not only renders nicely through actual overstriking on the kind
of printer it originates with, but also renders as unhighlighted text
if sent straight to any non-printing terminal.  Legible everywhere.

It would therefore be of some benefit if someone were to implement
something akin to Pod::Perldoc::ToTerm that emitted text using
these overstrike sequences to represent highlighting.  (Call it
"ToOverstriking".)  This is in fact the form in which groff (used by the
ToMan formatter, which used to be the default) represents highlighting
in its output.  The resulting output is plain enough that there's no
need to worry about whether the pager or terminal can handle it, and
those who are using a pager that renders overstriking the way less(1)
does get the benefit of the highlighting.

I'm not aware of any pager that uses termcap to render highlighing
that was expressed on input in the form of ANSI escape sequences or
indeed equivalent sequences for any specific non-printing terminal.
Obviously there would be some benefit in such a beast, but that's a
matter of pager development, not something we'd do on the Perl side.
The closest we've seen is the "-R" option provided by less(1) and some
implementations of more(1), which *passes through* ANSI escape sequences.
To use this route correctly, perldoc needs to be sure (whether through
termcap or otherwise) that the terminal accepts these sequences, needs
to be sure that the pager actually being used is of a version that is
capable of passing them through, and needs to invoke the pager with
the option telling it to do so.  This is not a general solution, but if
implemented correctly could address some users.

You also mentioned Pod::Text::Termcap.  This is an interesting module, but
has two serious flaws for perldoc's purposes.  Firstly, where a terminal
doesn't support highlighting or is unknown to termcap, the module falls
back to using ANSI escape sequences, which are almost certainly wrong.
I reported that as [ #131124]; the fallback behaviour needs
to be removed before Pod::Text::Termcap can be relied upon to produce
legible output.  Secondly, and more fundamentally, Pod::Text::Termcap
is only useful if the output is going directly to the terminal: it is
really not usable if the output is to go through a pager.

>                The change should be reverted, and any of the alternate
>approaches that
>I've outlined implemented or documented to replace it.

The change should remain in place until we have some better highlighting
logic that ensures that everyone gets legible output.  The documentation
being legible for everyone is a vitally important consideration, and
must not be compromised by any over-eager attempt to provide highlighting.

You're welcome to resolve this by implementing some suitably safe
highlighting logic in Pod::Perldoc.  This could be the superior "less -R"
logic that Sawyer and I discussed at length on [ #120229],
or the groff version logic also discussed there to make ToMan the default
for most users, or the ToOverstriking formatter that I suggested above.


Thread Previous | Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About