Re: [frogs] CG chapter 3, first draft

[Graham Percival <graham@xxxxxxxxxxxxxxxxx>]

On Fri, Jan 22, 2010 at 8:10 PM, Graham Percival
<graham@xxxxxxxxxxxxxxxxx> wrote:
> On Fri, Jan 22, 2010 at 4:36 AM, Mark Polesky <markpolesky@xxxxxxxxx> wrote:
>> Graham Percival wrote:
>>> Similarly, let's stop talking about g++ 3.4; just say 4.0
>>> or higher.... I mean, if somebody complains that it
>>> doesn't work in 3.4, we're (probably) not going to
>>> actually fix that.
>>
>> Not done.  I met with some resistance on -devel.  Feel free
>> to step in there.
>> http://lists.gnu.org/archive/html/lilypond-devel/2010-01/msg00499.html
>
> Me?  I don't know how this stuff works.  Go with whatever Patrick says.
>
>>> It would be *really* nice if we stopped telling people to
>>> look at input/regression/utf-8.ly for hints about fonts,
>>> and had that info in the install chapter directly.
>>
>> Done.  But---what's the RPM equivalent of "apt-get install"?
>
> Depends on the distro.  Everybody has their own.  Just list the
> package names; anybody fussing with this stuff should be able to
> figure it out, anyway.
>
>>> 3.3
>>>
>>> Don't tell people about the source snapshot.
>>
>> Hmm.  Certainly some readers might be curious to see the
>> snapshot without bothering with Git.  I don't think that
>> including a quick link to it is going to harm anybody.  How
>> strongly do you feel about this?  I kind of like it there.
>
> I strongly feel that I will (continue to) get royally pissed off when
> we receive emails saying "random
> snapshop-a785b67c4g6d56ef675eedc86c86e.tar.bz2 doesn't work!"
> (for bonus marks, find the illegal character in the above string)
>
> If somebody discovers the snapshot link on their own, fine.  But
> having a link in the CG seems to be asking for trouble.  Packagers
> should work from compilable-tarballs (at least compilable on linux);
> developers should work from git (so they can get easy bugfixes).
> Snapshots combine the worst of both worlds, with none of the benefits.
>
> If you still really want to have the link there, fine, but when
> somebody runs into trouble with a snapshot, I'm going to take it out
> on them.  IMO, one of the implied trade-offs of yelling at people for
> doing stupid things is that the docs should be written so that it's
> very hard to do stupid things.
>
> Having "use at your own risk" isn't sufficient discouragement, IMO.
>
>
> BTW, why use that gunzip command?  Just use
>  tar -xj
>
>>> Who's going to update the list of generated files whenever
>>> they change?  Also, I don't believe that autogen.sh
>>> creates an out/ dir.
>>>
>>> I'd rather just say that it creates a number of files and
>>> directories to aid configuration (or something like that).
>>
>> Done.
>>
>>> as Carl or John already pointed out, you don't need to run
>>> ./configure if you run ./autogen.sh.
>>
>> Okay, I changed "you need to run" to "you should run".
>>
>>> BTW, ./configure is *known* to not check all doc
>>> requirements.  A warning here would definitely be
>>> appropriate.
>>
>> Which doc requirements does it not check?  I know that
>> ./configure doesn't issue an ERROR when missing a doc
>> requirement, but it was my assumption that it should issue a
>> WARNING.  This much is clear in the text (I thought), so let
>> me know what I'm missing.
>>
>>> Changing the install directory doesn't force a full
>>> recompile, so changing the --prefix after compiling isn't
>>> a big deal.
>>
>> Okay, I removed the portentous sentence.
>>
>>> You also don't need to create the directory; as long as
>>> you have write permission to the higher directory, make
>>> install will create the install dir just fine.
>>
>> Hmm.  I didn't think the paragraph implies that the directory
>> needs to exist.  Should I add "(or within)" like this?
>>
>>  `make install' will only succeed if the installation
>>  prefix points to (or within) a directory where you have
>>  write permission (such as your home directory).
>>
>>> The technical term for separate build directory is
>>> "out-of-tree build".  Note that in some cases, you'll need
>>> to run make distclean in the main source dir before you
>>> can successfully do the out-of-tree configure and make.
>>
>> Okay, I added a note about it.
>>
>>> I'd put ./configure --help at the top of this subsection.
>>
>> Done.
>>
>>> 3.5.1
>>>
>>> You don't need to run "make clean" unless you specifically
>>> want to.  If the build system worked perfectly, you'd
>>> *never* need to run make clean.  As it is, "make clean" is
>>> only needed once every 2-3 months (from empirical
>>> evidence).
>>
>> Oh.  I must have over-interpreted this post of yours:
>> http://lists.gnu.org/archive/html/lilypond-devel/2009-12/msg00496.html
>>
>>> I'd mention -jX somewhere, since that's a very
>>> commonly-used and desired option, with most people having
>>> 2 or 4 cores.
>>
>> You mean specifically for `make' and not `make doc'?  If so,
>> could you write a little paragraph?  I don't really know how
>> it works.  I added a node.
>>
>>> 3.6.2
>>>
>>> sweet mao, we don't want people running doc-clean!!!
>>
>> Why not?  You make it sound like there's something I don't
>> know.  Something that should be mentioned, perhaps...
>>
>>> I wouldn't bother mentioning info.  If somebody wants to
>>> trawl through the make targets, they'll find it... but
>>> really, who on earth wants info?
>>
>> Apparently John does; he's the one who wrote it:
>> http://git.savannah.gnu.org/gitweb/?p=lilypond.git;h=0c9af42
>>
>>> I'd put the -j3 CPU_COUNT=3 earlier in the section.
>>> Again, it's getting more and more useful with the
>>> direction that cpu manufacturers are going.
>>
>> Done.
>>
>> Thanks for your input.  Looking forward to more!
>> - Mark
>>
>>
>>
>>
>

---
----
Join the Frogs!