Documentation, Was: convert-ly problem

[Mats Bengtsson]

Han-Wen Nienhuys wrote:
> Changing fonts has become so much easier. See
>
>   http://pegasus.rutgers.edu/~elflord/unix/latex/no-bs.html
>
> for what it takes to put a Type1 font into LaTeX (let alone into 
> LilyPond) and compare it to  dropping the .pfa into ~/.fonts and doing
>
>      #(define fonts
>        (make-pango-font-tree
>         "Times New Roman" "Helvetica" "Courier"
>         (/ myStaffSize 20)))

This could certainly be considered "much easier" if it had been
documented in the manual, but it's not even mentioned there, so I would
rather consider it completely impossible for an ordinary user.
OK, after some searching, I found an example in the NEWS file for 2.6
and in the Regression Tests, but still no clear explanation of what
this Scheme code does.

I would claim that no feature can be considered implemented and
available unless it is documented in the manual. Even though Graham has
the main responsibility for the documentation, all the documentation
burden cannot be put on him. Especially, for sponsored features, I
would never pay such a feature unless the resulting documentation was of
the same quality as the implementation. For the pitched trills, for
example, I was very surprised to see that there is no link from
"6.5.5 Running trills" to the new section "8.4.6 Pitched trills"
and that there is no entry in the Index.

   /Mats