Mailing List Archive

Hi there,

On Thu, 16 Mar 2023, demerphq wrote:

> 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.
> ...
> ...
> What do folks think?

I'm with Karl. Don't do it. Even if you convince Karl to change his
mind, still don't do it.

--

73,
Ged.

I'm all for the standardization of this and similar things such as the
indentation.

The proposed standard is sane and should be the default.

Thanks Yves for your intensive work with Perl this year.


On Thu, Mar 16, 2023 at 10:50?PM demerphq <demerphq@gmail.com> wrote:

> 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/"
>

On 3/16/23 14:49, demerphq wrote:
> 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.

I never learned full stop/dot, two spaces in school. It was always one.

+1 for single space for me.

Cheers,
Wesley

--
Wesley Schwengle

On Thu, Mar 16, 2023 at 7:49?PM demerphq <demerphq@gmail.com> wrote:

> 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.
>
> <https://www.independent.co.uk/tech/one-space-or-two-spaces-after-a-full-stop-scientists-have-finally-found-the-answer-a8337646.html>
>
I was taught two spaces in typing classes in high school, and later in word
processing classes. The software (Scriptsit) that we used supported it,
inserting a special triangle character for two spaces so we could instantly
recognize it. I've used two spaces ever since I've learned to type, 40
years ago.

Yet I support one space, despite my finger memory. This is a good change.

Best,
Ovid

I too strongly favour adopting consistent single spaces after full stops.

Despite also having been taught double-spacing, way back in my Early
Jurassic schooldays,
I never double-space my own text or comments, and I have no plans to ever
offer a
double-spacing option in Text::Autoformat (because of the near-endless
supply of
false-positive edge-cases that Yves has already mentioned).

Although, just out of interest, I gave the following made-up Perl comment
to ChatGPT 3.5:

# Don't try this at home, kids! We need these etc. so we can pretend
that they
# are built-in constructs. It's very cheeky (like Dr. Who) to be
messing with builtin pragmas,
# but these intrusions et al. are careful not to hook any existing
behaviour. They only
# add simulations of the proposed new behaviour. I judge that to be
marginally
# more acceptable. Especially if they are invoked only explicitly, by
loading this module.

I then asked it to double-space between sentences . It returned the
following (which it got 100% right):

# Don't try this at home, kids! We need these etc. so we can pretend
that they
# are built-in constructs. It's very cheeky (like Dr. Who) to be
messing with builtin pragmas,
# but these intrusions et al. are careful not to hook any existing
behaviour. They only
# add simulations of the proposed new behaviour. I judge that to be
marginally
# more acceptable. Especially if they are invoked only explicitly, by
loading this module.

So I guess, once we upgrade Text::Autoformat to a 175-billion-parameter
large language model,
Yves won't have a problem any more.

Till then, however, I support this proposed change.

Damian

On Thu, 16 Mar 2023 19:49:27 +0100, demerphq <demerphq@gmail.com> wrote:

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

As with mixed indent: I am in the camp of not caring at all.

It does not speed up or slow down my reading speed: that is very slow
as it is already. Maybe this is more important to the native English
tongues

--
H.Merijn Brand https://tux.nl Perl Monger http://amsterdam.pm.org/
using perl5.00307 .. 5.37 porting perl5 on HP-UX, AIX, and Linux
https://tux.nl/email.html http://qa.perl.org https://www.test-smoke.org

On 3/16/23 12:49, demerphq wrote:
> 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.
>

The bottom line for me personally, is if this rule were adopted, I would
quit the project.

One reason is because of muscle memory. I have been following the two
spaces rule for quite a bit longer than Damian. It would be hard for me
to stop.

But more importantly, I would lose respect for a project that sought to
dictate what's basically an aesthetic issue that has no bearing on the
correct functioning of our product. Timtoady abandoned.

It is not true that tooling is hard. This pretty much does it:
s/\. (*nla: )/. /g
It enforces the two space rule. Use of \B{sb} matching before the dot
and a lookup hash of exceptions would improve the results.

I didn't see anyone say that the two spaces is less readable than
single. Rather, the arguments admit the single space has a negative
effect but try to minimize that importance. So why standardize on
something that is less readable (however small you may think it is) when
we could easily standardize on something that is more readable.

The argument that everybody else is doing it are specious. The links I
followed say not doing it is because of the advent of proportional
fonts. They are assuming a WYSIWYG editor. But I can't imagine using
such an editor for writing code or pod. Those arguments simply are not
applicable to our situation.

Bringing up "e.g.," and ".t" is also irrelevant as there is no space
after any period there.

If you recoil at my suggestion of instead enforcing a two-space rule,
Why? The source is easier to read, and any documentation that gets
formatted for output will have the formatter's rules imposed upon it.
Proportional font output will have the spacing evened out between words
on a line; and the current groff for fixed fonts simply strips off the
second space. (The original nroff did honor them.) This means there is
essentially no effect on users reading documentation.

As another example of tools that work: vim has done a fine job of
wrapping comment blocks, for decades, without AI.

And I have come to believe that code should not be reformatted
automatically at all. I don't think it can be done well enough.
(Expanding tabs into the appropriate number of spaces is not really
reformatting, and is ok.)

Part of that is informed by the recent changes to embed.fnc. The
entries are now sorted and grouped better, which is good, but the #if's
that I and others so carefully wrote out in such a way as to make it
easier to follow the why and wherefore of them, are trashed. Often, the
most important condition has been moved from first to last. This is a
big step backwards, making it harder to maintain.

I write a lot of comments that use vertical alignment to clarify and
make things easier to read. It's just not a good idea to try to second
guess how people have formatted their stuff. I don't object if others
want to follow the single space rule for their code; I just am unwilling
to be forced to follow their aesthetic, nor have my code automatically
formatted to follow it.

The bottom line from a project point of view is that we already are too
intrusive in automatic formatting; it can't be done well enough, so we
shouldn't add more. And there really is no need to make single space
(or double space) a standard. Leave it up to the coder.

If you were one of those who recoiled at the idea of a two space rule.
Again why? I believe I demonstrated it was better than the one space
one. So why would you recoil? My guess is it would be that you
wouldn't want to have my aesthetic imposed on you, but have no problem
imposing yours on me. That's not perly. But it's best to not have such
a picayune rule at all.

Karl Williamson

* perl5@tux.freedom.nl <perl5@tux.freedom.nl> [2023-03-17 11:53:37 +0100]:

> On Thu, 16 Mar 2023 19:49:27 +0100, demerphq <demerphq@gmail.com> wrote:
>
> > 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.
>
> As with mixed indent: I am in the camp of not caring at all.
>
> It does not speed up or slow down my reading speed: that is very slow
> as it is already. Maybe this is more important to the native English
> tongues

Doesn't matter, but same here. I do more so pay attention to line
widths and find vertical "rivers"* extremely distracting. HTML
collapses consecutive spaces anyway, which I think is why people
have forgotten this rule.

* https://en.wikipedia.org/wiki/River_(typography)

Somebody once said, don't take down a fence until you know why it
was put there in the first place. WWW and the fog of HTML might be
the reason we might not "care" about it.

Anyway, there is a reason this double spacing happens. What is it?

Here's some science on the matter, I mean if anyone trusts it
anymore:

* https://en.wikipedia.org/wiki/Sentence_spacing#Studies

Wikipedia's article claims improvement are dubious and describes
conflicting results.

Cheers,
Brett

>
> --
> H.Merijn Brand https://tux.nl Perl Monger http://amsterdam.pm.org/
> using perl5.00307 .. 5.37 porting perl5 on HP-UX, AIX, and Linux
> https://tux.nl/email.html http://qa.perl.org https://www.test-smoke.org
>



--
--
oodler@cpan.org
oodler577@sdf-eu.org
SDF-EU Public Access UNIX System - http://sdfeu.org
irc.perl.org #openmp #pdl #native

On Fri, Mar 17, 2023, at 13:57, Karl Williamson wrote:
> But more importantly, I would lose respect for a project that sought to
> dictate what's basically an aesthetic issue that has no bearing on the
> correct functioning of our product. Timtoady abandoned.

So, first I want to say why I disagree with Karl, but then I'm going to agree with him in the end. Just so you're prepared.

