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

[Neil Jerram <neil@ossau.uklinux.net>]

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