From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: "Eli Zaretskii" Newsgroups: gmane.emacs.devel Subject: Re: Update of Mode Line Format in the Lisp Reference Manual. Date: Sat, 27 Sep 2003 13:42:59 +0200 Sender: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Message-ID: <2719-Sat27Sep2003134258+0300-eliz@elta.co.il> References: Reply-To: Eli Zaretskii NNTP-Posting-Host: deer.gmane.org X-Trace: sea.gmane.org 1064659715 5715 80.91.224.253 (27 Sep 2003 10:48:35 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Sat, 27 Sep 2003 10:48:35 +0000 (UTC) Cc: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Sat Sep 27 12:48:33 2003 Return-path: Original-Received: from quimby.gnus.org ([80.91.224.244]) by deer.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 1A3Ccr-00063b-00 for ; Sat, 27 Sep 2003 12:48:33 +0200 Original-Received: from monty-python.gnu.org ([199.232.76.173]) by quimby.gnus.org with esmtp (Exim 3.35 #1 (Debian)) id 1A3Ccq-0001m0-00 for ; Sat, 27 Sep 2003 12:48:33 +0200 Original-Received: from localhost ([127.0.0.1] helo=monty-python.gnu.org) by monty-python.gnu.org with esmtp (Exim 4.22) id 1A3Cap-0003Du-32 for emacs-devel@quimby.gnus.org; Sat, 27 Sep 2003 06:46:27 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.22) id 1A3CaS-0003D9-Bb for emacs-devel@gnu.org; Sat, 27 Sep 2003 06:46:04 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.22) id 1A3CaO-0003Ba-G7 for emacs-devel@gnu.org; Sat, 27 Sep 2003 06:46:01 -0400 Original-Received: from [192.114.186.18] (helo=bilbo.inter.net.il) by monty-python.gnu.org with esmtp (Exim 4.22) id 1A3CaN-0003B8-Co for emacs-devel@gnu.org; Sat, 27 Sep 2003 06:45:59 -0400 Original-Received: from zaretski ([80.230.149.110]) by bilbo.inter.net.il (Mirapoint Messaging Server MOS 3.3.7-GR) with ESMTP id BNH93204; Sat, 27 Sep 2003 13:45:48 +0300 (IDT) Original-To: Lute Kamstra X-Mailer: emacs 21.3.50 (via feedmail 8 I) and Blat ver 1.8.9 In-reply-to: (message from Lute Kamstra on Thu, 25 Sep 2003 17:45:18 +0200) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.2 Precedence: list List-Id: Emacs development discussions. List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Xref: main.gmane.org gmane.emacs.devel:16695 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:16695 > From: Lute Kamstra > Date: Thu, 25 Sep 2003 17:45:18 +0200 > > I've updated the Mode Line Format node of the Lisp Reference Manual. > I documented a couple of new features like the (:propertize elt > props...) construct and the mode-line-position and mode-line-modes > variables. It would be nice if people involved in their > implementation would look at it before I commit the update. Thanks! A few minor comments: > + @item (:propertize @var{elt} @var{props}@dots{}) > + A list whose first element is the symbol @code{:propertize} says to > + process the mode line construct @var{elt} recursively and add the text > + properties specified by @var{props} to the result. The argument > + @var{props} should consist of zero or more pairs @var{text-property} > + @var{value}. (This feature is new as of Emacs 21.4.) > + @c FIXME: This might be Emacs 21.5. I think it's a good idea to add an index entry here, for users who might be looking for information on putting text properties on mode-line text. In general, I'd suggest to re-read your changes and try to add index entries for every piece of information that a user might need to find quickly. Think of programmers like you and me who need to write some Lisp code related to the features you describe, but who do not know by heart the names of functions/variables you are describing. > ! This variable holds the value of the mode-line construct that displays > whether the current buffer is modified. > > The default value of @code{mode-line-modified} is @code{("%1*%1+")}. > --- 1322,1334 ---- > @code{mode-line-format} were changed to use them. > > @defvar mode-line-mule-info > ! This variable holds the value of the mode line construct that displays I see that you've consistently replaced "mode-line" with "mode line" in this and similar contexts. I'm not sure which variant is more correct English; please note that the phrase "mode-line construct" can be rephrased as "construct of the mode line". I tend to write the dash in the former, but not in the latter. However, since English is not my first language, I'll leave the decision to others. > ! @defvar mode-line-position > ! This variable indicates the position in the buffer. The default value > ! (with text properties omitted) is: The Texinfo directive @defvar (as well as its other @def* brethren) defines a @vindex entry for its argument, which is good. However, if a user looks for this information without knowing the name of the variable, she will still be lost. Thus, I think that, ideally, every variable here should have a @cindex entry as well. For example, the variable mode-line-position might have these entries: @cindex buffer position indication, in mode line @cindex mode line, buffer position indication Thanks again for all your work.