From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Panicz Maciej Godek Newsgroups: gmane.lisp.guile.user Subject: Re: docstrings in the reference manual Date: Tue, 16 Dec 2014 13:18:49 +0100 Message-ID: References: <20141216114248.GA4960@intra> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: multipart/alternative; boundary=047d7b5d619484890b050a545c0a X-Trace: ger.gmane.org 1418732356 3970 80.91.229.3 (16 Dec 2014 12:19:16 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Tue, 16 Dec 2014 12:19:16 +0000 (UTC) Cc: guile-user To: John Darrington Original-X-From: guile-user-bounces+guile-user=m.gmane.org@gnu.org Tue Dec 16 13:19:10 2014 Return-path: Envelope-to: guile-user@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 1Y0r5p-0006Vk-9A for guile-user@m.gmane.org; Tue, 16 Dec 2014 13:19:09 +0100 Original-Received: from localhost ([::1]:44320 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Y0r5o-0005gG-8r for guile-user@m.gmane.org; Tue, 16 Dec 2014 07:19:08 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:39329) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Y0r5X-0005g6-LJ for guile-user@gnu.org; Tue, 16 Dec 2014 07:18:52 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Y0r5W-0005C4-8x for guile-user@gnu.org; Tue, 16 Dec 2014 07:18:51 -0500 Original-Received: from mail-wi0-x236.google.com ([2a00:1450:400c:c05::236]:54486) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Y0r5W-0005By-0W for guile-user@gnu.org; Tue, 16 Dec 2014 07:18:50 -0500 Original-Received: by mail-wi0-f182.google.com with SMTP id h11so12288135wiw.3 for ; Tue, 16 Dec 2014 04:18:49 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:in-reply-to:references:date:message-id:subject:from:to :cc:content-type; bh=wn/WhhwWiV/UD7Y/BvLb2Sh2/PHd9yiBPhMUq5KymDM=; b=qZbmSEm2wFI9u904zNAXDiE1IWXFuOEg7Eb7uBOlNIYF06w+hNOSQJTOjWPnm/BWFL W7f6Dtcy7vfrTRBWaE7BO0RYbf02teVsrbk6ydKhUNUR/ynJmZ/YeG6d5yDdMMRO5szg VUJ1Icuw0VWFyq7JwPCw90U17go4kLlsuIsyoZF8vcRwsvyAtBv3YKPqqqnJTZUjdZ35 K0p2m21dkvcJfmKLS2dAfyKvQkDifFWaPQywIJG9bWGkBhBdB7U2uZfbojO23YHqUjSS dVA3CQOMvt1RVLfMKODKrcAmcQzTQ3Flu09DnleL/QXj3R+kOrWD40Lb1Z+aSv4KAqTJ Rz0g== X-Received: by 10.194.19.4 with SMTP id a4mr60427284wje.3.1418732329272; Tue, 16 Dec 2014 04:18:49 -0800 (PST) Original-Received: by 10.194.102.38 with HTTP; Tue, 16 Dec 2014 04:18:49 -0800 (PST) In-Reply-To: <20141216114248.GA4960@intra> X-detected-operating-system: by eggs.gnu.org: Error: Malformed IPv6 address (bad octet value). X-Received-From: 2a00:1450:400c:c05::236 X-BeenThere: guile-user@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: General Guile related discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guile-user-bounces+guile-user=m.gmane.org@gnu.org Original-Sender: guile-user-bounces+guile-user=m.gmane.org@gnu.org Xref: news.gmane.org gmane.lisp.guile.user:11677 Archived-At: --047d7b5d619484890b050a545c0a Content-Type: text/plain; charset=UTF-8 2014-12-16 12:42 GMT+01:00 John Darrington : > > Why murder the English language more than necessary? "Docstrings" is a > cliche > which has come from other projects. Peope for whom English is not their > first > language can be confused by such aliterations. They won't find the word > in any > dictionary. > > Actually, there's a wikipedia entry regarding that notion: http://en.wikipedia.org/wiki/Docstring It appears that the word 'docstring' is already used in the technical jargon and Jamil's case proves that the manual could do better in faciliating the search. Write the term "documentation string" out in full, or simply "documentation" > where the context is clear. If you take a look at the index of the manual, you'll find entries like: "alist", "async", "errno", "smob", "vcell" and so on. I don't think that adding a "docstring" entry would do any harm in this particular context (on the other hand, the "documentation string" entry is lacking as well, so I agree that it is more important to add this one in the first place) --047d7b5d619484890b050a545c0a Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable
2014= -12-16 12:42 GMT+01:00 John Darrington <john@darrington.wattle.= id.au>:
Why murder the English language more = than necessary?=C2=A0 "Docstrings" is a cliche
which has come from other projects.=C2=A0 Peope for whom English is not the= ir first
language can be confused by such aliterations.=C2=A0 They won't find th= e word in any
dictionary.


Actually, there's a wikipedia entr= y regarding that notion:
It appears = that the word 'docstring' is already used in the technical jargon a= nd Jamil's case proves that the manual could do better in faciliating t= he search.

Write the term "documentation string" out in full, or simply &quo= t;documentation"
where the context is clear.

If you take a l= ook at the index of the manual, you'll find entries like:
&qu= ot;alist", "async", "errno", "smob", &qu= ot;vcell" and so on. I don't think that adding a "docstring&q= uot; entry would do any harm in this particular context (on the other hand,= the "documentation string" entry is lacking as well, so I agree = that it is more important to add this one in the first place)
--047d7b5d619484890b050a545c0a--