Date: Fri, 25 May 2018 12:06:46 +1000 (EST) From: Bruce Evans <brde@optusnet.com.au> To: Ed Maste <emaste@freebsd.org> Cc: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: Re: svn commit: r334171 - head Message-ID: <20180525113010.R1101@besplex.bde.org> In-Reply-To: <201805241708.w4OH8umj085934@repo.freebsd.org> References: <201805241708.w4OH8umj085934@repo.freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On Thu, 24 May 2018, Ed Maste wrote: > Log: > UPDATING: remove EOL whitespace in 20180523 entry This file has many other formatting errors. There are 2 more on just the line changed by this commit, and 1 of these is another implementation of EOL whitespace. > Modified: head/UPDATING > ============================================================================== > --- head/UPDATING Thu May 24 17:06:00 2018 (r334170) > +++ head/UPDATING Thu May 24 17:08:55 2018 (r334171) > @@ -53,7 +53,7 @@ NOTE TO PEOPLE WHO THINK THAT FreeBSD 12.x IS SLOW: > > 20180523: > The on-disk format for hwpmc callchain records has changed to include > - threadid corresponding to a given record. This changes the field offsets > + threadid corresponding to a given record. This changes the field offsets > and thus requires that libpmcstat be rebuilt before using a kernel > later than r334108. The first error is a misformatted sentence break of 1 space instead of 2. This file has about 158 lines matching '\. ' (2+-space sentence break) and about 142 lines matching '\. [^]' (1-space sentence break). The next error was 4 spaces after "offsets" before EOL. This was visible as ugly vertical whitespace in 1 or 2 mail programs, but by the time it got to EDITOR=vi, some mail program corrupted the whitespace by removing it, so it doesn't even show up in the above diff. The next error is a line of length 80. This also shows up as vertical whitespace on 80-column terminals with auto-wrap. Display programs like less and vi normally use termcap to avoid extra vertical whitespace and scrolling from auto-wrap. On some terminals, it is impossible to display a character in the bottom right corner since printing it would scroll. less and vi handle this problem by using the last line only for status messages. 'expand UPDATING | grep ...' shows: - 24 lines misformatted with length 80 - 1 line misformatted with length 81 - 3 lines misformatted with length 82 - no lines misformatted with length > 82. 79 is also too wide. It makes minor editing often require re-wrapping whole paragraps. Paragraph formatting in UPDATING is also bad. Everything except dates and meta-info is supposed to be indented by 1 tab, and mostly is (the tab is only corrupted to 8 spaces on 1 line). But this effectively reduces the line length to 72 so encourages going closer to length 80 counting the tab. But then the large uniform left margin looks especially ugly compared to the smaller non-uniform right margin. The size of the right margin varies a lot with the entry. Some entries are fairly carefully formatted to give a right marging of at least 8 spaces and therefore sometimes 15 spaces if the 8 is strictly enforced. Some lines then have length only 80 - 8 - 15 = 57. I try to use a maximum width of at 72 in mail, and a bit larger in comments in C programs, and 80 only in statements in C programs where reducing this or splitting the line would be uglier. Bruce
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20180525113010.R1101>