Re: improving docs (was: Break_Align_Order-3)
On Fri, 14 Mar 2003 23:48:21 -0700 Paul Scott [EMAIL PROTECTED] wrote: I can certainly do some of that. My next concern/question would be concerning versions. I use whatever is packaged for Debian unstable - currently 1.6.6. Is there much point improving that documentation when the development is done on a later version? I see the online manual is actually 1.6.0. That's a bit misleading -- IIRC, the version number of the manual is simply a string in the .itely or .tely file. The manual _has_ been updated since 1.6.0. About what version to document: 1.6.x is frozen (apart from major bug fixes), and that unfortunately applies to the documentation too. So doc patches would need to apply to 1.7.x. However, most things that were hard to learn for 1.6.6 (which is what's in Debian right now) will still be hard to learn for 1.7.x, so you could still work on the documentation for 1.7.x although you just use 1.6.6. Alternately, you could work on other things -- the tricks examples, or an entirely seperate document about common problems, or a FAQ, or something ilke that. Cheers, - Graham ___ Lilypond-user mailing list [EMAIL PROTECTED] http://mail.gnu.org/mailman/listinfo/lilypond-user
Break_Align_Order-3
No spacing entry from BarLine/TimeSignature/KeySignature to `left-edge'/`key-signature'/`left-edge The example is not really complete. You should start from the current default setting and just move the objects that you want to move. Ah, so I was on the right track. I included all of the elements: \property Score.breakAlignOrder = #'( instrument-name left-edge ambitus span-bar breathing-sign clef staff-bar key-signature time-signature custos) And it seems to work. I *still* got lots of error messages in the console. programming error: No spacing entry from BarLine to `' or `key-signature' The documentation should be updated. If I may, I'd like to say something about the documentation in general. From an end-user standpoint I'd have to say that the docs are the weakest part of Lilypond. I don't mean to say that they're bad. I'm sure it is all very well documented. What I find problematic is that the docs go from a fairly simple example of HOW THINGS WORK straight to a gory-details nuts-and-bolts description of the minute workings of the program. I don't have a problem with that, either. What I find lacking is much of anything in-between. For example: \property Score.MultiMeasureRest \override #'expand-limit = #9 ...was exactly what I needed to adjust the block rest behavior. I didn't need several paragraphs of dense description of how this mechanism works. That I can save for later. Now please, I'm not complaining. I think Lilypond is great. It appeals to me for many reasons. I just think a middle ground level of docs would be of great value to the new users as well as the sometimes users. I fall into this category. I'll have a project, learn a bunch of Lilypond tricksand then forget them all before I have another project. Should I read the docs more? Sure. But knowing a bunch of specific operations beforehand make it easier to generalize and make use of the nuts-and-bolts docs. One thing I want to do for myself is make a list of all the tricks etc. that I've learned that (like the multimeasure rest adjustment above) and organize them so that they will form the middle level docs I'm talking about (I *have* found the occasional fix on the wiki) . If I manage that, the next step would be to post them on the web. I don't know if that will happen any time soon but I can wish. Thanks, David Bobroff The irony is that Bill Gates claims to be making a stable operating system and Linus Torvalds claims to be trying to take over the world. ___ Lilypond-user mailing list [EMAIL PROTECTED] http://mail.gnu.org/mailman/listinfo/lilypond-user
Re: Break_Align_Order-3
David Bobroff wrote: No spacing entry from BarLine/TimeSignature/KeySignature to `left-edge'/`key-signature'/`left-edge The example is not really complete. You should start from the current default setting and just move the objects that you want to move. Ah, so I was on the right track. I included all of the elements: \property Score.breakAlignOrder = #'( instrument-name left-edge ambitus span-bar breathing-sign clef staff-bar key-signature time-signature custos) And it seems to work. I *still* got lots of error messages in the console. programming error: No spacing entry from BarLine to `' or `key-signature' These are only warnings, Lilypond mostly does something sensible anyway, as you have noticed. If you want to get rid of the warnings or if you are not happy about the default spacing, you should set the space-alist property of the BarLine object to include a value of the spacing also to key-signature. Something like (again untested): \property Score.BarLine \override #'space-alist = #'( (time-signature . (extra-space . 0.75)) (custos . (minimum-space . 2.0)) (clef . (minimum-space . 1.0)) (first-note . (extra-space . 1.3)) (key-signature . (minimum-space . 1.0)) ) You may want to use some other spacing value. /Mats ___ Lilypond-user mailing list [EMAIL PROTECTED] http://mail.gnu.org/mailman/listinfo/lilypond-user
Re: Break_Align_Order-3
David Bobroff wrote:
If I may, I'd like to say something about the documentation in general.
From an end-user standpoint I'd have to say that the docs are the weakest
part of Lilypond. I don't mean to say that they're bad. I'm sure it is
all very well documented. What I find problematic is that the docs go from
a fairly simple example of HOW THINGS WORK straight to a gory-details
nuts-and-bolts description of the minute workings of the program. I don't
have a problem with that, either. What I find lacking is much of anything
in-between. For example:
\property Score.MultiMeasureRest \override #'expand-limit = #9
...was exactly what I needed to adjust the block rest behavior. I didn't
need several paragraphs of dense description of how this mechanism works.
That I can save for later.
Now please, I'm not complaining. I think Lilypond is great. It appeals
to me for many reasons. I just think a middle ground level of docs would
be of great value to the new users as well as the sometimes users. I
fall into this category. I'll have a project, learn a bunch of Lilypond
tricksand then forget them all before I have another project. Should I
read the docs more? Sure. But knowing a bunch of specific operations
beforehand make it easier to generalize and make use of the nuts-and-bolts
docs.
I kind of agree, but my first priority (I've probably said for over a
year that I will do this as soon as I get some time) is to rewrite the
fine tuning sections of the manual. The point is that it would take
too large space to include an example of every possible application of
every property. Remember that most of the properties are common to a
number of different graphical objects, whereas the documentation of each
property currently is only written once (and then duplicated in the
autogenerated part of the manual).
Also, there are typically several ways to apply the same setting.
Consider the setting shown above as an example. If you want the
same setting in the full score or even in a global.ly file that you
include in several scores, it would be better to put it within the
paper section:
\paper{
...
MultiMeasureRest \override #'expand-limit = #9
}
whereas the version given above is more appropriate if you want to
have different settings in different bars or in different staves,
for example. My conclusion is that it's essential for most users
to have an idea of the general principles of how to set a property.
However, I agree that the current manual does not manage completely
to describe these fairly simple principles in a clear way.
/Mats
___
Lilypond-user mailing list
[EMAIL PROTECTED]
http://mail.gnu.org/mailman/listinfo/lilypond-user
Re: Break_Align_Order-3
Han-Wen Nienhuys wrote: [EMAIL PROTECTED] writes: How about some diagrams showing the relationships between the various dimensions and what they apply to? Yes! Please make some! :-) I wish I knew enough about these to do that. Seriously -- I've tried explaining this a lot of times: it is very hard for me to write adequate newbie documentation, and see where the current doc is lacking, because I know lily so well. If you people want to have better docs, than the best way to ensure that is by helping to write them. I completely understand and appreciate what you have been able to do. I hope to know enough in the near future to be able to help more. I used to hand copy parts professionally for orchestral works and know most of that side of things. I also develop software but still don't know enough about Lily to help more yet. Paul ___ Lilypond-user mailing list [EMAIL PROTECTED] http://mail.gnu.org/mailman/listinfo/lilypond-user
Re: improving docs (was: Break_Align_Order-3)
Graham Percival wrote: On Fri, 14 Mar 2003 17:00:18 -0700 Paul Scott [EMAIL PROTECTED] wrote: Han-Wen Nienhuys wrote: How about some diagrams showing the relationships between the various dimensions and what they apply to? Please make some! :-) I wish I knew enough about these to do that. You don't really need to know a lot to improve docs (this isn't just directed at you, Paul; as Han-Wen says, many people have asked for better documentation). If you (or anybody else) is a good proofreader, then simply proofread the documents -- that's what I did until I agreed to finish my cello suite before I graduate (in a few weeks). While you're proofreading, you can add in a bit of rephrasing, extra explanations, or better examples. I can certainly do some of that. My next concern/question would be concerning versions. I use whatever is packaged for Debian unstable - currently 1.6.6. Is there much point improving that documentation when the development is done on a later version? I see the online manual is actually 1.6.0. When you're having trouble understanding something, make a note of it. Once you _do_ understand it, rewrite or create a new piece of documentation that makes it easier to understand. I will see what I can do. Thanks, Paul ___ Lilypond-user mailing list [EMAIL PROTECTED] http://mail.gnu.org/mailman/listinfo/lilypond-user
