who wrote the manual?

who wrote the manual?

[Andy Wingo]

Hi,

I was looking at the manual preface, and it says, quote:

    The Guile reference and tutorial manuals were written and edited
    largely by Mark Galassi and Jim Blandy.  In particular, Jim wrote
    the original tutorial on Guile's data representation and the C API
    for accessing Guile objects.

But that sounds old. I cloned git://git.lwn.net/gitdm.git, and now we
see that:

    ~/src/guile$ git log -p -M doc | ../gitdm/gitdm -c /dev/null
    Grabbing changesets...done       
    Processed 1515 csets from 26 developers
    33 employers found
    A total of 214004 lines added, 117077 removed (delta 96927)

    [...]

    Developers with the most changed lines
    Neil Jerram               100687 (36.2%)
    Marius Vollmer            38745 (13.9%)
    Martin Grabmüller        16468 (5.9%)
    Andy Wingo                13156 (4.7%)
    Thien-Thi Nguyen          11676 (4.2%)
    Kevin Ryde                10417 (3.7%)
    Jim Blandy                8589 (3.1%)
    Ludovic Courtes           7979 (2.9%)
    Ludovic Courtès          4252 (1.5%)
    Julian Graham             3129 (1.1%)
    Rob Browning              2363 (0.8%)
    Mikael Djurfeldt          1790 (0.6%)
    Gary Houston              1605 (0.6%)
    Michael Gran              1368 (0.5%)
    Han-Wen Nienhuys          1221 (0.4%)
    Brian Gough               1024 (0.4%)
    Keisuke Nishida            603 (0.2%)
    Andreas Rottmann           342 (0.1%)
    Dirk Herrmann              247 (0.1%)
    Ken Raeburn                 50 (0.0%)
    No Itisnt                   42 (0.0%)
    Stefan Jahn                 27 (0.0%)
    Daniel Kraft                17 (0.0%)
    Greg J. Badros              10 (0.0%)
    Jose A. Ortega Ruiz          8 (0.0%)
    Michael Livshin              4 (0.0%)

Assuming that changed lines is the real measure of committing to the
manual, we can fairly say that Neil wrote the manual, with important
contributions from Marius on down. If we place the cutoff at 1% (and
that's totally arbitrary), we can mention 8 more names, which is plenty
for a preface, no?

But where is Mark Galassi in all of that, I wonder...

Andy
-- 
http://wingolog.org/

Re: who wrote the manual?

[Ludovic Courtès]

Hi!

Andy Wingo <wingo@pobox.com> writes:

> Assuming that changed lines is the real measure of committing to the
> manual, we can fairly say that Neil wrote the manual, with important
> contributions from Marius on down. If we place the cutoff at 1% (and
> that's totally arbitrary), we can mention 8 more names, which is plenty
> for a preface, no?

Fine with me.

And kudos to Neil, I think we owe him a great debt!

Ludo’.

Re: who wrote the manual?

[Andy Wingo]

On Mon 11 Oct 2010 22:16, ludo@gnu.org (Ludovic Courtès) writes:

> And kudos to Neil, I think we owe him a great debt!

Indeed, and it's ongoing :)

Here is what I put into preface.texi. Feel free to criticize or, better
yet, fix directly :)

  Like Guile itself, the Guile reference manual is a living entity, cared
  for by many people over a long period of time.  As such, it is hard to
  identify individuals of whom to say ``yes, this person, she wrote the
  manual.''

  Still, among the many contributions, some caretakers stand out.  First
  among them is Neil Jerram, who has been working on this document for ten
  years now.  Neil's attention both to detail and to the big picture have
  made a real difference in the understanding of a generation of Guile
  hackers.

  Next we should note Marius Vollmer's effect on this document.  Marius
  maintained Guile during a period in which Guile's API was
  clarified---put to the fire, so to speak---and he had the good sense to
  effect the same change on the manual.

  Martin Grabmueller made substantial contributions throughout the manual
  in preparation for the Guile 1.6 release, including filling out a lot of
  the documentation of Scheme data types, control mechanisms and
  procedures.  In addition, he wrote the documentation for Guile's SRFI
  modules and modules associated with the Guile REPL.

  Ludovic Courtès and Andy Wingo, the Guile maintainers at the time of
  this writing (late 2010), have also made their dent in the manual,
  writing documentation for new modules and subsystems in Guile 2.0.  They
  are also responsible for ensuring that the existing text retains its
  relevance as Guile evolves.  @xref{Reporting Bugs}, for more information
  on reporting problems in this manual.

  The content for the first versions of this manual incorporated and was
  inspired by documents from Aubrey Jaffer, author of the SCM system on
  which Guile was based, and from Thomas Lord, Guile's first maintainer.
  Although most of this text has been rewritten, all of it was important,
  and some of the structure remains.

  The first versions of the first versions of Guile were written and
  edited largely by Mark Galassi and Jim Blandy.  In particular, Jim wrote
  the original tutorial on Guile's data representation and the C API for
  accessing Guile objects.

  Significant portions were also contributed by Thien-Thi Nguyen, Kevin
  Ryde, Mikael Djurfeldt, Christian Lynbech, Julian Graham, Gary Houston,
  Tim Pierce, and a few dozen more.  You, reader, are most welcome to join
  their esteemed ranks.  Visit Guile's web site at
  @uref{http://www.gnu.org/software/guile/} to find out how to get
  involved.



-- 
http://wingolog.org/

Re: who wrote the manual?

[Ludovic Courtès]

Hi Andy,

Andy Wingo <wingo@pobox.com> writes:

> Here is what I put into preface.texi. Feel free to criticize or, better
> yet, fix directly :)

Nice text, and pleasant writing style as usual!

Ludo’.

Re: who wrote the manual?

[Neil Jerram]

ludo@gnu.org (Ludovic Courtès) writes:

> Hi Andy,
>
> Andy Wingo <wingo@pobox.com> writes:
>
>> Here is what I put into preface.texi. Feel free to criticize or, better
>> yet, fix directly :)
>
> Nice text, and pleasant writing style as usual!

