two spaces after sentence + other doc janitorial duties

two spaces after sentence + other doc janitorial duties

[Thien-Thi Nguyen]

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

Re: two spaces after sentence + other doc janitorial duties

[Andy Wingo]

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/

Re: two spaces after sentence + other doc janitorial duties

[Ludovic Courtès]

Hi,

Andy Wingo <wingo@pobox.com> writes:

> 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’m not sure whether/how TeX gets it right.

Two spaces after a sentence is visually the closest thing to English
typography rules, which thereby distinguish end-of-sentence periods from
abbreviation periods, as mentioned in the Texinfo manual (info
"(texinfo) Ending a Sentence").  The GCS also recommends it (info
"(standards) Comments"), and Emacs’ M-e expects it too.

>>   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.

Same for me.  So I’m curious.  :-)

>> 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.

+1

(Likewise, “e.g.” -> “e.g.,”.)

>>  - choose "Returns" or "Return" and use it everywhere;
>
> Sure.

“Return”, I think.

Thanks,
Ludo’.

Re: two spaces after sentence + other doc janitorial duties

[Andy Wingo]

Heya Ludovic,

On Fri 02 Jul 2010 14:23, ludo@gnu.org (Ludovic Courtès) writes:

> Andy Wingo <wingo@pobox.com> writes:
>
>> 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’m not sure whether/how TeX gets it right.

For TeX, the end of a sentence comes when a terminal punctuation mark
(e.g., `.' or `!') is followed by any amount of whitespace, and not
preceded by a capital letter. For example the period after the T in
"I.T. Department" does not end the sentence.

You do have to play tricks with TeX when you're doing something that
doesn't conform to its expectations; see "Inserting Space" in the
texinfo manual.

But since you have to placate TeX already, for print output, it seems
the one-space or two-space shenanigans are completely redundant, and
provide no new information. Info output is already reflowed in
paragraphs, I don't see why its textual rendering doesn't follow TeX's
rules rather than introducing its own redundancies on top of it.

If it is how it must be for GNU, though, then I will try to change. But
I don't like it.

Andy
-- 
http://wingolog.org/

Re: two spaces after sentence + other doc janitorial duties

[dsmich]

---- Andy Wingo <wingo@pobox.com> wrote: 
> Heya Ludovic,
> 
> On Fri 02 Jul 2010 14:23, ludo@gnu.org (Ludovic Courtès) writes:
> 
> > Andy Wingo <wingo@pobox.com> writes:
> >
> >> 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’m not sure whether/how TeX gets it right.
> 
> For TeX, the end of a sentence comes when a terminal punctuation mark
> (e.g., `.' or `!') is followed by any amount of whitespace, and not
> preceded by a capital letter. For example the period after the T in
> "I.T. Department" does not end the sentence.
> 
> You do have to play tricks with TeX when you're doing something that
> doesn't conform to its expectations; see "Inserting Space" in the
> texinfo manual.
> 
> But since you have to placate TeX already, for print output, it seems
> the one-space or two-space shenanigans are completely redundant, and
> provide no new information. Info output is already reflowed in
> paragraphs, I don't see why its textual rendering doesn't follow TeX's
> rules rather than introducing its own redundancies on top of it.

I think it's because the original texinfo -> info formatter was in emacs-lisp,
and wasn't smart enough to DTRT.  I'm not sure if the makeinfo command is smart
enough.

-Dale

Re: two spaces after sentence + other doc janitorial duties

[Karl Berry]

[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

Re: two spaces after sentence + other doc janitorial duties

[Andy Wingo]

On Mon 12 Jul 2010 02:51, karl@freefriends.org (Karl Berry) writes:

>     > >> Why is this the case? TeX itself gets this right, why can't makeinfo?
>
> [history]
>
> Perhaps one day it will, it's on the wishlist, but don't hold your
> breath.  Sorry.

Heh, understood, and thanks for the explanation. Happy hacking!

Andy
-- 
http://wingolog.org/