Re: Underfull and Overfull warnings for URLs

On Fri, Nov 01, 2024 at 10:38:17AM +0100, R. Diez wrote:
> Hi all:
> 
> OpenOCD's manual is written in Texinfo format:
> 
> https://sourceforge.net/p/openocd/code/ci/master/tree/doc/openocd.texi
> 
> An example of the generated PDF is here:
> 
> http://openocd.org/doc-release/pdf/openocd.pdf
> 
> When generating the PDF on my computer, I get some warnings like these:
> 
> Underfull \hbox (badness 10000) in paragraph at lines 525--528
>  []@textrm Link: [][]@texttt https://  software-dl.  ti.  com/  ccs/  esd/  doc
> uments/  xdsdebugprobes/
> 
> Underfull \hbox (badness 10000) in paragraph at lines 525--528
>  []@textrm Link: [][]@texttt https://  software-dl.  ti.  com/  ccs/  esd/  doc
> uments/  xdsdebugprobes/
> 
> These are the related .texi lines:
> 
> @item @b{TI XDS110 Debug Probe}
> @* Link: @url{https://software-dl.ti.com/ccs/esd/documents/xdsdebugprobes/emu_xds110.html}
> @* Link: @url{https://software-dl.ti.com/ccs/esd/documents/xdsdebugprobes/emu_xds_software_package_download.html#xds110-support-utilities}
> @end itemize
> 
> The generated text in the PDF looks indeed weird, and that is the reason for the warnings. Such long URLs are broken into the next line, but the first line is justified, so the first part of the URL gets moved to the right inside the line. Somebody helped me by posting this image of the problem:  https://ibb.co/M53SjdM
> 
> Alternatively, just search for "xdsdebugprobes" in the example PDF linked near the top of this e-mail to see the effect.
> 
> I already asked in the OpenOCD project, but I got no help:
> 
> https://sourceforge.net/p/openocd/mailman/openocd-devel/thread/19873a0f-4c6e-4484-8dc1-80656c5e4dda%40yahoo.de/#msg58778698
> 
> The trouble is, I know next to nothing about Textinfo, TeX or LaTeX. I have searched the Internet, and there are lots of advice about underfull and overfull warnings, but I haven't figured it out yet.
> 
> Could someone here tell me the best way to fix this problem with long URLs?

It is difficult to break URLs in a way that works for all cases.  There
have been complaints about this on multiple occasions.

There is not always a good place to break a URL.  It may be harder in your
case because it is inside an indented environment, making the line length
shorter.

There is some information on URL line breaking in the Texinfo manual:

https://www.gnu.org/software/texinfo/manual/texinfo/html_node/URL-Line-Breaking.html

Unfortunately, the information there doesn't help for this particular case.

We introduced code to allow URLs to break with a ragged-right margin to
prevent underfull lines:

https://lists.gnu.org/archive/html/bug-texinfo/2019-03/msg00007.html

However, this led to complaints for particular use cases:

https://lists.gnu.org/archive/html/bug-texinfo/2019-09/msg00021.html
https://lists.gnu.org/archive/html/bug-texinfo/2020-10/msg00021.html

We can make the output in your case achieve a raggged right by increasing
the space in \urefallowbreak from 2 em to e.g. 4 em.  However,
we have in fact decreased this length in the past:

2019-09-24  Gavin Smith  <[email protected]>

        @url line-breaking.

        * doc/texinfo.tex (\urefallowbreak): Discourage ragged right by 
        reducing end-line stretch and increasing penalty.  Test cases 
        sent by Vincent Lefevre.
        * doc/texinfo-tex-test.texi (URL line breaking): Add test cases.

(this is commit e5c979bcc43).

We keep examples to check in doc/texinfo-tex-test.texi.  This is to try
to stop us from just changing the output randomly, risking making the output
worse by accident for previously fixed cases.

Increasing the ragged right space from 2 em to 3 em doesn't break any
of the cases in that file, so I have made this change (commit 752656cc29,
2024-11-01).