Re: GDP: the snippets vs. texinfo

[Eyolf Østrem]

On 09.11.2007 (21:02), Graham Percival wrote:
> OK, it's finally time for the big fight!

> In managing the docs, I need to weigh multiple contradictory demands.

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

> Stable docs vs. wiki: some people want an unchanging, complete, finished 
> set of docs, particularly if they print them out.  Other people like the 
> constant flux of web 2.0 stuff.

I agree completely with your position that there should be one stable,
complete, fixed set of docs, and that a wiki solution is not good for a
complex piece of software like LP.
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.
This may not be an accurate description anymore: with the LSR as a
well-established and semi-official entity, there is hardly any need for the
private pages anymore. In other words: I think it's fine as it is now: a
fixed documentation and an officially endorsed repo of user-contributed
stuff. 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.

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

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

> 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? Or phrased differently: given the lack of resources and
the concern that the documentation files grow too big, is it really a good
idea to fill it up with appetizers?  What I want to say is: if what you're
saying is that everything which is now in @commonprop is just appetizers,
some of it could even be removed, and what remains will remain as
appetizers, I disagree, but if you're saying that the @commonprops should
be revised so that all that which is necessary to accomplish normal
typesetting tasks, i.e. solve commonly encountered problems, or as Trevor
recently wrote: "to reproduce anything in a score found on their
bookshelves", should be elevated to main documentation text whereas that
which is more of the "btw, you can also do THIS" kind could be moved to the
LSR, I do agree. 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).

On the whole: the NR should contain everything and nothing but that which
is necessary for the "score on the bookshelf" test.

Eyolf

-- 
Several years ago, an international chess tournament was being held in a
swank hotel in New York.  Most of the major stars of the chess world were
there, and after a grueling day of chess, the players and their entourages
retired to the lobby of the hotel for a little refreshment.  In the lobby,
some players got into a heated argument about who was the brightest, the
fastest, and the best chess player in the world.  The argument got quite
loud, as various players claimed that honor.  At that point, a security
guard in the lobby turned to another guard and commented, "If there's
anything I just can't stand, it's chess nuts boasting in an open foyer."