Re: referencing a certain snippet

[James]

On 02/06/14 23:02, Thomas Morley wrote:
> Hi,
> currently I'm working on
> http://code.google.com/p/lilypond/issues/detail?id=3939
> https://codereview.appspot.com/96650050/
>
> I want to reference to the snippet `Separating key cancellations from
> key signature changes' from Documentation/snippets, section `Tweaks
> and overrides'
>
> Though, I don't know how to reference directly to this snippet. Best I
> managed is:
> "
> ...
> see `Separating key cancellations from key signature changes' in
> @rlsr{Tweaks and overrides}"
> Which points to the section and one would have to search it there.
>
> Is there a way to do it directly?
No. Or if there is it would probably start a precedence that we don't
follow in our CG Doc policy (you would need I expect to include an
@section or @node or similar in the snippet which would be horrendous).

Regardless, i think I agree with Carl's comments:

"
The appropriate way for a user to come to understand this (if they
haven't found the snippet) is to find the appendix, then search the
manual for break-align-orders.

Trying to maintain bidirectional linkage between the code and the
documentation is a recipe for bitrot, I believe.
"
I tend to agree. We don't, for instance, link back from snippets to the
Manuals.

The example should be clear in the @snippets section - don't forget you
can include text 'outside' of the snippet before you link it it (i.e.
the snippet does not have to include any extra text that you might want
in the NR, a snippet is conceptually - at least in my mind - a glorified
@lilypond or @example.

Make the @cindex or @index more obvious and  the explanatory notes
around the snippet and just use the snippet as the example.

Does that make sense?

james