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: On being web-friendly and why info must die Date: Fri, 12 Dec 2014 16:27:47 +0100 Organization: Organization?!? Message-ID: <87r3w4dh1o.fsf@fencepost.gnu.org> References: <20141205123549.GA29331@thyrsus.com> <87ppbqb6s1.fsf@gnu.org> <87388mme16.fsf@newcastle.ac.uk> <87a92u86wv.fsf@gnu.org> <87egs5ktdv.fsf@newcastle.ac.uk> <548AE361.6050403@gmx.at> <87iohhj8dk.fsf@newcastle.ac.uk> <548AF765.5000009@gmx.at> <87fvckj52f.fsf@newcastle.ac.uk> <83388ksye4.fsf@gnu.org> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Transfer-Encoding: 8bit X-Trace: ger.gmane.org 1418398138 10242 80.91.229.3 (12 Dec 2014 15:28:58 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 12 Dec 2014 15:28:58 +0000 (UTC) To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Dec 12 16:28:50 2014 Return-path: Envelope-to: ged-emacs-devel@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 1XzS9C-0002sy-H5 for ged-emacs-devel@m.gmane.org; Fri, 12 Dec 2014 16:28:50 +0100 Original-Received: from localhost ([::1]:57856 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XzS9B-0006FK-Rz for ged-emacs-devel@m.gmane.org; Fri, 12 Dec 2014 10:28:49 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:50627) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XzS8U-0005h6-Qi for emacs-devel@gnu.org; Fri, 12 Dec 2014 10:28:11 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1XzS8P-0001hX-Jd for emacs-devel@gnu.org; Fri, 12 Dec 2014 10:28:06 -0500 Original-Received: from plane.gmane.org ([80.91.229.3]:43214) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XzS8P-0001gM-Dd for emacs-devel@gnu.org; Fri, 12 Dec 2014 10:28:01 -0500 Original-Received: from list by plane.gmane.org with local (Exim 4.69) (envelope-from ) id 1XzS8N-0001Xv-OZ for emacs-devel@gnu.org; Fri, 12 Dec 2014 16:27:59 +0100 Original-Received: from x2f49c01.dyn.telefonica.de ([2.244.156.1]) by main.gmane.org with esmtp (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Fri, 12 Dec 2014 16:27:59 +0100 Original-Received: from dak by x2f49c01.dyn.telefonica.de with local (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Fri, 12 Dec 2014 16:27:59 +0100 X-Injected-Via-Gmane: http://gmane.org/ Original-Lines: 52 Original-X-Complaints-To: usenet@ger.gmane.org X-Gmane-NNTP-Posting-Host: x2f49c01.dyn.telefonica.de X-Face: 2FEFf>]>q>2iw=B6, xrUubRI>pR&Ml9=ao@P@i)L:\urd*t9M~y1^:+Y]'C0~{mAl`oQuAl \!3KEIp?*w`|bL5qr,H)LFO6Q=qx~iH4DN; i"; /yuIsqbLLCh/!U#X[S~(5eZ41to5f%E@'ELIi$t^ Vc\LWP@J5p^rst0+('>Er0=^1{]M9!p?&:\z]|;&=NP3AhB!B_bi^]Pfkw User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.0.50 (gnu/linux) Cancel-Lock: sha1:L7sQ6evGYe6bMOVC/NwC/TQnry8= X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 80.91.229.3 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:179925 Archived-At: Eli Zaretskii writes: >> From: phillip.lord@newcastle.ac.uk (Phillip Lord) >> Date: Fri, 12 Dec 2014 14:50:00 +0000 >> Cc: esr@thyrsus.com, Ludovic Courtès , >> emacs-devel@gnu.org >> >> I don't want to put the docstring in. I want to put a reference to the >> docstring. > > What for? What problem would that solve? > >> I want to write "(current-buffer)" and have it evaled when the doc is >> produced. This is the sort of thing that I expect when writing notes to >> teach programming. Why would I not want it in Emacs? > > First, you _can_ do that in Emacs. We have infrastructure and > functions that return the doc strings. > > But for writing a manual, this is usually not the right thing to do. > When you write a manual, you need to think differently than when you > write a doc string, otherwise there will be little added value in the > manual. > > Yes, I know about projects that generate Texinfo sources of their > manuals from the doc strings. But I consider those manuals of a lower > quality than what we have in Emacs. LilyPond does that in its reference appendices. Of course, the doc strings look Texinfoized in the source: displayMusic = #(define-music-function (parser location port music) ((output-port?) ly:music?) (_i "Display the internal representation of @var{music} to @var{port}, default to the console.") (let ((port (or port (current-output-port)))) (newline port) (display-scheme-music music port)) music) And are converted into @item @code{displayMusic} [music] - @var{port} [output port] @var{music} (music) @funindex displayMusic Display the internal representation of @var{music} to @var{port}, default to the console. Basically, all LilyPond documentation strings are written in Texinfo. Texinfo is lightweight enough not to make that annoying when you just query the doc strings from Scheme. -- David Kastrup