Here are three presentations of some code. First, as stored in the repository:
if (name)
Perl_sv_catpv(aTHX_ report, name);
else if (isGRAPH(rv))
{
Perl_sv_catpvf(aTHX_ report, "'%c'", (char)rv);
if ((char)rv == 'p')
sv_catpvs(report, " (pending identifier)");
}
else if (!rv)
sv_catpvs(report, "EOF");
else
Perl_sv_catpvf(aTHX_ report, "?? %" IVdf, (IV)rv);
switch (type) {
case TOKENTYPE_NONE:
break;
case TOKENTYPE_IVAL:
Perl_sv_catpvf(aTHX_ report, "(ival=%" IVdf ")", (IV)lvalp->ival);
break;

Then, as I would format it:
if (name) {
Perl_sv_catpv(aTHX_ report, name);
} else if (isGRAPH(rv)) {
Perl_sv_catpvf(aTHX_ report, "'%c'", (char)rv);
if ((char)rv == 'p') sv_catpvs(report, " (pending identifier)");
} else if (!rv) {
sv_catpvs(report, "EOF");
} else {
Perl_sv_catpvf(aTHX_ report, "?? %" IVdf, (IV)rv);
}

switch (type) {
case TOKENTYPE_NONE:
break;
case TOKENTYPE_IVAL:
Perl_sv_catpvf(aTHX_ report, "(ival=%" IVdf ")", (IV)lvalp->ival);
break;

Then, whimsically:
if (name) Perl_sv_catpv(aTHX_ report, name);
else if (isGRAPH(rv)) {
Perl_sv_catpvf(aTHX_ report, "'%c'", (char)rv);
if ((char)rv == 'p')
sv_catpvs(report, " (pending identifier)");
}
else if (!rv) sv_catpvs(report, "EOF");
else Perl_sv_catpvf(aTHX_ report, "?? %" IVdf, (IV)rv);

/**/

switch (type) {
case TOKENTYPE_NONE: break;
case TOKENTYPE_IVAL: Perl_sv_catpvf(aTHX_ report, "(ival=%" IVdf ")", (IV)lvalp->ival);
break;

These (modulo any accidental error I introduced) are aesthetic issue that has no bearing on the correct functioning of our product. But we don't want to continually mix them all throughout the source code, these and many other style intertwined and shifting around as code is rewritten.

The product will function either way, but one gets in the way of just dropping into any part of the code and reading it for content. The varied form obscures the (unchanged) function from the would-be editor. So I strongly believe that it is a good idea for a software project to enforce aesthetic choices for the good of the project. In a language that's more amenable to static analysis, I'd also say that automatic enforcement of style is not necessarily an evil.

That said… one of two spaces after a full stop does not strike me as something the casual editor will notice. It is not something whose variance between parts of the code is going to cause strife. This sounds like forcing an aesthetic choice for the sake of some automated bit of tooling, at cost to humans. So, the cost to humans who are now hitting "space space backspace" every sentence has to buy something pretty valuable. *What is that?*

Yves said that the primary problem was that "it is relatively difficult to write software that can identify a full stop as a full stop and do the right thing". So, what software is it that we need to run against our comments, and which has to be so unerring that we want to change how people write prose?

--
rjbs

TLDR: I do not want anyone to stop hacking on my perl becuase of my
proposal, and therefore I withdraw my proposal. My intention is not that
anyone should follow /my/ style, but rather to free myself and the rest of
the developers on the project from thinking about style at all, by using
tooling to enforce /a/ consistent style. The style I proposed is merely the
one that I think is the most available (in terms of tooling) and thus the
least worst option to follow. I just want to be able to fix the wrapping
on text after it has been search and replaced or otherwise modified with a
keypress or a tool. I do not want spend any more time than absolutely
necessary thinking about style. Computers were supposed to free us from
tedious work, not be the source of new forms of it, and all i want to do is
use tools to ensure that we meet the requirements of our tests and broader
comprehension requirements.

On Fri, 17 Mar 2023 at 18:57, Karl Williamson <public@khwilliamson.com>
wrote:

> On 3/16/23 12:49, demerphq wrote:
> > 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.
> >
>
> The bottom line for me personally, is if this rule were adopted, I would
> quit the project.
>

FWIW. I have mixed feelings about this comment. The prevailing feeling I
have is that you are a very valuable contributor to the project, and
someone who I consider a friend, and I would hate that an action of mine
was the reason for you to leave the project, so I withdraw the proposal to
make a rule about this.

To repeat, because of what you say here I *withdraw* my rule proposal.

However there is a secondary level which I feel I should mention. This kind
of comment makes me really uncomfortable, as you are essentially saying
"unless the project plays by my rules I will walk". My normal response to
that kind of statement from /anyone/ would be "ok walk then", just on
principle; no person is important enough to the project that they should
get to unilaterally set the rules or hold the project hostage to their
policy demands, and I personally would do my best to avoid making that kind
of statement, and instead would leave it implicit in wording like "Such a
policy would strongly discourage my participation in the project" or
something to that effect. It expresses the same thing but without the
hostage implication that triggers my principled response.

Regardless, I don't want you to walk, especially not over /this/ so I
withdraw the rule proposal. But I really wish that you hadn't said it like
that. It sets an ugly precedent.


>
> One reason is because of muscle memory. I have been following the two
> spaces rule for quite a bit longer than Damian. It would be hard for me
> to stop.
>

So what stops you from using tooling like Text::Autoformat, or similar to
format your comments just like I do? Then you wouldnt have to learn to stop
and you would likely save time worrying about how the text is wrapped as
well.

Part of my objection to the two space rule is that I dont want to spend
time thinking about wrapping prose. I want to use software to wrap my
prose. I want to be able to write my text however I like, and then
highlight it and hit a key press, and "poof" have it formatted correctly.
Or I want to write a search and replace, or a perl -i command and fix up a
bunch of things across multiple files, and then be able to easily have the
text autowrapped. Especially as we have tests that will fail if POD text is
too wide. Reading text that is all "zig-zaggy" in terms of line length is
annoying, having it roughly the same width is a win. Being able to get
prose into that format without a lot of effort is really helpful.

I likely would care much less about this subject if it werent for those
tests. If we ditched the POD lines must be so long tests, then I probably
would not care about wrapping pod as much as I currently do. But we do have
test for line length for POD, and if I rename a constant in our code so it
is wider, and that then results in the POD in some prose you wrote starting
to fail test I want to be able to highlight it and wrap it and move on.


> But more importantly, I would lose respect for a project that sought to
> dictate what's basically an aesthetic issue that has no bearing on the
> correct functioning of our product. Timtoady abandoned.
>

I dont have an issue with Timtoady. I have an issue with having to tasks
manually that should be delegated to software. I /loathe/ makework.

Let me illustrate my point here with code style. I do not necessarily want
there to be a single style for code in our files. I like my personal style,
and in the files I created I like that the file follows my style. However
I know that other folks find my style a little jarring, and I know that
their finger memory is different from mine and they find it hard to follow
my style. That is why i go out of my way to put documentation in the Perl
code I have contributed to the project for a perltidy recipe that can be
used to format the file correctly. I want others that need to work on the
file be able to forget our style differences, focus on the problem at hand
and use tooling to resolve our differences. So if it were up to me every
perl script we have would have a well defined "perltidy definition block",
and we would have a tool that autoextracts that definition and formats our
files according to its documented rules.

The point here I am making is that I do not want uniformity, I want tooling
that automates these decisions so that I don't have to worry about
the rules. I do not want H. Merijn Brand, nor Abigail (both
contributors who also have what might called an "esoteric style") to adopt
my coding style, I want to use automation so that I don't need to worry
about their styles, and so that other folks don't need to worry about my
own. For instance recently I worked on Porting/sync-with-cpan. This file
contains a mixture of styles, some from Abgail, some from other people. In
a single statement or subroutine there are vestigal elements of multiple
styles, for instance function calls where there is a space after the
function name and then parenthesized options combined with other function
calls where there is no space. I find that mixture of different styles
/incredibly/ jarring, and I am never sure what to do. The normal rule of
thumb from Larry is that people should follow the style of the file. But
that is hard when it is alien to you and there is no tooling to support it.

All of the above is about code. And luckily perltidy is incredibly powerful
and customizable and its author, Steve Hancock, is a great guy who will add
features to support different peoples style providing he can figure out a
way to do so. Merijn and I both have had patches accepted by him, or
features added by him to reflect our style desires. I *wish* there were a
tool of similar flexibility and capability for our C code. I tried to find
one and basically the options in the C world suck.



> It is not true that tooling is hard.


I just don't agree. I tried and it is hard enough that like Damian I
decided I don't want to play this game. Reminds me of War Games: "The only
way to win is not to play.".

Autoformatting text so it respects the gamut of human formatting
conventions, AND also handles wrapping, and this rule is non-trivial, it is
hard. There are loads of edge cases.


> This pretty much does it:
> s/\. (*nla: )/. /g
> It enforces the two space rule. Use of \B{sb} matching before the dot
> and a lookup hash of exceptions would improve the results.
>

perl -le'$_="Dr. Who etc. and et. al. is a great show."; s/\. (*nla: )/.
/g; print '
Dr. Who etc. and et. al. is a great show.

Doesn't look great to me. And it doesn't deal with no leaving trailing
whitespace at the end of a line.


>
> I didn't see anyone say that the two spaces is less readable than
> single. Rather, the arguments admit the single space has a negative
> effect but try to minimize that importance.


No, that isnt correct. The one with a study said that people who were
trained to put two spaces after a dot had a faster comprehension. For
people who were not trained there was no difference.


> So why standardize on
> something that is less readable (however small you may think it is) when
> we could easily standardize on something that is more readable
>

Because it is not easy.


> The argument that everybody else is doing it are specious. The links I
> followed say not doing it is because of the advent of proportional
> fonts. They are assuming a WYSIWYG editor. But I can't imagine using
> such an editor for writing code or pod. Those arguments simply are not
> applicable to our situation.
>
> Bringing up "e.g.," and ".t" is also irrelevant as there is no space
> after any period there.
>

Well I mentioned .t because it comes up with automating detecting if
somthing is a full stop or not. Perhaps I should have omitted that point,
but your claim that "e.g." is irrelevant is just wrong as a simple git grep
will show:

git grep -P 'e\.g\. \w' pod | head -n 10
pod/perl5004delta.pod:was called as a plain function (e.g. C<Foo::bar()>),
not a method
pod/perl5004delta.pod:(e.g. C<< Foo->bar() >> or C<< $obj->bar() >>).
pod/perl5004delta.pod:This now works. (e.g. C<delete @ENV{'PATH',
'MANPATH'}>)
pod/perl5004delta.pod:a fixed value are now inlined (e.g. C<sub PI () {
3.14159 }>).
pod/perl5004delta.pod:requested with the ":flock" tag (e.g. C<use Fcntl
':flock'>).
pod/perl5004delta.pod:were csh (e.g. C<full_csh='/usr/bin/tcsh'>);
otherwise, make them all
pod/perl5005delta.pod:on the operator (e.g. C<CORE::log($x)>) or by
declaring the subroutine
pod/perl5005delta.pod:package, e.g. bless($ref, $p || 'MyPackage');
pod/perl5005delta.pod:e.g. C<&our()>, or C<Foo::our()>.
pod/perl5100delta.pod:(e.g. with C<@ISA = @ISA>).

The cases with POD are great examples of the hidden complexity here that
belies your claim this is easy. "e.g. C<&our()>" is a good example.
Neither dot in "e.g." is a full stop, and neither should have two spaces
after it.


>
> If you recoil at my suggestion of instead enforcing a two-space rule,
> Why?


Because I find myself doing search and replace, or manual edits on existing
prose all the time such that the text grows and changes and requires
rewrapping when I am done. Partly it requires rewrapping because of our POD
tests will *fail* if it isnt rewrapped, and partly it requires rewrapping
for readability.

As I said above, I don't want a specific style, I want to be able to
automate these updates so that when I finish updating comments or POD docs
I can rewrap with software.

Damian has written "Text::Autoformat" so that you can easily do fairly
advanced text wrapping and reformatting activities without having to think
about it. He extended it to handle C comments at my request recently
(which works pretty well, although I still owe him detailed feedback on it)
and to handle pod directives properly (eg NOT wrapping POD).
Text::Autoformat is really nice, it handles outdenting 'NOTE:' type text,
and various other task (like rewrapping email content) in a nice way that
does a good enough job often enough that I use it for almost all text I do
in my text editor. (Not in gmail obviously.)

If you could point me at a script that wraps or replaces Text::Autoformat
that allows me to do what I can currently do and enforces your desired
formatting rules then I would be fine with using it. Until then I think I
will apply "Timtoady" as you have said here and when I need to reformat
paragraphs you wrote with two spaces after periods I will just let the
tooling replace it with one space and just Not Feel Guilty About It. For
the last while I have been spending time going back through to do the
teduous task of adding the double spaces back.

The source is easier to read,


For you. Not for me. I find reading both styles equally easy.


> and any documentation that gets
> formatted for output will have the formatter's rules imposed upon it.
> Proportional font output will have the spacing evened out between words
> on a line; and the current groff for fixed fonts simply strips off the
> second space. (The original nroff did honor them.) This means there is
> essentially no effect on users reading documentation.
>

Like I said, my concern is the time i need to spend to fix comments and
docs. Ideally I would spend as close to 0 time as I can to wrap text. If
reducing that time means giving up double spaces after periods then I am
fine with that. I do not see any impact from it at all personally.


> As another example of tools that work: vim has done a fine job of
> wrapping comment blocks, for decades, without AI.
>

Not in my experience.


>
> And I have come to believe that code should not be reformatted
> automatically at all. I don't think it can be done well enough.
> (Expanding tabs into the appropriate number of spaces is not really
> reformatting, and is ok.)
>

Aren't you contradicting yourself here? First you say its easy, adn not you
say it can't be done well enough. Which is it?


> Part of that is informed by the recent changes to embed.fnc. The
> entries are now sorted and grouped better, which is good, but the #if's
> that I and others so carefully wrote out in such a way as to make it
> easier to follow the why and wherefore of them, are trashed. Often, the
> most important condition has been moved from first to last.


I'd like a solid example of that. I think in most regards getting the
defines right and understanding if you were duplicating a set of defines
was a bigger maintenance burdern than anything that happens now.


> This is a
> big step backwards, making it harder to maintain.
>

I dont agree at all. The older code was much harder to maintain when doing
something like splitting up a large file like regcomp.c or moving code
around between different defines. And the varying ways of writing the list
of defines meant that you could have two identical blocks that were created
by different people and laid our differently from each other. Making it
more difficult to understand what was happening. And the generated files
that were coming from it would pseudorandomly change due to the way tha the
clauses were sorted together.

I think if you have an issue with embed.fnc you should reach out to me
privately, or via a separate thread. We can adjust the automation as you
wish. But there is no way I will ever agree that we should all just
randomly do what we think looks best and end up a bunch of different styles
in a jumble with no checking or validation or anything like that.



> I write a lot of comments that use vertical alignment to clarify and
> make things easier to read. It's just not a good idea to try to second
> guess how people have formatted their stuff. I don't object if others
> want to follow the single space rule for their code; I just am unwilling
> to be forced to follow their aesthetic, nor have my code automatically
> formatted to follow it.
>

The thing is I often find that when you do this it is NOT easier to read,
at least for me, and to make it worse, it is much more costly for me to
update the code after you have done thse things. Every time I am forced to
make a decision about whether I should just ignore your preferences, or if
I should take the time to manually make the code meet what I think are your
preferences and the time I spend wondering if I should do this or that to
avoid having to think about your expectations. (I have posted patches that
replace certain types of code with macros just so that I didnt have to deal
with some of your expectations about how to lay out the code when it became
mult-line.) I would have no objection to this if it was managed by a tool;
I'd just use the tool and be done with it. But often it requires manual
work that IMO I shouldn't have to do.


> The bottom line from a project point of view is that we already are too
> intrusive in automatic formatting; it can't be done well enough, so we
> shouldn't add more. And there really is no need to make single space
> (or double space) a standard. Leave it up to the coder.
>

I dont agee. I think we should be using automatic formatting on everything.
Then everyone is treated equally, we can all learn and get used to whatever
the standard is, and most importantly we won't have to spend time on
dealing with these questions manually.

Some time back a bunch of people got really riled up when I suggested we
change our rules regarding line length. I would much prefer it if we used a
120 or 140 characters per line maximum, instead of the 80
character maximum. But the community as a whole said "no we prefer 80
columns", and I do my best to live with that decision, and in fact that
decision is part of the reason we are having this conversation. 80
characters is sufficiently short that I find that almost any edit to
existing text results in /some/ of the text going over 80 characters. As
such I have invested the time to use tooling to format code and prose to
those line limits. I would like to be able to use even more tooling to meet
these limits.


> If you were one of those who recoiled at the idea of a two space rule.
> Again why?


Because of the dearth of tooling that allows me to automate the task of
laying out text in comments and pod blocks to satisfy it.

We have tests that nag me if my POD lines are too long. POD does not
actually care how long lines are, and I certainly wouldn't willingly
inflict a 80 column rule on myself if I could avoid it. So I want to be
able to edit POD (and comments) and just hit the "reformat text" key in my
editor and have it pass the tests and be reasonably readable. I do NOT want
to waste my time with such matters, I want to automate it away. If I could
reliably automate your style I would and we wouldnt be having this
conversation, but as has been stated elsewhere (including by you), some
types of formatting are "automation unfriendly", and teaching humans is
easier than teaching computers.


I believe I demonstrated it was better than the one space
> one.


I dont think you did. The studies out there show that people who *expect*
the two spaces read less well without it. For those who do not have
that expectation there is no difference. And the difference is extremely
minor even when it is apparent. It is very grey area as to whether it makes
a difference really.



> So why would you recoil? My guess is it would be that you
> wouldn't want to have my aesthetic imposed on you,


No, that isn't correct. If there was tooling that automated your style
which I could use then I would use it and presumably we wouldn't be having
this conversation. There isn't and I suspect the reason there isn't is
because it is a harder problem than you admit.

> but have no problem imposing yours on me.

Characterizing it as "my style" is not fair. I actually *would* prefer if
all of our comments and docs used the double space after a full stop model,
as I said in my original post I also come from the time period where that
was the standard. The only reason I want to standardize it to a
single space is that there are no good tools to help me achieve that style,
and there is a large group of people younger than me who don't think the
rule exists at all so I want to make them feel comfortable as well.

BTW, as I recall you were one of the people who favoured an 80 column limit
for our code when I was asking for something wider. Why was imposing that
expectation on me ok, but me suggesting this not ok?

The advantage of having a standardized set of tooling which manages
formatting is that it side-steps these kinds of discussions. I don't get
everything I want (140 column text), and you dont everything you want (two
spaces after a full stop), but most importantly we don't argue about who
gets what they want, it comes down to what the tool does or can do. I dont
want you to have to manually follow /my/ style, and I dont want to have to
manually follow /your/ style. I just want to be able to use a tool so that
I dont have to worry about style at all and leave it up to tooling instead.
If that means I don't get every one of my preferences respected it still is
a big win for me and the project because /nobody has to to think about
it/. If you gave me a tool that formatted stuff the way you liked, and the
rest of the community agreed we should use it then I would be happy to use
it.


That's not perly. But it's best to not have such
> a picayune rule at all.
>

Sure, but if we go that way then I reserve the right to reformat any text I
feel necessary to reformat in my style without feeling guilty at all. I
just wanted a rule about this so that it was clear that it is not an error
to replace two spaces after a period with one space if I need to. It seems
that not having a rule has the same outcome, so then I am happy I guess. I
would prefer that we came to a consensus that using specific tooling to
enforce whatever conventions we want to follow is better than expecting
everyone to follow each other's style manually. Going back to code now, my
experience is that outside of one developer I have worked most people do
have a consistent style even if they think they do. I know from running
perltidy on my own code that I often violate my own preferences in minor
and subtle ways.

Yves


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

On Thu, 16 Mar 2023 19:49:27 +0100, demerphq <demerphq@gmail.com> wrote:

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

While well meant, the solution here shoots past the /achieve.

Some experience from my time in the field indicates the best solution here is to apply a lenient measurement and test that complains when a test suite is run, and leaves it to the author whether to ignore it or apply changes.

In my particular case this stems from having a perl critic script that complains about policies, but only considers the changes of the past few commits, skipping files that have not been changed substantially. Even myself will often ignore it on account of time constraints, but on the whole it helps without being a hindrance.

```

use Test::Perl::Critic 'critic_ok';

...;

critic_ok($_) for big_perl_changes_since_previous_commit();

sub commits { "HEAD~" . ( $ARGV[0] // 1 ) }
sub git_diff { capture qw( git diff ), shift, commits(), @_ }
sub change_count { ( split ' ', ( git_diff "--stat", $_[0] )[0] )[2] }
sub change { change_count( $_[0] ) / capture " <$_[0] wc -l " }

sub big_perl_changes_since_previous_commit {
const my $LIMIT_FOR_SELECT => 0.05;
return
## skip files with minor changes
grep change($_) >= $LIMIT_FOR_SELECT,
## skip deleted files from git history
grep -e,
## perl files only (also split on newline)
map /^(.*[.](?:pm|pl|psgi|t))$/,
## files in recent commit range, including outstanding changes
( git_diff "--name-only" );
}

```

(Cheers to mst for some of the fine-tuning on this.)

--
With regards,
Christian Walde

On Sat, Mar 18, 2023 at 4:16?PM demerphq <demerphq@gmail.com> wrote:


> Part of my objection to the two space rule is that I dont want to spend
> time thinking about wrapping prose.
>

As someone who's not a core committer, I recognize that my opinion should
not have the same weight, so please take what I say with a grain of salt,

Arguments over formatting are soul-destroying. I have never found them
productive. However, the arguments are persistent and they can be a serious
time sink.

When I put together a team to release Test::Harness 3.0, one extremely
talented developer objected to my coding standard on the grounds that "only
amateurs use four space indent."

Because I was running that project, I put my foot down over a .perltidyrc
file and mandated its use. I *hated* the format it produced, but because we
found a compromise, I swallowed my pride because for me, it was more
important that we develop than argue over formatting. It shut down the
arguments and we were able to focus on delivering 3.0.

Later, at the BBC, I wasn't running the project I was on, but I pushed hard
for a similar approach. There was one holdout, a developer who also
couldn't stand the output (in part for reasons that the entire team,
including myself, agreed with), and he was given permission to spend some
time augmenting Perl::Tidy with PPI to get that preferred format. I bet our
team lead five quid that he would fail. I won that bet. That was time spent
on fixing a personal preference rather than building value.

Given what I do now, I often have the luxury of dictating a .perltidyrc
file and a test to ensure that all code respects that. I still hate its
output, but it works. In ten years of our consulting firm, we've only had
one argument over formatting and the developer in question won because he
was able to provide a .perltidyrc file that respected his choice. I just
hit ,pt in my editor and it does the right thing.

To my surprise, I've found that a few of the consultants we've worked with
have gone on to apply this to their other clients' projects. Seems they
prefer not arguing over formatting.

Me? For POD, I prefer two spaces after a full stop instead of one because
I've been using two spaces for decades. If we can find a way to automate
this and people agree, I'd be happy. However, if we agree on one space,
three spaces, a tab, *whatever*, I don't care. I'd go with it so long as we
can automate it. I can write POD and let some automated tool take it over.
Again, I know I'm not a committer, but I hope sharing my first-hand
experience might help.

So whatever is decided, I'm neutral on it, but formatting arguments are
soul-destroying to me. The Perl community has had enough soul-destroying
arguments. Please let's find a compromise :)

Hugs,
Ovid

On Sat, 18 Mar 2023 at 19:31, Christian Walde <walde.christian@gmail.com>
wrote:

> On Thu, 16 Mar 2023 19:49:27 +0100, demerphq <demerphq@gmail.com> wrote:
>
> > 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".
> >
> > 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.
>
> While well meant, the solution here shoots past the /achieve.
>
> Some experience from my time in the field indicates the best solution here
> is to apply a lenient measurement and test that complains when a test suite
> is run, and leaves it to the author whether to ignore it or apply changes.


> In my particular case this stems from having a perl critic script that
> complains about policies, but only considers the changes of the past few
> commits, skipping files that have not been changed substantially. Even
> myself will often ignore it on account of time constraints, but on the
> whole it helps without being a hindrance.
>

Interesting notion, but we don't want people merging patches that fail
test.

My intent and desire is to produce and use tooling that ensures our files
are formatted in some consistent manner. Once those tools exist I dont have
to worry about my own personal style, I just have to ensure I run the
tools. IOW, I dont want to have to think about it. I want tools to think
about it.

As I said in my TLDR, I want to free people from thinking about style
because there is tooling in place that ensures that the style is consistent
and meets "regulations" and that if they use the tooling all will be well.
I dont want tests that nag me when I fail to comply, especially if there
isn't tooling to make sure my code complies with the rules, that is just
torture to me. Assuming there is tooling that makes sure my code is
compliant with the rules I'd rather prefer that it gets executed
automatically so I dont have to think about it than getting nagged about it.

I generally think computers and software should free me from having to do
tedious tasks, and they should not be the source of new tedious tasks.
Sometimes this means adjusting my own expectations and adopting rules that
make it easier for the tooling to know what is going on so that they can do
the job.

Just think about how the vast majority programming languages are
structured. They aren't structured in the ways humans who speak language X
would expect, they are structured so that you can produce an LR grammar and
have it compile correctly without grammar conflicts (IOW so you can use
Bison or something equivalent to convert the grammar into a program). They
are structured so that the compiler has an easier time, not so that the
user has an easier time. There are many practices that are conventional in
programming because it means the tooling we use can be simpler and more
effective. There is a good reason for this: humans are easier to teach than
programs, and natural languages are not very consistent despite what
their speakers think. (I remember from University that studies on
grammatical consistency of English speakers showed that the better educated
you were the less consistent your grammar was.) The few programming
languages that tried to go against this type of reasoning were disasters.
(COBOL anyone?)

Anyway, I am fine to let this thread die. Karl has stated he will walk away
if we adopt the rule I proposed. I dont want Karl to walk away, so I
withdraw the proposal that we adopt this rule. Should someone give me a
tool that enforces Karls style I will happily use it, until then I will
continue to use Text::Autoformat instead. Other than this issue with full
stops it does a *great* job and I use it to format my commit messages, my
pod updates and my C and perl comment updates. Ever since I adopted it I
stopped getting nagged by our tests for POD line lengths, and I stopped
spending time thinking about text wrapping and layout. I just highlight and
then hit the key binding I set up in my editor. That is how things
*should* be IMO.

cheers,
Yves






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

On Sat, 18 Mar 2023 at 20:11, Ovid <curtis.poe@gmail.com> wrote:

> On Sat, Mar 18, 2023 at 4:16?PM demerphq <demerphq@gmail.com> wrote:
>
>
>> Part of my objection to the two space rule is that I dont want to spend
>> time thinking about wrapping prose.
>>
>
> As someone who's not a core committer, I recognize that my opinion should
> not have the same weight, so please take what I say with a grain of salt,
>
> Arguments over formatting are soul-destroying. I have never found them
> productive. However, the arguments are persistent and they can be a serious
> time sink.
>
> When I put together a team to release Test::Harness 3.0, one extremely
> talented developer objected to my coding standard on the grounds that "only
> amateurs use four space indent."
>
> Because I was running that project, I put my foot down over a .perltidyrc
> file and mandated its use. I *hated* the format it produced, but because
> we found a compromise, I swallowed my pride because for me, it was more
> important that we develop than argue over formatting. It shut down the
> arguments and we were able to focus on delivering 3.0.
>

Yes. This. As long as a tool enforces the style rule it doesn't matter
what the rule is really. I like to left hug my assignment operators because
it saves me from making stupid mistakes, especially when mixing mysql code
and perl code in the same file. If I have a tidy rule to undo that habit
then it is much better than being forced to remember that some folks will
ask me to correct any such cases before they will approve my commits. But
that requires the file I am working has a tidy rule to start with, if it
doesn't then it almost for sure will not be consistently styled as humans
make mistakes. So in most cases I end up manually searching for my style
leaking through. (Although it doesn't come up enough that i have written
any tools to fix it /yet/)


> Later, at the BBC, I wasn't running the project I was on, but I pushed
> hard for a similar approach. There was one holdout, a developer who also
> couldn't stand the output (in part for reasons that the entire team,
> including myself, agreed with), and he was given permission to spend some
> time augmenting Perl::Tidy with PPI to get that preferred format. I bet our
> team lead five quid that he would fail. I won that bet. That was time spent
> on fixing a personal preference rather than building value.
>
> Given what I do now, I often have the luxury of dictating a .perltidyrc
> file and a test to ensure that all code respects that. I still hate its
> output, but it works. In ten years of our consulting firm, we've only had
> one argument over formatting and the developer in question won because he
> was able to provide a .perltidyrc file that respected his choice. I just
> hit ,pt in my editor and it does the right thing.
>
> To my surprise, I've found that a few of the consultants we've worked with
> have gone on to apply this to their other clients' projects. Seems they
> prefer not arguing over formatting.
>

FWIW, I would *love* this. I basically said the same thing in my mail to
Karl. All the Perl files in our repo that use "my" style include something
like this:

# The style of this file is determined by:
#
# perltidy -w -ple -bbb -bbc -bbs -nolq -l=80 -noll -nola -nwls='=' \
# -isbc -nolc -otr -kis -ci=4 -se -sot -sct -nsbl -pt=2 -fs \
# -fsb='#start-no-tidy' -fse='#end-no-tidy'

I used to have some tooling that would autodetect such a comments and then
run perltidy on the file with the rules specified. If it were up to me
every single one of our Perl scripts and perl files would include
something like this. For instance Tux'es files would have his rules in
it. Abigail files would have his, etc. So I wouldn't have to worry about
using the wrong style when I update their code. I would just update it and
then run the tidy tool and it would get fixed. Heck, in the worst case I
could run perltidy over their files with my rules, do what I need to do,
and then run tidy with their rules and in an ideal world nobody would know
the difference.

Me? For POD, I prefer two spaces after a full stop instead of one because
> I've been using two spaces for decades. If we can find a way to automate
> this and people agree, I'd be happy. However, if we agree on one space,
> three spaces, a tab, *whatever*, I don't care. I'd go with it so long as
> we can automate it. I can write POD and let some automated tool take it
> over. Again, I know I'm not a committer, but I hope sharing my first-hand
> experience might help.
>
> So whatever is decided, I'm neutral on it, but formatting arguments are
> soul-destroying to me. The Perl community has had enough soul-destroying
> arguments. Please let's find a compromise :)
>

I agree. I don't care *what* the style is, I just want tooling to deal with
it. I only proposed the style rule I did because I could not find a tool
that knows how to sensibly wrap text like Text::Autoformat does that also
knows how to do the double space after a full stop. On the other hand,
Text::Autoformat does a great job.

I basically use this:

use Text::Autoformat qw(autoformat protect_pod);
my $in= fix_typos(do { local $/; <>});
my $out= autoformat $in, { all => 1, right=>72, protect => protect_pod };
print $out;

I have that bound to a key in vim, so I just highlight the text, hit the
key, and it's done. The fix_typos() function I dont show here just does
some basic s/// on the text to correct some common typos, such as
converting "dont" into "don't".

I am using a custom hacked version of Text::Autoformat that Damian put
together for me that understands C comments, but without that
Text::Autoformat is really nice. Except I suppose for the small issue that
it doesn't grok the two spaces after full stop rule. :-)

cheers,
Yves

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

On Sat, 18 Mar 2023 20:28:55 +0100, demerphq <demerphq@gmail.com> wrote:

> Interesting notion, but we don't want people merging patches that fail
> test.

That would be easy to solve. Make it report instead of fail. :D

In any case: My email was sent and needs to be understood in the context that any automatic enforcement is doomed and was obviously so by the time the original email was sent, and to provide a way to get halfway there. Under that understanding, it points out a way to create something that'd help without impacting Karl. Discussion of it in other contexts is not necessary. :)

--
With regards,
Christian Walde

TLDR: I do not want anyone to stop hacking on my perl becuase of my
proposal, and therefore I withdraw my proposal. My intention is not that
anyone should follow /my/ style, but rather to free myself and the rest
of the developers on the project from thinking about style at all, by
using tooling to enforce /a/ consistent style. The style I proposed is
merely the one that I think is the most available (in terms of tooling)
and thus the least worst option to follow.  I just want to be able to
fix the wrapping on text after it has been search and replaced or
otherwise modified with a keypress or a tool. I do not want spend any
more time than absolutely necessary thinking about style. Computers were
supposed to free us from tedious work, not be the source of new forms of
it, and all i want to do is use tools to ensure that we meet the
requirements of our tests and broader comprehension requirements.

On Fri, 17 Mar 2023 at 18:57, Karl Williamson <public@khwilliamson.com
<mailto:public@khwilliamson.com>> wrote:

On 3/16/23 12:49, demerphq wrote:
> 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.
>

The bottom line for me personally, is if this rule were adopted, I
would
quit the project.


FWIW. I have mixed feelings about this comment.  The prevailing feeling
I have is that you are a very valuable contributor to the project, and
someone who I consider a friend, and I would hate that an action of mine
was the reason for you to leave the project, so I withdraw the proposal
to make a rule about this.

To repeat, because of what you say here I *withdraw* my rule proposal.

However there is a secondary level which I feel I should mention. This
kind of comment makes me really uncomfortable, as you are essentially
saying "unless the project plays by my rules I will walk". My normal
response to that kind of statement from /anyone/ would be "ok walk
then", just on principle; no person is important enough to the project
that they should get to unilaterally set the rules or hold the project
hostage to their policy demands, and I personally would do my best to
avoid making that kind of statement, and instead would leave it implicit
in wording like "Such a policy would strongly discourage my
participation in the project" or something to that effect. It expresses
the same thing but without the hostage implication that triggers my
principled response.

Regardless, I don't want you to walk, especially not over /this/ so I
withdraw the rule proposal. But I really wish that you hadn't said it
like that. It sets an ugly precedent.


One reason is because of muscle memory.  I have been following the two
spaces rule for quite a bit longer than Damian.  It would be hard
for me
to stop.


So what stops you from using tooling like Text::Autoformat, or similar
to format your comments just like I do? Then you wouldnt have to learn
to stop and you would likely save time worrying about how the text is
wrapped as well.

Part of my objection to the two space rule is that I dont want to spend
time thinking about wrapping prose. I want to use software to wrap my
prose. I want to be able to write my text however I like, and then
highlight it and hit a key press, and "poof" have it
formatted correctly. Or I want to write a search and replace, or a perl
-i command and fix up a bunch of things across multiple files, and then
be able to easily have the text autowrapped. Especially as we have tests
that will fail if POD text is too wide.  Reading text that is all
"zig-zaggy" in terms of line length is annoying, having it roughly the
same width is a win. Being able to get prose into that format without a
lot of effort is really helpful.

I likely would care much less about this subject if it werent for those
tests. If we ditched the POD lines must be so long tests, then I
probably would not care about wrapping pod as much as I currently do.
But we do have test for line length for POD, and if I rename a constant
in our code so it is wider, and that then results in the POD in some
prose you wrote starting to fail test I want to be able to highlight it
and wrap it and move on.

But more importantly, I would lose respect for a project that sought to
dictate what's basically an aesthetic issue that has no bearing on the
correct functioning of our product.  Timtoady abandoned.


I dont have an issue with Timtoady. I have an issue with having to tasks
manually that should be delegated to software.  I /loathe/ makework.

Let me illustrate my point here with code style. I do not necessarily
want there to be a single style for code in our files. I like my
personal style, and in the files I created I like that the file follows
my style.  However I know that other folks find my style a little
jarring, and I know that their finger memory is different from mine and
they find it hard to follow my style.  That is why i go out of my way to
put documentation in the Perl code I have contributed to the project for
a perltidy recipe that can be used to format the file correctly. I want
others that need to work on the file be able to forget our style
differences, focus on the problem at hand and use tooling to resolve our
differences. So if it were up to me every perl script we have would have
a well defined "perltidy definition block", and we would have a tool
that autoextracts that definition and formats our files according to its
documented rules.

The point here I am making is that I do not want uniformity, I want
tooling that automates these decisions so that I don't have to worry
about the rules. I do not want H. Merijn Brand, nor Abigail (both
contributors who also have what might called an "esoteric style") to
adopt my coding style, I want to use automation so that I don't need to
worry about their styles, and so that other folks don't need to worry
about my own. For instance recently I worked on Porting/sync-with-cpan.
This file contains a mixture of styles, some from Abgail, some from
other people. In a single statement or subroutine there are
vestigal elements of multiple styles,  for instance function calls where
there is a space after the function name and then parenthesized options
combined with other function calls where there is no space.  I find that
mixture of different styles /incredibly/ jarring, and I am never sure
what to do.  The normal rule of thumb from Larry is that people should
follow the style of the file.  But that is hard when it is alien to you
and there is no tooling to support it.

All of the above is about code. And luckily perltidy is incredibly
powerful and customizable and its author, Steve Hancock, is a great guy
who will add features to support different peoples style providing he
can figure out a way to do so. Merijn and I both have had patches
accepted by him, or features added by him to reflect our style desires.
I *wish* there were a tool of similar flexibility and capability for our
C code. I tried to find one and basically the options in the C world suck.

It is not true that tooling is hard.

I just don't agree. I tried and it is hard enough that like Damian I
decided I don't want to play this game. Reminds me of War Games: "The
only way to win is not to play.".

Autoformatting text so it respects the gamut of human formatting
conventions, AND also handles wrapping, and this rule is non-trivial, it
is hard. There are loads of edge cases.

This pretty much does it:
        s/\. (*nla: )/.  /g
It enforces the two space rule.  Use of \B{sb} matching before the dot
and a lookup hash of exceptions would improve the results.


perl -le'$_="Dr. Who etc. and et. al. is a great show."; s/\. (*nla: )/.
 /g; print '
Dr.  Who etc.  and et.  al.  is a great show.

Doesn't look great to me. And it doesn't deal with no leaving trailing
whitespace at the end of a line.


I didn't see anyone say that the two spaces is less readable than
single.  Rather, the arguments admit the single space has a negative
effect but try to minimize that importance.

No, that isnt correct. The one with a study said that people who were
trained to put two spaces after a dot had a faster comprehension. For
people who were not trained there was no difference.

So why standardize on
something that is less readable (however small you may think it is)
when
we could easily standardize on something that is more readable


Because it is not easy.

The argument that everybody else is doing it are specious.  The links I
followed say not doing it is because of the advent of proportional
fonts.  They are assuming a WYSIWYG editor.  But I can't imagine using
such an editor for writing code or pod.  Those arguments simply are not
applicable to our situation.

Bringing up "e.g.," and ".t" is also irrelevant as there is no space
after any period there.


Well I mentioned .t because it comes up with automating detecting if
somthing is a full stop or not. Perhaps I should have omitted that
point, but your claim that "e.g." is irrelevant is just wrong as a
simple git grep will show:

git grep -P 'e\.g\. \w' pod | head -n 10
pod/perl5004delta.pod:was called as a plain function (e.g.
C<Foo::bar()>), not a method
pod/perl5004delta.pod:(e.g. C<< Foo->bar() >> or C<< $obj->bar() >>).
pod/perl5004delta.pod:This now works.  (e.g. C<delete @ENV{'PATH',
'MANPATH'}>)
pod/perl5004delta.pod:a fixed value are now inlined (e.g. C<sub PI () {
3.14159 }>).
pod/perl5004delta.pod:requested with the ":flock" tag (e.g. C<use Fcntl
':flock'>).
pod/perl5004delta.pod:were csh (e.g. C<full_csh='/usr/bin/tcsh'>);
otherwise, make them all
pod/perl5005delta.pod:on the operator (e.g. C<CORE::log($x)>) or by
declaring the subroutine
pod/perl5005delta.pod:package, e.g. bless($ref, $p || 'MyPackage');
pod/perl5005delta.pod:e.g. C<&our()>, or C<Foo::our()>.
pod/perl5100delta.pod:(e.g. with C<@ISA = @ISA>).

The cases with POD are great examples of the hidden complexity here that
belies your claim this is easy. "e.g. C<&our()>" is a good example. 
Neither dot in "e.g." is a full stop, and neither should have two spaces
after it.


If you recoil at my suggestion of instead enforcing a two-space rule,
Why?

Because I find myself doing search and replace, or manual edits on
existing prose all the time such that the text grows and changes and
requires rewrapping when I am done. Partly it requires rewrapping
because of our POD tests will *fail* if it isnt rewrapped, and partly it
requires rewrapping for readability.

As I said above, I don't want a specific style, I want to be able to
automate these updates so that when I finish updating comments or POD
docs I can rewrap with software.

Damian has written "Text::Autoformat" so that you can easily do fairly
advanced text wrapping and reformatting activities without having to
think about it.  He extended it to handle C comments at my request
recently (which works pretty well, although I still owe him detailed
feedback on it) and to handle pod directives properly (eg NOT wrapping
POD). Text::Autoformat is really nice, it handles outdenting 'NOTE:'
type text, and various other task (like rewrapping email content) in a
nice way that does a good enough job often enough that I use it for
almost all text I do in my text editor. (Not in gmail obviously.)

If you could point me at a script that wraps or replaces
Text::Autoformat that allows me to do what I can currently do and
enforces your desired formatting rules then I would be fine with using
it. Until then I think I will apply "Timtoady" as you have said here and
when I need to reformat paragraphs you wrote with two spaces after
periods I will just let the tooling replace it with one space and just
Not Feel Guilty About It. For the last while I have been spending time
going back through to do the teduous task of adding the double spaces back.

The source is easier to read,

For you. Not for me. I find reading both styles equally easy.

and any documentation that gets
formatted for output will have the formatter's rules imposed upon it.
Proportional font output will have the spacing evened out between words
on a line; and the current groff for fixed fonts simply strips off the
second space.  (The original nroff did honor them.)  This means
there is
essentially no effect on users reading documentation.


Like I said, my concern is the time i need to spend to fix comments and
docs. Ideally I would spend as close to 0 time as I can to wrap text. If
reducing that time means giving up double spaces after periods then I am
fine with that. I do not see any impact from it at all personally.

As another example of tools that work: vim has done a fine job of
wrapping comment blocks, for decades, without AI.


Not in my experience.


And I have come to believe that code should not be reformatted
automatically at all.  I don't think it can be done well enough.
(Expanding tabs into the appropriate number of spaces is not really
reformatting, and is ok.)


Aren't you contradicting yourself here? First you say its easy, adn not
you say it can't be done well enough. Which is it?

Part of that is informed by the recent changes to embed.fnc.  The
entries are now sorted and grouped better, which is good, but the #if's
that I and others so carefully wrote out in such a way as to make it
easier to follow the why and wherefore of them, are trashed.  Often,
the
most important condition has been moved from first to last.

I'd like a solid example of that. I think in most regards getting the
defines right and understanding if you were duplicating a set of defines
was a bigger maintenance burdern than anything that happens now.

This is a
big step backwards, making it harder to maintain.


I dont agree at all. The older code was much harder to maintain when
doing something like splitting up a large file like regcomp.c or moving
code around between different defines. And the varying ways of writing
the list of defines meant that you could have two identical blocks that
were created by different people and laid our differently from each
other.  Making it more difficult to understand what was happening. And
the generated files that were coming from it would pseudorandomly change
due to the way tha the clauses were sorted together.

I think if you have an issue with embed.fnc you should reach out to me
privately, or via a separate thread. We can adjust the automation as you
wish. But there is no way I will ever agree that we should all just
randomly do what we think looks best and end up a bunch of different
styles in a jumble with no checking or validation or anything like that.

I write a lot of comments that use vertical alignment to clarify and
make things easier to read.  It's just not a good idea to try to second
guess how people have formatted their stuff.  I don't object if others
want to follow the single space rule for their code; I just am
unwilling
to be forced to follow their aesthetic, nor have my code automatically
formatted to follow it.


The thing is I often find that when you do this it is NOT easier to
read, at least for me, and to make it worse, it is much more costly for
me to update the code after you have done thse things. Every time I am
forced to make a decision about whether I should just ignore your
preferences, or if I should take the time to manually make the code meet
what I think are your preferences and the time I spend wondering if I
should do this or that to avoid having to think about your expectations.
(I have posted patches that replace certain types of code with macros
just so that I didnt have to deal with some of your expectations about
how to lay out the code when it became mult-line.) I would have no
objection to this if it was managed by a tool; I'd just use the tool and
be done with it.  But often it requires manual work that IMO I shouldn't
have to do.

The bottom line from a project point of view is that we already are too
intrusive in automatic formatting; it can't be done well enough, so we
shouldn't add more.  And there really is no need to make single space
(or double space) a standard.  Leave it up to the coder.


I dont agee. I think we should be using automatic formatting on
everything. Then everyone is treated equally, we can all learn and get
used to whatever the standard is, and most importantly we won't have to
spend time on dealing with these questions manually.

Some time back a bunch of people got really riled up when I suggested we
change our rules regarding line length. I would much prefer it if we
used a 120 or 140 characters per line maximum, instead of the 80
character maximum. But the community as a whole said "no we prefer 80
columns", and I do my best to live with that decision, and in fact that
decision is part of the reason we are having this conversation. 80
characters is sufficiently short that I find that almost any edit to
existing text results in /some/ of the text going over 80 characters. As
such I have invested the time to use tooling to format code and prose to
those line limits. I would like to be able to use even more tooling to
meet these limits.


If you were one of those who recoiled at the idea of a two space rule.
Again why?


Because of the dearth of tooling that allows me to automate the task of
laying out text in comments and pod blocks to satisfy it.

We have tests that nag me if my POD lines are too long. POD does not
actually care how long lines are, and I certainly wouldn't willingly
inflict a 80 column rule on myself if I could avoid it. So I want to be
able to edit POD (and comments) and just hit the "reformat text" key in
my editor and have it pass the tests and be reasonably readable. I do
NOT want to waste my time with such matters, I want to automate it away.
If I could reliably automate your style I would and we wouldnt be having
this conversation, but as has been stated elsewhere (including by you),
some types of formatting are "automation unfriendly", and teaching
humans is easier than teaching computers.


I believe I demonstrated it was better than the one space
one.

I dont think you did. The studies out there show that people who
*expect* the two spaces read less well without it. For those who do not
have that expectation there is no difference. And the difference is
extremely minor even when it is apparent. It is very grey area as to
whether it makes a difference really.

So why would you recoil?  My guess is it would be that you
wouldn't want to have my aesthetic imposed on you,

No, that isn't correct. If there was tooling that automated your style
which I could use then I would use it and presumably we wouldn't be
having this conversation. There isn't and I suspect the reason there
isn't is because it is a harder problem than you admit.

> but have no problem imposing yours on me.

Characterizing it as "my style" is not fair. I actually *would* prefer
if all of our comments and docs used the double space after a full stop
model, as I said in my original post I also come from the time period
where that was the standard. The only reason I want to standardize it to
a single space is that there are no good tools to help me achieve that
style, and there is a large group of people younger than me who don't
think the rule exists at all so I want to make them feel comfortable as
well.

BTW, as I recall you were one of the people who favoured an 80 column
limit for our code when I was asking for something wider. Why was
imposing that expectation on me ok, but me suggesting this not ok?

The advantage of having a standardized set of tooling which manages
formatting is that it side-steps these kinds of discussions. I don't get
everything I want (140 column text), and you dont everything you want
(two spaces after a full stop), but most importantly we don't argue
about who gets what they want, it comes down to what the tool does or
can do.  I dont want you to have to manually follow /my/ style, and I
dont want to have to manually follow /your/ style. I just want to be
able to use a tool so that I dont have to worry about style at all and
leave it up to tooling instead. If that means I don't get every one of
my preferences respected it still is a big win for me and the project
because /nobody has to to think about it/.  If you gave me a tool that
formatted stuff the way you liked, and the rest of the community agreed
we should use it then I would be happy to use it.

That's not perly.  But it's best to not have such
a picayune rule at all.


Sure, but if we go that way then I reserve the right to reformat any
text I feel necessary to reformat in my style without feeling guilty at
all. I just wanted a rule about this so that it was clear that it is not
an error to replace two spaces after a period with one space if I need
to. It seems that not having a rule has the same outcome, so then I am
happy I guess. I would prefer that we came to a consensus that using
specific tooling to enforce whatever conventions we want to follow is
better than expecting everyone to follow each other's style manually. 
Going back to code now, my experience is that outside of one developer I
have worked most people do have a consistent style even if they think
they do. I know from running perltidy on my own code that I often
violate my own preferences in minor and subtle ways.

Yves


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

On 3/21/23 09:50, Karl Williamson wrote:


Sorry for the tardy reply; I've had health issues that have kept me
mostly AFK

First some general points:

I can see how my initial response might come across as me being a
spoiled prima donna throwing a tantrum. And indeed that I had more
linked-in searches that week than ever before indicates to me that this
could have occurred to other people. But I'd like to think that my mind
doesn't work that way. It doesn't occur to me that I should get special
treatment. When I read that comments would need to be single-spaced, I
knew I couldn't cope with that. And that's what I said. Now it turns
out that Yves didn't quite mean what he said in the opening lines, and
that he was referring to tooling reformatting existing text.

We are talking about various things here, and any solution to one may
very well not be applicable to the others. There is pod, comments,
non-comment C language source and perl source. perl source was not
really on the agenda, but it has come up in the discussion, so I mention
it here to mean I'm not addressing it. When I use the word "code',
therefore, I'm referring to C language source, excluding comments.

A significant amount of text is NOT prose that can be wrapped at will.
POD invented verbatim lines to cope with this. It is an inelegant
solution that has many shortcomings, but it was simple to implement, and
no one has yet to implement anything further. Verbatim lines are to be
output as-is in monospace font. This is still the only way to show
tabular data in general pod. Regular pod is treated as prose that wraps
to the output device width. Verbatim pod when displayed in a too narrow
window will generally have the display device wrap in mid-word with the
tail end showing up at the left margin on the next line; and then the
next input line starts on the line after that. Such text is hard to
read, contradicting the point of having documentation at all. Having a
test that raises a warning to developers about this allows them to
decide if the text really has to be that wide, or if it can be
reformatted to not be. This porting test is effectively our guarantee
to our customers that if you have a window that is at least this many
columns wide, we will strive to write readable documentation. And there
are indeed legitimate cases where a wider line is required. The test
output can be silenced for them. But we should make those choices
deliberately.

80 columns was chosen because that has been a standard width for a long
time now. I remain convinced that it is a reasonable choice. I need
larger fonts than when I was young. Few people will escape the same
fate. 80 is about what fits two adjacent terminal windows in a legible
font size on a fairly standard size laptop. On a 31 inch monitor, it is
3 windows.

Yves is confused about our POD implementation, as he repeats several
times the falsehood that POD prose is required to fit in 80 columns.
There is NO restriction on the width input POD prose can be. The
restriction is on non-prose. And it is needed because it is specified
as verbatim text as I explained above. If POD were to be enhanced in
various ways, there would be less need for verbatim text, and this issue
would come up much less frequently. For example, often the source of
too-long verbatim lines is a series of lines of code snippets with
accompanying comments in a right column. If POD had tables, these
snippets could be written using them, and the table would handle the
wrapping.

I think that this example will prove useful. Consider these lines:

#if defined(DEBUGGING) \
|| (defined(USE_LOCALE) && ( defined(USE_THREADS) \
|| defined(HAS_IGNORED_LOCALE_CATEGORIES)\
|| defined(USE_POSIX_2008_LOCALE) \
|| ! defined(LC_ALL)))


It's clear at a glance that the code will be compiled if either of two
major conditions is true, but one of the conditions additionally
requires any of several other conditions (including one complemented
one). The && is important and prominent, and one of the || constructs is
also more important than the others, and more prominent than they.

And the order matters. If the two major conditions were reversed:

#if (defined(USE_LOCALE) && ( defined(USE_THREADS) \
|| defined(HAS_IGNORED_LOCALE_CATEGORIES)\
|| defined(USE_POSIX_2008_LOCALE) \
|| ! defined(LC_ALL))) \
|| defined(DEBUGGING)


