From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Andy Wingo Newsgroups: gmane.lisp.guile.devel Subject: Re: two spaces after sentence + other doc janitorial duties Date: Mon, 28 Jun 2010 15:57:34 +0200 Message-ID: References: <87tyorqddl.fsf@ambire.localdomain> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: dough.gmane.org 1277733390 11547 80.91.229.12 (28 Jun 2010 13:56:30 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Mon, 28 Jun 2010 13:56:30 +0000 (UTC) Cc: guile-devel@gnu.org To: Thien-Thi Nguyen Original-X-From: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Mon Jun 28 15:56:29 2010 Return-path: Envelope-to: guile-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1OTEp1-0004zN-TO for guile-devel@m.gmane.org; Mon, 28 Jun 2010 15:56:28 +0200 Original-Received: from localhost ([127.0.0.1]:48314 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OTEp1-0006jM-EF for guile-devel@m.gmane.org; Mon, 28 Jun 2010 09:56:27 -0400 Original-Received: from [140.186.70.92] (port=54303 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OTEns-00069C-Rj for guile-devel@gnu.org; Mon, 28 Jun 2010 09:55:18 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1OTEni-0001uA-Pz for guile-devel@gnu.org; Mon, 28 Jun 2010 09:55:16 -0400 Original-Received: from a-pb-sasl-quonix.pobox.com ([208.72.237.25]:58864 helo=sasl.smtp.pobox.com) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OTEni-0001ty-K2 for guile-devel@gnu.org; Mon, 28 Jun 2010 09:55:06 -0400 Original-Received: from sasl.smtp.pobox.com (unknown [127.0.0.1]) by a-pb-sasl-quonix.pobox.com (Postfix) with ESMTP id C521FBFC70; Mon, 28 Jun 2010 09:55:05 -0400 (EDT) DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=pobox.com; h=from:to:cc :subject:references:date:in-reply-to:message-id:mime-version :content-type:content-transfer-encoding; s=sasl; bh=GCNES3OAIXIz kIayuycFugqSCO0=; b=CBr+x5y6TwTlgRhpZcCpvU22bM+osqFWJ4dQNKZs2+mm wDhqnSaBPoPkMD1YUxfndXufLMq1brQyKwTRObidoUjTnUOBFa91OBYySc+qdSB0 IvEYrpYdcE0MBH5Oo3Cph8OOzzCNCA9KD2KkxdxOx1+iB723vN7WLOK/rAT9dNY= DomainKey-Signature: a=rsa-sha1; c=nofws; d=pobox.com; h=from:to:cc :subject:references:date:in-reply-to:message-id:mime-version :content-type:content-transfer-encoding; q=dns; s=sasl; b=EYqQkV q1fxUc7UQSfVPXwjtrx69bfKZh19xXsa9JnV5PaqIs7nElxFLsWiYjQMOlYU6AuN AxTQ3qnz4Imt0Y5lyR3C3SfrDNjpKntNv6wcJXPEAR16fVujLJZkGhHFL+6x0zMH mDBnwqLV15m9SqJaBsbVt4VVPV4220BLr3+Vk= Original-Received: from a-pb-sasl-quonix. (unknown [127.0.0.1]) by a-pb-sasl-quonix.pobox.com (Postfix) with ESMTP id AD4A3BFC6E; Mon, 28 Jun 2010 09:55:04 -0400 (EDT) Original-Received: from unquote.localdomain (unknown [83.202.24.141]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by a-pb-sasl-quonix.pobox.com (Postfix) with ESMTPSA id 1813BBFC67; Mon, 28 Jun 2010 09:55:02 -0400 (EDT) In-Reply-To: <87tyorqddl.fsf@ambire.localdomain> (Thien-Thi Nguyen's message of "Fri, 25 Jun 2010 18:35:18 +0200") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/23.2 (gnu/linux) X-Pobox-Relay-ID: C0EF6966-82BC-11DF-8EB8-9056EE7EF46B-02397024!a-pb-sasl-quonix.pobox.com X-detected-operating-system: by eggs.gnu.org: Solaris 10 (beta) X-BeenThere: guile-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Developers list for Guile, the GNU extensibility library" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Errors-To: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.lisp.guile.devel:10583 Archived-At: Heya, On Fri 25 Jun 2010 18:35, Thien-Thi Nguyen writes: > Normally, texinfo source should have two spaces after each sentence: > > Blah the first. Blah more. ;; only one space, not cool > Blah the first. Blah more. ;; two spaces, ok Why is this the case? TeX itself gets this right, why can't makeinfo? > I started locally modifying doc/ref/*.texi, when midway though discovered > api-undocumented.texi, which led me to doc/maint/docstring.el, which leads > me to believe that modifing doc/ref/*.texi is not so smart, since a future > update using docstring.el would overwrite them. Better to make the chang= es > upstream (in libguile/*.c SCM_DEFINE forms, to be precise), no? Yes indeed. > Further digging, i see one of the last docstring.el-using updates was: > > commit 3323ec063ccc87b210e6da04c57c625af270b230 > Author: Neil Jerram > Date: Sun Dec 27 23:24:09 2009 +0000 >=20=20=20 > Automatic manual updates following libguile docstring changes >=20=20=20=20=20=20=20 > and since then there have been many other manual updates. So, should i > interpret the six months since that update to mean that we are no longer > using a docstring.el-based system? Am i missing something? I don't really understand docstring.el. How should I use it? I have simply been copying changes over manually. I guess if we are to get back onto the docstring.el wagon, we should first do a docstring.el commit -- carefully examining the changes to make sure any .texi-only changes are not lost -- then proceed. > I suppose a shorter question would be: What do you all suggest for doing > "two spaces" and other doc cleanups -- which source is the true source? For docstring'd things, the .c files. I am hesitant regarding two spaces, and would like a little more discussion on that. > Other changes i have in mind: > > - convert "..." to "@dots{}"; > - convert "i.e. FOO" to "i.e., FOO" > (and likewise "i. e. FOO" and "e.g. FOO"); Great. > - choose "Returns" or "Return" and use it everywhere; Sure. > Last related question: I realize that a subset of the doc/ref/*.texi do > not derive from docstring.el (for example vm.texi), so can be operated > on directly w/o qualms. How about i collect changes to those files onto > branch =E2=80=98ttn/janitor-doc=E2=80=99 and simply post "rfc: SHA1"? I = can't imagine > huge diffs would be welcome on the list... Sure, sounds fine to me. Andy --=20 http://wingolog.org/