Re: [Guile-commits] GNU Guile branch, wip-manual-2, updated. release_1-9-9-85-g0a864be

Re: [Guile-commits] GNU Guile branch, wip-manual-2, updated. release_1-9-9-85-g0a864be

[Ludovic Courtès]

Hi Neil,

"Neil Jerram" <neil@ossau.uklinux.net> writes:

>     Improvements to Introduction chapter
>     
>     * doc/ref/intro.texi (Introduction): Change "some" to "the".
>       (Guile and Scheme): "multithreading" -> "multithreaded".
>       (Combining with C): Mention "libguile" as library name.
>       (Guile and the GNU Project): New text.
>       (Interactive Programming): New text.
>       (Supporting Multiple Languages): New text, reflecting currently
>       supported languages.
>       (Obtaining and Installing Guile): Use @var for version placeholder.
>       Remove mention of separate tutorial.

FWIW I really like “Guile and the GNU Project” and “Interactive
Programming”.  I think they concisely convey the GNU vision to provide
software that’s not only released under a free software license (the
legal aspect of freedom) but is also liberating and empowering (the
technical aspect).

Thanks,
Ludo’ (looking forward to having this nice manual on his bookshelf.  :-))

Re: [Guile-commits] GNU Guile branch, wip-manual-2, updated. release_1-9-9-85-g0a864be

[Neil Jerram]

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

> Hi Neil,

Hi Ludo!

> "Neil Jerram" <neil@ossau.uklinux.net> writes:
>
>>     Improvements to Introduction chapter
>>     
>>     * doc/ref/intro.texi (Introduction): Change "some" to "the".
>>       (Guile and Scheme): "multithreading" -> "multithreaded".
>>       (Combining with C): Mention "libguile" as library name.
>>       (Guile and the GNU Project): New text.
>>       (Interactive Programming): New text.
>>       (Supporting Multiple Languages): New text, reflecting currently
>>       supported languages.
>>       (Obtaining and Installing Guile): Use @var for version placeholder.
>>       Remove mention of separate tutorial.
>
> FWIW I really like “Guile and the GNU Project” and “Interactive
> Programming”.  I think they concisely convey the GNU vision to provide
> software that’s not only released under a free software license (the
> legal aspect of freedom) but is also liberating and empowering (the
> technical aspect).

Hey, thanks!  Your feedback is very much appreciated.

I'm not sure if I raised it on the list, but for a while I was worried
about the manual being so big, and I wasn't sure about how to form its
contents into a coherent narrative - or about the extent to which that
matters.

My eventual conclusion from that was that what's really important is to
have a good Introduction chapter.  If the Introduction does a good
enough job of laying out the Big Picture, I think that effectively
_creates_ the narrative for the whole manual, and the job for the rest
of the manual is simplified to making sure that it is complete and
technically correct (and has pleasant smaller-scale structure, of
course).

Hence, that's what I've been focussing on recently in the wip-manual-2
branch.  I'm sure I'm still not getting everything perfect, though, so
please do keep an occasional eye on that branch, and let me know if you
have any developing concerns.  I will merge from master regularly so as
not to miss stuff that's added there, and to avoid building up a
conflict backlog.  Then, hopefully, at a point in the not too distant
future, the manual in wip-manual-2 will be ready for pulling back into
master, and publishing.

<tongue slightly in cheek>

The trouble is, though, when the ground keeps shifting under one's
feet.  Now that multiple language support is really starting to take
off, last night I was thinking that the first sentence "Guile is an
implementation of the Scheme programming language." is probably not the
right first sentence any more...

</>

> Thanks,
> Ludo’ (looking forward to having this nice manual on his bookshelf.  :-))

Me too, and that reminds me that I need to get in touch with Brian to
discuss a new realistic schedule.

Thanks again,

     Neil

Re: [Guile-commits] GNU Guile branch, wip-manual-2, updated. release_1-9-9-85-g0a864be

[Ludovic Courtès]

Hello Neil!

Neil Jerram <neil@ossau.uklinux.net> writes:

