Re: contributor/user split in docs

[Carl D. Sorensen]

On 1/1/09 10:26 PM, "Graham Percival" <address@hidden> wrote:

> Hi all,
> 
> While I was working on the new website, I realized that the info I
> was adding would work better as a manual rather than a few web
> pages.  Therefore, in Feb (after 2.13 starts), I'll be creating a
> new manual: the Contributor's Guide.

Great idea!

> 
> (I /was/ going to call it the Developer's Guide, but then I
> realized that "DG" has rather a unfortunate meaning amongst
> computer geeks in my generation, and if my friends heard that I
> was working on the "new DG manual" I'd never live it down. :)
> 
> 
> This will contain the INSTALL docs, doc policy, "working with
> texinfo" stuff, the git guide, info about what all the branches
> are, where to find gub, any potential tips to translators or
> bugfixers, code style, policy for bug reports, checklist for
> normal and major releases, etc.  Generally, I'll be combining all
> the README documents that nobody (including me) looks at and
> putting them all in one place.  I'll also try to write down all
> the `oral tradition' knowledge about lilypond that various people
> have.
> 

I'm currently working on a README for Frogs, so that I can give them
something to get started with.  It would be great in the Contributor's
Guide.

Four things that don't currently exist that ought to go in the Contributor's
Guide:

1) How to make a stable version and a development version coexist on your
machine

2) How to build the code with debug information, and how to use a debugger
with LilyPond

3) How to get LilyPond running and make it pause at a guile prompt so that
you have the full LilyPond guile environment in order to do some exploring
in Scheme

4) A brief overview of how LilyPond processes a file, perhaps extracted from
Erik Sandberg's thesis.
> 
> ... actually, on second thought, perhaps I don't need to wait.  I
> don't think that anything in there should be translated; the
> translators need to read enough English to understand the main
> docs so they should be able to handle their instructions, and (for
> better or worse) we do everything else in English.
> 

I agree with this, but John's opinion is certainly more important than mine.

> John, your opinions as both Translation Guy and the person who'd
> be adding the stubs for this to the build system?  :)
> (starting from next Sep, I should have a linux machine powerful
> enough to build lilypond, so my excuse will be gone.  However,
> until then... ;)

I'm building lilypond on my MacBook; why can't you ;)?

Carl