2.1.35 Documentation bugs

[Hans Forbrich]

(In response to the request to proofread v2.1.35 "Changing Defaults dssection, 
I looked and found the following.  Except as noted, these verified on web 
site as well as locally built version.  I use ====== to separate web pages 
being reviewed.)

=============
A) In "Appendix C Interfaces for programmers" 
-> "C.1 Programmer interfaces for input"
-> "C.1.2 Internal music representation" 
(http://lilypond.org/doc/v2.1/Documentation/user/out-www/lilypond/Internal-music-representation.html#Internal%20music%20representation)

a) Link  "Music expressions" contains a space and gives "404 Not Found" error
( http:// ... /Documentation/user/out-www/lilypond-internals/Music 
expressions.html)

b) incorrectly formed "under Music expressionsexpressions." should be "under 
Music expressions."

c) Link "Music classes" contains a space and gives "404 Not Found" error
(http: ... /Documentation/user/out-www/lilypond-internals/Music classes.html)

d) Link "Music properties" contains a space and gives "404 Not Found" error
(http: ... /Documentation/user/out-www/lilypond-internals/Music 
properties.html)

===============
B) In "4 Changing Defaults"
http://lilypond.org/doc/v2.1/Documentation/user/out-www/lilypond/Changing-defaults.html#Changing%20defaults

a) Link "Program reference" (second paragraph) contains a space and gives "404 
Not Found" error 
(http: ... /Documentation/user/out-www/lilypond-internals/Program 
reference.html)

b) I recommend a 'Note on Properties" link between the "Scheme tutorial" and 
the "Interpretation Contexts" that discusses the difference between Context 
Properties and Layout Properties.  This could be an expansion of the 
discussion in "Tuning Output" and would allow "Tuning Output" to flow more 
smoothly.  

If I understand the difference between Translator and Layout porperties 
correctly, my thoughts on this Note would be something like:

------------------------
A Note on Properties

Lilypond has two general types of variables, more formally called Properties', 
that can be referenced or updated.  These are Translation properties and 
Layout properties.  

Changes in the value of a property are effective at the musical point-in-time 
when they are set and stay effective for the remainder of the score.  The 
exception, explained later, is to use the special operator \once which 
changes the property back to the previous value after it has been used.

Translation properties are used within the Context level and may affect the 
behaviour of Engravers (programs responsible for actual typesetting), nested 
Contexts and Objects.  The definition of a Context includes the list of 
Translation properties.

Translation properties are identified by the mixed case naming style.  They 
are manipulated using the \set and \unset operators:

        \set Context.propertyName = value

Layout properties are used at the grob (graphical object) level and generally 
only impact the visual style of the objects from that point forward.  The 
definition of an object, such as Fingering or NoteHead, includes the list of 
Layout properties.

Layout properties are use Scheme style variable naming, i.e. lower case words 
separated with dashes. They are symbols, and should always be quoted using 
#'.  They are generally manipulated using the \override operator" 

        \override Object #'layout-property-name = #value

(One tricky thing:  boolean 'True' and 'False' have values #t and #f.  Don't 
forget the leading # - for example "\override Stem #'transparent = ##t")


------------------------

c) Locally built version does not have the "page" number (4) in front of 
Changing Defaults.
============
C) In "4.3 Tuning Output"
http: ... 
Documentation/user/out-www/lilypond/Tuning-output.html#Tuning%20output

a) Paragraphs "-nmost adjustments simply" and "The commands changes" are not 
complete.  Not quite sure what you are attempting wto say.

b) If my recommendation for a 'Note on Properties" is accepted, the "Do not 
confuse ..." paragraph can be removed.

c) Locally built version does not have the numbering (4.3)

=============

D)  4.3.4 Layout Interfaces

a) In the locally built version ONLY, the first paragraph is not separated 
from the title, resulting in bold "Layout interfacesFingering is a layout 
..." 

b) Locally built version does not have the numbering (4.3.4)

=============

E) 4.4 Fonts

a) I recommend an opening paragraph like

-------------
In traditional typesetting, the letters on the printed page come from a 
lettering style, called a font.  TeX, the typesetting language  under 
Lilypond, extends this concept to all graphical objects.

In addition to the standard fonts, such as Computer Modern, provided by the 
TeX  environment, Lilypond adds music fonts.  The predominant one is the Feta 
font that contains the style and shape of all the music symbols used.
------------

===============
A brief look at "4.5 Text Markup", "4.6 Global Layouts" and "4.7 Output 
Details" did not find any link problems and was generally quite readable.

HTH
/Hans