Menu
▾
▴
#1015 doc line width
Originally created by: *anonymous
Originally created by: percival.music.ca@gmail.com
There's some questions/concerns about the default line-width for lilypond
in the docs. Investigate, and produce a good, definitive, line-width.
It must look good in all output formats: html, pdf, info, pdf printed on a4
and usletter, html on a window 800 pixels wide. If there's any output
formats I've missed, please add them to this issue.
Frog: 10 hours.
(once this issue is fixed, we should eliminate all [line-width] from the
docs, apart from anything in the Spacing chapter which requires a *smaller*
line-width. But that's a separate issue)
Originally posted by: PhilEHol...@googlemail.com
Not sure I understand this. line-width referring to what? LilyPond documentation input files; LilyPond .ly files; LilyPond documentation output files? I'd be happy to have look at this with a little more context.
Originally posted by: PhilEHol...@googlemail.com
Just this moment moved to read another issue (https://code.google.com/p/lilypond/issues/detail?id=590) and it referred to line-width in the \paper{} section. So I'm guessing this is what's being referred to. Please confirm.
Originally posted by: percival.music.ca@gmail.com
It refers to documentation source files... this falls under the "Medium tasks" on the Help us page -- you'd need to be able to compile the docs.
I think there's better uses for your time/energy (such as issue 989), but if you're particularly interested in this, we could start training you as a doc editor.
Originally posted by: tdanielsmusic
The "real music" example in section Tweaking output in the LM currently overrides the line-width to ensure the music appears on a single line. Without the override the music breaks after measure 2, causing the phrasing slur to collide with the 6/8 time signature. This needs to be taken into consideration when resolving this issue.
Trevor
Originally posted by: percival.music.ca@gmail.com
No; we should not consider individual examples when deciding the line-width. The maximum line-width should be specified based on:
- the whole-page width of the pdf we produce
- the whole-page witdh of whatever paper people usually use to print out our pdf onto
- whatever additional margins lilypond-book and/or lilypond use.
- the maximum length of png examples we want in the html docs
- anything that the info guys want with regards to length
Once we have an answer, that will be the default + maximum line width for *all* the examples. Note that ragged-right is enabled by default for single-staff output. Docs about spacing may *reduce* the line-width if that's necessary (say, to demonstrate some line breaking stuff), but nothing is allowed to *increase* the line-width.
That's why I said that 1015 was blocking 1180.
Originally posted by: percival.music.ca@gmail.com
(No comment was entered for this change.)
Owner: percival.music.ca
Status: Started
Originally posted by: percival.music.ca@gmail.com
Some initial info:
- the docs current set the line width to be 160mm in:
python/book_texinfo.py
(all our manuals use @afourpaper)
This seems very reasonable. A4 paper is narrower (210.0mm) than usletter (215.9mm), so we should use the narrower version. If we have a 25mm left+right margin, then this leaves 160mm for the width.
NB: this leaves no space for a gutter. I'm comfortable with that, but I'm prepared to listen to arguments in favour of gutters.
However, the lilypond line-width is *not* 160mm.
- currently, 3mm is subtracted from this figure. I believe this is to reserve space for bar numbers.
- we SHOULD (but currently do not) reserve space for instrument names, or make lilypond automatically shift the music to the right. (this is issue 766 and 1093, which on a quick reading are duplicates? and 766 is lacking an image)
- we SHOULD (but currently do not) reserve space for [quote].
A clear demonstration of these problems is the snippet heavily-customized-polymetric-time-signatures.ly. In snippets.pdf, the music extends into the right-hand page margins. In the HTML output, this image is 683 pixels wide, whereas other "full-width" images are 639 pixels. (this number must have been chosen deliberately, and IMO is quite appropriate)
So I think this issue is blocked on the instrument name and (maybe) the bar number shifting. But the overall effect is that the amount of horizontal space will be reduced; probably to about 150mm.
Originally posted by: tdanielsmusic
That's interesting. If I look at an @lilypond in the 2.13 manuals I see
\paper {
indent = 0\mm
line-width = 160\mm - 2.0 * 0.4\in
ragged-right = ##t
force-assignment = #""
line-width = #(- line-width (* mm 3.000000))
}
Why is 0.8 inches subtracted? This already reduces it to 140 mm.
Trevor
Originally posted by: percival.music.ca@gmail.com
Oops, my fault. I picked a random .ly compiled bit to look at, but I evidently ended up with one without quote. I didn't do enough investigation.
python/book_snippets.py defines exampleindent (also used for [quote]) as 0.4\in. My guess is that they thought that it would look better if *both* sides of the image were indented, so that a "full-width" image would still be centered on the page. (I quite agree with that decision)
If I'm correct about this, I'd propose changing the 0.4in into 10mm (just for consistency in units). This gives us 137mm for music, pending some uncertainty about the "3mm for bar numbers" question.
(I'd rather have the page width specified as 160mm-2*(quote_length) = 140mm, then let lilypond figure out how much space it should use for the staff, and how much space it should use for bar numbers and instrument names... but this would require some programming work)
Originally posted by: percival.music.ca@gmail.com
I think any "final solution" to this issue depends on the instrument-name issue.
Blockedon: 766
Originally posted by: percival.music.ca@gmail.com
(No comment was entered for this change.)
Owner: ---
Status: Accepted
Originally posted by: pkx1...@gmail.com
Just some information/thoughts to add to this.
In the CG it states
• Inspirational headwords are produced with:
@lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16]
{pitches-headword.ly}
• LSR snippets are linked with:
@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
{filename.ly}
Now with regard to https://code.google.com/p/lilypond/issues/detail?id=1691 (Ugly bars in PDF), it seems from some experimenting that, instrument names aside, putting 'line-width=15.5\cm,' or less helps remove the ugly bars that occur on standard LP examples that are not ragged right (because they usually go over more than one line) good examples are in the Learning Manual (i.e. 2.3.2 Aligning lyrics to a melody).
By explicitly putting line-width=15.5\cm (or less), this removes the bars but seems to be not too small to preserve the layout of the staff lines.
Until this issue is solved (or unless we adopt something like adding a line-width to the @lilypond[..] variables, then I cannot see how we can reconcile 1691 where most difficulty is going to come in this area (esp with LM and snippets in the NR).
I didn't try 15.6\cm as I figured if we went this route we'd want to keep a reasonably round-ish number.
Originally posted by: percival.music.ca@gmail.com
(No comment was entered for this change.)
Blocking: 1691
Originally posted by: percival.music.ca@gmail.com
We already have a default line width. (Frog: ETA 30 minutes to find it. Senior developer: 30 seconds to find it.) as you note, in conjunction with other demands on the final image size, it goes into the paper margins in latex. This produces the warning "ugly black bars" in the pdf.
Totally aside helpful hint I discovered by accident: if you type "issue 1691" then the issue tracking software automatically turns it into a link.
I agree that this issue blocks any serious work on issue 1691. But in turn, this issue cannot be fully resolved until issue 766 (or something like it) is resolved -- as far as I know, there is currently no way of forcing a snippet to be less than a certain length (we can limit the staff to be a certain length, but the instrument name is added after that, so a really really really really really long instrument name will screw stuff up).
Originally posted by: PhilEHol...@googlemail.com
See my comments on Issue 1691. 16cm is _just_ too wide and produces black bars in the final output. If a line width is set manually, using 15.5cm gives plenty of leeway to get rid of the problem for most cases. This value should generally be used for lilypond examples in the docs, where a line-width is explicitly stated. http://lilypond.org/doc/v2.13/Documentation/contributor/lilypond-formatting needs updating to use the 15.5cm value, and chaneg the 2.0 multiplier to 2.05. GP - do you want a patch with this update?
I do think we should now mark this fixed. I understand that there are issues that this will not fix, but we do have a general solution. The exceptions (instrument names) should be treated as exceptions.
Originally posted by: percival.music.ca@gmail.com
(No comment was entered for this change.)
Labels: -Maintainability Type-Maintainability
Originally posted by: PhilEHol...@googlemail.com
The general solution to this problem was provided a long time ago in changes to lilypond-book. There is a specific situation where this isn't resolved - where there is an image with a long instrument name, but this is a separate bug report (Issue 766) and is easily worked around with line-width. To verify - look in the NR for images which are full-line-width. Is there a black bar on the right? If not, this is verified.
Blockedon: -lilypond:766 lilypond:766
Labels: -Frog -Type-Maintainability Fixed_2_15_42
Status: Fixed
Originally posted by: PhilEHol...@googlemail.com
(No comment was entered for this change.)
Blocking: lilypond:1691
Originally posted by: gra...@percival-music.ca
I agree with instrument names being an exception, but I don't think this is done quite yet. So 15.5cm is ok in pdf and presumably html (how many pixels is that in html, BTW?). I'm not too chuffed about info, so let's not bother with that.
Tasks now:
- make this the actual default for lilypond-book. I'm not certain where it's set; probably in ly/ or scm/ or python/ or scripts/
- put that 15.5cm in the CG doc chapter.
Labels: -Fixed_2_15_42
Status: Accepted
Originally posted by: PhilEHol...@googlemail.com
That won't help. The only solution currently for snippets with instruments is to hand craft the line width. If the instrument is "violin" 15.5cm will likely be OK. If it's "reallylonginstrumentname" then it definitely won't. We could document the need to set line-width explicitly where a snippet has an instrument name. Alternatively we could launch an appeal for someone who understands spacing to fix issue 766 - it's probably one of the worst aspects of LilyPond's aesthetics that remains.
Originally posted by: gra...@percival-music.ca
huh? I'm not talking about snippets with instruments. I'm talking about comment 0 of this issue, namely "Investigate, and produce a good, definitive, line-width.".
...
ok, on second thought I admit that the above quote doesn't imply that the "good, definitive, line-width" should be the default behaviour. So if you want, I suppose you could close this issue and open a new issue for "make the definitive line-width the default behaviour". I think it makes slightly more sense to solve that as part of this issue 1015, but if you want a separate issue number then I'm fine with that.
Bottom line: you've identified 15.5cm as the best line-width, but lilypond-book does not produce images with that line-width by default.
Originally posted by: PhilEHol...@googlemail.com
No. The best linewidth for 99% of the documentation is not to have it as an option - i.e to use the default setting. The work Reinhold did last year fixed this. I've just done some experiments, and it looks like the widest we could have a snippet would be something like 18 cm, and -book currently defaults to 16 and so all is well. So this bug has been fixed. The only exception is long instrument names...
Originally posted by: PhilEHol...@googlemail.com
Just noticed this and that I didn't revert the status to fixed although I believe it definitely is. Add any snippet (except one with instrument name) to the docs with no option for line-width, and it _will_ appear OK in the doc. So the best option for line-width it not to set it unless there is a very good reason.
Labels: Fixed_2_15_42
Status: Fixed
Originally posted by: ma...@gregoriana.sk
How to verify this?
Originally posted by: bealings...@googlemail.com
If there are not a load of images with black bars on the right side of the page (the NR would be the best place to check) then you can verify.