[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Documentation fixes, updates, and changes
Documentation fixes, updates, and changes
Thu, 15 Feb 2007 20:42:44 +0000 (UTC)
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:
Section 7.2.2 – Chords mode (pg. 106, final para): should read "... does not
sound good when combined with an unaltered _13_,..."
Section 7.2.2 - Chords mode (pg. 106, para. 2): should read "...bass note can
be added instead _of_ transposed..."
Section 8.1.2 - Text Spanners (pg. 159, Predefined Commands section): all
predefined commands up to this point have included the leading '\'. They
should be included here also.
Section 8.4.8 - Selecting notation font size (pg. 196, first two examples):
It took me quite a while to get the difference between these two examples. I
would propose adding the following to the end of the paragraph preceeding the
second example. "The font-size property can also be set directly, so that all
layout obejcts are not affected."
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.1 - Context explained (pg. 207, para 1): should read "...
notational elements must be added to the _output_."
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?
Section 9.2.5 - Layout Tunings within Contexts (pg. 213, para 4): Paragraph
starts "Analagous...". In this sentance it isn't clear if leaving out the
context will _always_ default to voice, or just in this instance. If it is
the former, change the first sentance to: "Analogous to \set, the context
argument may be left out, causing the default context Voice to always be
used." If it is the second, change the first sentance to: "Analogous to \set,
the context argument may be left out, causing it to apply to the current
context (in this case Voice)."
Same place: make the last comma segment a sentance (it introduces a new idea)
as follows: "Adding \once applies the change during one timestep only"
Section 9.2.6 - Changing context default settings (pg. 214, para 2 "Here
\Staff..."): I'm not even quite sure what this is trying to say. How about
changing it to? "Here the \Staff command identifies this section as changing
the settings for the staff context." Or how about "The \staff command brings
in the existing definition of the staff context so that it can be modified."
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
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."
Section 9.2.7 - Defining new context (pg. 215, para 4): should read "In the
following discussion, the example input shown should go in place of the ... in
the previous fragment."
In general this section could be enhanced by providing further expainations of
commands rather than just showing a single example. I've done my best below:
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.
Next paragraph: Even after reading this I don't really understand what \alias
does. Can someone provide a quick definition of what \alias does. 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".
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,"
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???
Section 9.3 The \override command & 9.3.1 Constructing a tweak (pgs. 216-7):
It seems to me that this should start with some sort of definition.
How about changing the entire 9.3 to:
9.3 The \override command
In the previous section, we have already touched on a command that changes
layout details: the \override command. In this section, we will look in more
detail at how to use the command in practice. The general syntax of this
\override context.layout_object layout_property = value
This will set the layout_property of the specified layout object, which is a
member of the context, to the value.
To try and explain how to construct an \override some examples will be worked
\override Voice.Stem #'thickness = #3.0
To construct this tweak we must determine these bits of information: ...
** end quote **
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.
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.
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?
Section 9.3.3 - Layout interfaces (pg. 218, end of para 2): should
read "...kept at a distance of at least _0.5_ _from_ the note head."
Section 9.3.6 - \set vs. \override (pg. 220, para 2, line 2): should read "...
from music to _notation_,...
Section 10.1.1 - File structure (introduction) (pg. 223, last para, last
sentace): should read "Section 10.1.4 enumerates them all." as 10.1.2 does not
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:
** start quote **
Sec. 10.1.1 - File Structure (introduction): should stay where it is.
Sec. 10.1.4 - File Structure: should become 10.1.2
Sec. 10.1.5 - A single music expression: should become 10.1.3
Sec. 10.1.2 - Multiple scores in a book: should beomce 10.1.4 since it needs
to have both score and book introduced by (current) section 10.1.4, with the
expansion of the idea expressed in 10.1.5 about building a score before also.
Sec. 10.1.6 - Including Lilypond files: should be 10.1.5
Sec. 10.1.7 - Text encoding: should be 10.1.6
Sec. 10.1.3 - Extracing fragments of notation: should be 10.1.7 as it the
least likely to be used and the most esoteric section in 10.1
** end quote **
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."?
Section 10.3.1 - Creating MIDI files (pg. 232, first eg.): delete FIXME, or
fixme then delete FIXME
Section 10.3.2 - MIDI block (pg. 223): should appear before 10.3.1 - Creating
MIDI files, since it introduces the midi block which "Creating MIDI files"
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
Section 11.3.1 - Vertical spacing inside a system (pg. 240, para 3): I can't
really understand what this is trying to say. I would have to fool around
with it to see how it works before coming up with a concrete replacement.
Would someone be willing to have a peak and see if it couldn't be made a bit
Section 11.4.2 - New spacing area (pgs. 245-6, two examples): I really can't
see a difference between the output of these two examples. Could it be that
the wrong output files were linked, or there is a scaling problem? Not sure
what is wrong, but in my PDF, they appear identical. Or perhaps some text
could be included as to what to look for that is different?
Section 11.5.4 - Optimal page turning (pg. 259, para 5): I'm afraid as a
relative newbie reading this I still don't understand what the arguments to
minimumPageTurnLength are. I can make a guess that the following might
do? "...#(ly:make-moment 1 1) i.e. one whole note. If you ... very large. In
this example it is set to 5 half notes:"
*** 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!
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...
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.
- Documentation fixes, updates, and changes,
Jonathan Henkelman <=