From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: David Kastrup Newsgroups: gmane.emacs.devel Subject: Re: Uncomprehensible DOC string Date: Fri, 09 May 2008 10:30:11 +0200 Message-ID: <86fxsrop64.fsf@lola.quinscape.zz> References: <86abj2wdry.fsf@lola.quinscape.zz> <874p98awa4.fsf@gmx.de> <85tzh8j79e.fsf@lola.goethe.zz> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: ger.gmane.org 1210321910 9654 80.91.229.12 (9 May 2008 08:31:50 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 9 May 2008 08:31:50 +0000 (UTC) Cc: emacs-devel@gnu.org To: Michael Albinus Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri May 09 10:32:26 2008 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.50) id 1JuO1V-0000wR-0F for ged-emacs-devel@m.gmane.org; Fri, 09 May 2008 10:32:13 +0200 Original-Received: from localhost ([127.0.0.1]:35257 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1JuO0m-0001Eu-Du for ged-emacs-devel@m.gmane.org; Fri, 09 May 2008 04:31:28 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1JuNze-0000xj-Mq for emacs-devel@gnu.org; Fri, 09 May 2008 04:30:18 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1JuNzc-0000x4-Rs for emacs-devel@gnu.org; Fri, 09 May 2008 04:30:18 -0400 Original-Received: from [199.232.76.173] (port=54535 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1JuNzc-0000wx-FB for emacs-devel@gnu.org; Fri, 09 May 2008 04:30:16 -0400 Original-Received: from mail.quinscape.de ([212.29.44.217]:47045) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1JuNzb-000727-Tf for emacs-devel@gnu.org; Fri, 09 May 2008 04:30:16 -0400 Original-Received: (qmail-ldap/ctrl 25162 invoked from network); 9 May 2008 08:30:12 -0000 Original-Received: from unknown (HELO lola.quinscape.zz) ([10.0.3.43]) (envelope-sender ) by quinx.quinscape.de (qmail-ldap-1.03) with SMTP for ; 9 May 2008 08:30:12 -0000 Original-Received: by lola.quinscape.zz (Postfix, from userid 1001) id E647B8EEBA; Fri, 9 May 2008 10:30:11 +0200 (CEST) In-Reply-To: (Michael Albinus's message of "Fri, 09 May 2008 09:53:55 +0200") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/23.0.60 (gnu/linux) X-AntiVirus: checked by AntiVir MailGate (version: 2.1.3-2; AVE: 7.8.0.14; VDF: 7.0.4.19; host: quinx) X-detected-kernel: by monty-python.gnu.org: Linux 2.6 (newer, 3) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:96865 Archived-At: Michael Albinus writes: > David Kastrup writes: > >> That addresses the last partial sentence of my report. What about the >> rest? There is no sense to leave a fragmentary explanation in the DOC >> string when you need to read up the function's behavior elsewhere, >> anyhow. The manual reference should be there to explain the _terms_ >> used in the DOC string, but the DOC string should still be _complete_ >> once the terms are clear. > > I'll try to be a little bit more comprehensive in the doc > string. However, I don't believe that the doc string of > `start-file-process' is the place to explain what are file name > handlers at all. No, but saying a file name handler will be called based on default-directory without telling what the file name handler is actually supposed to be processing is not much use I think. The command? The command line arguments? The executable? -- David Kastrup