unofficial mirror of guile-devel@gnu.org 
 help / color / mirror / Atom feed
* two spaces after sentence + other doc janitorial duties
@ 2010-06-25 16:35 Thien-Thi Nguyen
  2010-06-28 13:57 ` Andy Wingo
  0 siblings, 1 reply; 7+ messages in thread
From: Thien-Thi Nguyen @ 2010-06-25 16:35 UTC (permalink / raw)
  To: guile-devel

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 <neil@ossau.uklinux.net>
  Date:   Sun Dec 27 23:24:09 2009 +0000
  
      Automatic manual updates following libguile docstring changes
      
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 ‘ttn/janitor-doc’ and simply post "rfc: SHA1"?  I can't imagine
huge diffs would be welcome on the list...

thi



^ permalink raw reply	[flat|nested] 7+ messages in thread
* Re: two spaces after sentence + other doc janitorial duties
@ 2010-07-12  0:51 Karl Berry
  2010-07-13 21:13 ` Andy Wingo
  0 siblings, 1 reply; 7+ messages in thread
From: Karl Berry @ 2010-07-12  0:51 UTC (permalink / raw)
  To: dsmich, guile-devel

[Sorry if there has been later replies on this.]

    > >> Why is this the case? TeX itself gets this right, why can't makeinfo?

There is no overwhelming reason, it's just the historical fact that it's
never tinkered with intersentence spaces, aside from trying
half-heartedly to detect sentences at the end of lines.

rms wrote all this stuff originally, and in his world, the source files
all have two spaces at the end of sentences already, for the sake of
Emacs sentence commands.  So there was no reason for him to have
texinfo-format-buffer (or later makeinfo) to do anything.

Perhaps one day it will, it's on the wishlist, but don't hold your
breath.  Sorry.

karl



^ permalink raw reply	[flat|nested] 7+ messages in thread

end of thread, other threads:[~2010-07-13 21:13 UTC | newest]

Thread overview: 7+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2010-06-25 16:35 two spaces after sentence + other doc janitorial duties Thien-Thi Nguyen
2010-06-28 13:57 ` Andy Wingo
2010-07-02 13:23   ` Ludovic Courtès
2010-07-08 10:10     ` Andy Wingo
2010-07-08 17:04       ` dsmich
  -- strict thread matches above, loose matches on Subject: below --
2010-07-12  0:51 Karl Berry
2010-07-13 21:13 ` Andy Wingo

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).