[PATCH v2] Complete example in error message documentation.

[ricaljasan]

On 03/06/2015 01:14 AM, Mike Frysinger wrote:
> honestly, the smaller/more self contained your patches, the more likely they are 
> to get reviewed/merged.  larger patches that combine multiple changes into one 
> are significantly less likely to get reviewed.  especially changes to the 
> manual.  will power is a commodity.

And how.  Not to make this an eternal thread, but you touched on one of
my major editing struggles, and this patch holds a perfect example.
I've managed to narrow the scope of my edits to (what I consider)
essential grammar, and keep a few to-do lists for other clean-ups when
I'm done.  I'm not so concerned that I will have too large a scope of
edits - there are going to be a lot no matter what - but I recognize the
need to keep the diffs easily readable.  This is somewhat for posterity,
esp. given how patchwork displays the thread with the patch, which I can
use for illustration, but I'm also curious if you or any other developer
who might care to weigh in would consider my final conclusion appropriate.

Example.  If I were to redo the patch from this thread, one thing that
bugged me was the reformatting of the entire compatibility note after
the deletion of the first sentence.  Having to read that after a few
months, it took me a few glances back and forth to see what I did -
which wound up only being a change to the first line.  Reformatting the
whole paragraph actually induces a need to inspect the entire thing more
closely than normal, looking for changes that aren't even there, when
one could have simply glanced and seen it all.

I think the prevailing rationale at the time was
obey-the-laws-of-the-land ...and anything you touch, bring into
72-column widths.  I swear I read that once somewhere, specifically for
the manual, and have never been able to find it again.  In reality, the
law of manual-land is something like, "Eh, 72-ish is OK."  Were I to add
new content (not happening in the proofing phase anyway), I would format
my paragraphs uniformly, but I think edits are fine to only touch what
they need and line-lengths be damned. (<-conclusion)

To support my 72-ish hypothesis, I couldn't help writing a quick
histogram in awk.  The following will provide the full graph; attached
is a slice from line lengths of 50 to 85, where you can see a sharp
preference for 72.

awk '
{
 len=length();
 if (len>=0) {
  hist[len]++;
 }
}
END {
 printf "len cnt\n--- ---\n";
 for (i=0; i<length(hist); i++) {
  printf "%3d %d\n", i, hist[i];
 }
}' manual/*.texi
-------------- next part --------------
len cnt
--- ---
 50 292
 51 303
 52 277
 53 279
 54 316
 55 306
 56 317
 57 406
 58 458
 59 497
 60 604
 61 600
 62 753
 63 922
 64 1143
 65 1351
 66 1635
 67 2055
 68 2443
 69 2972
 70 3357
 71 3097
 72 3063
 73 621
 74 452
 75 278
 76 184
 77 158
 78 126
 79 77
 80 40
 81 49
 82 37
 83 33
 84 32
 85 28
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 836 bytes
Desc: OpenPGP digital signature
URL: <http://sourceware.org/pipermail/libc-alpha/attachments/20150307/adb95635/attachment.sig>