Re: contributors manual

[Graham Percival]

On Mon, May 17, 2010 at 04:03:11AM -0600, Carl Sorensen wrote:
> 
> On 5/16/10 6:12 PM, "Mark Polesky" <address@hidden> wrote:
> 
> > Graham Percival wrote:
> >> A larger question is whether we should keep "3.6
> >> Post-installation options".  In the first place, the word
> >> "options" implies (to me) something akin to configuration
> >> options, not "a list of possible commands" (which is the
> >> meaning used here).
> > 
> > How about restructuring the nodes like this (note that I
> > renamed some node names here):
> > 
> > 3. Compiling LilyPond
> >    3.1 Overview of compiling
> >    3.2 Requirements
> >    3.3 Getting the source code

I'm not 100% certain that we need this at all.  (then again, I'm
not 100% certain that we *don't* need it)

if somebody's looking at the CG, they'll already have access to
CG 2, and anybody wanting to compile lilypond won't be so
abysmally stupid as to think they can compile it without the
source, and CG 2 is easy to find.

if they're looking at it via the INSTALL.txt file, then they're
already staring at the source code


now, it wouldn't be good to lose the info about the tarball
version archive, but that could probably live in CG 2.

> >    3.4 Configuring make
> >    3.5 Compiling
> >    3.6 Installing and testing
> >        3.6.1 Installing from a local build
> >        3.6.2 Testing

See below about testing.

> >    3.7 Generating documentation
> >        3.7.1 Documentation editor's edit/compile cycle
> >        3.7.2 Building documentation
> >        3.7.3 Saving time with CPU_COUNT
> >        3.7.4 Installing documentation
> >        3.7.5 Building documentation without compiling

I think this works best as a separate section, but see below about
CG 2 vs. the doc chapter.

> >    3.8 Problems
> > 
> >    etc.

If we're having a serious discussion about this chapter, then I
don't like the "etc".  These are obviously tacked on to the end of
this chapter as a quick "dump this somewhere before we forget
about the info"; if we're seriously working on CG 3, then we
should deal with them properly.


> >> Second, it might be easier to find relevant material if we
> >> just kept 3.6.1 Installing from a local build, and moved
> >> the doc-material to the Doc chapter, and the regrest
> >> material to the Regression chapter.
>
> > I don't think we should burden the Doc chapter with the
> > business of building docs.  I see the Doc chapter as being
> > accessible to contributors who won't be compiling.

That's actually a reason in favor of moving the doc-building stuff
*out* of chapter 2 -- the "building the docs without compiling"
would be more visible to them.
 
> For my money, I think we should have the regression test stuff
> in the regression test chapter.  I consider the regression test
> to be completely separate from installation.

In practice, yes.

> There's no need to run the regression tests to verify an
> installation.  Any test file will do, IMO.

Well, not quite.  "any test file" won't necessarily include utf-8
lyrics.  It might not include embedded postscript.  Etc.  I could
well imagine a package builder wanting to test his package (on
mipsel? :)  before distributing it.

However, that could be easily covered by leaving a link from the
"compiling" chapter to the relevant part of the "regression tests"
chapter.

Cheers,
- Graham