Re: GDP: introducing examples

[Eyolf Østrem]

On 19.10.2007 (14:58), Graham Percival wrote:


> Mark Knoop wrote:
> >Graham Percival wrote:

> >>1)  The text just continues directly into

> >>2)  The text suggests that one may do foo,

> >>3)  The text directs the reader to the following example:

> >>4)  The text forms a complete sentence.

> >>Should allow all?  Specify one method?  Disallow one or two methods?
> >I prefer 4, 3, 2, 1 (in that order). But I don't think standardisation
> >is necessary, although perhaps an official preference could be specified.

> That's my preference as well, although IMO #1 looks like a mistake 
> (missing punctuation) -- my vote is to not allow #1, but let writers pick 
> any of the other three methods.

I agree too. I can probably think of a case where 1) MIGHT be
permissible, (sth like:

"if you file has
[example]
you will get ... ")

but such constructions will rarely look elegant, and it's better to
rephrase it to 2)-4).

eyolf

-- 
   "All this modern technology just makes people try to do everything at once."
-Hobbes


___
lilypond-user mailing list
lilypond-user@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-user

Re: GDP: introducing examples

[Graham Percival]

Mark Knoop wrote:

Graham Percival wrote:


1)  The text just continues directly into

2)  The text suggests that one may do foo,

3)  The text directs the reader to the following example:

4)  The text forms a complete sentence.

Should allow all?  Specify one method?  Disallow one or two methods?


I prefer 4, 3, 2, 1 (in that order). But I don't think standardisation
is necessary, although perhaps an official preference could be specified.


That's my preference as well, although IMO #1 looks like a mistake 
(missing punctuation) -- my vote is to not allow #1, but let writers 
pick any of the other three methods.


Cheers,
- Graham


___
lilypond-user mailing list
lilypond-user@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-user

Re: GDP: introducing examples

[Hans Aberg]

On 19 Oct 2007, at 16:38, Francisco Vila wrote:


So how do you find the LSR?...


You have the link into the main documentaion page
http://lilypond.org/web/documentation
and it links to http://lsr.dsi.unimi.it/


Actually, I see now where the problem is:

If one follows the shortcuts on the main page
  http://lilypond.org/web/
then one ends up a page like
  http://lilypond.org/doc/v2.11/Documentation/
If one then on that page follows "Snippets", one ends up with
  http://lilypond.org/doc/v2.11/input/lsr/collated-files
and following the links there, leads to pages with broken images (at  
least in Safari 3).


So this is not the LSR. For that, one has to go to the documents main  
page.


  Hans Åberg




___
lilypond-user mailing list
lilypond-user@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-user

Re: GDP: introducing examples

[Hans Aberg]

On 19 Oct 2007, at 16:38, Francisco Vila wrote:


So how do you find the LSR?...


You have the link into the main documentaion page
http://lilypond.org/web/documentation
and it links to http://lsr.dsi.unimi.it/


Thank you, but the question is then why the search on the first page  
did not find it.


  Hans Åberg



___
lilypond-user mailing list
lilypond-user@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-user

Re: GDP: introducing examples

[Hans Aberg]

On 19 Oct 2007, at 16:59, Eyolf Østrem wrote:


So how do you find the LSR?...


You have the link into the main documentaion page
http://lilypond.org/web/documentation
and it links to http://lsr.dsi.unimi.it/


... and in the final GDP, there will be so many LSR links that you're
going to moan: "Oh, please, Graham -- not another LSR snippet, I can't
take it anymore!" :-)


I suspected that. - So it might be better putting at least the more  
prominent examples in a special examples PDF, and reference that. The  
LSR could still be there, for new examples that have not yet worked  
up the hierarchy.


I also brought forward the idea of a Wiki. These are great to put  
silly little facts one does not know where to put elsewhere.  
Abbreviations and such, for example.


  Hans Åberg




___
lilypond-user mailing list
lilypond-user@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-user

Re: GDP: introducing examples

[Eyolf Østrem]

On 19.10.2007 (16:38), Francisco Vila wrote:
> 2007/10/19, Hans Aberg <[EMAIL PROTECTED]>:
> > So how do you find the LSR?...
> 
> You have the link into the main documentaion page
> http://lilypond.org/web/documentation
> and it links to http://lsr.dsi.unimi.it/

... and in the final GDP, there will be so many LSR links that you're
going to moan: "Oh, please, Graham -- not another LSR snippet, I can't
take it anymore!" :-)

you'll find it, rest assured.

eyolf

-- 
Insults are effective only where emotion is present.
-- Spock, "Who Mourns for Adonais?"  stardate 3468.1


___
lilypond-user mailing list
lilypond-user@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-user

Re: GDP: introducing examples

[Francisco Vila]

2007/10/19, Hans Aberg <[EMAIL PROTECTED]>:
> On 19 Oct 2007, at 14:37, Mats Bengtsson wrote:
>
> > What you describe sounds like the LSR, which already now has free
> > text search facilities (at least if you stay connected).
>
> So how do you find the LSR?...

You have the link into the main documentaion page
http://lilypond.org/web/documentation
and it links to http://lsr.dsi.unimi.it/

