Okay...
I'll just show you what I was thinking. I know this looks
like a lot of work, but most of it would be shuffling stuff
around to have a more logical order of presentation, and a
more organized structure to facilitate referring to
specifics.
Some of it would entail adding text, but I'd be the one
doing it, so the only issue would be if you think it burdens
the reader. Personally, I don't like it too short and
sweet, because currently I think too much is assumed of the
reader.
I suppose my particular perspective here is as a recent
Windows user compiling LilyPond on Linux. The clarity I'd
like to bring to this manual shouldn't detract from its
value. I think I would've been developing a lot sooner if
it had been organized this way, but obviously, share with me
your reactions.
The changes I'd like to make would affect CG 1 and 2 only.
The current CG sections 3-9 (from "Documentation work" to
"Release work") would remain untouched, only the numbering
would change.
I've attached two text files. The first is a proposed
reorganization of the material in the form of an index (with
current node numbers annotated down the right side). The
second is my proposal for an `Introduction to LilyPond
development'. Here's a less detailed version of the index
included in the attachment:
1. Introduction to LilyPond development
2. Obtaining a LilyPond repository
2.1 Starting with Git
2.2 Initializing Git branches
3. Developing without compiling
3.1 Basic procedures
3.2 Advanced procedures
3.3 Git on Windows
3.4 Repository directory structure
3.5 Other Git documentation
4. Compiling
4.1 Installing build dependencies
4.2 Configuring `make'
4.3 Compiling LilyPond
4.4 Tasks requiring a successful compile
4.5 Concurrent Stable and Development Versions
4.5 Compiling on Windows
5. Documentation work
6. Website work
7. LSR work
8. Issues
9. Regression tests
10. Programming work
11. Release work
A. GNU Free Documentation License
Let me know what you think.
Thanks
- Mark
LilyPond Contributor's Guide: proposed revised structure
1. Introduction to LilyPond development
2. Obtaining a LilyPond repository
2.1 Starting with Git
2.1.1 Installing Git
2.1.2 Initializing a repository
2.1.3 Configuring Git
* Global settings (1.1.2)
* Repository settings
2.2 Initializing Git branches
2.2.1 LilyPond repository sources (1.1.6)
2.2.2 The `master' branch (1.1.3)
2.2.3 The `lilypond/translation' branch (1.1.4)
2.2.4 Other branches (1.1.5)
3. Developing without compiling
3.1 Basic procedures
3.1.1 Staying current
* Pulling (1.2.1, .2)
* Resolving conflicts (1.2.3)
3.1.2 Working with branches (1.4.2)
* Creating and removing branches
* Listing branches
* Checking out branches
* Merging branches
3.1.3 Modifying source files
* Making commits
* Formatting patches (1.3.1)
3.2 Advanced procedures
3.2.1 Working with remote branches (1.4.3)
3.2.2 Git log (1.4.4)
3.2.3 Applying remote patches (1.4.5)
3.2.4 Pushing to git.sv.gnu.org (1.3.2)
3.3 Git on Windows
3.4 Repository directory structure (1.7)
3.5 Other Git documentation (1.6)
4. Compiling
4.1 Installing build dependencies (2.1.2)
4.1.1 Using `build-dep'
4.1.2 Requirements for compiling LilyPond
4.1.3 Requirements for running LilyPond
4.1.4 Requirements for building documentation
4.2 Configuring `make'
4.2.1 Creating generated files (2.1.1)
4.2.1 Running ./configure (2.1.3)
* Configuring target directories
* Configuring for multiple platforms
4.3 Compiling LilyPond
4.3.1 Using make (2.1.3)
4.4 Tasks requiring a successful compile
4.4.1 Installing LilyPond (2.1.3)
4.4.2 Generating documentation (2.1.4)
* Building documentation
* Installing documentation
* Building documentation without compiling
4.4.3 Testing LilyPond (2.1.5)
4.5 Concurrent Stable and Development Versions (2.2)
4.5 Compiling on Windows (2.3)
5. Documentation work (3)
6. Website work (4)
7. LSR work (5)
8. Issues (6)
9. Regression tests (7)
10. Programming work (8)
11. Release work (9)
A. GNU Free Documentation License (A)
LilyPond Contributor's Guide: proposed addition
"Introduction to LilyPond Development"
Before you start developing, it will be helpful to
understand a few basic concepts related to LilyPond
development.
The LilyPond source code is maintained as a Git repository.
A LilyPond Git repository is a directory which contains:
1) all of the source files needed to build LilyPond, and
2) a `.git' directory which is used by the git program to
keep track of the data and the changes made over time.
The `official' LilyPond Git repository is hosted by the GNU
project at git.savannah.gnu.org (note that shortened form
git.sv.gnu.org resolves to the same host). However, since
Git uses a `distributed' model, technically there is no
central repository. Each contributor has a complete copy of
the entire repository (about 116M). Changes made within one
contributor's copy of the repository can be shared with
other contributors using `patches'.
A `patch' is a simple text file generated by the git program
that indicates what changes have been made (using a special
format). If a contributor's patch is approved for inclusion
(usually through the mailing list), someone on the current
development team will `apply' the patch to the official
repository.
A Git repository can be used to build (`compile') the entire
program, but it is not strictly necessary---LilyPond can be
compiled from a downloaded tarball instead. Tarballs are
useful if you want to install the program from source files
but you don't want to do any developing.
However, a Git repository is needed to produce patches and
contribute to LilyPond development. And even with your own
Git repository, you may choose not to compile LilyPond at
all. In fact, compiling LilyPond is a rather involved
process, and many development tasks do not require it.
However, if you wish to see the effect of your changes on
the program itself, you will need to compile it.
To put it simply, if you only want to use the program, you
only need to *install* it. If you want to modify source
files and create patches for development, you only need a
Git repository (technically you don't even need an installed
copy of the program, but it helps). If you want modify
source files *and* see how your changes affect the finished
product, then you'll need a Git repository *and* you'll need
to compile the program on your own.
_______________________________________________
lilypond-devel mailing list
lilypond-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-devel
