Re: GDP: links to other doc sections

[Graham Percival]

Mats Bengtsson wrote:
> Graham Percival wrote:
> > It was originally written this way, but I would rather keep all the
> > links in the @seealso section at the bottom.  If we absolutely must
> > include some links in the main text, I suppose we could... but I am not
> > (yet) convinced that this is one such case.
>
> Why move a hypertext link away from its context?

  The basic problem is this: if we write

In @ref{Moving objects}, we saw how to move a @code{TextScript} object.

  then the HTML looks great.  In the pdf, it looks like

In Section 5.1.1 [Moving objects], page 48, we saw how to move a 
TextScript object.

  in the info, it looks like

In *note Moving objects::, we saw how to move a `TextScript' object.


  It gets worse with links to items in other manuals:

For example, at the bottom of *note Dynamics: (lilypond)Dynamics, we see 
that blah blah...


The recommended texinfo solution is to always use @ref{} at the end of a 
sentence; for more information, see @ref{foo}.  This sometimes leads to 
awkward phrasing.

If we group all the references to other sections in the @seealso 
section, then there's no problems about twisting the English explanation 
to fit the way texinfo displays stuff.


I admit that I'm not certain this is the best solution, but I'd like to 
give it a try.  I'll have two people look at Pitches with this in mind 
-- clarifying the main part of the docs as much as possible without 
using references in the middle of text.  Then I'll take another look at 
those sections, potentially do some more rewriting, and advertise a 
third draft.

I am aware that this might lessen the usability of the HMTL docs in 
order to make the printed output look better.  When we have the next 
version in front of us, we can decide if it's worth it or not.  My 
belief is that, if _all_ the links are together at the bottom of the 
page, users will be able to find them easily in any case, so this 
doesn't lessen the usability.  I might be wrong about this, but we can't 
really tell until it's been tried.

Cheers,
- Graham