Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

"Underfull" and "Overfull" warnings emitted from Latex. #693

Closed
burblebee opened this issue Apr 13, 2016 · 14 comments
Closed

"Underfull" and "Overfull" warnings emitted from Latex. #693

burblebee opened this issue Apr 13, 2016 · 14 comments
Labels
big An issue causing a large set of changes, scattered across most of the text.

Comments

@burblebee
Copy link
Contributor

We get a ton of "Underfull" and "Overfull" warnings emitted during the Latex build of the spec. What causes them? Can they be fixed?

@godbyk
Copy link
Contributor

godbyk commented Apr 13, 2016

The underfull and overfull warnings mean that TeX was unhappy with the spacing in a line—either the line ended up being too short or too long.

For small values of points, this is rarely noticeable to the casual reader and can be ignored. For larger values, there will be white space at the end of a line or a line may overrun its margin.

The amount that you let TeX stretch or shrink the spaces in a line to make it fit the margins can be modified to make TeX more or less lax.

Generally, I just look for overfull or underfull lines that are more than a few points and visually inspect them to see if I need to make any adjustments (e.g., teach TeX how to hyphenate a new word, reword a sentence so it can be typeset more easily, adjust TeX's line breaking parameters to better accommodate that paragraph).

@zygoloid
Copy link
Member

@tkoeppe went through and fixed a bunch of these, but I don't think he got through all of the document. It would be good to get this clean before we produce the C++17 IS.

@burblebee
Copy link
Contributor Author

I tracked down one of the Underfull cases - it's caused by a section name which is too long in xref.tex:
func.searchers.boyer_moore_horspool.creation\quad\ref{func.searchers.boyer_moore_horspool.creation}\\
which ends up spilling over to two lines in the spec:

    func.searchers.boyer_moore_horspool.creation
    20.12.13.3.1

The warning is:

    Underfull \hbox (badness 10000) in paragraph at lines 642--787
    \T1/lmr/m/n/10 (+20) func.searchers.boyer_-moore_-hor-spool.creation

although the actual line is 759.
This long section name also causes the section title to spill over:

    20.12.13.3.1 boyer_moore_horspool_searcher creation functions
                 [func.searchers.boyer_moore_horspool.creation]

I also tracked down an overfull case. The warning is:

    Overfull \hbox (34.36942pt too wide) in paragraph at lines 262--264
    []\T1/lmr/m/n/10 (-20) whether stack is un-wound be-fore call-ing \T1/lmtt/m/n/
    10 std::terminate()

caused by an impldef being too long in exceptions.tex line 1296:
\impldef{whether stack is unwound before calling \tcode{std::terminate()}
and results in an over-long line in the spec:

    whether stack is unwound before calling std::terminate()
            when a noexcept specification is violated,
            429

which causes the xrefs on that page to be only a single column.

It would be good to know what the maximums/minimums are which cause these warnings in various cases so that we could better track the warnings down and avoid them in the future. Is that information available anywhere?

@tkoeppe
Copy link
Contributor

tkoeppe commented Nov 15, 2016

First off: you will never ever be able to fix all the justification problems, since many of them will require wording changes or non-standard hyphenation, and it'd be a futile task, because you'd have to redo the work after every meeting.

What I propose instead is to create a filter on the log to only show those warnings where the excess is large (say over 10pt, or maybe over 3pt later on), and concentrate on those first.

@tkoeppe
Copy link
Contributor

tkoeppe commented Nov 16, 2016

@jensmaurer: If you want to get your hands dirty, here are two typical challenges which you need to be able to answer:

  • [exception]p5: The inline code is too long to fit on the line, but cannot reasonably be broken. To fix the presentation, you would probably need to rephrase the text.
    image
  • Table 29 (Allocator requirements), the "default" entry for max_size. The tabular presentation of requirements is just totally awful, and I have no idea how to fix this other than by getting rid of the tables altogether (I have a proposal for that).
    image

(To be clear, my personal position is that we should leave both of those cases alone and instead exercise discretion. We should only fix those instances of overfull boxes that are obviously disruptive.)

jensmaurer added a commit to jensmaurer/draft that referenced this issue Nov 16, 2016
@jensmaurer
Copy link
Member

@tkoeppe: We can certainly fix the overlong stable names; those will continue to bite us otherwise. For the requirements tables, we can either abandon them or ignore the problem. For [exception]p5 in particular, I'll send a pull request.

jensmaurer added a commit to jensmaurer/draft that referenced this issue Nov 18, 2016
jensmaurer added a commit to jensmaurer/draft that referenced this issue Nov 18, 2016
jensmaurer added a commit to jensmaurer/draft that referenced this issue Nov 18, 2016
tkoeppe pushed a commit that referenced this issue Nov 18, 2016
tkoeppe pushed a commit that referenced this issue Nov 18, 2016
@tkoeppe
Copy link
Contributor

tkoeppe commented Nov 29, 2016

This may be of interest: if you change the memoir class option from final to draft, you get big black bars printed onto all the overfull boxes, making them very easy to spot.

@godbyk
Copy link
Contributor

godbyk commented Nov 29, 2016

The draft option often has other side-effects, too, as it's passed on to packages. (For example, any graphics will just be empty boxes.)

If you just want the black slugs denoting overfull boxes, you can \setlength\overfullrule{5pt} (where 5pt is the desired size of the slug).

@tkoeppe
Copy link
Contributor

tkoeppe commented Nov 30, 2016

@godbyk: Thanks, good tip!

tkoeppe added a commit that referenced this issue Nov 30, 2016
tkoeppe added a commit that referenced this issue Dec 9, 2016
@tkoeppe
Copy link
Contributor

tkoeppe commented Dec 10, 2016

A handy enumeration of problem spots is easily obtained from the logs:

fgrep std.log -e .tex -e Overfull

The log lets you find the page number of the problem and the file location to fix, and the slugs let you find the problem on the page.

@tkoeppe
Copy link
Contributor

tkoeppe commented Dec 10, 2016

793a12c fixes most boxes in strings.tex.

tkoeppe added a commit that referenced this issue Dec 10, 2016
tkoeppe added a commit that referenced this issue Dec 10, 2016
Addresses #693 for locales.tex.
tkoeppe added a commit that referenced this issue Dec 10, 2016
…"specialization of *template*".

The containing lines were too long (cf. #693), and the change is a mild increase in pedantic correctness.
tkoeppe added a commit that referenced this issue Dec 10, 2016
tkoeppe added a commit that referenced this issue Dec 10, 2016
tkoeppe added a commit that referenced this issue Dec 10, 2016
Use placeholder macros. Reformat class synopsis in our usual style. Reorder private members. Use codeblocks for long descriptions.

Addresses #693.
tkoeppe added a commit that referenced this issue Dec 10, 2016
Use codeblocks for long return elements.

Addresses #693 for this part.
tkoeppe added a commit that referenced this issue Dec 10, 2016
tkoeppe added a commit that referenced this issue Dec 10, 2016
tkoeppe added a commit that referenced this issue Dec 10, 2016
tkoeppe added a commit that referenced this issue Dec 10, 2016
Addresses #693 for this subclause.
tkoeppe added a commit that referenced this issue Dec 10, 2016
…rement in [futures.async].

Addresses #693 for this Clause.
@tkoeppe
Copy link
Contributor

tkoeppe commented Dec 10, 2016

I have fixed the important problems in all files except containers.tex and iostreams.tex. Many of the container problems come from the requirements tables; many iostreams problems seem to come from filesystem.

There are a few remaining overfull boxes in utilities and lib-intro which I think are benign and should just stay. The excess is very small, and the affected line is usually by itself, so the protrusion is almost imperceptible.

@tkoeppe tkoeppe added the big An issue causing a large set of changes, scattered across most of the text. label Dec 10, 2016
tkoeppe added a commit that referenced this issue Dec 10, 2016
tkoeppe added a commit to tkoeppe/draft that referenced this issue Dec 11, 2016
tkoeppe added a commit to tkoeppe/draft that referenced this issue Dec 11, 2016
…ch *j' in terms of indexes

Addresses cplusplus#693 for this part, but is also clearer.
tkoeppe added a commit to tkoeppe/draft that referenced this issue Dec 12, 2016
…ch *j' in terms of indexes

Addresses cplusplus#693 for this part, but is also clearer.
zygoloid pushed a commit that referenced this issue Dec 14, 2016
…ch *j' in terms of indexes

Addresses #693 for this part, but is also clearer.
jensmaurer added a commit to jensmaurer/draft that referenced this issue Dec 19, 2016
to avoid 'Overfull hbox' warnings.

Partially addresses cplusplus#693.
tkoeppe added a commit that referenced this issue Jan 13, 2017
…he result of" from return statements

This fixes overfull hboxes, see #693.
@tkoeppe
Copy link
Contributor

tkoeppe commented Feb 5, 2017

Almost all the remaining overfull boxes in containers.tex occur in tables.

@jensmaurer
Copy link
Member

Richard has fixed all overfull hboxes with commit 89260fb.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
big An issue causing a large set of changes, scattered across most of the text.
Projects
None yet
Development

No branches or pull requests

5 participants