Doc: avoid implicit \relative; issue 4371

Docs: stop using the hidden implicit \relative; issue 4371
    
Remove the lilypond-book feature of 'relative=n' in  conjunctin with 'verbatim', so that examples cut-and-paste into user scores, and so that we show wiser use of relative.

[Trevor Daniels, 2015-05-17 21:54:07]

I'm not opposed to the change to explicit \relative; it avoids having to explain
why it was omitted in the examples, and makes the example code more exactly
correspond to the code obtained by clicking on the image.  But I think if are to
make this change it would also be good to say what leaving out \relative means. 
It was difficult to do this before as all the examples left it out (apparently).
 Now we can do it.  Placing a brief explanation at the beginning of 1.2.1 would
explain the mysterious 's in those first examples of code.

https://codereview.appspot.com/237340043/diff/10006/Documentation/learning/tw...
File Documentation/learning/tweaks.itely (right):

https://codereview.appspot.com/237340043/diff/10006/Documentation/learning/tw...
Documentation/learning/tweaks.itely:2124: \relative c' {
no leading spaces

[Keith, 2015-05-18 02:02:33]

On 2015/05/17 21:54:07, Trevor Daniels wrote:
> But I think if are to
> make this change it would also be good to say what leaving out \relative
means. 
> It was difficult to do this before as all the examples left it out
(apparently).
>  Now we can do it.  Placing a brief explanation at the beginning of 1.2.1
would
> explain the mysterious 's in those first examples of code.
> 

The tutorial almost never leaves out \relative,
but I did add at the start of 'Pitches' an explanation of the system within
which c' denotes middle C

[Keith, 2015-06-21 23:25:49]

finished all docs

[Keith, 2015-06-22 00:33:58]

error corrections

[Keith, 2015-06-22 04:40:21]

I started this with the belief that relative octave notation is easier to write
(for some people) but absolute octave notation is easier to read, and thus the
expectation that many examples would be simpler using absolute pitches, or the
new \fixed c'' {}.
However, there were not so many examples where a fixed octave reference would
really help.

https://codereview.appspot.com/237340043/diff/110001/Documentation/learning/c...
File Documentation/learning/common-notation.itely (right):

https://codereview.appspot.com/237340043/diff/110001/Documentation/learning/c...
Documentation/learning/common-notation.itely:912: >>
One of only two examples in Learning where a single \relative was bad advice.

https://codereview.appspot.com/237340043/diff/110001/Documentation/learning/f...
File Documentation/learning/fundamental.itely (right):

https://codereview.appspot.com/237340043/diff/110001/Documentation/learning/f...
Documentation/learning/fundamental.itely:625: the passing note and a slur:
This pair of examples changes the entry order of the pitches, so would be easier
to read with  \fixed c'

https://codereview.appspot.com/237340043/diff/110001/Documentation/learning/f...
Documentation/learning/fundamental.itely:646: }
The example is a case where a single \relative applied to parallel voices might
be practical.
It would line up better with its re-arrangement below if we use \fixed c'

https://codereview.appspot.com/237340043/diff/110001/Documentation/learning/f...
Documentation/learning/fundamental.itely:668: >>
The other example in Learning where the single outer \relative was really bad
advice.

[Trevor Daniels, 2015-06-22 11:04:45]

I'm generally happy with this, but I've made quite a few nit-picking comments. 
I think it is important that the manuals rigorously show a consistent style,
particularly with regard to indentation and the placement of block delimiters. 
We frequently criticise users presenting examples on the mailing list for bad
layout, so I think the manuals must be impeccable in this respect.

Trevor

https://codereview.appspot.com/237340043/diff/110001/Documentation/learning/c...
File Documentation/learning/common-notation.itely (right):

https://codereview.appspot.com/237340043/diff/110001/Documentation/learning/c...
Documentation/learning/common-notation.itely:243: \key aes \major
I wonder if it might be preferable to place the \key outside the \relative? 
This would be in keeping with the emerging opinion that we should encourage
placing \relative blocks around smaller sections of notes.