Agreed, that's nice, and I think fair.  Thanks,

        Neil

Re: who wrote the manual?

[Mike Gran]

> But where is Mark Galassi in all of that, I wonder...

You can see the last version of the Guile manual that he
wrote on his page at http://www.galassi.org/mark/mydocs/

Regards,

Mike Gran

Re: who wrote the manual?

[Neil Jerram]

Andy Wingo <wingo@pobox.com> writes:

>     Developers with the most changed lines
>     Neil Jerram               100687 (36.2%)

Quick, publish now before that changes!  :-)

> Assuming that changed lines is the real measure of committing to the
> manual, we can fairly say that Neil wrote the manual, with important
> contributions from Marius on down. If we place the cutoff at 1% (and
> that's totally arbitrary), we can mention 8 more names, which is plenty
> for a preface, no?

Seriously, this is a hard question.  Although Marius and I have written
a lot of new material, I'd say that our percentages are over-represented
because of the amount of large scale reorganization that we've done.  (I
believe that if you just move 100 lines from A to B, Git will count that
as 100 additions and 100 deletions.)

Also supporting that, there was a great deal of manual already in
existence when I first started contributing to it (around 1998).

That then means that the top contributions are not as dominant as they
first look, and so maybe it's less fair to exclude people below some
arbitrary cutoff.  In any case, perhaps we could list all of those names
in an Acknowledgements section, even if we decide to have a limited
subset upfront.

> But where is Mark Galassi in all of that, I wonder...

I'm afraid I don't know.  Although I'm familiar with his name, I believe
his main involvement was before my time.  I've internalised the text you
quoted about Mark writing the manual originally, and surely there must
be some substance to it - but I don't have more detail than that.

But I have a feeling (somehow) that Mark still follows the list
occasionally - so hopefully he may respond himself.

Regards,
        Neil

Re: who wrote the manual?

[Andy Wingo]

On Mon 11 Oct 2010 23:30, Neil Jerram <neil@ossau.uklinux.net> writes:

>> Assuming that changed lines is the real measure of committing to the
>> manual
>
> Seriously, this is a hard question.

Yeah, agreed, and agreed regarding the reorganization points; but still,
the general gist is right, and reorganization is sometimes almost as
much work as writing :P

I know you've seen the other mail with the text. I fixed a couple typos
in git but it's pretty much the same; I think I kept everyone's names in
there. But if you think the tack of the text isn't right, please let me
know or otherwise fix it. I think it reflects reality better, but I'm
very happy to defer to you in any aspect that you choose :)

Peace,

A
-- 
http://wingolog.org/