(sorry, re-sending to list as well)
On Mon, Jan 11, 2010 at 7:23 AM, Mark Polesky <markpole...@yahoo.com> wrote: > Hey everyone. Here's a first draft of my idea for the new > CG chapter 2. Don't use $ in front of examples. It makes it impossible to cut&paste! This is an abomination that probably started in printed manuals (where you'd have to type it in manually anyway), but has *no* business being on any kind of webpage. @example mkdir ~/lilypond-git/; cd ~/lilypond-git/ git init @end example Don't bother quoting the output. > I say "I hope" because I > worry that some of you might think it's too much? Yes and no. I think a fair chunk of it will be wasted effort, but it's *your* effort to waste. As long as 2.1 is easy to find (and it is), and the rest of the chapter is well-organized (and it is), then I have nothing to complain about. 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. As an aside, I've been working on cross-platform python programming (on windows), so I've worked with the git bash shell. Other than extra instructions saying "type this in carefully" or "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!), I'm not certain we need anything different for windows users. Oh, maybe a note explaining the directory/ vs. directory\ - please refer to ~/lilypond-git/ as the SOURCE directory, not BUILD directory. Or maybe "top source directory". If anybody touches the build system, then should be doing an out-of-tree build, in which case ~/lilypond-git definitely isn't the builddir. - editor: please suggest nano instead of emacs. I love vim, I respect and fear emacs, but if somebody doesn't know about unix editors, they should be using pico or nano. - a normal confused user doesn't need to know about .git/config. ok, I know I said that I wouldn't complain, but I am. :) What about adding a @subsubheading Technical details right after the cut&paste "git config --global core.editor pico" line? And do this throughout the manual -- give the command(s) to cut&paste with a minimal explanation, then have the side explanations about .git/config and whatnot after a sign that lets users know they don't need to know everything in that section. - there is no web branch. Well, ok, there is right at the moment, but it's dead. It's not pining for the fjords. Eliminate all mention of this from the new git chapter. - making commits: this section could really benefit from the "short explanation + command, followed by detailed explanation" approach. 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. The TOC looks good, other than slight doubts about 2.6 Repository directory structure, but that's a problem that existed before. I'm thinking about adding a chapter just for building, and maybe that would fit in better in there. I'll get back to you about this. Cheers, - Graham _______________________________________________ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