it's less legible. A minor point, but the "defined"s all are vertically
aligned, and the ! stands out. This makes things slightly faster to skim.

But, putting those lines in embed.fnc and run the tooling transmogrifies
them to

# if ( ( defined(HAS_IGNORED_LOCALE_CATEGORIES) || !defined(LC_ALL) || \
defined(USE_POSIX_2008_LOCALE) || defined(USE_THREADS)
) && \
defined(USE_LOCALE) ) || defined(DEBUGGING)

If this is as clear to you as either of the first two, you're a better
machine than I. This change slows down comprehension of what is meant.

This example shows the dangers of tooling. Fortunately most of the
conditionals in embed.fnc are fairly simple, but the complex ones are
now pretty much destroyed.

The project would need to have a robust debate on whether or not to
subject our C code to a Ctidy utility, which really is what Yves is
driving towards. That discussion has not happened.



> TLDR: I do not want anyone to stop hacking on my perl becuase of my
> proposal, and therefore I withdraw my proposal. My intention is not that
> anyone should follow /my/ style, but rather to free myself and the rest
> of the developers on the project from thinking about style at all, by
> using tooling to enforce /a/ consistent style. The style I proposed is
> merely the one that I think is the most available (in terms of tooling)
> and thus the least worst option to follow.  I just want to be able to
> fix the wrapping on text after it has been search and replaced or
> otherwise modified with a keypress or a tool. I do not want spend any
> more time than absolutely necessary thinking about style. Computers were
> supposed to free us from tedious work, not be the source of new forms of
> it, and all i want to do is use tools to ensure that we meet the
> requirements of our tests and broader comprehension requirements.
>
> On Fri, 17 Mar 2023 at 18:57, Karl Williamson <public@khwilliamson.com
> <mailto:public@khwilliamson.com>> wrote:
>
>     On 3/16/23 12:49, demerphq wrote:
>      > 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.
>      >
>
>     The bottom line for me personally, is if this rule were adopted, I
>     would
>     quit the project.
>
>
> FWIW. I have mixed feelings about this comment.  The prevailing feeling
> I have is that you are a very valuable contributor to the project, and
> someone who I consider a friend, and I would hate that an action of mine
> was the reason for you to leave the project, so I withdraw the proposal
> to make a rule about this.
>
> To repeat, because of what you say here I *withdraw* my rule proposal.
>
> However there is a secondary level which I feel I should mention. This
> kind of comment makes me really uncomfortable, as you are essentially
> saying "unless the project plays by my rules I will walk". My normal
> response to that kind of statement from /anyone/ would be "ok walk
> then", just on principle; no person is important enough to the project
> that they should get to unilaterally set the rules or hold the project
> hostage to their policy demands, and I personally would do my best to
> avoid making that kind of statement, and instead would leave it implicit
> in wording like "Such a policy would strongly discourage my
> participation in the project" or something to that effect. It expresses
> the same thing but without the hostage implication that triggers my
> principled response.
>
> Regardless, I don't want you to walk, especially not over /this/ so I
> withdraw the rule proposal. But I really wish that you hadn't said it
> like that. It sets an ugly precedent >
>
>     One reason is because of muscle memory.  I have been following the two
>     spaces rule for quite a bit longer than Damian.  It would be hard
>     for me
>     to stop.
>
>
> So what stops you from using tooling like Text::Autoformat, or similar
> to format your comments just like I do? Then you wouldnt have to learn
> to stop and you would likely save time worrying about how the text is
> wrapped as well.

