Publishing the manual...

Publishing the manual...

[Neil Jerram]

I should let you all know that Brian Gough has approached me about
publishing the Guile manual.

Brian is a fairly well known person in the GNU project; for example he
organised a GNU Hackers Meeting that I attended last year in Bristol,
and he's worked for some time on the GNU Scientific Library.

He also works for Network Theory (http://www.network-theory.co.uk/),
who publish books about free software, and it's obviously in that
context that he's interested in publishing our manual.

I've agreed in principle, and we're looking at doing this after the
2.0 release, so that the published manual can include all the exciting
new things that will be in 2.0.

As Ludovic recently noted, the manual currently runs to about 650
pages.  I was concerned that that would be too much for a manageable
book, but by way of comparison I checked a copy of O'Reilly's The
Python Programming Language - and that's around 1200 pages, and still
a lot thinner than (e.g.) the last Harry Potter book.  So now I think
that 650 is fine, and that there's even room for further expansion if
we need it.

I had a flick through last night.  While the vast majority of the
manual material is useful and correct, I'm not sure it reads as a
coherent document all the way through.  I'd like to try to improve
that before the publication - but to be honest I'm not really sure
how, so any ideas on that would be much appreciated.  I also intend to
do a round of general sub-editing: removing unnecessary words,
unwarranted emphasis, repeated "however...but...", that sort of thing.

If you have any ideas about this, or would like to help out, or have
any concerns, please let me know.

Regards,
        Neil

Re: Publishing the manual...

[Ludovic Courtès]

Hey!

Glad to learn the manual is still thinner than Harry Potter.  ;-)

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

> I also intend to do a round of general sub-editing: removing
> unnecessary words, unwarranted emphasis, repeated "however...but...",
> that sort of thing.

Perhaps GNU Diction (http://www.gnu.org/software/diction/) can help with
it, but I've never actually used it.

This all sounds like a nice plan anyway.

Thanks,
Ludo'.

Re: Publishing the manual...

[Andy Wingo]

On Sun 31 May 2009 02:11, Neil Jerram <neil@ossau.uklinux.net> writes:

> I should let you all know that Brian Gough has approached me about
> publishing the Guile manual.

How lovely! This is great news :-)

> If you have any ideas about this, or would like to help out, or have
> any concerns, please let me know.

Consider adding a section on GOOPS, from the GOOPS manual and tutorial.
Folding that into the Guile manual would be great.

We need to document syntax-rules and syntax-case, and the concept of
hygiene wrt macros and modules.

We should document the new REPL.

Anyway, just some scattered evening thoughts. Good luck, and let me know
if I can help in any specific way!

Andy
-- 
http://wingolog.org/

Re: Publishing the manual...

[Jose A. Ortega Ruiz]

Hi Neal. This sounds neat. I was thinking that, by the time the manual
hits the bookshelves, Geiser will probably have matured to the point of
having documentation: if you and/or the editors think it'd be worth it,
count on me to contribute (or help with) a short chapter on Geiser (i'll
understand it if you think it's out of scope; after all, although
Guile is its best supported Scheme, Geiser is not Guile-specific).

I'm not very familiar with Guile's documentation, or with its
implementation. On top of that, English is not my mother tongue. Despite
of that, if you think i can be of any help during the edition process,
feel free to drop me a line--i think writing about Guile would be fun.

Cheers,
jao

Re: Publishing the manual...

[Neil Jerram]

"Jose A. Ortega Ruiz" <jao@gnu.org> writes:

> Hi Neal. This sounds neat. I was thinking that, by the time the manual
> hits the bookshelves, Geiser will probably have matured to the point of
> having documentation: if you and/or the editors think it'd be worth it,
> count on me to contribute (or help with) a short chapter on Geiser (i'll
> understand it if you think it's out of scope; after all, although
> Guile is its best supported Scheme, Geiser is not Guile-specific).

I think that would be fantastic!  (Also I see that you
already have a copyright assignment on file for Guile, so there is no
obstacle there.)

(And, just to be completely explicit, I don't perceive any conflict at
all with GDS; it's great to have multiple options available for Guile
in Emacs.)

> I'm not very familiar with Guile's documentation, or with its
> implementation. On top of that, English is not my mother tongue. Despite
> of that, if you think i can be of any help during the edition process,
> feel free to drop me a line--i think writing about Guile would be fun.

If you have high-level thoughts about the overall organisation, I'd be
happy to hear them.  (To get a feel for what it's like at the moment,
use `make dvi' and xdvi.)  I think that is the difficult part, and to
some extent English-independent.

Regards,
        Neil

Re: Publishing the manual...

[Neil Jerram]

Andy Wingo <wingo@pobox.com> writes:

> Consider adding a section on GOOPS, from the GOOPS manual and tutorial.
> Folding that into the Guile manual would be great.

Yes, absolutely, I already had that in mind.  There's no case for
GOOPS to be separated out any more, and it's a fun bit of the
technology.

I'll assume this is on my todo list... but if anyone else fancies
handling it (and already has copyright assignment on file, or is happy
to organize that), let me know.

> We need to document syntax-rules and syntax-case, and the concept of
> hygiene wrt macros and modules.

Agreed.  I think we should consider the option of just referencing
coverage of these ideas elsewhere, but

- we will still need at least a statement of what Guile supports

- these ideas are tricky, and it can help (in some global sense) for
  us to provide another exposition of them, even if they are
  technically already covered elsewhere

- in particular, the combination of hygiene with modules does not seem
  to be well covered anywhere yet, even in R6RS.  (Although I haven't
  looked really extensively, e.g. in the other Scheme implementations'
  docs.)

> We should document the new REPL.

Agreed there too.  There is a section on the pre-VM REPL, so maybe it
would make sense to extend that.

Would you be interested in covering either of these areas?

> Anyway, just some scattered evening thoughts. Good luck, and let me
> know if I can help in any specific way!

Well, as above :-) and also any thoughts on the overall
organisation...

Regards,
        Neil

Re: Publishing the manual...

[Neil Jerram]

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

> Perhaps GNU Diction (http://www.gnu.org/software/diction/) can help with
> it, but I've never actually used it.

Thanks for the idea!  I'll give it a try...

   Neil