Re: two spaces after sentence + other doc janitorial duties

[Andy Wingo <wingo@pobox.com>]

Heya,

On Fri 25 Jun 2010 18:35, Thien-Thi Nguyen <ttn@gnuvola.org> 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 changes
> 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 <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 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 ‘ttn/janitor-doc’ and simply post "rfc: SHA1"?  I can't imagine
> huge diffs would be welcome on the list...

Sure, sounds fine to me.

Andy
-- 
http://wingolog.org/