Habit certainly, but the vim reformat option that I already know is
adequate for my purposes, and accommodates easily the many slight
revisions I tend to go through. And it sounds like I would like it less
than the builtin vim version. And not all comments are prose. There is
tabular data, etc.
>
> Part of my objection to the two space rule is that I dont want to spend
> time thinking about wrapping prose. I want to use software to wrap my
> prose. I want to be able to write my text however I like, and then
> highlight it and hit a key press, and "poof" have it
> formatted correctly. Or I want to write a search and replace, or a perl
> -i command and fix up a bunch of things across multiple files, and then
> be able to easily have the text autowrapped. Especially as we have tests
> that will fail if POD text is too wide.  Reading text that is all
> "zig-zaggy" in terms of line length is annoying, having it roughly the
> same width is a win. Being able to get prose into that format without a
> lot of effort is really helpful.
>
> I likely would care much less about this subject if it werent for those
> tests. If we ditched the POD lines must be so long tests, then I
> probably would not care about wrapping pod as much as I currently do.
> But we do have test for line length for POD, and if I rename a constant
> in our code so it is wider, and that then results in the POD in some
> prose you wrote starting to fail test I want to be able to highlight it
> and wrap it and move on.

Then your wish is already granted. POD prose can be any line width you
want. Only the non-prose is tested, as I explained at the beginning.
>
>     But more importantly, I would lose respect for a project that
> sought to
>     dictate what's basically an aesthetic issue that has no bearing on the
>     correct functioning of our product.  Timtoady abandoned.
>
>
> I dont have an issue with Timtoady. I have an issue with having to tasks
> manually that should be delegated to software.  I /loathe/ makework.
>
> Let me illustrate my point here with code style. I do not necessarily
> want there to be a single style for code in our files. I like my
> personal style, and in the files I created I like that the file follows
> my style.  However I know that other folks find my style a little
> jarring, and I know that their finger memory is different from mine and
> they find it hard to follow my style.  That is why i go out of my way to
> put documentation in the Perl code I have contributed to the project for
> a perltidy recipe that can be used to format the file correctly. I want
> others that need to work on the file be able to forget our style
> differences, focus on the problem at hand and use tooling to resolve our
> differences. So if it were up to me every perl script we have would have
> a well defined "perltidy definition block", and we would have a tool
> that autoextracts that definition and formats our files according to its
> documented rules.
>
> The point here I am making is that I do not want uniformity, I want
> tooling that automates these decisions so that I don't have to worry
> about the rules. I do not want H. Merijn Brand, nor Abigail (both
> contributors who also have what might called an "esoteric style") to
> adopt my coding style, I want to use automation so that I don't need to
> worry about their styles, and so that other folks don't need to worry
> about my own. For instance recently I worked on Porting/sync-with-cpan.
> This file contains a mixture of styles, some from Abgail, some from
> other people. In a single statement or subroutine there are
> vestigal elements of multiple styles,  for instance function calls where
> there is a space after the function name and then parenthesized options
> combined with other function calls where there is no space.  I find that
> mixture of different styles /incredibly/ jarring, and I am never sure
> what to do.  The normal rule of thumb from Larry is that people should
> follow the style of the file.  But that is hard when it is alien to you
> and there is no tooling to support it.
>
> All of the above is about code. And luckily perltidy is incredibly
> powerful and customizable and its author, Steve Hancock, is a great guy
> who will add features to support different peoples style providing he
> can figure out a way to do so. Merijn and I both have had patches
> accepted by him, or features added by him to reflect our style desires.
> I *wish* there were a tool of similar flexibility and capability for our
> C code. I tried to find one and basically the options in the C world suck.

