Re: [PATCH] Doc: CG: add lily-git instructions.

[Graham Percival]

On Tue, Feb 16, 2010 at 10:16:11AM -0800, Mark Polesky wrote:
>  
> +The lily-git script is located at

> address@hidden://git.sv.gnu.org/cgit/lilypond.git/plain/scripts/auxiliar/lily-git.tcl}.

Could this be inside an @example ?

> +Using a web browser (or @command{wget}), save the page as
> address@hidden

I'd rather not confuse people with wget.  I'd just write:

-----
Download the lily-git script from:

@example
@uref{http://git.sv.gnu.org/cgit/lilypond.git/plain/scripts/auxiliar/lily-git.tcl}.
@end example
-----

if somebody wants to download it with smoke signals, more power to
them.

> +To run the program from the command line, navigate to the
> +directory containing @file{lily-git.tcl} and enter:
> +
> address@hidden
> +wish lily-git.tcl &
> address@hidden example

I'd omit the & -- again, let's try to avoid confusing windows
users.  Unix people know how to add & if they want it.  If
somebody on windows wants to know how to run the command and still
be able to use that particular terminal, they can ask their
mentor.

Based on my experience in teaching programming to newbies, I don't
want to underestimate the cognitive load of looking for an
unfamiliar character on a keyboard.

(yes, cue snarky comments about how bad the younger generation is.
But it's the younger generation of Canadians *and* Scots that seem
to get thrown for a loop trying to find the ; symbol on their
keyboard.  :(


> address@hidden The @qq{Get source} button

Could this be
    @subsubheading Get source / Update source
?  I'd like to have the second label in there as well... also, I
think the double-quotes and "The button" are unnecessary.

> address@hidden The @qq{Make patch set} button
> +
> address@hidden making a patch set from any commits, you should
> +click the @qq{Update source} button to make sure the commits are
> +based on the most recent remote snapshot.}

I'd rather not use a @warning here; we should reserve them for
only truly vital things.  Plain text should be sufficient.

> address@hidden The @qq{Abort changes -- Reset to origin} button
> +
> address@hidden use this if your local commit history gets

hopelessly confused, or under the direction of your mentor!}



Looks great!  If you agree with those comments, please change and
then push.  If you disagree with them, go ahead and push anyway
(it's definitely good enough to get into git), and we can continue
talking.  :)

Cheers,
- Graham