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

[Bjarni Ingi Gislason]

Package: xserver-xorg-video-radeon
Version: 1:18.0.1-1
Severity: minor
Tags: patch

Dear Maintainer,

Summary of changes:

Remove superfluous quotation marks (") from the argument of a
single-font macro.

Use a better presentation for an ellipsis (with narrow space between
the periods).

Split long lines (> 80).

Begin a sentence on a new line if there is only one space separating
sentences.

Don't begin a sentence with a digit.

Add a comma after "e.g.".

Separate numbers from the units (with an unpaddable space).

Change - to \- if it shall be printed as a minus.

Change a two-fonts macro to an one-font macro for a
single argument.

Protect . if not an end of sentence.

Don't repeat a "long" word, but rephrase the text.

Use "tbl" to create a table, otherwise the text looks ugly with a
proportional font.

Protect . if not an end of sentence.

####

The patch is in the attachment.

-- System Information:
Debian Release: buster/sid
APT prefers stable-updates
APT policy: (500, 'stable-updates'), (500, 'proposed-updates'), (500, 'testing'), (500, 'stable')
Architecture: amd64 (x86_64)

Kernel: Linux 4.9.110-1 (SMP w/2 CPU cores)
Locale: LANG=is_IS.iso88591, LC_CTYPE=is_IS.iso88591 (charmap=ISO-8859-1), LANGUAGE=is_IS.iso88591 (charmap=ISO-8859-1)
Shell: /bin/sh linked to /bin/dash
Init: sysvinit (via /sbin/init)

Versions of packages xserver-xorg-video-radeon depends on:
ii libc6 2.27-3
ii libdrm-radeon1 2.4.92-1
ii libudev1 238-5
ii xserver-xorg-core [xorg-video-abi-23] 2:1.19.6-1

xserver-xorg-video-radeon recommends no packages.

Versions of packages xserver-xorg-video-radeon suggests:
ii firmware-amd-graphics 20170823-1

-- no debconf information

[Michel Dänzer]

Please send this kind of change directly upstream to the
amd-***@lists.freedesktop.org list for review, split up into one patch
per logical change.

Post by Bjarni Ingi Gislason
Don't begin a sentence with a digit.

Why not? What's the problem with that?

Post by Bjarni Ingi Gislason
Add a comma after "e.g.".

That looks odd to me.

[G. Branden Robinson]

Post by Michel Dänzer
Please send this kind of change directly upstream to the
per logical change.

Well, a lot of these changes aren't "logical", they're stylistic.

Post by Michel Dänzer

Post by Bjarni Ingi Gislason
Don't begin a sentence with a digit.

Why not? What's the problem with that?

It's considered substandard English style.

See, e.g., [1]

https://www.editage.com/insights/scientific-writing-avoid-starting-sentences-with-a-number-or-abbreviation

The Chicago Manual of Style, which is the preferred style guide of
Michael Kerrisk of the Linux Man-Pages Project, is paywalled[2], but my
copy of the 14th edition says:

§8.9 "At the beginning of a sentence any number that would ordinarily be
set in numerals is spelled out, regardless of any inconsistency this may
create [...]".

Other style guides broadly agree, though they might not be quite as
militant about it as Chicago is.

Post by Michel Dänzer

Post by Bjarni Ingi Gislason
Add a comma after "e.g.".

That looks odd to me.

It's standard to have the comma.

Chicago, 14th ed. again:

§5.62 "A comma is usually used after such expressions as _that is_,
_namely_, _i.e._, and _e.g._ The punctuation preceding such expressions
should be determined by the magnitude of the break in continuity. If
the break is minor, a comma should be used. If the break is greater
than that signaled by a comma, a semicolon or an em dash may be used, or
the expression and the element it introduces may be enclosed in
parentheses". [italics replaced by underscore delimeters]

I've run into Bjarni in the groff and man-pages projects. He's a
detail-oriented style maven after my own heart and I can vouch that his
proposed corrections are usually sound ones.

[1] ;-)
[2] >:( http://www.chicagomanualofstyle.org/16/ch06/ch06_toc.html
redirects me to a login screen.

[Michel Dänzer]

Post by G. Branden Robinson

Post by Michel Dänzer
Please send this kind of change directly upstream to the
per logical change.

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.

[Bjarni Ingi Gislason]

Post by Michel Dänzer

Post by G. Branden Robinson

Post by Michel Dänzer
Please send this kind of change directly upstream to the
per logical change.

I sent the same patch upstream.

Post by Michel Dänzer

Post by G. Branden Robinson
Well, a lot of these changes aren't "logical", they're stylistic.

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

[Michel Dänzer]

Post by Bjarni Ingi Gislason

Post by Michel Dänzer
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.

I'm not going to argue with you over this. As I said, I'm willing to
make an exception this one time, under the condition above.