[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: GDP: the snippets vs. texinfo
Re: GDP: the snippets vs. texinfo
Sat, 10 Nov 2007 06:17:33 -0800
Thunderbird 220.127.116.11 (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
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
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
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
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.