unofficial mirror of guile-devel@gnu.org 
 help / color / mirror / Atom feed
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


  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).