Menu
▾
▴
#1691 Ugly bars in PDF documents
Originally created by: *anonymous
Originally created by: PhilEHol...@googlemail.com
In the documentation build it's common to see an error message beginning "Overfull \hbox".
Looking on the web for what this means, I found
http://docs.freebsd.org/info/texinfo/texinfo.info.Overfull_hboxes.html which says:
"TeX is sometimes unable to typeset a line without extending it into the
right margin."... "unless told otherwise, TeX will print a large, ugly,
black rectangle beside the line that contains the overfull hbox."
There are quite a few of these in, say, the 2.14.0 NR - see the PDF page 33 and 37 for example.
It would seem there are 2 options: either fix the text/diagram sizes, or
compile as suggested in the page above:
"To prevent such a monstrosity from marring your final printout, write the following in the beginning of the Texinfo file on a line of its own, before the `@titlepage' command:"
@finalout
The current consensus is that it would be better to start by looking at correcting the documentation to get the text correctly sized.
Issue 1015 is related to this.
Originally posted by: PhilEHol...@googlemail.com
OK. Further updates. I started my testing today using this:
@lilypond[fragment]
\repeat unfold 100 { c'4 }
@end lilypond
I now realise that this is generally not used for the docs, but hadn't caught on earlier. It produces a lily source file with this paper block:
\paper {
indent = 0\mm
line-width = #(- paper-width left-margin-default right-margin-default )
ragged-right = ##t
force-assignment = #""
line-width = #(- line-width (* mm 3.000000))
}
Note the lack of numeric varibles in the line-width. This produces a snippet of a normal size for output to PDF, but much too wide for the docs - it goes way over the right of the page. Note also the minor reduction in width - it looks to me like the bottom line takes 3mm off the line width, for some reason. It's set in the definition PREAMBLE_LY =
I then looked at
@lilypond[verbatim,quote]
\repeat unfold 100 { c'4 }
@end lilypond
This gives us this paper block:
\paper {
indent = 0\mm
line-width = 160\mm - 2.0 * 0.4\in
force-assignment = #""
line-width = #(- line-width (* mm 3.000000))
}
which comes from the line:
QUOTE: r'''line-width = %(line-width)s - 2.0 * %(exampleindent)s''',
This gives black bars, but is only just too wide.
which is not reset to the value above, since that's only done if the snippet is not quoted. Following the earlier work testing which line-width I tried:
@lilypond[verbatim,quote,line-width=15.5\cm]
\repeat unfold 100 { c'4 }
@end lilypond
which gives the paper block:
\paper {
indent = 0\mm
line-width = 15.5\cm
line-width = 15.5\cm - 2.0 * 0.4\in
force-assignment = #""
line-width = #(- line-width (* mm 3.000000))
}
which gives no black bars. I now understand this quite a bit better, and you were clearly quite right about my previous suggestion! I think the mechanism of reducing the line width of quoted snippets by 2 times the indent takes off _just_ too little width - if we replace 2 * exampleindent with 2.05 *, the problem is again solved for these snippets.
Originally posted by: percival.music.ca@gmail.com
Excellent! You now pretty much know all I do about the situation:
- for most intents and purposes, lilypond-book has NOTHING to do with the documentation or the build system.
- you have a minimal test case for which you can experiment, with both texi2html and texi2pdf (without involving the build system!)
- you see that lilypond-book produces a .ly file, and you've noticed the difference between the values in that .ly file with various options. (there's probably a few more different options you can toss in there to see different \paper{} settings, but that's a minor detail compared to noticing those differences in the first place!)
IIRC the 3mm comes from an attempt to "reserve" space for bar numbers, which would otherwise stick out into the left-hand margin.
I re-iterate that a complete solution will need to involve the "dealing with instrument names (and bar numbers)" issue. At it currently stands, lilypond-book deals with a **staff line-width**, but material to the left of the staff line takes additional space. I think we need some programmer way of defining a **system width** (including left material like instrument name and bar numbers), and then change lilypond-book to set that value instead of line-width.
The bad news it that such an addition is completely outside of your and my area of expertise. The good news is that we have a couple of programmers now who work on such things, and maybe if you ask them politely to work on it, you'll get some interest. Also, if we end up having a Type-maintainability (which seems likely), that could help attract attention to such problems.
Originally posted by: PhilEHol...@googlemail.com
OK. Thanks. On my local system, I've changed the multiplier to 2.05 rather than 2.0, nuked build, rebuilt and the black lines where they used to be on line-wrapped music have mostly gone. I've also checked other output and can't see any other noticeable differences. I don't think we can claim fixed, since there are other black lines which need fixing - for example, the expressive-headword.ly has a fixed paper width of 16cm, which is too wide. There are also examples of things like LilyPond code which are too wide. However, it's a step forward. You want a patch?
I see two ways forward. I could work my way through each doc and make a list of the black bars for a "proper" doc editor to correct, or I could make corrections to the best of my ability and submit (what could be quite a large) patch for each manual.
Also see my note on Issue 1015.
Originally posted by: percival.music.ca@gmail.com
I'm not convinced that an ad-hoc solution is the way forward. Where does the extra .05 come from? For that matter, where does the 0.4\in come from? Is this just a problem of converting units?
Originally posted by: percival.music.ca@gmail.com
More generally: could you create a Tiny example (of a full .tely document, not just
@lilypond[verbatim,quote]
\repeat unfold 100 { c'4 }
@end lilypond
) which shows the black bars? and maybe even make that a new issue?
Fundamentally, this has nothing to do with the documentation. As far as I understand, you can reliably produce bad output (i.e. black bars) from a completely reasonable example. We should treat that as a programming problem, not a documentation one.
On a programming note, the question is "why does lilypond produce an image of music which (apparently) cannot fit in the space provided". But that's a comment that can be attached to the new issue, not this one.
Originally posted by: PhilEHol...@googlemail.com
The 0.4\in comes from this:
QUOTE: r'''line-width = %(line-width)s - 2.0 * %(exampleindent)s''',
It's the value of exampleindent. It seems that the rationale is that if you subtract 2* the indent from the linewidth, then you get a usable linewidth. Given how close this is to correct, I was concluding the it's essentially a rounding error, so that we should go with subtracting just more than twice the indent from the linewidth.
I've attached my line length test file, together with the resulting output, having reverted my update changing 2.0 to 2.05. As you see, you get black bars for 2 perfectly reasonable bits of -book syntax. I believe this is a bug in -book - it seems to me that, for music which wraps to more than one system, -book will never produce acceptable output. As you say, that's another bug.
This one is about the bars in _our_ docs. We/I now know how to take them out, and in the situation where users adopt the [quote] option, how to help users. Please comment, but I am pretty convinced that the change I'm suggesting will improve our docs and -book generally.
Originally posted by: percival.music.ca@gmail.com
I can break your 2.05 "solution" with the following example.
The problem is that line-width is NOT the same thing as the width of the image. Until that is addressed, you're stuck with picking random values that are big enough for "reasonable" line widths. That's do-able for bar numbers, but how large do you want to hard-code an instrument name? Always reserve 5cm in case somebody wants to write "Clarinet in B flat" all on one line? that'll look silly if somebody doesn't use any instrument name. Always reserve 2cm, and document that nobody is allowed to use longer instrument names inside lilypond-book? Tell people they need to manually set an indent=0 or 3 or 10\cm depending on their instrument name?
-----------
\input texinfo @c -*- coding: utf-8; mode: texinfo; -*-
@setfilename LineTest
@settitle PhilTest
@afourpaper
Test Lorem ipsum dolor sit amet, consectetur adipisicing elit.
@lilypond[relative=2]
\repeat unfold 100 { c4 }
@end lilypond
Test Lorem ipsum dolor sit amet, consectetur adipisicing elit.
@lilypond[relative=2]
\set Score.currentBarNumber = 99999999
\repeat unfold 100 { c4 }
@end lilypond
Test Lorem ipsum dolor sit amet, consectetur adipisicing elit.
@bye
Originally posted by: PhilEHol...@googlemail.com
I can break the docs in a number of ways, including using incorrect syntax and by putting long unbreakable lines in. However, we tell people not to do this. The point of this fix is that it improves the docs by fixing almost all the examples where line breaks occur. There are exceptions (instrument names, ridiculous bar numbers), but we can fix them manually to start with and then tell people how to fix them if they see them in new images that they put in.
This change improves the situation considerably and should be pushed. It's like a code change that adds collision avoidance code. We don't junk that because it doesn't fix all collisions; we welcome it as a welcome improvement. This is the same.
Originally posted by: percival.music.ca@gmail.com
The 2.05 is completely irrelevant -- it's not used at all in this example, which still has the overflow black bars. Without using any bar numbers or instrument names!
Something is fundamentally broken in lilypond-book. Don't try to sandpaper over it. If we wanted a cosmetic solution, we could just add @finaloutput, or whatever it was that Werner suggested.
\input texinfo @c -*- coding: utf-8; mode: texinfo; -*-
@setfilename LineTest
@settitle PhilTest
@afourpaper
still problem:
@lilypond[]
\layout {
\context {
\Score
\remove "Bar_number_engraver"
}
}
\repeat unfold 50 { c'4 }
@end lilypond
@bye
Originally posted by: PhilEHol...@googlemail.com
I know this very well. My example pointed it out to you. If you want to deliberately avoid the instructions in the CG, then you'll get crap output. The CG says:
•Most LilyPond examples throughout the documentation can be produced with:
@lilypond[verbatim,quote,relative=1]
where's your [quote]? If you want to raise a separate issue called "Liylpond-book produces bad output unless quote is used" (or want me to) then let's do this. But again, I emphasise - this patch fixes many, many problems with bad doc output. Let's push this one, and move on to the other problems it doesn't fix.
Originally posted by: PhilEHol...@googlemail.com
Request to push this change of 2.0 * %(exampleindent)s''' to 2.05 * . This will fix all the instances of black bars where the snippet is > 1 line long, and [quote] is used in the snippet, as it should be.
Originally posted by: reinhold...@gmail.com
Actually, the problem has nothing to do with the missing quote. E.g. simply try this trivial snippet: (which has the quote and the verbatim, and still produces overfull hboxes)
\input texinfo @c -*- coding: utf-8; mode: texinfo; -*-
@setfilename LineTest
@settitle PhilTest
@afourpaper
still problem:
@lilypond[verbatim,quote]
\repeat unfold 50 { c4 }
@end lilypond
@bye
It's actually a very general problem of lilypond-book. The reason why you are not seeing it with @lilypond[verbatim,quote,relative=1] is that relative=1 for some very strange reason also sets ragged-right=##t, so none of the lines will use the full line-width (which is wider than the latex width!) and therefore you won't see the bars. I don't think that this is actually intended (why should relative imply ragged-right????). So, you are seeing a perfect example of two lilypond-book bugs offsetting each other:
Bug 1: lilypond-book uses a line-width that is too large
Bug 2: relative implies ragged-right, which will not use the full allowed width in most cases.
Originally posted by: PhilEHol...@googlemail.com
If [quote] is used, and the change I suggested is made, you no longer get overfull hboxes. In book_snippets.py we have this line:
QUOTE: r'''line-width = %(line-width)s - 2.0 * %(exampleindent)s''',
If you change the 2.0 to slightly more than 2.0 (and I suggested 2.05) then the output is no longer too wide. My presumption is that this is to do with rounding errors - taking exactly twice the indent from the linewidth doesn't narrow the resulting output quite enough. I understand that this doesn't fix every single problem with the docs or how lilypond-book works, but it does fix a lot of ugly output in the docs.
Originally posted by: reinhold...@gmail.com
Again, this would just be a workaround for a severe lilypond-book bug, namely that it creates images that are wider than allowed.
By shrinking the line-width by an arbitrary (sufficiently large) amount, of course you will get images that fit, but that's not the real solution to the problem, rather painting over the rust and hoping that it won't surface somewhere else.
Also, it won't fix the the problem when you don't use quote (which should be just a special case of a lilypond snippet, not a required snippet option!).
Originally posted by: percival.music.ca@gmail.com
The problem is not a rounding error. The first problem Reinhold identified is detailed in issue 1816, which has a patch. We know the problem, we know the solution, and we have the fix ready.
If you would like to move forward on this, please test that patch. Otherwise we'll just wait for James to test it (to move the patch from Patch-new to Patch-review, at which point it can go through the countdown).
Blockedon: 1816
Originally posted by: percival.music.ca@gmail.com
Trevor reminded us (by email) that lilypond automatically sets ragged-right=##t if the music is less than a full line. This might be the behavior Reinhold was seeing. If he was seeing it in a different context, then this sounds like another bug. There's no reason why relative=1 should imply ragged-right.
Originally posted by: reinhold...@gmail.com
Is this still an issue or was the problem fixed with my fix to issues 1816 and 1836?
Looking at today's LM and NR, I don't see any bars in the LM and only very few in the NR. In particular:
-) Several lilypond code lines are too long
-) Some eyecatcher examples at the begin of a section are too wide
-) One example for accidental styles ('teaching' style) is too wide, but that is inside a list, so the width is really hard to determine...
-) The table-of-contents examples are too large, and the example in 3.2.3
-) The chord name charts in appendix A.1. Problem is the "instrumentName" before the ChordNames context
-) fretboards in appendix A.4
Originally posted by: PhilEHol...@googlemail.com
I would expect the changes you made to -book will have fixed almost all of these, although I've not checked. As you say, there are a few left-over, which I hope to look at in the not-too-distant future.
Originally posted by: pkx1...@gmail.com
(No comment was entered for this change.)
Labels: -Priority-Medium
Originally posted by: pkx1...@gmail.com
Learning Manual has been taken care of with regard to this.
Thanks to Phil.
James
Originally posted by: PhilEHol...@googlemail.com
NR now has no black bars. To verify, look in the PDf, for example at the section "Staff notation". Is there a black bar to the right of the image? If no, please verify.
Blockedon: -lilypond:1015 -lilypond:1816 lilypond:1015 lilypond:1816
Originally posted by: PhilEHol...@googlemail.com
Aargh. Forgot to change status
Labels: Fixed_2_15_42
Status: Fixed
Originally posted by: Elu...@gmail.com
(No comment was entered for this change.)
Status: Verified