Heya,
On Fri 25 Jun 2010 18:35, Thien-Thi Nguyen <t...@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 <n...@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/
