Re: CG chapter 2, first draft

[Graham Percival]

On Tue, Jan 12, 2010 at 4:03 AM, Mark Polesky <address@hidden> wrote:
> Graham Percival wrote:

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

Ok.  I suggest dropping the "sometimes"; let's make sure it's *always*
referred to as the "top source directory".  Even if people never get
start touching the build system, using the exact term won't hurt.

>> - 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.

Whenever I don't know what I'm doing, if I see a command-line I'll try
a cut&paste.  As such, having "emacs" in the @example qualified as
"suggesting".  Thanks for changing it.  :)


>> What about adding a
>> @subsubheading Technical details
>
> Not a bad idea.

It's looking good.

>> 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?

It's more visible, thanks.

> I've attached the latest revision.

- linux package managers: it won't always be called "git-core".  Just
say that they need to install git, and add a warning that most
distributions call it "git-core" due to a naming clash.
(with GNU Interactive Tools)

- I'd personally use @var{branch-name} instead of @q, but I don't have
any particularly compelling reason to do so.

- if you want some extra work (and who doesn't?!), consider looking
for Jan's git setup.  He does something like setting up an alias of
"gnu" for git://git.svn.gnu.org/ so his download location is something
like gnu:lilypond.git/

I only mention it because I see the long lines broken with \
It would be nice if we didn't have to do that... but this is a fairly
minor issue.  And the argument against this proposal is that if
somebody skips over the updated "configuring git" step, they'd be
screwed when they get to "downloading individual branches".

- let's say "10 minutes" instead of "three and a half minutes"; that
way, we're safer if somebody has a slow connection, and if it finished
in three minutes, they'll feel special because their connection is
faster than ours.  :)

- good job having the warning about git's misleading warnings about
the branch yet to be born; now that I see them again, I remember the
fear and loathing it produces.

- I suggest "When developers push new patches to the git.sv.gnu.org
repository" -> "When the git.sv.gnu.org repository is updated,".  I
think the term "push" is a bit confusing at this stage -- the
important fact to get across is that their local copy is *not* updated
when the shared copy is changed.
It's probably worth using a @strong{not} in there, since this has
really tripped up at least 2 contributors in the past 6 months.

- I'd rather have the instructions for git rebase -r # for master
first, since most people (well, over 50%) aren't translators.  I see
why you didn't, though, and if you'd rather keep it that way, I won't
complain again.

- I'm not wild about the branch.master.rebase true  command.  I mean,
if we always want to rebase on master, then why not put this in the
earlier "configuring git" section?
Actually, since we want (I think?) to rebase for everything *other*
than the translations, can't we make "rebase true" for the default
settings, then override them with a "branch.translations rebase false"
command?
...
I still don't understand the warning about comittishes and
translations and doc editors.  But that's not your problem.
...
I see that "git pull --no-rebase" overrides the default settings, so
it should be safe to make "rebase true" in the .git/config, and let
people doing the weird doc+translation-editing-on-master thing add
--no-rebase to their git command manually.  AFAIK, John, Carl, and
Neil are the only people who have ever done this.

- The section "making commits" has tons of info... could the git log
stuff go in the technical details?
Hmm.  Even after that, the section still looks a bit overwhelming, but
I can't immediately see what else to suggest.

- git format-patch origin   looks right to me.


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

I think are within the cygwin window and bash window, but I don't know
if they're hidden in the normal cmd window.

Cheers,
- Graham