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

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

• Proposal: Standardize to one space after full stops indocumentation, pod, comments, etc. by demerphq
• Re: Proposal: Standardize to one space after full stops indocumentation, pod, comments, etc. by Ovid
• Re: Proposal: Standardize to one space after full stops indocumentation, pod, comments, etc. by Damian Conway
• Re: Proposal: Standardize to one space after full stops indocumentation, pod, comments, etc. by Elvin Aslanov
• Re: Proposal: Standardize to one space after full stops indocumentation, pod, comments, etc. by Christian Walde
• Re: Proposal: Standardize to one space after full stops indocumentation, pod, comments, etc. by demerphq
• Re: Proposal: Standardize to one space after full stops indocumentation, pod, comments, etc. by Christian Walde
• Re: Proposal: Standardize to one space after full stops indocumentation, pod, comments, etc. by Karl Williamson
• Re: Proposal: Standardize to one space after full stops indocumentation, pod, comments, etc. by Karl Williamson
• Re: Proposal: Standardize to one space after full stops indocumentation, pod, comments, etc. by Karl Williamson
• Re: Proposal: Standardize to one space after full stops indocumentation, pod, comments, etc. by demerphq
• Re: Proposal: Standardize to one space after full stops indocumentation, pod, comments, etc. by Ovid
• Re: Proposal: Standardize to one space after full stops indocumentation, pod, comments, etc. by demerphq
• Re: Proposal: Standardize to one space after full stops indocumentation, pod, comments, etc. by Ricardo Signes
• Re: Proposal: Standardize to one space after full stops indocumentation, pod, comments, etc. by perl5
• Re: Proposal: Standardize to one space after full stops indocumentation, pod, comments, etc. by Oodler 577 via perl5-porters
• Re: Proposal: Standardize to one space after full stops indocumentation, pod, comments, etc. by Wesley via perl5-porters
• Re: Proposal: Standardize to one space after full stops indocumentation, pod, comments, etc. by "G.W. Haywood" via perl5-porters