Re: stop breaking the docs

[John Mandereau]

Le mardi 26 février 2008 à 11:42 -0800, Graham Percival a écrit :
> On Tue, 26 Feb 2008 15:54:08 +0100
> John Mandereau <address@hidden> wrote:
> > A dedicated branch would be the best option for GDP, with
> > regular merging from and into master; it's not harder than using
> > push, pull, checkout and merge Git commands.
> 
> That's not what we thought a few months ago:
> http://lists.gnu.org/archive/html/lilypond-devel/2007-10/msg00001.html
> http://lists.gnu.org/archive/html/lilypond-devel/2007-11/msg00149.html

The main problem was, we didn't merge master and gdp fraquently, and I
had the bad idea to rebase instead of merging.  This is an old story now
(see below)



> Here's my opinion: I am not playing with switching between branches,
> and the GDP helpers who use git are certainly not doing this either.  If
> you want lilypond/gdp on a separate branch, then
[snip]
> I think this causes unnecessary overhead; that's why we stopped using
> this method last Nov.  But it's up to you two.

You have a point, that's why I decided to create my own branch; as I
already play with master and lilypond/translation as local cloned
repositories (made with 'git clone -l -s -n'), I don't mind playing 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.



> > - improve the silly @lsr and @lsrdir macros with duplicate arguments I
> > proposed a while ago (see new thread on -devel)
> 
> Err... displaying the name, you mean?  I already did that.  Also, you
> might want to wait until we know if we're keeping @lsr at all.  I'm
> 90% certain that we're junking that macro.

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

If there are concerns about building time, we can share lilypond-book
snippets between input/lsr/out-www and Documentation/user/out-www to
avoid duplicate ly snippets compilation, exactly like in translated
docs.  The only technical detail is about setting @lilypondfile options
in Snippets the same way as in the manuals, to get the same hashes in
lily-*.


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

It'll work out of the box in Info output (when Snippets are compiled in
Info of course), except that we should name the output file
lilypond-snippets.info.  It'll require some links hacking in
add_html_footer.py to make it work in HTML output, and it'll require
moving snippets.pdf to Documentation/user during www_post step to make
it work in PDF output.

Cheers,
John