From: "Drew Adams" <drew.adams@oracle.com>
To: "'Eli Zaretskii'" <eliz@gnu.org>
Cc: cyd@stupidchicken.com, 6018@debbugs.gnu.org, larsi@gnus.org
Subject: bug#6018: 23.1.96; doc of version(-list)*
Date: Thu, 14 Jul 2011 07:05:57 -0700 [thread overview]
Message-ID: <6939AE9645124A98A704884D2C66A2B1@us.oracle.com> (raw)
In-Reply-To: <E1QhFRo-0003ID-T5@fencepost.gnu.org>
> > > > The doc string of `version-regexp-alist' refers to the
> > > > `version-list-*' functions, saying to consult their doc, so they
> > > > cannot be said to be "internal".
>
> That doc string no longer refers to anything but version-to-list.
I was going by the description of the bug fix in this thread, which didn't
mention that.
> And version-regexp-alist is itself an internal variable, so this is
> not an evidence to the effect you want it to be. The doc string of
> version-regexp-alist is for developers of this group of functions, not
> for users of their advertised APIs.
Really? What about these parts of the doc string of `version-to-list':
1. "SEPARATOR ::= `version-separator' (which see)
`version-regexp-alist' (which see)."
2. "The NUMBER part is optional if SEPARATOR is a match for an element
in `version-regexp-alist'."
3. "See documentation for `version-separator' and `version-regexp-alist'."
What, anywhere, indicates that `version-regexp-alist' is "internal"? All
indications point to the contrary.
Or are you now claiming that `version-to-list' is also internal, like you
claimed for `version-list*'? It was you who placed an internal/external line in
the sand here, pointing out that `v-r-alist' now refers only to `v-to-list' and
no longer to `v-list*' (because "internal").
> > about the `version* (non-list) functions:
> >
> > > nothing is said about the comparison of strings with digits
> > > other than zero. And that's arguably the most important and
> > > most up for grabs.
>
> You mean, it isn't obviously clear that 3 is greater than 2 and less
> than 4? It needs to be documented in a doc string?
A digit is not a string of digits. And as you know full well (or should know),
there are various ways to order strings of digits.
One need look no further than the "interesting" way MS Windows (e.g. Windows
Explorer) sorts file names that contain digits: "google windows explorer file
name sort order". Don't you think we should specify how strings containing
digits are ordered? It's not about 3 > 2.
> > > And again, even for zeros and alpha strings, the
> > > "explanation" is only via examples. At least say something
> > > about what kind of string comparison is done:
> > > alphabetic for non-digits, describe the comparison of digit
> > > strings, mention case-insensitivity etc.
>
> See above
Yes, please see above.
How are strings containing digits compared? What about case sensitivity? Does
`case-fold-search' affect that or not? Especially if the comparison is simple
(e.g. orthographic/alphabetical order), it is simple to state what it is.
For the rest - if you have removed all mention of everything you designate as
"internal" from the doc of what you designate as not internal, then that part of
the bug could be considered fixed. Fixed by sleight of hand, perhaps, but
fixed.
If there remain non-internal things whose doc is incompletely specified (see
above), then that doc would remain to be fixed.
next prev parent reply other threads:[~2011-07-14 14:05 UTC|newest]
Thread overview: 12+ messages / expand[flat|nested] mbox.gz Atom feed top
2010-04-23 19:04 bug#6018: 23.1.96; doc of version(-list)* Drew Adams
2010-04-23 20:39 ` Eli Zaretskii
2010-04-23 21:06 ` Drew Adams
2011-07-13 18:06 ` Lars Magne Ingebrigtsen
2011-07-13 18:20 ` Drew Adams
2011-07-14 2:04 ` Chong Yidong
2011-07-14 2:51 ` Drew Adams
2011-07-14 6:30 ` Eli Zaretskii
2011-07-14 14:05 ` Drew Adams [this message]
2011-07-14 15:58 ` Eli Zaretskii
2012-01-07 6:15 ` Lars Magne Ingebrigtsen
2011-07-16 18:42 ` Stefan Monnier
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
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=6939AE9645124A98A704884D2C66A2B1@us.oracle.com \
--to=drew.adams@oracle.com \
--cc=6018@debbugs.gnu.org \
--cc=cyd@stupidchicken.com \
--cc=eliz@gnu.org \
--cc=larsi@gnus.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.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.