Overfull hboxes in pdf manual

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

Overfull hboxes in pdf manual

mmuetzel
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?

Markus

Reply | Threaded
Open this post in threaded view
|

Re: Overfull hboxes in pdf manual

apjanke-floss


On 1/19/19 6:09 AM, "Markus Mützel" wrote:

> 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?
>
> Markus
>

I'm also seeing this in the PDF manual I'm generating for my Chrono
package. I can get a listing from the "make" output; maybe you can too.

[~/local/repos/octave-addons-chrono]
$ PATH="/usr/local/opt/texinfo/bin:$PATH" make doc | grep Overfull
Overfull \hbox (43.6852pt too wide) in paragraph at lines 109--109
Overfull \hbox (141.4129pt too wide) in paragraph at lines 173--173
Overfull \hbox (14.94176pt too wide) in paragraph at lines 229--229
Overfull \hbox (43.6852pt too wide) in paragraph at lines 109--109
Overfull \hbox (141.4129pt too wide) in paragraph at lines 173--173
Overfull \hbox (14.94176pt too wide) in paragraph at lines 229--229
[~/local/repos/octave-addons-chrono]
$ PATH="/usr/local/opt/texinfo/bin:$PATH" texi2pdf --version | head -1
texi2pdf (GNU Texinfo 6.5) 7842

By examining the combined .texi file, one could map those lines back to
the files the texinfo help was originally extracted from.

I'm using a customized set of doco generation scripts based on those
from the Octave Forge communications package.

https://github.com/apjanke/octave-addons-chrono/tree/master/doc

I'm interested in getting this cleared up too, but I haven't had time to
dig down into the PDF generation code.

Cheers,
Andrew

Reply | Threaded
Open this post in threaded view
|

Re: Overfull hboxes in pdf manual

mmuetzel
In reply to this post by mmuetzel
Am 19. Januar 2019 um 12:09 Uhr schrieb "Markus Mützel":
>
> 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"

I pushed this changeset to get rid of some of the overfull lines in the examples:
http://hg.savannah.gnu.org/hgweb/octave/rev/ae1542fb58ba

For the "See also" lists: The overfull lines typically occur if some of the referenced functions have very long names.
Do we want to make these lists left aligned (instead of justified) to give tex a less hard time finding nicer line breaks?

Markus

Reply | Threaded
Open this post in threaded view
|

Re: overfull hboxes in pdf manual

Rik-4
In reply to this post by mmuetzel
On 01/19/2019 09:00 AM, [hidden email] wrote:
Subject:
Overfull hboxes in pdf manual
From:
"Markus Mützel" [hidden email]
Date:
01/19/2019 03:09 AM
To:
"Octave Maintainers" [hidden email]
List-Post:
[hidden email]
Precedence:
list
MIME-Version:
1.0
Message-ID:
<trinity-2803354b-dffd-4264-9e03-cc75219e9986-1547896192295@3c-app-gmx-bs39>
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
Reply | Threaded
Open this post in threaded view
|

Re: overfull hboxes in pdf manual

John W. Eaton
Administrator
On 1/21/19 12:16 PM, Rik wrote:

> 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 see some changes in the PDF output when using different values of N
for "@exampleindent N", but the spacing seems wider than the documented
N ems.  Nothing seems to change for Info output.  This looks like a bug
in texinfo to me.

jwe

Reply | Threaded
Open this post in threaded view
|

Re: overfull hboxes in pdf manual

Rik-4
On 01/21/2019 10:29 AM, John W. Eaton wrote:
On 1/21/19 12:16 PM, Rik wrote:

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 see some changes in the PDF output when using different values of N for "@exampleindent N", but the spacing seems wider than the documented N ems.  Nothing seems to change for Info output.  This looks like a bug in texinfo to me.

jwe

I did some experimentation.  The spacing used in the PDF is measured in ems, a typographical unit that used to be the width of a capital 'M', but is now the width of an em-dash by definition.  While the default value of @exampleindent is 5, in TeX this is rendered as 0.4 inches.  However, if you specify the value as 5 then TeX renders 5 em-dashes which is actually larger than 0.4".  In the figure below, the first indent is "asis" which is 0.4".  Then there is a cascade of 0, 1, 2, 3, 4, 5.  I propose setting the example indent to 2.  The value of 3 produces an indent which is already larger than the default which itself I consider too big.  Unfortunately, fractional values are not allowed.

We could also consider changing @paragraphindent for improved readability.

--Rik