include snippets in docs [was: Re: stop breaking the docs]

[John Mandereau]

Le mercredi 27 février 2008 à 21:36 -0800, Graham Percival a écrit : 
> On Wed, 27 Feb 2008 10:46:39 +0100
> John Mandereau <address@hidden> wrote:
>  On one hand,
> > snippets referenced with @lsr are only accessible in HTML output, and
> 
> and in PDF.

Oh, I forgot about it; maybe it would make more sense that links direct
to the PDF form (see blurb about @rlsr below).


>   I don't know about info.

They weren't compiled in Info, I just added them.  The layout in Info is
ugly (no space between the snippet and file name of the next), but this
kind of issue can wait a bit :-)


> 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)

In this case, we could use @lilypondfile without verbatim, but it makes
the ly code difficult to reach from PDF; I've made an attempt at making
clickable snippets like in HTML docs, but it looks like handling URIs in
PDFs pointing to the current directory is not standardized.  Maybe
setting up a 'Launch' PDF action would do, but it would involve trickery
in texinfo.tex... well, it's not for tomorrow.


There's another related issue: snippet titles are not printed in
manuals, should we use printfilename fragment option as in snippets
pages?  It'd be even better to print real snippet titles instead of
those filenames with dashes; adding that feature mainly requires
Valentin and me to work on requests to Sebastiano ;-)


> > @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.

OK, I've added @rlsr as a generic cross-reference to Snippets; it'll
also work for links to individual snippets, as soon as we can mark them
with @node and @unnumberedsec without splitting up HTML pages...

Cheers,
John