https://codereview.appspot.com/237340043/diff/110001/Documentation/learning/c...
Documentation/learning/common-notation.itely:646: | c2 \acciaccatura b16 c2 }
This might look prettier but it also omits a bar check at the end of the last
bar.  I'm not convinced this is a good idea.

https://codereview.appspot.com/237340043/diff/110001/Documentation/learning/c...
Documentation/learning/common-notation.itely:962: | r4 <c e g>8.\p <c f a>16( <c
e g>4-. <c f a>) }
Last bar is not checked.  Bad advice.

https://codereview.appspot.com/237340043/diff/110001/Documentation/learning/c...
Documentation/learning/common-notation.itely:1420: So far we have always used
@code{\relative} to define pitches.
This is not true.  There are a couple of examples earlier where you have used
absolute pitches.

https://codereview.appspot.com/237340043/diff/110001/Documentation/learning/t...
File Documentation/learning/tweaks.itely (right):

https://codereview.appspot.com/237340043/diff/110001/Documentation/learning/t...
Documentation/learning/tweaks.itely:330: b c }
The LilyPond style, I believe, is to place the terminating } in line with the
corresponding \ of \relative.  Are you proposing we change this?

https://codereview.appspot.com/237340043/diff/110001/Documentation/learning/t...
Documentation/learning/tweaks.itely:2324: c4( c^\markup { \tiny \sharp } d4.) c8
}
Again, using | as a prettifying aid to the detriment of its primary purpose. 
The first one does nothing useful and the last bar is not checked.

https://codereview.appspot.com/237340043/diff/110001/Documentation/learning/t...
Documentation/learning/tweaks.itely:2439: ees,2.~\)\mf ees4 r8 }
Needs final bar check and } on following line.

https://codereview.appspot.com/237340043/diff/110001/Documentation/notation/a...
File Documentation/notation/ancient.itely (right):

https://codereview.appspot.com/237340043/diff/110001/Documentation/notation/a...
Documentation/notation/ancient.itely:871: ais bis }
Misplaced }

https://codereview.appspot.com/237340043/diff/110001/Documentation/notation/c...
File Documentation/notation/changing-defaults.itely (right):

https://codereview.appspot.com/237340043/diff/110001/Documentation/notation/c...
Documentation/notation/changing-defaults.itely:357: }
Can you really leave out the << ... >> here?

https://codereview.appspot.com/237340043/diff/110001/Documentation/notation/c...
Documentation/notation/changing-defaults.itely:733: }
Ditto

https://codereview.appspot.com/237340043/diff/110001/Documentation/notation/k...
File Documentation/notation/keyboards.itely (right):

https://codereview.appspot.com/237340043/diff/110001/Documentation/notation/k...
Documentation/notation/keyboards.itely:497: <d fis a>1\treCorde }
Misplaced }

https://codereview.appspot.com/237340043/diff/110001/Documentation/notation/k...
Documentation/notation/keyboards.itely:525: \bar "|." }
Misplaced }

https://codereview.appspot.com/237340043/diff/110001/Documentation/notation/p...
File Documentation/notation/pitches.itely (right):

https://codereview.appspot.com/237340043/diff/110001/Documentation/notation/p...
Documentation/notation/pitches.itely:407: cis'' cis'' cis''! cis''? c'' c'' c''!
c''?
Wouldn't \relative be preferable here?  And in most of the examples in this
section.

https://codereview.appspot.com/237340043/diff/110001/Documentation/notation/p...
Documentation/notation/pitches.itely:1280: \clef "treble_8" c'4 }
Misplaced }

https://codereview.appspot.com/237340043/diff/110001/Documentation/notation/p...
Documentation/notation/pitches.itely:1443: a2 b }
Misplaced }

And several more following.

