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 _______________________________________________ lilypond-devel mailing list [email protected] https://lists.gnu.org/mailman/listinfo/lilypond-devel
