develooper Front page | perl.perl5.porters | Postings from March 2023

Proposal: Standardize to one space after full stops indocumentation, pod, comments, etc.

Thread Next
From:
demerphq
Date:
March 16, 2023 18:49
Subject:
Proposal: Standardize to one space after full stops indocumentation, pod, comments, etc.
Message ID:
CANgJU+U9MAnfQAAbDZ6TXtgzT_BnW_cs-JVx8xmgiMZUBDPzxA@mail.gmail.com
TLDR: Single space after a full stop is easier to automate, the current
standard taught in school, and minimally impacts reading speed. Let us make
the standard be one space after a full stop.

Traditional typesetting rules would put two spaces after a full stop (known
to North Americans as the "period"[1]) in documentation. This is what I was
taught in school, and I suspect that most people over a certain age learned
in school as well. In modern context however it seems that this convention
is no longer considered correct. The general argument seems to be that two
spaces makes some sense in monospaced text, but for text written using
proportional fonts it is no longer appropriate and considered archaic
looking. For instance, modern typesetting using proportional fonts will
often use an "em-space", that is a space which is the width of a capital M
character after a full stop, and this width is typically about 1.5 "spaces"
wide in a monospaced font.

In our documentation we have a mixture of the two styles. Depending on who
wrote the docs (and also whether the text has been touched by any
autoformatting tooling), the text may use two spaces after a full stop, or
one. Ever since I discussed this subject with Karl W, and he passionately
preferred two spaces, I have /tried/ to use 2 spaces consistently, *but*, I
find that it adds a tedious amount of extra work to maintaining our docs
and after some thought I believe we should standardize around 1 space.

The primary reason I think we should standardize around 1 space is that it
is relatively difficult to write software that can identify a full stop as
a full stop and do the right thing. At the very least it has more edge
cases to consider. For instance, a full stop followed by a newline does not
need any spaces at all, the single "space" character of the newline is
sufficient. If you look at tooling like Text::Wrap, Text::Autoformat, etc,
none of them even try to add two spaces after a full stop, presumably
because of difficulty in identifying a dot in the text as a full
stop. Consider for instance an abbreviation of a honorific like "Dr. Who",
the dot in this case is not a full stop and should not have two spaces
after it, and to make things worse, it is followed by a name, which should
be capitalized, thus defeating the most obvious rule for when to inject two
spaces: "after a dot which is followed by a word which is capitalized". I
personally have Text::Autoformat bound to a keypress in my editor, and I
routinely use it to reformat text in commit messages, comments, and other
text. (I even asked Damian Conway to enhance Text::Autoformat's support for
C comments!)

I wrote some code some time back which was intended to auto format all of
our documentation, side-bar comments, and etc, so that they respected our
"80 column preference". This revealed many cases where the documentation
uses a two space after full stop, and when Karl reviewed the patch sequence
he pointed out the issue, so I spent some time trying to come up with
tweaks to the existing autotformat tools, and discovered that there are a
lot of edge cases. "etc.", "e.g.", "i.e.", "Inc.", there are also a lot of
places where we spell out file extensions (without quoting them), such as
.t and .c in our code, which also make the rules difficult to manage.

Of late I have found myself often using Text::Autoformat to reformat text,
and then having to manually go through it afterwards to add the second
space after full stops that don't end a line. This is tedious, and IMO not
of particular usefulfulness to the project.

So I would like to propose that we standardize our text to use one space
after a full stop, and make it "ok" to reformat any text that uses two
spaces after a full stop to have only one. Such matters should be left up
to rendering tools, and we should not impose tedious manual work on our
devs.

What do folks think?

Some references:One space:
https://www.grammarly.com/blog/spaces-after-period/
https://www.masterclass.com/articles/how-many-spaces-after-a-period
https://www.writing-skills.com/one-space-two-full-stop
https://www.thesaurus.com/e/writing/is-there-1-space-or-2-after-a-period/

Two Space (But!)
https://www.independent.co.uk/tech/one-space-or-two-spaces-after-a-full-stop-scientists-have-finally-found-the-answer-a8337646.html
"Reading speed only improved marginally, the paper found and only for the
21 “two spacers”, who naturally typed with two spaces between sentences.
The majority of one spacers, on the other hand, read at pretty much the
same speed either way. And reading comprehension was unaffected for
everyone, regardless of how many spaces followed a period."

Cheers,
Yves

[1] This is one of those cases where in fact the US term is arguably more
historically correct than the UK usage. Both are valid terms, but "period"
predates the term "full stop" by some time, and US typesetters and language
kept the older term while the UK usage standardized around the newer term
"full stop". On the other hand, the UK usage has the advantage that it
makes the difference between a dot used for abbreviation, and the dot used
to end a sentence more explicit. Anyway, for those that care about such
things the reason that the US and Canada use the term "period" but the UK
uses the term "full stop" is interesting enough to justify some
research. The wikipedia article is a good starting place:
https://en.wikipedia.org/wiki/Full_stop

-- 
perl -Mre=debug -e "/just|another|perl|hacker/"
Thread Next

nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About