Re: [frogs] CG chapter 3, first draft

[Graham Percival <graham@xxxxxxxxxxxxxxxxx>]

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!