Re: GDP predefined commands
Isn't the main points of this discussion that:
- Predefined commands like \fatText should be described in the NR.
Even if the implementation of it might change over the years, the
semantics
will remain the same.
- Somewhere in the NR, it should be described how an advanced user
can find the exact implementation of these predefined commands, in case
he/she wants to do something similar but on another object, for example.
- On the other hand, the exact definition should not be copied verbatim into
the NR (perhaps with the exception of one single example in the
description
mentioned in the previous item), since as Graham points out, the
information
may easily get outdated.
/Mats
Graham Percival wrote:
Trevor Daniels wrote:
Actually, \fatText _is_ simply an arcane override -- but one which
the developers thought was so common that they included a
predefined variable.
The difference exactly. That's why I think this
predefined variable should be in the main text.
No, absolutely not. That would be the *worst* possible thing to do.
(below)
Look in ly/propert-init.ly :
fatText = { \override TextScript #'extra-spacing-width = #'(0 . 0)
\override TextScript #'infinite-spacing-height = ##t }
There was a proposal to explain this in every single @commonprop
section, but I think it's better to include one GOOD explanation of
this kind of thing in the LM.
I agree entirely. A ref to the explanation is all that is required.
Summary: documentation is a process and we don't have the resources.
The exact definition of commands like \fatText changes. I would be
willing to bet money that \fatText will change at least once over the
next five years.
If we discuss \fatText in the main docs (or in the @commonprop), then
what happens when the definition changes? either
1) the docs don't match the program. (very bad!) or
2) the docs need to be updated.
We don't have the resources to update the .tely files every time
something changes. We don't have the programmer resources to get them
to do it, we don't have the documenter resources to find all these
changes and update the appropriate places. Would it be nice if we
were overflowing with offers of help and could do this stuff? Yes,
totally. But the lilypond community -- with a few notable exceptions,
yourself included -- has not been willing to get involved in the
development.
(I _will_ say that it's been getting better in the past year or so...
but still nowhere enough help to make this feasible)
So how should users figure out what \fatText does exactly? They read
LM 4.2.1 and find ly/property-init.ly on their own computer. This
file is *guaranteed* to be correct for their exact version of lilypond.
Documentation is a process, not a product.
(let's put this specific question to rest for a few days; I promise
we will return to it)If you want to continue talking about this
without any examplesN
Sorry, couldn't resist replying :)
At this point I'd like to state that LSR tags have been implemented
and that we're 2 or 3 days away from having some useful examples to
discuss, and it will be much easier to understand once you see an
example.
Cheers,
- Graham
___
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 predefined commands (was: text first draft)
Graham Percival wrote on 08 November 2007 12:26 Trevor Daniels wrote: Actually, \fatText _is_ simply an arcane override -- but one which the developers thought was so common that they included a predefined variable. The difference exactly. That's why I think this predefined variable should be in the main text. No, absolutely not. That would be the *worst* possible thing to do. (below) I think we have misunderstood each other. I said: I agree entirely. A ref to the explanation is all that is required. In other words say what \fattext _does_ in the main text but do not mention how it does it. Most people don't care _how_ it works, but most people will certainly need to _use_ it at some time. Perhaps I misunderstood you, but I took your earlier note to mean the command should be relegated to @commonprop. I'm saying it should be in the main text, but without any explanation of the underlying mechanism anywhere in the NR - just a ref to the source code. That needs less effort, not more. Cheers, - Graham ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP predefined commands
Mats Bengtsson wrote: Isn't the main points of this discussion that: - Predefined commands like \fatText should be described in the NR. Even if the implementation of it might change over the years, the semantics will remain the same. Yes. \fatText: pushes the next note to the right to allow the complete piece of markup to be printed before that note. (or whatever -- that description was badly worded and possibly incorrect; I can't remember what it does) - Somewhere in the NR, it should be described how an advanced user can find the exact implementation of these predefined commands, in case he/she wants to do something similar but on another object, for example. - On the other hand, the exact definition should not be copied verbatim into the NR (perhaps with the exception of one single example in the description mentioned in the previous item), since as Graham points out, the information may easily get outdated. Yes, with one quirk: the LM/NR division. The current changing defaults doesn't make anybody happy. It's too verbose for programmers (or people who are already familiar with it, but can't remember certain details), but much too short for first-time readers. So we're going to compact that chapter in the NR, and expand the relevant chapter in the LM. By analogy, consider the man pages in unix. If you've never used a command before -- say, git :) -- then the man pages are useless. You can't learn how to use git just from reading the man pages. You need to read a tutorial, web pages, etc. OTOH, if you're already familiar with the basic concepts, and just can't remember if you want git-diff -M --cached or git-diff -B HEAD then the man pages are great. NR is a reference to look stuff up; LM is for learning the material in the first place. Cheers, - Graham ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP predefined commands
Graham Percival wrote: Yes, with one quirk: the LM/NR division. The current changing defaults doesn't make anybody happy. It's too verbose for programmers (or people who are already familiar with it, but can't remember certain details), but much too short for first-time readers. So we're going to compact that chapter in the NR, and expand the relevant chapter in the LM. By analogy, consider the man pages in unix. If you've never used a command before -- say, git :) -- then the man pages are useless. You can't learn how to use git just from reading the man pages. You need to read a tutorial, web pages, etc. OTOH, if you're already familiar with the basic concepts, and just can't remember if you want git-diff -M --cached or git-diff -B HEAD then the man pages are great. NR is a reference to look stuff up; LM is for learning the material in the first place. Agreed! However, what's special with LilyPond is that it's three levels, not two. Often for me, the IR is the real reference to look stuff up. The division between NR and IR is obvious for you and me, who know that the IR is the autogenerated stuff. However, there's some information, in particular hidden in some interface descriptions, that could just as well have been in the NR. Again, I don't argue againts the current division, I'm just pointing out the fact that this three level division is fairly uncommon compared to many other programs and may not seem that obvious to new users. /Mats ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP predefined commands
Graham Percival wrote: True. This problem is exacerbated by the fact that I have no clue how the IR is constructed -- if I _did_ understand it, we could probably make a few changes that would make the whole thing considerably easier to read. However, that's one thing that I'm never going to tackle. If anybody wants to attempt it, great! But the IR is officially out of bounds of GDP. Perhaps you can just send out a wish list, hoping that some Scheme hacker finds it an interesting project. /Mats ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP predefined commands
Mats Bengtsson wrote: Graham Percival wrote: NR is a reference to look stuff up; LM is for learning the material in the first place. Agreed! However, what's special with LilyPond is that it's three levels, not two. Often for me, the IR is the real reference to look stuff up. The division between NR and IR is obvious for you and me, who know that the IR is the autogenerated stuff. True. This problem is exacerbated by the fact that I have no clue how the IR is constructed -- if I _did_ understand it, we could probably make a few changes that would make the whole thing considerably easier to read. However, that's one thing that I'm never going to tackle. If anybody wants to attempt it, great! But the IR is officially out of bounds of GDP. Cheers, - Graham ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP predefined commands
Mats Bengtsson wrote: Graham Percival wrote: However, that's one thing that I'm never going to tackle. If anybody wants to attempt it, great! But the IR is officially out of bounds of GDP. Perhaps you can just send out a wish list, hoping that some Scheme hacker finds it an interesting project. I'm not optimistic -- there's a bunch of much easier items on the technical-todo list. But I've added this anyway; maybe in a few years, somebody will pick it up. Cheers, - Graham ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: Predefined commands vs. commonly teaked properties
2007/9/22, Trevor Bača [EMAIL PROTECTED]: On 9/21/07, Graham Percival [EMAIL PROTECTED] wrote: Should we keep @refcommands independent from @commonprop ? For example, look at Tuplets. Do you like it as it is, or should we move \tupletUp \tupletDown etc inside the Commonly tweaked properties ? I vote for combine. -1; the @refcommands shorcuts are much simpler than the \overrides (to understand, and to use), and therefore IMO they should be above @commonprop, just like they're now. Or, another idea, on the opposite: if they got merged with @commonprops, we should mention the extensive definition of each @refcomman, so that users could see by themselves a concrete application of some of the commonly tweaked properties, and feel somehow invited to write their own shortcuts. The reason I'm mentioning that is because we already specify the full syntax on several pages,like in Special NoteHeads, or Improvisation. (If this option is eventually accepted, I'm ready to write the full explanation of each refcommand myself, btw) Valentin ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
