Re: how offsets and alignment works: an explanation

[Jean-Charles Malahieude]

Le 23/03/2013 18:13, Trevor Daniels disait :
> Noeck wrote Saturday, March 23, 2013 5:55 PM
> > > This is explained very concisely and without examples in the NR, see
> > > http://www.lilypond.org/doc/v2.17/Documentation/notation/aligning-objects
> >
> > I disagree. As an average user, I feel quite lost in this section
> > especially with the "two-dimensional" extents.
>
> The Notation Reference is a _reference_ document.  It is intended to
> remind users of information which they already understand.  Explanations
> belong either in the Learning Manual, the Extensions Manual or the
> Contributor's Guide.  We need to be quite strict about this, other the
> NR will become far too long.  The pdf version is already 800 pages
> long and takes several minutes to download.  That is why we moved
> material into the other manuals.
>
> > The CG is too far away from the normal user. I would only put the part
> > on scheme functions there.
>
> I'm quite happy to see extensive links to the CG.  These will take you to the
> appropriate section just as easily as if they are in the same manual.

I would add that the CG is not and should not get translated in other 
languages, if it really is considered as the reference guide for any 
CONTRIBUTOR to LilyPond (which might an average user not be). I would 
therefore  place such material in "Extending" (why not in 2.9).

> > »An image tells you more than a thousand words« is a German saying which
> > applies very well to this section, IMHO. But I think that lacks at many
> > places in the docs: images. They are very text-centred and sometimes an
> > image would be much quicker to understand than pages of text. This
> > particularly applies to spacing and positioning issues.
>
> That's because we have several blind users.  Images are useless for them.

I think that verbalizing "-> see image (1) in attached images.png" might 
help blind users to understand what does happen in an @example.

My 2 cts
Jean-Charles