[dak, 2015-06-22 11:24:30]

https://codereview.appspot.com/237340043/diff/110001/Documentation/learning/t...
File Documentation/learning/tweaks.itely (right):

https://codereview.appspot.com/237340043/diff/110001/Documentation/learning/t...
Documentation/learning/tweaks.itely:330: b c }
On 2015/06/22 11:04:44, Trevor Daniels wrote:
> The LilyPond style, I believe, is to place the terminating } in line with the
> corresponding \ of \relative.  Are you proposing we change this?

This is pretty much my objection here as well.  When \relative is a line
starter, it's very much
\relative {
  ...
}
that we want to see.  That's consistent with the indentation stlyes of many
programming languages.  Scheme is not even an exception here since Scheme may
start off with (((sth and so finishing with sth))) is at least symmetric.

Yes, there will be an additional cost in additional pages.  This cost has to
factor in our decision whether to become more explicit: I don't think that we
want to have this change in presented indentation style.

[Keith, 2015-06-22 15:30:19]

https://codereview.appspot.com/237340043/diff/110001/Documentation/learning/t...
File Documentation/learning/tweaks.itely (right):

https://codereview.appspot.com/237340043/diff/110001/Documentation/learning/t...
Documentation/learning/tweaks.itely:330: b c }
On 2015/06/22 11:04:44, Trevor Daniels wrote:
>  Are you proposing we change this?

Yes, proposing to consider it.
I put the summary on the issue
https://code.google.com/p/lilypond/issues/detail?id=4371#c8

https://codereview.appspot.com/237340043/diff/110001/Documentation/learning/t...
Documentation/learning/tweaks.itely:2324: c4( c^\markup { \tiny \sharp } d4.) c8
}
On 2015/06/22 11:04:44, Trevor Daniels wrote:
> Again, using | as a prettifying aid to the detriment of its primary purpose. 
> The first one does nothing useful and the last bar is not checked.

Yep.  The |-at-front style is much easier to type consistently, and compensates
for missing indentation at broken bars, so I wanted to see what people thought
about it in the docs. (The initial bar check helps often enough at the star of
sequences in variables.)

For the manual, we can just do careful indentation.

https://codereview.appspot.com/237340043/diff/110001/Documentation/notation/p...
File Documentation/notation/pitches.itely (right):

https://codereview.appspot.com/237340043/diff/110001/Documentation/notation/p...
Documentation/notation/pitches.itely:407: cis'' cis'' cis''! cis''? c'' c'' c''!
c''?
On 2015/06/22 11:04:44, Trevor Daniels wrote:
> Wouldn't \relative be preferable here?  And in most of the examples in this
> section.

Yes, I thought we might stay in absolute mode when thinking explicitly about
pitches for the first section of Pitches, but the '' are more distracting than
\relative
It should be \relative c'' {...} so that the first pitch octave doesn't obscure
the points of these examples.

[Keith, 2015-06-23 06:20:24]

formatting

[Trevor Daniels, 2015-06-25 10:14:53]

LGTM

Thanks Keith

[Keith, 2015-06-28 05:32:30]

apply patch to translations

[Keith, 2015-07-06 06:28:43]

finish all translations

[Keith, 2015-07-06 06:44:35]

The part of notation.pdf before the tables grows from 613 to 622 pages, 2%, even
with the closing }s always on their own line.

https://codereview.appspot.com/237340043/diff/110001/Documentation/learning/c...
File Documentation/learning/common-notation.itely (right):

https://codereview.appspot.com/237340043/diff/110001/Documentation/learning/c...
Documentation/learning/common-notation.itely:243: \key aes \major
On 2015/06/22 11:04:44, Trevor Daniels wrote:
> I wonder if it might be preferable to place the \key outside the \relative? 

I thought it better to keep the \key near the notes here, because we show
appropriate placement of the \relative around inner structures in files like
/notation/staff.itely