From mboxrd@z Thu Jan  1 00:00:00 1970
Path: news.gmane.org!not-for-mail
From: Neil Jerram <neil@ossau.uklinux.net>
Newsgroups: gmane.lisp.guile.devel
Subject: Minor queries about Unicode char docs
Date: Mon, 31 Aug 2009 11:21:57 +0100
Message-ID: <87ocpwuvui.fsf@arudy.ossau.uklinux.net>
NNTP-Posting-Host: lo.gmane.org
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
X-Trace: ger.gmane.org 1251714177 18839 80.91.229.12 (31 Aug 2009 10:22:57 GMT)
X-Complaints-To: usenet@ger.gmane.org
NNTP-Posting-Date: Mon, 31 Aug 2009 10:22:57 +0000 (UTC)
Cc: Guile Development <guile-devel@gnu.org>
To: Mike Gran <spk121@yahoo.com>
Original-X-From: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Mon Aug 31 12:22:50 2009
Return-path: <guile-devel-bounces+guile-devel=m.gmane.org@gnu.org>
Envelope-to: guile-devel@m.gmane.org
Original-Received: from lists.gnu.org ([199.232.76.165])
	by lo.gmane.org with esmtp (Exim 4.50)
	id 1Mi42E-0001S9-15
	for guile-devel@m.gmane.org; Mon, 31 Aug 2009 12:22:50 +0200
Original-Received: from localhost ([127.0.0.1]:48513 helo=lists.gnu.org)
	by lists.gnu.org with esmtp (Exim 4.43)
	id 1Mi42D-0002x3-3P
	for guile-devel@m.gmane.org; Mon, 31 Aug 2009 06:22:49 -0400
Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43)
	id 1Mi429-0002wy-Gn
	for guile-devel@gnu.org; Mon, 31 Aug 2009 06:22:45 -0400
Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43)
	id 1Mi424-0002tV-Kz
	for guile-devel@gnu.org; Mon, 31 Aug 2009 06:22:44 -0400
Original-Received: from [199.232.76.173] (port=54842 helo=monty-python.gnu.org)
	by lists.gnu.org with esmtp (Exim 4.43) id 1Mi424-0002tS-Eq
	for guile-devel@gnu.org; Mon, 31 Aug 2009 06:22:40 -0400
Original-Received: from mail3.uklinux.net ([80.84.72.33]:33950)
	by monty-python.gnu.org with esmtp (Exim 4.60)
	(envelope-from <neil@ossau.uklinux.net>) id 1Mi424-0002gs-0Y
	for guile-devel@gnu.org; Mon, 31 Aug 2009 06:22:40 -0400
Original-Received: from arudy (host86-152-99-133.range86-152.btcentralplus.com
	[86.152.99.133]) by mail3.uklinux.net (Postfix) with ESMTP
	id 489681F6A27; Mon, 31 Aug 2009 11:21:58 +0100 (BST)
Original-Received: from arudy.ossau.uklinux.net (arudy [127.0.0.1])
	by arudy (Postfix) with ESMTP id 5C37938023;
	Mon, 31 Aug 2009 11:21:57 +0100 (BST)
User-Agent: Gnus/5.11 (Gnus v5.11) Emacs/22.2 (gnu/linux)
X-detected-operating-system: by monty-python.gnu.org: GNU/Linux 2.4-2.6
X-BeenThere: guile-devel@gnu.org
X-Mailman-Version: 2.1.5
Precedence: list
List-Id: "Developers list for Guile,
	the GNU extensibility library" <guile-devel.gnu.org>
List-Unsubscribe: <http://lists.gnu.org/mailman/listinfo/guile-devel>,
	<mailto:guile-devel-request@gnu.org?subject=unsubscribe>
List-Archive: <http://lists.gnu.org/pipermail/guile-devel>
List-Post: <mailto:guile-devel@gnu.org>
List-Help: <mailto:guile-devel-request@gnu.org?subject=help>
List-Subscribe: <http://lists.gnu.org/mailman/listinfo/guile-devel>,
	<mailto:guile-devel-request@gnu.org?subject=subscribe>
Original-Sender: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org
Errors-To: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org
Xref: news.gmane.org gmane.lisp.guile.devel:9220
Archived-At: <http://permalink.gmane.org/gmane.lisp.guile.devel/9220>

First of all, thanks for making these docs (specifically, commit
3f12aed) so clear.  They seem so much clearer and simpler to me than
the months of back-and-forth discussion on r6rs-discuss.  I know those
things are not really comparable, but I hope you can see what I mean.

Then, a couple of queries.

 SCM_DEFINE1 (scm_char_less_p, "char<?", scm_tc7_rpsubr, 
              (SCM x, SCM y),
-            "Return @code{#t} iff @var{x} is less than @var{y} in the Unicode sequence,\n"
-            "else @code{#f}.")
+             "Return @code{#t} iff the code point of @var{x} is less than the code\n"
+             "point of @var{y}, else @code{#f}.")

I think there's a case here for making the docstring not identical to
the corresponding manual text.  In the manual context, the section
begins with talking about Unicode, so "Unicode" can be assumed for
everything that follows.  But in the docstring, when someone types
(help char<?), they'll just see

  Return `#t' iff the code point of `x' is less than the code
  point of `y', else `#f'.

For this context I think it would be clearer to say

  Return `#t' iff the Unicode code point of `x' is less than the
  code point of `y', else `#f'.

+Case-insensitive character comparisons of characters use @emph{Unicode
+case folding}.  In case folding comparisons, if a character is
+lowercase and has an uppercase form that can be expressed as a single
+character, it is converted to uppercase before comparison.  Unicode
+case folding is language independent: it uses rules that are generally
+true, but, it cannot cover all cases for all languages.

That's very clear, but what if a character doesn't have an uppercase
form that can be expressed as a single character?  Does Guile then
throw an exception, or does it perform the comparison with the
lowercase code point?

Thanks!

     Neil