> I'm not sure if I raised it on the list, but for a while I was worried
> about the manual being so big, and I wasn't sure about how to form its
> contents into a coherent narrative - or about the extent to which that
> matters.
>
> My eventual conclusion from that was that what's really important is to
> have a good Introduction chapter.  If the Introduction does a good
> enough job of laying out the Big Picture, I think that effectively
> _creates_ the narrative for the whole manual, and the job for the rest
> of the manual is simplified to making sure that it is complete and
> technically correct (and has pleasant smaller-scale structure, of
> course).

Indeed, that makes a lot of sense to me.

> Hence, that's what I've been focussing on recently in the wip-manual-2
> branch.  I'm sure I'm still not getting everything perfect, though, so
> please do keep an occasional eye on that branch, and let me know if you
> have any developing concerns.  I will merge from master regularly so as
> not to miss stuff that's added there, and to avoid building up a
> conflict backlog.  Then, hopefully, at a point in the not too distant
> future, the manual in wip-manual-2 will be ready for pulling back into
> master, and publishing.

Sounds like a nice plan!

> <tongue slightly in cheek>
>
> The trouble is, though, when the ground keeps shifting under one's
> feet.  Now that multiple language support is really starting to take
> off, last night I was thinking that the first sentence "Guile is an
> implementation of the Scheme programming language." is probably not the
> right first sentence any more...

Well, I think it’s still too early to say it’s taking off, especially
since it already took off to a similar extent back in the day, e.g.,
when you were working on elisp in the 1.6 era.  Notably the ES compiler
has yet to be fixed, the elisp one isn’t actually used yet, and
Brainfuck, well...  ;-)

Just to say that we should be careful not to make too broad promises, IMO.

> Me too, and that reminds me that I need to get in touch with Brian to
> discuss a new realistic schedule.

Yes.

Speaking of this, the “standard library” section needs to be improved,
particularly the SXML sections, which look poor to me.

Thanks,
Ludo’.

Re: [Guile-commits] GNU Guile branch, wip-manual-2, updated. release_1-9-9-85-g0a864be

[Andy Wingo]

Hi Neil,

I also think that wip-manual-2 is looking great! Your commit granularity
is also really nice.

On Mon 12 Apr 2010 02:15, Neil Jerram <neil@ossau.uklinux.net> writes:

> at a point in the not too distant future, the manual in wip-manual-2
> will be ready for pulling back into master, and publishing.

From my perspective each commit is ready! Why not just merge now? It's
getting monotonically better :)

That way when someone writes new docs, they have a better idea about how
that fits in. For example I need to write something about "nil", and
I'll look at your branch and see where you're going, but if it were
merged already I could just look at the state of master and see where
the right place would be.

> Now that multiple language support is really starting to take off,
> last night I was thinking that the first sentence "Guile is an
> implementation of the Scheme programming language." is probably not
> the right first sentence any more...
>
> </tongue-in-cheek>

I still think it's the right statement to make :) Guile _is_ and _has_
other things as well, but fundamentally it's a Scheme. IMO at least :)

Happy hacking!

Andy
-- 
http://wingolog.org/

Re: [Guile-commits] GNU Guile branch, wip-manual-2, updated. release_1-9-9-85-g0a864be

[Neil Jerram]

Andy Wingo <wingo@pobox.com> writes:

> Hi Neil,

Hi Andy,

> I also think that wip-manual-2 is looking great! Your commit granularity
> is also really nice.

Thanks.

>>From my perspective each commit is ready! Why not just merge now? It's
> getting monotonically better :)

OK, I'll do that; thanks for the suggestion.  For the sake of
explanation: I guess when I started wip-manual-2 I wasn't totally sure
that my direction was correct, or that it would meet with approval.  But
given that it does, I agree that it makes sense now to continue in
master.

> That way when someone writes new docs, they have a better idea about how
> that fits in. For example I need to write something about "nil", and
> I'll look at your branch and see where you're going, but if it were
> merged already I could just look at the state of master and see where
> the right place would be.

Yes, absolutely.

> I still think it's the right statement to make :) Guile _is_ and _has_
> other things as well, but fundamentally it's a Scheme. IMO at least :)

Agreed.  Historically and philosophically that's clearly true.  And from
a practical point of view, however many other languages we support,
Scheme will always remain special because the compiler itself is written
in Scheme.

Regards,
      Neil