Bug#902555: radeon.4: Some fixes in the manual
On 2018-07-05 02:04 AM, Bjarni Ingi Gislason wrote: > On Fri, Jun 29, 2018 at 10:56:39AM +0200, Michel Dänzer wrote: >> >> 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. -- Earthling Michel Dänzer | http://www.amd.com Libre software enthusiast | Mesa and X developer ___ xorg-driver-ati mailing list xorg-driver-ati@lists.x.org https://lists.x.org/mailman/listinfo/xorg-driver-ati
Bug#902555: radeon.4: Some fixes in the manual
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-...@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
___
xorg-driver-ati mailing list
xorg-driver-ati@lists.x.org
https://lists.x.org/mailman/listinfo/xorg-driver-ati
Bug#902555: radeon.4: Some fixes in the manual
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-...@lists.freedesktop.org list for review, split up into one patch >> 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. -- Earthling Michel Dänzer | http://www.amd.com Libre software enthusiast | Mesa and X developer signature.asc Description: OpenPGP digital signature ___ xorg-driver-ati mailing list xorg-driver-ati@lists.x.org https://lists.x.org/mailman/listinfo/xorg-driver-ati
Bug#902555: radeon.4: Some fixes in the manual
At 2018-06-28T11:31:30+0200, Michel Dänzer wrote: > > 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. Well, a lot of these changes aren't "logical", they're stylistic. > On 2018-06-27 09:07 PM, Bjarni Ingi Gislason wrote: > > > > 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. > > 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. -- Regards, Branden signature.asc Description: PGP signature ___ xorg-driver-ati mailing list xorg-driver-ati@lists.x.org https://lists.x.org/mailman/listinfo/xorg-driver-ati
Bug#902555: radeon.4: Some fixes in the manual
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. On 2018-06-27 09:07 PM, Bjarni Ingi Gislason wrote: > > Don't begin a sentence with a digit. Why not? What's the problem with that? > Add a comma after "e.g.". That looks odd to me. -- Earthling Michel Dänzer | http://www.amd.com Libre software enthusiast | Mesa and X developer ___ xorg-driver-ati mailing list xorg-driver-ati@lists.x.org https://lists.x.org/mailman/listinfo/xorg-driver-ati
Bug#902555: radeon.4: Some fixes in the manual
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
--
Bjarni I. Gislason
--- radeon.42018-03-20 12:17:16.0 +
+++ radeon.4.new2018-06-27 01:55:21.0 +
@@ -1,13 +1,14 @@
+'\" t
.ds q \N'34'
.TH RADEON 4 "xf86-video-ati 18.0.1" "X Version 11"
.SH NAME
radeon \- ATI/AMD RADEON video driver
.SH SYNOPSIS
.nf
-.B "Section \*qDevice\*q"
+.B Section \*qDevice\*q
.BI " Identifier \*q" devname \*q
.B " Driver \*qradeon\*q"
-\ \ ...
+\ \ \&.\|.\|.\&
.B EndSection
.fi
.SH DESCRIPTION
@@ -18,7 +19,8 @@ following features:
.PD 0
.TP 2
\(bu
-Full support for 8-, 15-, 16- and 24-bit pixel depths, and for 30-bit depth on
Linux 3.16
+Full support for 8-, 15-, 16- and 24-bit pixel depths, and for 30-bit
+depth on Linux 3.16
and later;
.TP
\(bu
@@ -37,7 +39,8 @@ only available on R/RV3xx, R/RV/RS4xx, R
.SH SUPPORTED HARDWARE
The
.B radeon
-driver supports PCI, AGP, and PCIe video cards based on the following ATI/AMD
chips
+driver supports PCI, AGP, and PCIe video cards based on the following
+ATI/AMD chips
(note: list is non-exhaustive):
.PP
.PD 0
@@ -243,33 +246,43 @@ Option \*qZaphodHeads\*q \*qLVDS,VGA-0\*
will assign xrandr outputs LVDS and VGA-0 to this instance of the driver.
.TP
.BI "Option \*qColorTiling\*q \*q" "boolean" \*q
-The framebuffer can be addressed either in linear or tiled mode. Tiled mode
can provide
-significant performance benefits with 3D applications. Tiling will be
disabled if the drm
-module is too old or if the current display configuration does not support it.
On R600+
-this enables 1D tiling mode.
+The framebuffer can be addressed either in linear or tiled mode.
+Tiled mode can provide
+significant performance benefits with 3D applications.
+Tiling will be disabled if the drm
+module is too old or if the current display configuration does not support
+it.
+On R600+ this enables 1D tiling mode.
.br
The default value is
.B on
-for R/RV3XX, R/RV4XX, R/RV5XX, RS6XX, RS740, R/RV6XX, R/RV7XX, RS780, RS880,
-EVERGREEN, CAYMAN, ARUBA, Southern Islands, and Sea Islands and
+for R/RV3XX, R/RV4XX, R/RV5XX, RS6XX, RS740, R/RV6XX, R/RV7XX, RS780,
+RS880, EVERGREEN, CAYMAN, ARUBA, Southern Islands, and Sea Islands and
.B off
-for R/RV/RS1XX, R/RV/RS2XX, RS3XX, and RS690/RS780/RS880 when fast fb feature
is enabled.
+for R/RV/RS1XX, R/RV/RS2XX, RS3XX, and RS690/RS780/RS880 when fast fb
+feature is enabled.
.TP
.BI "Option \*qColorTiling2D\*q \*q" "boolean" \*q
-The framebuffer can be addressed either in linear, 1D, or 2D tiled modes. 2D
tiled mode can
-provide significant performance benefits over 1D tiling with 3D applications.
Tiling
-will be disabled if the drm module is too old or if the current display
configuration
-does not support it. KMS ColorTiling2D is only supported on R600 and newer
chips and requires
-Mesa 9.0 or newer for R6xx-ARUBA, Mesa 9.2 or newer for Southern Islands, and
Mesa
-10.1 or newer for Sea Islands.
+The framebuffer can be addressed either in linear, 1D, or 2D tiled
+modes.
+The 2D tiled mode can
+provide significant performance benefits over 1D tiling with 3D
+applications.
+Tiling will be disabled if the drm module is too old or if the current
+display configuration does not support it.
+KMS
