From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#19338: [PATCHv2 1/2] descr-text: add `describe-char-eldoc' describing character at point Date: Sun, 14 Dec 2014 21:46:33 +0200 Message-ID: <83egs2xbdy.fsf@gnu.org> References: <1418313752-13536-1-git-send-email-mpn@google.com> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8BIT X-Trace: ger.gmane.org 1418586504 1639 80.91.229.3 (14 Dec 2014 19:48:24 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 14 Dec 2014 19:48:24 +0000 (UTC) Cc: 19338@debbugs.gnu.org To: Michal Nazarewicz Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sun Dec 14 20:48:17 2014 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1Y0F9L-0002WD-EV for geb-bug-gnu-emacs@m.gmane.org; Sun, 14 Dec 2014 20:48:15 +0100 Original-Received: from localhost ([::1]:36983 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Y0F9L-0000o1-3S for geb-bug-gnu-emacs@m.gmane.org; Sun, 14 Dec 2014 14:48:15 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:54358) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Y0F9D-0000nR-TE for bug-gnu-emacs@gnu.org; Sun, 14 Dec 2014 14:48:13 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Y0F98-0003jW-DK for bug-gnu-emacs@gnu.org; Sun, 14 Dec 2014 14:48:07 -0500 Original-Received: from debbugs.gnu.org ([140.186.70.43]:36902) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Y0F98-0003jS-A7 for bug-gnu-emacs@gnu.org; Sun, 14 Dec 2014 14:48:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1Y0F97-0003EB-NK for bug-gnu-emacs@gnu.org; Sun, 14 Dec 2014 14:48:01 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 14 Dec 2014 19:48:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 19338 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 19338-submit@debbugs.gnu.org id=B19338.141858642212342 (code B ref 19338); Sun, 14 Dec 2014 19:48:01 +0000 Original-Received: (at 19338) by debbugs.gnu.org; 14 Dec 2014 19:47:02 +0000 Original-Received: from localhost ([127.0.0.1]:46268 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1Y0F89-0003Cn-Ar for submit@debbugs.gnu.org; Sun, 14 Dec 2014 14:47:02 -0500 Original-Received: from mtaout24.012.net.il ([80.179.55.180]:46476) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1Y0F83-0003CQ-RY for 19338@debbugs.gnu.org; Sun, 14 Dec 2014 14:46:57 -0500 Original-Received: from conversion-daemon.mtaout24.012.net.il by mtaout24.012.net.il (HyperSendmail v2007.08) id <0NGL008007EVY000@mtaout24.012.net.il> for 19338@debbugs.gnu.org; Sun, 14 Dec 2014 21:38:59 +0200 (IST) Original-Received: from HOME-C4E4A596F7 ([87.69.4.28]) by mtaout24.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0NGL0050G7WZJM50@mtaout24.012.net.il>; Sun, 14 Dec 2014 21:38:59 +0200 (IST) In-reply-to: <1418313752-13536-1-git-send-email-mpn@google.com> X-012-Sender: halo1@inter.net.il X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 140.186.70.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:97335 Archived-At: > From: Michal Nazarewicz > Date: Thu, 11 Dec 2014 17:02:31 +0100 > Cc: 19338@debbugs.gnu.org > > From: Michal Nazarewicz > > * lisp/descr-text.el (describe-char-eldoc): New function returning > basic Unicode codepoint information (e.g. name) about character > at point. It is meant to be used as a default value of the > `eldoc-documentation-function' variable. > (describe-char-eldoc--format, describe-char-eldoc--truncate): > New helper functions for `describe-char-eldoc' function. > > * tests/automated/descr-text-test.el: New file with tests for > `describe-char-eldoc--truncate', `describe-char-eldoc--format', > and `describe-char-eldoc'. Thanks. Allow me a few comments about the documentation parts. > +(defun describe-char-eldoc--truncate (name width) > + "Truncate NAME at white spaces such that it is no longer than WIDTH. > + > +If NAME consists of white space only, return an empty string. > + > +Otherwise, if NAME consists of a single word (where word is defined as sequence > +of non-white space characters), return that word even if it's longer than WIDTH. > + > +Otherwise, if first word in NAME is longer or equal WIDTH, return that word with > +ellipsis character (\"…\") appended; this results in a string longer than WIDTH. > + > +Otherwise, take as many words from NAME as possible, separating them with > +a single space character, while not exceeding WIDTH characters length limit. If > +not all words fit, append ellipsis character (\"…\") at the end; the ellipsis is > +counted towards WIDTH." The lines in this doc string are too long, some of them are longer than 79 characters, which will overflow the typical line width on a TTY. More importantly, this kind of "pseudo-code" description of what the function does is not the best way of documenting a function. It is best to describe it in natural-language terms, and start with the most general, then go to the corner cases. Pseudo-code usually forces you to describe the corner cases first, which is confusing and might lead the reader to wrong conclusions. Likewise with minor details, like the fact that words are separated with a single space: this should be mentioned only after you describe the main job. > + (let ((ellipsis (and (cdr last) "…"))) Btw, will this display OK on a TTY? Not all TTYs support UTF-8. > +Full description message has a \"U+: (: )\" > +format where: > +- is a hexadecimal codepoint of the character (zero-padded to at least > + four digits), > +- is name of the character. We don't use to describe parameters, we use THIS STYLE. > +(defun describe-char-eldoc () > + "Returns a description of character at point for use by ElDoc mode. "Return", not "Returns". > +If character at point is a printable ASCII character (i.e. codepoint between 32 > +and 127 inclusively), nil is returned. Otherwise a description formatted by > +`describe-char-eldoc--format' function is returned taking into account value Here you suddenly switch to passive tense, which is both longer and make the sentence more complicated. Try sticking to active as much as is practical. Thanks again for working on this.