I don't understand. Isn't it the case that one codes in one's own
style, and the result is transformed into a generic one. But then the
original style is lost, and one is stuck forever more with the generic
one. I don't see that as a solution unless it's automatically reversible.

That the C options suck indicate this is a hard problem.
>
>     It is not true that tooling is hard.
>
> I just don't agree. I tried and it is hard enough that like Damian I
> decided I don't want to play this game. Reminds me of War Games: "The
> only way to win is not to play.".
>
> Autoformatting text so it respects the gamut of human formatting
> conventions, AND also handles wrapping, and this rule is non-trivial, it
> is hard. There are loads of edge cases.
>
>     This pretty much does it:
>              s/\. (*nla: )/.  /g
>     It enforces the two space rule.  Use of \B{sb} matching before the dot
>     and a lookup hash of exceptions would improve the results.
>
>
> perl -le'$_="Dr. Who etc. and et. al. is a great show."; s/\. (*nla: )/.
>   /g; print '
> Dr.  Who etc.  and et.  al.  is a great show.
>
> Doesn't look great to me. And it doesn't deal with no leaving trailing
> whitespace at the end of a line.

It is just as easy to ensure two spaces after every period as it is to
ensure one. The problem is that that is unacceptable to you. And I did
not claim that that bit of code was a complete one. The hash I
mentioned would be a dictionary of exceptions, "Dr" would be in it.
There would be very few words in it longer than 3 characters.
>
>
>     I didn't see anyone say that the two spaces is less readable than
>     single.  Rather, the arguments admit the single space has a negative
>     effect but try to minimize that importance.
>
> No, that isnt correct. The one with a study said that people who were
> trained to put two spaces after a dot had a faster comprehension. For
> people who were not trained there was no difference.

