[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Doc organization (Re: Around again, and docs lead role)
From: |
Max Techter |
Subject: |
Re: Doc organization (Re: Around again, and docs lead role) |
Date: |
17 May 2003 05:02:24 +0200 |
User-agent: |
Gnus/5.09 (Gnus v5.9.0) Emacs/21.2 |
Mikael Djurfeldt <address@hidden> writes:
> Bill Schottstaedt <address@hidden> writes:
>
> > My take on Guile (which seems to me to have stalled out over the last
> > few years) is that the current developers think of it as an extended
> > shell-based interpreter
>
> Maybe this is totally out of context and misplaced---
snip
I don`t think so, Mikael.
Part of this thread stayed on documentation issues.
I promised, to use my current first dive
into scheme and guile to produce
* critical remarks on the documentation
* a proposal for changes concerning the
overall-layout of the documentation
As I got it,
Neil thinks that "high level questions" about
documentation structure have to be dealt with.
Your mentioning of once formulated goals
for the guile project fits quite well.
> I include below the stated goals of Guile. Even though I'm not a
> particularly active developer right now, these are goals that I
> support strongly, and I think most of the other developers do as well,
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
snip
If this is the case, the introductory parts of the
manual should directly reflect these goals, as you
state below.
(I would say the guile tutorial should do so too)
This would have accelerated my efforts to grasp the
guile concept and scope quite a bit.
> My contribution to this discussion would be that there is no single
> "canonical" way of using Guile. Rather, there is a small handful of
> canonical ways (which are reflected in the goals below).
snip
> I therefore think that many of the ideas that were discussed before
> initiating work on the current manual were very good: that the manual
> should present Guile from a small set of viewpoints connected to the
> small set of canonical ways to use Guile.
snip
I cut out your thoughts on the C API,
because I have no opinion on this issue yet.
> workbook/policy/goals.text
> ----------------------------------------------------------------------
> This file states the goals of Guile.
>
> * Goals of Guile
>
> ** Guile as an extension language library
>
> ** Guile as a programming language
>
> ** Guile as an interface to the operating system
>
> ** Guile as an interactive shell
>
> ** Guile as an integration platform
>
> ** Guile as a basis for other languages
>
As a newbie I agree with Mikael's reasoning and
conclusions.
What goes against using this structure for the
introduction part of the manual?
Then --if possible-- reflecting it in the tutorial
and maybe it could even be used as a pattern for
subsequent parts of the manual. I am not sure about
this, but I bet most of the existing (and valuable)
stuff of the documentation could be fitted in such a
layout.
It would be a structure a guile newbie could hang on
to (I miss such a lifeline in the current manual),
when coping with all those "strange new scheme and
guile" concepts at once.
regards max.
PS:
We would have to change the order:
programming language
and
interactive interpreter
comes first, then
interface to os
then the
advanced concepts:
extension, integration, ...
(already mentioned --in short-- at the top of cause)
- Re: Doc organization (Re: Around again, and docs lead role), (continued)
- Re: Doc organization (Re: Around again, and docs lead role), Rob Browning, 2003/05/08
- Re: Doc organization (Re: Around again, and docs lead role), David Van Horn, 2003/05/09
- Re: Doc organization (Re: Around again, and docs lead role), Neil Jerram, 2003/05/10
- Re: Doc organization (Re: Around again, and docs lead role), Rob Browning, 2003/05/15
- Re: Doc organization (Re: Around again, and docs lead role), Paul Jarc, 2003/05/15
- Re: Doc organization (Re: Around again, and docs lead role), Bill Schottstaedt, 2003/05/09
- Re: Doc organization (Re: Around again, and docs lead role), Neil Jerram, 2003/05/13
- Re: Doc organization (Re: Around again, and docs lead role), Viktor Pavlenko, 2003/05/13
- Re: Doc organization (Re: Around again, and docs lead role), Bill Schottstaedt, 2003/05/14
- Re: Doc organization (Re: Around again, and docs lead role), Mikael Djurfeldt, 2003/05/15
- Re: Doc organization (Re: Around again, and docs lead role),
Max Techter <=
- Re: Doc organization (Re: Around again, and docs lead role), Ricard Mira, 2003/05/18
Re: Doc organization (Re: Around again, and docs lead role), tomas, 2003/05/09