Re: CG chapter 2, first draft

[Mark Polesky]

Graham Percival wrote:
> Don't use $ in front of examples.  It makes it impossible
> to cut&paste!

Well, not impossible.  Besides, it's good to differentiate
the input from the output when quoting the output.

> Don't bother quoting the output.

Right.

> I think a fair chunk of it will be wasted effort, but it's
> *your* effort to waste.

Geez, Graham, sometimes I wish you *would* mince a few words
from time to time!  I don't think it's a waste at all.  I
remember wasting so much time just trying to figure out how
to exit the commit message without killing the whole shell:

http://lists.gnu.org/archive/html/lilypond-devel/2009-05/msg00365.html

And then half a year later, Trevor D. went through the exact same
thing:

http://lists.gnu.org/archive/html/lilypond-devel/2009-12/msg00011.html

*That's* where the waste is.  The intent of my revisions is
to prevent these stupid traps for the next generation of
contributors.  Get them up and running as painlessly as
possible.

> That said, a few more comments: - if you're going to go to
> all this effort, please eliminate the "git on windows"
> section -- for each portion of the (unix-aimed) docs, just
> dump the relevant windows instructions on the bottom of
> the page.

I'm considering it.  This is still a work-in-progress.

> ..."here's how to paste to a git bash window" (I don't
> remember if _that_ was hard, but cutting&pasting to/from a
> cygwin window is a nightmare!)

Now that I'm back home I don't have access to a Schmindows
machine, so I forget the details.  But I do remember it
being a pain.  Something like

1) Right-click on the title-bar of the Git Bash window
2) Select Edit > Mark
3) Left-click and drag your selection.
4) Press enter to copy it to the clipboard.

Ugh.  Something terrible like that.  Trevor, if you have
some time, could you write a line or two about this sort of
thing?  I'm not done with the CG, so I'll find a place to
put it.  Also, Trevor: changing the editor on Windows with
`git config', ie. without troubling with environment
variables---is it as simple as doing this?

git config --global core.editor wordpad

I doubt it.  But let me know if you have any insights.

> Oh, maybe a note explaining the directory/ vs. directory\

I seem to recall Git bash fixed those automatically.  Don't
remember.  Trevor?

> - please refer to ~/lilypond-git/ as the SOURCE directory,
> not BUILD directory.  Or maybe "top source directory".

Of the two, I prefer "top...".

> - editor: please suggest nano instead of emacs.

I wasn't explicitly suggesting emacs, though I suppose it
might have looked that way.  I don't really care one way or
the other; I changed it to nano.

> What about adding a
> @subsubheading Technical details

Not a bad idea.

> - there is no web branch.  Well, ok, there is right at the
> moment, but it's dead.  It's not pining for the fjords.

It's bleedin' demised.

> In fact, when I unfocus my eyes and skim over the section
> (the usual way I read computer docs), I don't notice any
> git commit -a at all.

Hmm.  I tried putting @example's within the @item's, but I
don't know if I like that better.  What do you think?

I've attached the latest revision.
- Mark

p.s. are files that start with a period hidden on Windows
like they are on Unix?

working.itexi
Description: Binary data