Re: improving the CG

[Trevor Daniels]

Mark Polesky wrote Sunday, December 27, 2009 2:14 AM


> Carl Sorensen wrote:
> > Have you considered whether "Using Git" should be an
> > appendix?  To the extent that it's teaching about git,
> > rather than about LilyPond, it might belong in an
> > appendix.
> >
> > Maybe there should be a chapter called something like
> > "Contributing patches" that mentions all the possible ways
> > of contributing patches, and then appendices describing
> > various ways (diff, git, lilycontrib.tcl).
>
> Okay, I tried revising the structure to accommodate some
> suggestions, but I can't find a way to move the Git stuff to
> an appendix without creating awkward continuity issues.
>
> Because of this, I'd rather keep all the Git stuff together
> in the same chapter (even if some of it isn't LP-specific).

I agree; it should be kept together.

> So, how important is a Git appendix to you guys?  If it's
> important, do you have any suggestions for resolving the
> goose-chase problem?

I'm not very concerned either way.  It could all
be in an appendix with "see App" instructions liberally
scattered or in a self-contained chapter with "skip this
if you know all this stuff" prefixed.

> Furthermore, I prefer the hierarchy of nodes when `Using
> Git' is in its own chapter, ie. I don't want to squeeze all
> of this into a single @unnumberedsubsubsec:

It is better to have a self-contained chapter.  It
is then clearer what to skip or what to refer to as
appropriate.  And nodes at the lowest level enable
more precise cross-references - a big plus.

> Attached is the latest version of the index, hopefully
> you'll see what I mean.  Let me know what you think.

1.2 Beginners start here?
1.3 Experienced developers start here?

I see you still have the Windows section separate.
Is it not feasible to integrate it?  It's only
separate because the early contributions were made
independently.

The rest looks fine.

Trevor