That makes sense to me. It's plausible that people like me have had
their brain pattern matching capability trained to unconsciously look
for that distinction and it helps them in their speed. The untrained
ones don't have that advantage.

>
>     So why standardize on
>     something that is less readable (however small you may think it is)
>     when
>     we could easily standardize on something that is more readable
>
>
> Because it is not easy.

And why can't the tooling just respect what is already there. Don't
narrow 2 spaces to 1. That leaves only the case where a dot ended a
line is now in the middle. But I'm not advocating for tooling; just
saying if it does happen, most edge cases could be easily handled.
>
>     The argument that everybody else is doing it are specious.  The
> links I
>     followed say not doing it is because of the advent of proportional
>     fonts.  They are assuming a WYSIWYG editor.  But I can't imagine using
>     such an editor for writing code or pod.  Those arguments simply are
> not
>     applicable to our situation.
>
>     Bringing up "e.g.," and ".t" is also irrelevant as there is no space
>     after any period there.
>
>
> Well I mentioned .t because it comes up with automating detecting if
> somthing is a full stop or not. Perhaps I should have omitted that
> point, but your claim that "e.g." is irrelevant is just wrong as a
> simple git grep will show:
>
> git grep -P 'e\.g\. \w' pod | head -n 10
> pod/perl5004delta.pod:was called as a plain function (e.g.
> C<Foo::bar()>), not a method
> pod/perl5004delta.pod:(e.g. C<< Foo->bar() >> or C<< $obj->bar() >>).
> pod/perl5004delta.pod:This now works.  (e.g. C<delete @ENV{'PATH',
> 'MANPATH'}>)
> pod/perl5004delta.pod:a fixed value are now inlined (e.g. C<sub PI () {
> 3.14159 }>).
> pod/perl5004delta.pod:requested with the ":flock" tag (e.g. C<use Fcntl
> ':flock'>).
> pod/perl5004delta.pod:were csh (e.g. C<full_csh='/usr/bin/tcsh'>);
> otherwise, make them all
> pod/perl5005delta.pod:on the operator (e.g. C<CORE::log($x)>) or by
> declaring the subroutine
> pod/perl5005delta.pod:package, e.g. bless($ref, $p || 'MyPackage');
> pod/perl5005delta.pod:e.g. C<&our()>, or C<Foo::our()>.
> pod/perl5100delta.pod:(e.g. with C<@ISA = @ISA>).
>
> The cases with POD are great examples of the hidden complexity here that
> belies your claim this is easy. "e.g. C<&our()>" is a good example.
> Neither dot in "e.g." is a full stop, and neither should have two spaces
> after it.

