Re: overfull hboxes in pdf manual

[Rik]

On 01/19/2019 09:00 AM, address@hidden wrote:

Subject:

Overfull hboxes in pdf manual

From:

"Markus Mützel" <address@hidden>

Date:

01/19/2019 03:09 AM

To:

"Octave Maintainers" <address@hidden>

List-Post:

<mailto:address@hidden>

Precedence:

list

MIME-Version:

1.0

Message-ID:

<address@hidden>

Content-Type:

text/plain; charset=UTF-8

Message:

1

Scrolling through the PDF manual, I can see a couple of overfull hboxes. E.g. on:
- page 30 in the "See also" list of history_control
- page 83 in one of the examples for strsplit
- page 87 in two of the examples for erase
- page 118 in one of the examples for num2cell
- page 119 in the examples for mat2cell
- page 128 in the "See also" list of makeValidName
- page 213 in the description for the warning "Octave:singular-matrix"

After these, I stopped scrolling further. I also might have skipped a few.

In all of these occurrences, one of our (custom?) macros seems to be involved.
Can we do something to improve the line wrapping in the PDF with those?

This isn't critical, but changing the code in @example blocks to have more reasonable breaks and limit line length can also make the code easier to understand.  If the line is barely longer than the hbox another strategy is to use @smallexample which sets the entire example block in a slightly smaller font.  Beyond that, I find the default indent of 5 spaces for an example block to be much too large.  In Octave's own code base we only use two spaces.  Theoretically this is controllable by issuing an @exampleindent N command at the beginning of the Octave documentation, but I have not gotten it to work.  Maybe we need a Texinfo wizard to help us set that up.

I wouldn't worry about overfull hboxes in the @seealso macro expansion.  The Tex interpreter does find a line break, it just may be slightly longer than optimal.  But it does not put the entire seealso string of references on one line.

--Rik