From: Neil Jerram <neil@ossau.uklinux.net>
Cc: Robert Uhl <ruhl@4dv.net>
Subject: Re: State of Docs [was] Re: Around again, and docs lead role
Date: 09 May 2003 00:11:42 +0100 [thread overview]
Message-ID: <m33cjpqbip.fsf@laruns.ossau.uklinux.net> (raw)
In-Reply-To: <20030508223242.GB3465@www>
>>>>> "rm" == rm <rm@fabula.de> writes:
rm> Yes. Right now, whenever i stumble upon a usefull but undocumented
rm> part of the Guile API i'm somehow reluctant to use it since i fear
rm> that it's not as stable as the documented part.
rm> Who to consult in such a case? Guile-devel or Guile-user?
guile-devel, I'd say. Although arguably you will always get the
answer yes, as the current position (I think) is that everything
exported by libguile is part of the API and therefore usable.
rm> Yes, i would assume that it's up to those who write the documentation
rm> for guile-embedding applications to provide helpfull intros/tutorials.
rm> After all: most general Scheme tutorials will present things like
rm> 'my-fact' or 'is-prime?' while users probably want to read about
rm> 'print-in-blue' or 'image-blur' ....
Agreed.
rm> BTW, in case i have a documentation patch: where to send it to?
rm> Post it here?
Strictly, bug-guile@gnu.org. But I don't think it would get lost if
you sent it to guile-devel instead.
rm> Finally, a proposal: I think it would be rather helpfull if the
rm> documentation for C functions as well as CPP makros would include
rm> the type specifier. So, instead of:
rm> scm_make_vector (k, fill)
rm> give
rm> scm_c_make_vector (unsigned long int k, SCM fill)
rm> Not having the parameter types is sometimes missleading,
rm> esp. if the same parameter name sometimes stands for a C value
rm> and sometimes for a SCM value (see for ex.: 'scm_vector_set_x
rm> vector k obj', where 'k' stands for SCM value). I'm willing
rm> to take over that job and update the relevant parts over the
rm> next few weeks if people find this helpfull.
I may be wrong, but I don't think there's any ambiguity in the current
docs. Wherever a type specifier is omitted, it should be understood
as SCM. (The reason for this is a makeinfo restriction: makeinfo
can't handle a @deffn followed by a @deftypefnx.)
I think the real problem is that, in many cases, the C level function
like scm_c_make_vector isn't documented. I completely agree that it
should be, and that its type specifiers should be shown explicitly.
Does this make sense?
Neil
_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-user
next prev parent reply other threads:[~2003-05-08 23:11 UTC|newest]
Thread overview: 38+ 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-10-28 16:09 ` Thien-Thi Nguyen
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-09 11:52 ` Bill Schottstaedt
2003-05-13 23:01 ` Neil Jerram
2003-05-14 1:07 ` Viktor Pavlenko
2003-05-14 14:29 ` Bill Schottstaedt
2003-05-15 7:55 ` Mikael Djurfeldt
2003-05-17 3:02 ` Max Techter
2003-05-09 8:15 ` tomas
2003-05-10 12:01 ` Neil Jerram
2003-05-12 11:40 ` tomas
2003-05-03 4:40 ` Around again, and docs lead role Robert Uhl
2003-05-03 11:34 ` rm
2003-05-03 22:21 ` Robert Uhl
2003-05-03 23:15 ` Thamer Al-Harbash
2003-05-04 8:40 ` David Allouche
2003-05-04 21:34 ` Robert Uhl
2003-05-04 19:47 ` rm
2003-05-04 21:42 ` Robert Uhl
2003-05-04 23:38 ` Thien-Thi Nguyen
2003-05-07 22:52 ` Neil Jerram
2003-05-08 22:32 ` State of Docs [was] " rm
2003-05-08 23:11 ` Neil Jerram [this message]
2003-05-10 0:47 ` State of Docs Kevin Ryde
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=m33cjpqbip.fsf@laruns.ossau.uklinux.net \
--to=neil@ossau.uklinux.net \
--cc=ruhl@4dv.net \
/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).