Re: GDP: the snippets vs. texinfo

[Graham Percival]

Eyolf Østrem wrote:
> On 09.11.2007 (21:02), Graham Percival wrote:
>
> > PDF vs. HTML: pdf readers generally prefer to have consecutive 
> > documentation, with few links.  HTML readers generally prefer to have 
> > links everywhere.
>
> Slight correction: pdf readers do like links -- internal ones -- it's a
> Good Thing. Having unneccessary divisions into separate documents which
> then cannot be linked, is a Bad Thing. 

Oh, was that your concern?  Separate documents can still be linked.  I 
thought we already had that, but apparently it wasn't working.  Take a 
look at tomorrow's GDP.

(I think the files need to be in the same directory, however)

(also, they look uglier than they should.  As always, I'm accepting 
technical help)

However, these links don't help people who print out PDFs.  (well, they 
help slightly, but they're not ideal.  OTOH, there's no difference 
between a link to a different document and a link to the same document 
-- actually, if anything I'd suggest that links to other documents are 
better, since you can have two printed manuals open at the same time)

> On the other hand, I see the numerous private LP-tips-and-tricks-pages as a
> result of this: a feeling something like: "I have figured out some neat
> things but since the docs are stable, complete, fixed, there is no way in
> there, so I'll make my own page." This is fine, but for the user who is
> looking for that extra information, it means that he has to hunt around
> among disparate pages of varying quality, organization, and up-to-date-ness.

I would argue that this is _not_ fine, for precisely the reasons you 
state.  Ideally, users should look for info in two places:
- official docs (be it NR, IR, LM, etc)
- LSR (which is massively promoted, and linked to, from the official docs)

>  One might still discuss practicalities: should the LSR only be
> snippets, is "snippets" the right term (or does it give too much
> associations in the direction of "trifles"?), etc. but that is another
> discussion for another thread.

The "real music" tag in LSR is aimed at longer pieces.  (it currently 
doesn't do that, simply because we don't have any pieces to tag with this)

> > Out of all of these concerns, I naturally feel that my own position is the 
> > most important.  If anybody wants me to relax my "we don't have the 
> > resources to do this" position, please volunteer in GDP.  If I have more 
> > resources, of course I'll accept more good doc ideas,
>
> As an aside: I did volunteer, but I still get the "we don't have the
> resources" reply.  :-) 

The volunteer more.  Eyolf, currently you are the *only* person working 
on Rewriting NR 1.  The entire chapter needs to be done before the end 
of 2007.

Now do you see why I keep on saying "we can't do X"?  :(

> > Some PDF users may not be so fond of the snippets because they move 
> > material out of the main docs.  I'd like to point out that the Snippets 
> > are available as PDF, so that might mitigate this concern.
>
> The pdf does not contain the LP code, so it is fairly useless, at least in
> its current state.

That's on the todo list.

> > My proposal, taking into consideration all the contradictory demands laid 
> > out at the top of this email, is to have one or two tweaks in the 
> > @commonprop.  The main goal of @commonprop is to pique the interest of a 
> > reader, to encourage him to follow the "Snippets: foo, bar" links.
>
> Finally, the reason why I started writing this: is this really the purpose
> of @commonprops?

Well, that's the main question in this discussion.  :-)

My proposal -- only a *proposal* -- is to use it as appetizers.

> In any case, the flow should go in both directions:
> important tweaks in the LSR should be moved into the docs (but I think we
> agree on that).

Important tweaks in LSR are moved into the docs by giving them a "docs" tag.


My rule of thumb for the docs: after the end of GDP, the NR should not 
change for the next five years.

This obviously isn't possible -- no matter how careful we are, we'll 
miss a few typos or have some badly worded English.  Lilypond will get 
some new features, which will need to some docs.  The syntax will 
change, but this can/should/might be updateable with convert-ly.  The 
non-tweaking syntax is fairly stable, at least.

Stuff which might be changing more often -- the exact syntax of tweaks, 
making tweaks more interesting/complicated/simpler/etc, adding new 
tweaks -- should be done in a manner which allows easy updating.  LSR is 
such a method.


In this case, about 80% of my argument relies on "lack of resources" 
rather than "I think that documentation looks better this way".  Or in 
other words, documentation is a process, not a product.  And we have 
very few resources which we direct towards that process.

Cheers,
- Graham