From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Thien-Thi Nguyen Newsgroups: gmane.lisp.guile.devel Subject: two spaces after sentence + other doc janitorial duties Date: Fri, 25 Jun 2010 18:35:18 +0200 Message-ID: <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 1277492786 29210 80.91.229.12 (25 Jun 2010 19:06:26 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Fri, 25 Jun 2010 19:06:26 +0000 (UTC) To: guile-devel@gnu.org Original-X-From: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Fri Jun 25 21:06:23 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 1OSEEJ-0004os-8u for guile-devel@m.gmane.org; Fri, 25 Jun 2010 21:06:23 +0200 Original-Received: from localhost ([127.0.0.1]:49841 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OSDz5-0002a6-H7 for guile-devel@m.gmane.org; Fri, 25 Jun 2010 14:50:39 -0400 Original-Received: from [140.186.70.92] (port=44167 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OSCvw-0002Dc-0u for guile-devel@gnu.org; Fri, 25 Jun 2010 13:43:21 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1OSBuU-0003Zz-R9 for guile-devel@gnu.org; Fri, 25 Jun 2010 12:37:48 -0400 Original-Received: from smtp204.alice.it ([82.57.200.100]:57078) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OSBuU-0003Zh-Ev for guile-devel@gnu.org; Fri, 25 Jun 2010 12:37:46 -0400 Original-Received: from ambire.localdomain (95.244.64.152) by smtp204.alice.it (8.5.124.08) id 4C1A26020096556E for guile-devel@gnu.org; Fri, 25 Jun 2010 18:37:44 +0200 Original-Received: from ttn by ambire.localdomain with local (Exim 4.69) (envelope-from ) id 1OSBs6-0005bd-SN for guile-devel@gnu.org; Fri, 25 Jun 2010 18:35:18 +0200 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. 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:10570 Archived-At: 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 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 changes upstream (in libguile/*.c SCM_DEFINE forms, to be precise), no? 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 Automatic manual updates following libguile docstring changes =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 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? 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"); - choose "Returns" or "Return" and use it everywhere; 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 ca= n't imagine huge diffs would be welcome on the list... thi