-- 
Francisco Vila. Badajoz (Spain)
http://www.paconet.org


___
lilypond-user mailing list
lilypond-user@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-user

Re: GDP: introducing examples

[Hans Aberg]

On 19 Oct 2007, at 14:37, Mats Bengtsson wrote:


What you describe sounds like the LSR, which already now has free
text search facilities (at least if you stay connected).


So how do you find the LSR? If I search on , it translates to a Goole search

  site:www.lilypond.org LSR
with no matches as a result.

I mean, if it is not easy tho find these things, it probably will  
translate into a lot of question on the LilyPond Users list. :-)


  Hans Åberg




___
lilypond-user mailing list
lilypond-user@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-user

Re: GDP: introducing examples

[Mats Bengtsson]

What you describe sounds like the LSR, which already now has free
text search facilities (at least if you stay connected).

  /Mats

Hans Aberg wrote:

On 19 Oct 2007, at 08:40, Graham Percival wrote:

Currently we have a few different ways of introducing examples in the 
docs.  Should we standardize on a particular way, or just let doc 
writers do whatever they want?


I have the idea that there should be created a separate PDF doc with 
examples, including the snippets (whose pics happen to be broken in my 
web browser, Safari 3). Then the user manual should reference that, 
with a list of what the examples manual contains.


The idea is based on what I find the easiest way to find programming 
usage, namely, in the PDF viewer (I use Preview, but I thing it works 
in Adobe Reader), type a keyword, and looking through all matches. The 
keyword can be both musical terms as well programming names. So 
therefore it helps with a manual mentioning these terms, and with 
directions for further reading


Also, the user manual is already somewhat heavy. So having a second 
manual with examples would be great.


In the context of your question, this gives the opportunity to put 
examples which are too spacious into the examples manual. The user 
manual should be restricted to examples that illustrate concept of the 
text.


Perhaps there should be a third manual: "advanced usage", as well.

  Hans Åberg




___
lilypond-user mailing list
lilypond-user@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-user


--
=
Mats Bengtsson
Signal Processing
Signals, Sensors and Systems
Royal Institute of Technology
SE-100 44  STOCKHOLM
Sweden
Phone: (+46) 8 790 8463 
   Fax:   (+46) 8 790 7260
Email: [EMAIL PROTECTED]
WWW: http://www.s3.kth.se/~mabe
=



___
lilypond-user mailing list
lilypond-user@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-user

Re: GDP: introducing examples

[Hans Aberg]

On 19 Oct 2007, at 08:40, Graham Percival wrote:

Currently we have a few different ways of introducing examples in  
the docs.  Should we standardize on a particular way, or just let  
doc writers do whatever they want?


I have the idea that there should be created a separate PDF doc with  
examples, including the snippets (whose pics happen to be broken in  
my web browser, Safari 3). Then the user manual should reference  
that, with a list of what the examples manual contains.


The idea is based on what I find the easiest way to find programming  
usage, namely, in the PDF viewer (I use Preview, but I thing it works  
in Adobe Reader), type a keyword, and looking through all matches.  
The keyword can be both musical terms as well programming names. So  
therefore it helps with a manual mentioning these terms, and with  
directions for further reading


Also, the user manual is already somewhat heavy. So having a second  
manual with examples would be great.


In the context of your question, this gives the opportunity to put  
examples which are too spacious into the examples manual. The user  
manual should be restricted to examples that illustrate concept of  
the text.


Perhaps there should be a third manual: "advanced usage", as well.

  Hans Åberg




___
lilypond-user mailing list
lilypond-user@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-user

Re: GDP: introducing examples

[Mark Knoop]

Graham Percival wrote:
> Currently we have a few different ways of introducing examples in the
> docs.  Should we standardize on a particular way, or just let doc
> writers do whatever they want?
> 
> Currently we have a combination of four different ways.
> 
> 1)  The text just continues directly into
> 
> c'4\mf
> 
> 2)  The text suggests that one may do foo,
> 
> c'4^"foo"
> 
> 3)  The text directs the reader to the following example:
> 
> << c'4 { e g } >>
> 
> 4)  The text forms a complete sentence.
> 
> c'4^-\mark \default
> 
> 
> Should allow all?  Specify one method?  Disallow one or two methods?

I prefer 4, 3, 2, 1 (in that order). But I don't think standardisation
is necessary, although perhaps an official preference could be specified.

-- 
Mark Knoop
[EMAIL PROTECTED]



___
lilypond-user mailing list
lilypond-user@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-user

GDP: introducing examples

[Graham Percival]

Currently we have a few different ways of introducing examples in the 
docs.  Should we standardize on a particular way, or just let doc 
writers do whatever they want?


Currently we have a combination of four different ways.

1)  The text just continues directly into

c'4\mf

2)  The text suggests that one may do foo,

c'4^"foo"

3)  The text directs the reader to the following example:

<< c'4 { e g } >>

4)  The text forms a complete sentence.

c'4^-\mark \default


Should allow all?  Specify one method?  Disallow one or two methods?
- Graham


___
lilypond-user mailing list
lilypond-user@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-user