[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: referencing a certain snippet

From: James
Subject: Re: referencing a certain snippet
Date: Tue, 03 Jun 2014 09:11:42 +0100
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:24.0) Gecko/20100101 Thunderbird/24.5.0

On 02/06/14 23:02, Thomas Morley wrote:
> Hi,
> currently I'm working on
> 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

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?


reply via email to

[Prev in Thread] Current Thread [Next in Thread]