Re: removing @lsr{} and only using @lsrdir{}

[David Kastrup]

"Valentin Villenave" <address@hidden> writes:

> 2008/4/24 David Kastrup <address@hidden>:
>
>>  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