On Sun, Apr 22, 2012 at 12:20 PM, Bruno Haible <br...@clisp.org> wrote: > Hi Paul, > > Thanks for looking into this doc improvement. > > I like the added text to "Target Platforms". > > However, I don't agree to putting the contributor's guide into the manual, > simply because that's not the target audience of the manual. It makes no > sense to me to have instructions for contributors located > - in README-dev for Hello, recutils, > - in README-hacking for Bison, findutils, gzip, idutils, patch, tar,
For findutils this is not the whole story by the way. README-hacking contains the information needed to get findutils git sources to the state expected in README (i.e. the things you need to to to set up a git checkout as if it was an unpacked source tarball). The actual documentation for contributors is in doc/find-main.texi. I did things this way so that the things that contributors need are right there with the source code. This isn't part of the main documentation because the readership is different, as Bruno says. > - in HACKING for Automake, gettext, guile, libtool, m4, Octave, > - in README-hacking and HACKING for Autoconf, coreutils, diffutils, > - in README-hacking and README-prereq and HACKING for grep, > - in README and etc/CONTRIBUTE for Emacs, > - in README.dev for texinfo, > - on the web (http://gcc.gnu.org/contribute.html) for GCC, > - on the web (http://sourceware.org/glibc/wiki/#Development) for glibc, > - and in the manual for gnulib. > > And if it needs to go into the manual, it should be in a separate chapter, > near the end - because it is of zero importance to the majority of the > target audience of the manual. > > The paragraph about the test suite "The goal is to have a 100% firm > interface..." (which you now have duplicated in two places) should IMO > better be split and rewritten to answer two questions: > 1. What does the test suite mean for the users of gnulib? > 2. What does the test suite mean for the contributors to gnulib? > The text for the users goes somewhere in chapter 1, the text for the > contributors is an addendum to the contributor's guide. > > Bruno > > -- -- This email is intended solely for the use of its addressee, sender, and any readers of a mailing list archive in which it happens to appear. If you have received this email in error, please say or type three times, "I believe in the utility of email disclaimers," and then reply to the author correcting any spellings (and, optionally, any incorrect spellings), accompanying these with humorous jests about the author's parentage. If you are not the addressee, you are nevertheless permitted to both copy and forward this email since without such permissions email systems are unable to transmit email to anybody, intended recipient or not. To those still reading by this point, the author would like to apologise for being unable to maintain a consistent level of humour throughout this disclaimer. Contents may settle during transit. Do not feed the animals.
