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

[ludo@gnu.org (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’.