Re: GDP: the snippets vs. texinfo

[Eyolf Østrem]

On 10.11.2007 (06:17), Graham Percival wrote:
>  Eyolf Østrem wrote:
> > 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?

Half of it. The other -- main --  half is searching. Furthermore,
cross-document linking isn't as uncomplicated as you make it appear: as you
say, the files must be in the same dir, and they have to exist in the first
place (what if I use my own copy of the NR and for some reason haven't
downloaded the PU?).

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

Agreed - that's what I meant too, and I think it's a great step when we
have in fact got these two channels. At the time, i.e. before LSR was
firmly established, it was fine, because there was no easy outlet for that
kind of "wiki-like" contributions, but now the LSR should  take care of
that. 

> > 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.
 
Well, if what you say below is the goal, that on the whole the docs should
not change after the GDP, I'd say there is no need to rush it, especially
if there are so few people to do the work. As for me, I have a daytime job
too...

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

Of course. As long as it doesn't turn into a "We can't do X, so we won't
even consider it, not even if it would make Y -- which we can and must do
-- easier."
But I'm not advocating featuritis.

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

but that will only include them in the snippet part of the docs, right?
This may of course be enough in many cases, but there are some snippets
which are central enough to merit inclusion in the main text as well. The
snippet Adding an extra staff (http://lsr.dsi.unimi.it/LSR/Item?id=110)
IMHO should be included directly, and Adding beams, slurs, ties, etc.
(http://lsr.dsi.unimi.it/LSR/Item?id=321) is even *formulated* in a
Documentation way, as an extension to what is already in there, rather than
an additional piece of information. Those two could go almost straight in.

eyolf (who will now stop spending time writing list mail and instead do
some volunteer work...)

-- 
Delay not, Caesar.  Read it instantly.
                -- Shakespeare, "Julius Caesar" 3,1
 
Here is a letter, read it at your leisure.
                -- Shakespeare, "Merchant of Venice" 5,1
 
        [Quoted in "VMS Internals and Data Structures", V4.4, when
         referring to I/O system services.]