From: Max Techter <mtechter@gmx.de>
Cc: guile-devel@gnu.org
Subject: Re: Doc organization (Re: Around again, and docs lead role)
Date: 09 May 2003 14:32:51 +0200 [thread overview]
Message-ID: <86znlwcnbg.fsf@520000401788.dialin.t-online.de> (raw)
In-Reply-To: <m38ythqc75.fsf@laruns.ossau.uklinux.net>
Neil Jerram <neil@ossau.uklinux.net> writes:
> >>>>> "Max" == Max Techter <mtechter@gmx.de> writes:
>
> >> My latest thinking is that we could be a lot more concrete, even
> >> proscriptive, about what Guile is for and how people should use it,
> >> and that if we did so it would be a lot easier to clearly assess the
> >> state of the documentation and to finish it off.
>
> >> (Right now, IMO, it is difficult even to describe the
> >> documentation status.)
>
> Max> My first impression was:
> Max> Oops...
> Max> such an important project, but obviously
> Max> abandoned...
>
> I don't see how you can conclude that the project is abandoned when
> we're right in the middle of a thread about it ....
>
I installed the guile package, had a look
at the manual and at the tutorial before
I subscribed and read the mailing list.
> Max> I typically look out for a tutorial, immediately
> Max> after installation. Not to learn, but to find out:
>
> Max> is this something for me?
>
> Did you look at the Guile Tutorial?
Yes, I did.
That`s what I do as one of my first steps,
when exploring s.th. new to me.
And this was part of the things
that caused my _first_ and _wrong_ impression.
Oops, abandoned.
Important GNU Packages, have excellent doc,
guile doc is not bad, but not excellent either.
(although it is an important Package,
as I got it now, and not abandoned... :-)
> How would you improve it?
>
Too much to say about this,
to be appropriate for this reply.
I`ll tell you in a couple of days, more precisely.
So far only this:
As an example:
There is a section
Using recursion to process a list.
Before anything was said about pairs,
and lists, and the concept of the null
in scheme.
If this is an tutorial about scheme, you can`t
ask the (potential) user, to take such a leap.
You can do this in a preview, but not in
a tutorial.
Now if this is not a scheme tutorial,
(the Title says `Guile tutorial'),
there is no need to supply such an
example, because it is a standard
scheme construct.
The problem is:
the parts of the documentation
seen as isolated pieces of
knowledge, are good, though not complete.
But being new to guile, and to scheme
I had problems to grasp the context (and the
rational).
> >> , I think the natural high level documentation structure
> >> would then be:
> >>
>
> Max> I am missing, things like: [...]
>
> I agree, and some of these pieces are already in place - see the Guile
> Reference manual. But I was really focussing on the issue of Scheme
> and C API documentation in my last message.
>
Ok, obviously I missed your focus.
That is because I am still struggling to get the big
picture:
The Algorithmic Language Scheme
* GOOPS: (goops). The GOOPS reference manual.
* Guile Reference: (guile). The Guile reference manual.
* Guile Tutorial: (guile-tut). The Guile tutorial.
* R5RS: (r5rs). The Revised(5) Report on Scheme.
(slib is missing in my local installation, what else
is missing?)
> >> - Scheme reference documentation - more or less like the current Part
> >> IV, but Scheme only, not C.
>
> >> - Task-based documentation describing everything needed for aspects of
> >> interfacing with C code:
>
> Max> Task based structuring the meat of the documentation
> Max> is an idea I like, Neil.
>
> Max> That`s what we use software for:
> Max> Solving Tasks
> Max> (beside for having incredible fun, of cause =:)
>
> OK, but given a general purpose language like Scheme, there's a limit
> to how fully you can document it in a task-based way.
> For Scheme you
> need a combination of reference documentation and examples.
>
I agree.
It is clear that this task-based way has advantages
and has tight limits on the other hand.
And may I add:
Reference
with short examples.
Tutorial
with intermediate examples,
Introduction / Basic Concepts
by the way, IMHO there should be a section
* `Basic Concepts of Scheme'
as there already is
__and__
* `Basic Concepts of Guile'
maybe the Whirlwind tour could be
extended to such a section, and
later on this extension could be boiled
down again to an improved Whirlwind tour
both with longer examples
(like the one in `An Example of Non-Lexical Scoping'
which helped me quite a lot, to dig one
of the not so simple concepts.)
> The C API on the other hand - at least as I think we should see it -
> is not general purpose.
> It has the specific job of interfacing C to
> Scheme and so can be fully covered in a task-based way.
>
I am definitely not the one to comment on this,
not yet ;-)
regards
max.
PS:
I would like to help in formulating the overall layout,
and I am prepared to get my hands on real work,
concerning the tutorials, if it is decided on
having (or keeping) them.
_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-devel
next prev parent reply other threads:[~2003-05-09 12:32 UTC|newest]
Thread overview: 28+ messages / expand[flat|nested] mbox.gz Atom feed top
2003-04-26 7:33 Around again, and docs lead role Neil Jerram
2003-04-26 10:19 ` Thamer Al-Harbash
2003-04-27 20:56 ` Neil Jerram
[not found] ` <3E92E1B40021F4D7@pop3.tiscalinet.es>
2003-04-27 21:01 ` Neil Jerram
[not found] ` <3E92E1B4002B0632@pop3.tiscalinet.es>
2003-04-30 22:47 ` Neil Jerram
[not found] ` <3EAFE4EC000D9733@pop1.tiscalinet.es>
2003-05-07 21:06 ` Doc organization (Re: Around again, and docs lead role) Neil Jerram
2003-05-08 16:21 ` Rob Browning
2003-05-08 17:50 ` rm
2003-05-08 22:47 ` Neil Jerram
2003-05-08 21:18 ` Wolfgang Jaehrling
2003-05-08 22:36 ` Neil Jerram
2003-05-09 2:23 ` Rob Browning
2003-05-09 17:46 ` David Van Horn
2003-05-10 11:32 ` Neil Jerram
2003-05-15 16:02 ` Rob Browning
2003-05-15 16:33 ` Paul Jarc
2003-05-08 16:21 ` Max Techter
[not found] ` <3EB9828B00021495@pop1.tiscalinet.es>
2003-05-08 21:12 ` Max Techter
2003-05-27 2:02 ` Max Techter
2003-05-08 22:57 ` Neil Jerram
2003-05-09 12:32 ` Max Techter [this message]
2003-05-09 8:15 ` tomas
2003-05-10 12:01 ` Neil Jerram
2003-05-12 11:40 ` tomas
2003-05-12 16:46 ` Around again, and docs lead role Max Techter
2003-05-12 20:25 ` Neil Jerram
2003-05-13 14:14 ` Max Techter
2003-05-13 19:56 ` Neil Jerram
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/guile/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=86znlwcnbg.fsf@520000401788.dialin.t-online.de \
--to=mtechter@gmx.de \
--cc=guile-devel@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).