These are all grammatical errors. Standard usage includes a comma
immediately after the final dot. The full correct pod should be
I<e.g.,> My claim is not contradicted by these examples.

>
>
>     If you recoil at my suggestion of instead enforcing a two-space rule,
>     Why?
>
> Because I find myself doing search and replace, or manual edits on
> existing prose all the time such that the text grows and changes and
> requires rewrapping when I am done. Partly it requires rewrapping
> because of our POD tests will *fail* if it isnt rewrapped, and partly it
> requires rewrapping for readability.
>
> As I said above, I don't want a specific style, I want to be able to
> automate these updates so that when I finish updating comments or POD
> docs I can rewrap with software.
>
> Damian has written "Text::Autoformat" so that you can easily do fairly
> advanced text wrapping and reformatting activities without having to
> think about it.  He extended it to handle C comments at my request
> recently (which works pretty well, although I still owe him detailed
> feedback on it) and to handle pod directives properly (eg NOT wrapping
> POD). Text::Autoformat is really nice, it handles outdenting 'NOTE:'
> type text, and various other task (like rewrapping email content) in a
> nice way that does a good enough job often enough that I use it for
> almost all text I do in my text editor. (Not in gmail obviously.)
>
> If you could point me at a script that wraps or replaces
> Text::Autoformat that allows me to do what I can currently do and
> enforces your desired formatting rules then I would be fine with using
> it. Until then I think I will apply "Timtoady" as you have said here and
> when I need to reformat paragraphs you wrote with two spaces after
> periods I will just let the tooling replace it with one space and just
> Not Feel Guilty About It. For the last while I have been spending time
> going back through to do the teduous task of adding the double spaces back.

