Re: stop breaking the docs

[Graham Percival]

On Wed, 27 Feb 2008 10:46:39 +0100
John Mandereau <address@hidden> wrote:

> with one or two extra branches.  After I've moved makefiles
> experiments on another branch, I hope we finally agree that it's a
> good thing to keep GDP on master.
 
OK.
 
> > > - improve the silly @lsr and @lsrdir macros with duplicate
> > > arguments I proposed a while ago (see new thread on -devel)
>
> I'm even 100% certain we want to junk that macro.  On one hand,
> snippets referenced with @lsr are only accessible in HTML output, and

and in PDF.  I don't know about info.

> this three arguments syntax I proposed is ugly.  On the other hand,
> we can include snippets directly with @lilypondfile, which makes the
> snippet directly available in Info, PDF and HTML outputs.  It's then
> obvious from both the user's and the developer's points of view that
> we prefer @lilypondfile over @lsr.

No.  Look at Tuplets right now -- the final snippets is way
too long and pointless.  OTOH, it might be worth linking to
it, instead of having it in the huge list of Rhythms snippets.

This is still under discussion.  (also, I'm not certain that
the correct snippet was linked to... but the basic point remains:
sometimes we have long examples which don't really add anything
to the NR, but which we may want to direct readers to)

> If there are concerns about building time, we can share lilypond-book

None at all, as far as I'm concerned.  :)

> As for @lsrdir, which I'd like to rename to @lsrtag, the most
> convenient definition for the doc writers who use this macro would be
> a standard Texinfo cross-reference between manuals, e.g.
> 
> @macro lsrtag{TEXT}
> @ref{\TEXT\,,,snippets}
> @end macro

Sounds fine to me; once everything else is set up, it'll be
a simple matter to do a global search&replace to change all the
@lsrdir stuff.

Cheers,
- Graham