Bug#902555: radeon.4: Some fixes in the manual

[Bjarni Ingi Gislason]

On Fri, Jun 29, 2018 at 10:56:39AM +0200, Michel Dänzer wrote:
> On 2018-06-28 03:58 PM, G. Branden Robinson wrote:
> > At 2018-06-28T11:31:30+0200, Michel Dänzer wrote:
> >>
> >> Please send this kind of change directly upstream to the
> >> amd-gfx at lists.freedesktop.org list for review, split up into one patch
> >> per logical change.
> > 

  I sent the same patch upstream.

> > Well, a lot of these changes aren't "logical", they're stylistic.
> 
> Funny. :) I'm sure you know what I meant though:
> 
> Every item listed in Bjarni's report is logically a separate change.
> Mixing up logically separate changes (especially such a large number)
> makes for a hard to review patch. Hard to review patches are less likely
> to be applied.
> 
> Anyway, Bjarni, if you can send a proper patch generated by git
> format-patch, I'm willing to make an exception this time.
> 

  I do not work that way with a text in a single file.

1) The extra work producing x patches instead of one for a man page is
a waste of time.

2) The changes are independent of each other.

3) Reviewing a patch for a man page with more than one "logical" change
is only hard for those who have never or too rarely done that or lack
the knowledge and do not want to gain it.

4) You can do the "splitting" to multiple patches yourself, and if not,
why should other want to do it?

5) Using the same rule (one patch for each "logical" type of change) in
all cases is simply ineffective.


  Here is a script that shows changes caused by patches to man pages:

#!/bin/sh
# Compare two versions of a man page
# 

set -efu
inputA=${1##*/}
inputB=${2##*/}
cp $1 /tmp/$inputA
cp $2 /tmp/$inputB

cd /tmp

MAN_KEEP_STDERR=yes
MANOPT='--warnings=w --no-justification --no-hyphenation'
MANWIDTH=80
export MAN_KEEP_STDERR MANOPT MANWIDTH

# Have no sentence space (.ss 12 0)

sed -e '/^.TH /i \
.ss 12 0' $inputA  | man -l - > \
  old.$inputA.txt 2> /dev/null

sed -e '/^.TH /i \
.ss 12 0' $inputB  | man -l - > \
  new.$inputA.txt 2> /dev/null

diff -adu old.$inputA.txt new.$inputA.txt > $inputA.txt.diff || :

# Difference in the output of "troff"

{ sed -e '/^.TH /i \
.ss 12 0\
.ad l' $inputA ; } | groff -t \
  -rHY=0 -rF0 -mandoc -Z - > old.$inputA.ml 2> /dev/null

{ sed -e '/^.TH /i \
.ss 12 0\
.ad l' $inputB ; } | \
  groff -t -rHY=0 -rF0 -mandoc -Z - > new.$inputA.ml 2> /dev/null

diff -adu old.$inputA.ml new.$inputA.ml > $inputA.ml.diff || :

less $inputA.txt.diff

less $inputA.ml.diff

-- 
Bjarni I. Gislason