[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Documentation fixes, updates, and changes
From: |
Graham Percival |
Subject: |
Re: Documentation fixes, updates, and changes |
Date: |
Fri, 16 Feb 2007 22:40:55 -0800 |
User-agent: |
Thunderbird 1.5.0.9 (Macintosh/20061207) |
Jonathan Henkelman wrote:
I recently read the manual and took notes on, among other things, the errata I
found. Here is a list. All references refer to 2.10.0 PDF version. Also
remember the caveat that editors make errors too:
Thanks! Some of these have already been fixed; the 2.10.0 docs were
released three months ago.
Given the amount of changes, if I have implemented the change you
suggest, I simply deleted it from the email instead of saying "thanks,
fixed" after each one -- but be assured that I am very grateful for all
these comments!
Note: I had quite a few problems with section 9. I am hoping to spend some
time rewritting portions of this section and adding a few sections in the
future. Here are my (relatively) short changes.
Section 9.2.2 - Creating contexts (pg. 209, third bullet in section, para 2):
should read? "... but matches _all_ context_s_ of type...". I assume changes
made to a context this way will apply to _all_ contexts of that type?
I'm not certain whether this should read "any" or "all".
Same section (pg. 215, para. 1): What does \RemoveEmptyStaffContext do? Does
it remove all previous settings i.e. return Staff to its default values? Can
this paragraph be clarified? How about: "\RemoveEmptyStaffContext will return
the staff context to its default values." or "\RemoveEmptyStaffContext will
remove any setting you have applied already within the current context
definition."
The former sentence looks better, but it isn't quite true -- the
\Remove... does _not_ return staff to the default values; it sets up a
Staff with mostly default values, but also sets the propertie(s) that
remove the staff when appropriate.
In this case, I think the current language is good: using \Remove...
overwrites the current Staff settings.
Same paragraph: Does this also apply to other contexts? Is there a
\RemoveEmptyVoiceContext? If so, please add the following sentance after the
example: "There are analagous functions for returning other contexts to thier
default settings, for example \RemoveEmptyVoiceContext."
No, there is no such command.
Next paragraph: replace with "First it is necessary to define a name for the
new context <LF>\name ImproVoice". We don't need the comparison with Voice
because it doesn't have a name yet and the next sentance deals with how to
link in the voice context.
Done.
Next paragraph: Even after reading this I don't really understand what \alias
does. Can someone provide a quick definition of what \alias does.
Sorry, I can't; hopefully somebody else can.
How about
something like replacing the last sentance ("This is acheived...") with "The
\alias command links the current context to an already existing context so
that functions that work on the old one will work on this one also. In this
case we need to link to the Voice context so that functions that work on Voice
will also operate on ImproVoice." or "The \alias command sets the default
values of this context to the values of an already existing context. This
allows functions that operate on the other context to also operate on this
one. In this case we need the functionality of the Voice context so that
functions that work on Voice will also operate on ImproVoice".
I haven't made any of these changes; please resubmit when we hear about
\alias.
Next paragraph: should read "The context will print notes, and instructive
texts so we need to add the engravers which provide this functionality"
Next sentance: should read "We only need this on the center of the line so,"
Both done.
Paragraph starting "All these plug-ins...", last sentace: should read "This
type should always be Engraver_group and it should appear immediately after
the name definition." If this is _always_ the case, why do we need the
definition. Couldn't we just assume it was the case for any new context and
include it as part of \name???
I'm not certain, so I haven't made these changes.
9.3.1
To try and explain how to construct an \override some examples will be worked
through
I think the current text explains this in fewer words.
Section 9.3.2 - Navigating the program reference (pg. 217, para 3 "Follow the
link..."): I found this section extremely difficult to follow as I am using
the PDF docs and it took my a while to figure out why there weren't links.
Also, I couldn't find the programmers reference and the single page version
was (temporarily) broken.
Replace with: "The programmers reference is an HTML document. The simplest way
to navigate through the programmers reference is to use the online version.
This section will be much more difficult to understand if you are using the
PDF manual, so please consider reading this section in conjunction with the
online programmers reference. If you have limited internet access, consider
downloading the programmers reference as a single page. It is not as easy to
follow as the online version because the formatting is more limited, but it
contains all the necessary links to understand these examples." Thanks, I had
no end of frustration/confustion over this! Perhaps this would better fit
somewhere at the beginning so all the references to PR in the docs so far
would make some sense - I couldn't figure out how one was supposed to use them.
I rewrote this somewhat, and it's been added to the non-HTML docs. I
don't think it's necessary to change all the "follow the link" language
as long as it's clear that HTML is recommended for the program reference.
If you can suggest exactly where to include info about references to the
PR earlier in the docs, I'd be happy to add it.
Next para ("By clicking..."): replace sentance with "By following related
links inside the programmers reference, we can figure out that the flow of
information moves like this:" This is more formal and gives the user the sense
that there it isn't just random or aprior knowledge.
Done.
I am hoping to expand this section to explain the logic behind the links...
Also, I have a note that the terms used in this doc to not match those used in
the PR (e.g. object, event, expression). I don't know enough yet to address
this. Would somebody else be willing to look into it?
Maybe -- when I have time to work on lilypond and don't have anything
more urgent. If you would like to see this done within the next six
months, I recommend that you do this.
Section 9.3.6 - \set vs. \override (pg. 220, para 2, line 2): should read "...
from music to _notation_,...
I believe that a music event is a specific thing. Actually, this
comment doesn't make sense -- could you look at the latest docs
(2.11.18) and check if this has already been updated (since 2.10.0) ?
Section 10.1.3 - Extracting fragments of notation: This section doesn't belong
here. In fact I think the sections here should be arranged as follows:
Yes, two doc sections were inserted into a non-optimal place. Fixed.
Section 10.2.1 - Creating titles (pg. 227, para 1): I don't understand what
this sentance is trying to say. Should it read "Titles are created for each
\score block within a \book."?
I rewrote this as:
Titles are created for each @code{\score} block, as well as for the full
input file (or @code{\book} block).
Is that more clear?
Section 10.3.3 - MIDI instrument names (pg. 223): should appear before 10.3.1
as one is more likely to need to know about defining instruments before
defining volumes and relative volumes. It is also a good intro to \set
Staff.midiproperty ... before the more complicated example in 10.3.1
I disagree; finding out how to get any MIDI output at all is more
important than setting up special instrument names. That said, I'm not
opposed to moving volume info out of 10.3.1 and making a new 10.3.4 for
such info.
Section 11.3.1 - Vertical spacing inside a system (pg. 240, para 3): I can't
Trevor is currently rewriting huge portions of chapter 11, so I won't
make any of these changes. When he's finished, could you take a look at
the new chapter and let me know if any of your concerns apply to the new
text?
*** That end the specific changes section. A few further comments:
Throughout the manual there is not a standard for "music, music expression,
musicexpr". I assume that if I think that should be standardized I should
come up with a punch list of changes (or better, learn how to use diff -u!
"musicexpr" is a "music expression". Using "music" instead of "music
expression" is a bit informal. It would be nice to fix this everywhere
that it occurs, but we can't do a global "music->music expression"
change, because sometimes "music" is used in a more general sense.
I think the manual uses a notation standard for different LP grammer elements
e.g. engravers, events etc. Is there a table somewhere that outlines this
notational convention i.e. engravers have first letter caps, underscores, and
no second work caps. If so, I apologize for missing it. If not, could it be
added by someone who knows the convention...
There is a convention about AllCapitalLetters and notAllCapitalLetters,
but I'm not certain what it is. It has to do with whether one uses \set
or \override.
I want to add that the only reason I'm being so fine tuned about the manual is
that I think it is well worth supporting. Good work to all involved.
Thanks!
In the future, could you separate long emails into emails about
chapters? Having four or five shorter emails is easier for me to handle
than one long thing -- then I can easily change one or two chapters,
instead of doing everything at once.
Cheers,
- Graham