If you had asked, I would have said that was excessive obeisance to the
existing format. If you revise comments, you get to choose the style of
the new portions.

>
>     The source is easier to read,
>
> For you. Not for me. I find reading both styles equally easy.
>
>     and any documentation that gets
>     formatted for output will have the formatter's rules imposed upon it.
>     Proportional font output will have the spacing evened out between
> words
>     on a line; and the current groff for fixed fonts simply strips off the
>     second space.  (The original nroff did honor them.)  This means
>     there is
>     essentially no effect on users reading documentation.
>
>
> Like I said, my concern is the time i need to spend to fix comments and
> docs. Ideally I would spend as close to 0 time as I can to wrap text. If
> reducing that time means giving up double spaces after periods then I am
> fine with that. I do not see any impact from it at all personally.
>
>     As another example of tools that work: vim has done a fine job of
>     wrapping comment blocks, for decades, without AI.
>
>
> Not in my experience.
>
>
>     And I have come to believe that code should not be reformatted
>     automatically at all.  I don't think it can be done well enough.
>     (Expanding tabs into the appropriate number of spaces is not really
>     reformatting, and is ok.)
>
>
> Aren't you contradicting yourself here? First you say its easy, adn not
> you say it can't be done well enough. Which is it?

Code is different than comments. And I was only talking about prose
comments as being not much harder than a single-space rule. I am very
leery of this tooling at all.
>
>     Part of that is informed by the recent changes to embed.fnc.  The
>     entries are now sorted and grouped better, which is good, but the
> #if's
>     that I and others so carefully wrote out in such a way as to make it
>     easier to follow the why and wherefore of them, are trashed.  Often,
>     the
>     most important condition has been moved from first to last.
>
> I'd like a solid example of that. I think in most regards getting the
> defines right and understanding if you were duplicating a set of defines
> was a bigger maintenance burdern than anything that happens now.

Example at the beginning of this response
>
>     This is a
>     big step backwards, making it harder to maintain.
>
>
> I dont agree at all. The older code was much harder to maintain when
> doing something like splitting up a large file like regcomp.c or moving
> code around between different defines. And the varying ways of writing
> the list of defines meant that you could have two identical blocks that
> were created by different people and laid our differently from each
> other.  Making it more difficult to understand what was happening. And
> the generated files that were coming from it would pseudorandomly change
> due to the way tha the clauses were sorted together.
>
> I think if you have an issue with embed.fnc you should reach out to me
> privately, or via a separate thread. We can adjust the automation as you
> wish. But there is no way I will ever agree that we should all just
> randomly do what we think looks best and end up a bunch of different
> styles in a jumble with no checking or validation or anything like that.

Like I said, the grouping and sorting of the lines is a big improvement.
But the rewriting of the preprocessor directives messes them up a
great deal. Fortunately many of the conditionals are simple and come
out ok, but all the complex ones are very negatively impacted.
>
>     I write a lot of comments that use vertical alignment to clarify and
>     make things easier to read.  It's just not a good idea to try to
> second
>     guess how people have formatted their stuff.  I don't object if others
>     want to follow the single space rule for their code; I just am
>     unwilling
>     to be forced to follow their aesthetic, nor have my code automatically
>     formatted to follow it.
>
>
> The thing is I often find that when you do this it is NOT easier to
> read, at least for me, and to make it worse, it is much more costly for
> me to update the code after you have done thse things. Every time I am
> forced to make a decision about whether I should just ignore your
> preferences, or if I should take the time to manually make the code meet
> what I think are your preferences and the time I spend wondering if I
> should do this or that to avoid having to think about your expectations.
> (I have posted patches that replace certain types of code with macros
> just so that I didnt have to deal with some of your expectations about
> how to lay out the code when it became mult-line.) I would have no
> objection to this if it was managed by a tool; I'd just use the tool and
> be done with it.  But often it requires manual work that IMO I shouldn't
> have to do.

Agreed. If you're changing my code, you shouldn't have to concern
yourself with spacing niceties. So just don't.
>
>     The bottom line from a project point of view is that we already are
> too
>     intrusive in automatic formatting; it can't be done well enough, so we
>     shouldn't add more.  And there really is no need to make single space
>     (or double space) a standard.  Leave it up to the coder.
>
>
> I dont agee. I think we should be using automatic formatting on
> everything. Then everyone is treated equally, we can all learn and get
> used to whatever the standard is, and most importantly we won't have to
> spend time on dealing with these questions manually.

As I said, there would have to be a robust conversation about going this
way. I am skeptical an acceptable tool can be written without AI.
>
> Some time back a bunch of people got really riled up when I suggested we
> change our rules regarding line length. I would much prefer it if we
> used a 120 or 140 characters per line maximum, instead of the 80
> character maximum. But the community as a whole said "no we prefer 80
> columns", and I do my best to live with that decision, and in fact that
> decision is part of the reason we are having this conversation. 80
> characters is sufficiently short that I find that almost any edit to
> existing text results in /some/ of the text going over 80 characters. As
> such I have invested the time to use tooling to format code and prose to
> those line limits. I would like to be able to use even more tooling to
> meet these limits.

Again, only verbatim lines are tested. Enhancing POD would reduce this
need, and have many other applicable uses as well.
>
>
>     If you were one of those who recoiled at the idea of a two space rule.
>     Again why?
>
>
> Because of the dearth of tooling that allows me to automate the task of
> laying out text in comments and pod blocks to satisfy it.
>
> We have tests that nag me if my POD lines are too long. POD does not
> actually care how long lines are, and I certainly wouldn't willingly
> inflict a 80 column rule on myself if I could avoid it. So I want to be
> able to edit POD (and comments) and just hit the "reformat text" key in
> my editor and have it pass the tests and be reasonably readable. I do
> NOT want to waste my time with such matters, I want to automate it away.
> If I could reliably automate your style I would and we wouldnt be having
> this conversation, but as has been stated elsewhere (including by you),
> some types of formatting are "automation unfriendly", and teaching
> humans is easier than teaching computers.

Again, you are misstating the situation. As I said at the beginning,
those tests aren't there for no good reason. They are there to make
sure we give readable output to our customers.
>
>
>     I believe I demonstrated it was better than the one space
>     one.
>
> I dont think you did. The studies out there show that people who
> *expect* the two spaces read less well without it. For those who do not
> have that expectation there is no difference. And the difference is
> extremely minor even when it is apparent. It is very grey area as to
> whether it makes a difference really.
>
>     So why would you recoil?  My guess is it would be that you
>     wouldn't want to have my aesthetic imposed on you,
>
> No, that isn't correct. If there was tooling that automated your style
> which I could use then I would use it and presumably we wouldn't be
> having this conversation. There isn't and I suspect the reason there
> isn't is because it is a harder problem than you admit.
>
>  > but have no problem imposing yours on me.
>
> Characterizing it as "my style" is not fair. I actually *would* prefer
> if all of our comments and docs used the double space after a full stop
> model, as I said in my original post I also come from the time period
> where that was the standard. The only reason I want to standardize it to
> a single space is that there are no good tools to help me achieve that
> style, and there is a large group of people younger than me who don't
> think the rule exists at all so I want to make them feel comfortable as
> well.
>
> BTW, as I recall you were one of the people who favoured an 80 column
> limit for our code when I was asking for something wider. Why was
> imposing that expectation on me ok, but me suggesting this not ok?
>
> The advantage of having a standardized set of tooling which manages
> formatting is that it side-steps these kinds of discussions. I don't get
> everything I want (140 column text), and you dont everything you want
> (two spaces after a full stop), but most importantly we don't argue
> about who gets what they want, it comes down to what the tool does or
> can do.  I dont want you to have to manually follow /my/ style, and I
> dont want to have to manually follow /your/ style. I just want to be
> able to use a tool so that I dont have to worry about style at all and
> leave it up to tooling instead. If that means I don't get every one of
> my preferences respected it still is a big win for me and the project
> because /nobody has to to think about it/.  If you gave me a tool that
> formatted stuff the way you liked, and the rest of the community agreed
> we should use it then I would be happy to use it.
>
>     That's not perly.  But it's best to not have such
>     a picayune rule at all.
>
>
> Sure, but if we go that way then I reserve the right to reformat any
> text I feel necessary to reformat in my style without feeling guilty at
> all. I just wanted a rule about this so that it was clear that it is not
> an error to replace two spaces after a period with one space if I need
> to. It seems that not having a rule has the same outcome, so then I am
> happy I guess. I would prefer that we came to a consensus that using
> specific tooling to enforce whatever conventions we want to follow is
> better than expecting everyone to follow each other's style manually.
> Going back to code now, my experience is that outside of one developer I
> have worked most people do have a consistent style even if they think
> they do. I know from running perltidy on my own code that I often
> violate my own preferences in minor and subtle ways.
>
> Yves
>
>