Re: [PATCH] Docs: resolve some FIXMEs in tutorial.

[Graham Percival]

On Mon, Dec 14, 2009 at 01:04:00AM -0800, Mark Polesky wrote:
> I assume this is okay to apply?

No; remember that some people skip over "intermediate" sections.

>  @node Compiling a file
>  @section Compiling a file
>  
> -FIXME: insert text
> +This section introduces @qq{compiling}---the processing of
> +LilyPond input files (written by you) to produce output files.
> +Output files are generally PDF (for printing or viewing), MIDI
> +(for playing), and PNG (for online use).

I'm not totally opposed to this...

>  @menu
>  * Entering input::              
> @@ -40,10 +43,7 @@ FIXME: insert text
>  @cindex example, first
>  @cindex case sensitive
>  
> address@hidden is the term used for processing an input file in
> -LilyPond format to produce output file(s).  Output files are
> -generally PDF (for printing or viewing), MIDI (for playing), and
> -PNG (for online use).  LilyPond input files are simple text files.
> +LilyPond input files are simple text files.

... but the description of compiling must stay here.  At the
beginning of this subsection, we must assume that the reader
doesn't know anything.

Of course, people reading the pdf _will_ see both pieces of text,
so a complete copy might look a bit weird.  And since this is the
very beginning of the documentation (other than _Text input_ in
web), I'd rather not have weirdness.

So could you just write some fluff for the text at the @section
level?

> @@ -334,7 +334,8 @@ You may view or print the resulting @file{text.pdf}.
>  @node How to write input files
>  @section How to write input files
>  
> -FIXME: insert text
> +This section introduces some basic LilyPond syntax to help get you
> +started writing input files.

That's great.

>  @menu
>  * Simple notation::             
> @@ -728,7 +729,9 @@ comments:
>  @node How to read the manuals
>  @section How to read the manuals
>  
> -FIXME: fluff here
> +This section shows how to read the documentation efficiently, and
> +also introduces some useful interactive features available in the
> +online version.

This is also great.

Cheers,
- Graham