[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: GDP: the snippets vs. texinfo

From: Graham Percival
Subject: Re: GDP: the snippets vs. texinfo
Date: Sat, 10 Nov 2007 06:17:33 -0800
User-agent: Thunderbird (X11/20071022)

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.

- Graham

reply via email to

[Prev in Thread] Current Thread [Next in Thread]