Re: Docs suggestion

[Mats Bengtsson]

In principle, I agree! However, I also have some comments:

- You didn't mention two other excellent sources of information:
  * The "Tips and tricks" document.
  * The mailing list archives.

- There are thousands of different things you can do with LilyPond
  that are not explained with a separate example in the manual.
  It's very difficult to know what to include, but one of the best
  ways to find out what is missing is to look at the questions to
  this mailing list. I know that Han-Wen and Jan struggle hard to
  remove not only bugs but all kind of limitations and problems that
  pop up on the mailing lists, still it would be great if someone had
  the time to collect a How-To or FAQ. We have discussed it several
  time on the list and even had a FAQ on the web using wiki-wiki
  technique so that anybody could update it. One of the main problems
  actually turned out to keep it up to date, the same problem as
  any other kind of documentation. So, in the end it boils down to
  finding one or more persons who have the time and ambition to
  maintain such a document.

- The specific issues you mention, are described in the
  "Global layout" section of the manual (in more or less detail).
  The first step, instead of creating a new How-To document, is
  to clarify the text of the existing manual.
  Here it's very easy for you and everybody else to make a contribution,
  just send suggestions for reformulations of the text to bug-lilypond.

    Mats

J. Daniel Ashton wrote:
> I'd like to see a new section in the fine manual: How-Tos.
>
> In specific, I'm looking for something like "How to adjust the 'margins'
> on output (see linewidth, place it _after_ the \include paper16.ly)."
> Or "How to move the lyrics closer to the notes."  Or "How to make the
> lyrics line up with the first note of each melisma."
>
> Some of this same material exists as comments or implications in the
> regression tests.  Some of it doesn't.  As a late-night frustrated user,
> I'd like a place in the manual that showed extremely brief but complete
> examples, preferrably accurate with the current version of the software.
>
> Someone asked recently for Docs suggestions and criticisms, so there's
> my two cents worth.
>
> I go to the docs, particularly the PDF file, for everything.  When I
> fail to find something there I turn to the regression tests and other
> .ly files littering the installation directory.
>
> My feeling is that new users have terminology problems (the docs could
> help somewhat).  For example, Margin is found in relation only to TeX
> and LaTex files: nothing ties it to linewidth.
>
> In the last two revisions Lilypond docs have added some excellent, very
> readable explanatory material.  I really like the new versions of the
> first two chapters.  But as someone who's operating under an intense
> time constraint, I also need a How-To section, which should embody the
> FAQs, the examples and samples, the regression tests, and a How-To spin
> on each of the remaining document sections.  Short but complete examples
> are intensely useful.

--
=============================================
        Mats Bengtsson
        Signal Processing
        Signals, Sensors and Systems
        Royal Institute of Technology
        SE-100 44  STOCKHOLM
        Sweden
        Phone: (+46) 8 790 8463                         
        Fax:   (+46) 8 790 7260
        Email: address@hidden
        WWW: http://www.s3.kth.se/~mabe
=============================================