"Valentin Villenave" <[EMAIL PROTECTED]> writes: > 2008/4/24 David Kastrup <[EMAIL PROTECTED]>: > >> The idea of a cross reference is to get me where I want directly. If it >> is in the vicinity of interesting material, nice (hopefully everything >> is interesting). But "it is good for you to wade through unrelated, >> closely situated material" is nothing that I buy. If I want to, I'll >> wade through, one time or other. But that should stay the reader's >> choice. > > I'm afraid you misunderstood Graham here (as I did earlier). Snippets > pages are absolutely NOT unrelated. Perhaps you know that LSR snippets > are now tagged by theme, *but* also according to their relevance as > documentation resources. > > In other words, on the "Pitches" snippets page, you will find *only* > snippets that have been > > -tagged as "Pitches": i;e. they deal with a subject that is related to > pitches definition and/or modification
Sure. But when referring to a particular construct related to pitches, it will be prominently visible mostly in one particular snippet in most cases. > -but *also* tagged as "docs": that means these snippets have been > considered interesting for the docs. That makes the situation decidedly _worse_ since it encourages referring to the pitches section for looking for an example for a particular pitch construct without making the documentation author double-check that this construct is actually present somewhere among the examples. If somebody decides to untag some snippet as being too contrived, the documentation compiler won't complain when this snippet is the one intended to explain a particular construct. So in the "better safe than sorry course", removing snippets becomes impossible: first you have to make a list of all constructs it references that are in no other snippet, then you have to check that nothing that refers to the "pitches snippet page" will do so in order to reference this particular construct. Having to specify a particular snippet makes sure that this snippet (and thus the construct) indeed appears in the docs, and that its absence will be noticed when compiling the documentation. -- David Kastrup _______________________________________________ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
