Re: [RFR] templates://glide/{libglide2.templates,libglide3.templates}
Christian Perrier wrote:
>>> + If the graphical card in this computer does not use one of these
>>> + chipsets, and you are not compiling programs against glide,
>>> + this package will be useless.
>>> + .
>>> + If the graphical card is based on one of these chipsets, you
>>> + should report a bug against this package, including the output from the
>>> + "lspci -vm" command.
>>> .
>>> + Please choose whether you want to manually select the driver to use for now.
>>
>> Why the switch from "please" to "should"?
>
> Mostly because of the rewording, but I think that both have the same
> weight. "Please report" or "you should report" have, IMHO, the same
> level of urgency.
I like the "should" version. You introduced a "please" to mark the
action that the user is being asked to make a decision about, which
is a common convention in templates. Having another "please" in the
same template might distract from that; saying "you should" turns it
into part of the factual background information (it's their duty as
well-behaved members of the community!) instead.
>> Why the switch from single quotes to double quotes for the lspci command?
>
> This is something we discussed in former reviews. The standard for
> en_US is definitely double quotes for quoting and our reviews are
> standardized on en_US spelling and typography....even if the main
> reviewers are British (except /me of course)..:-)
I'm happy to standardise things in either direction. I've never
seen any particular evidence that modern en_GB users as a whole
prefer singlequotes, especially when typing on keyboards with
perfectly good <"> keysyms that would otherwise go unused.
A harder question is whether we'd "correct" UTF-8 curlyquotes.
>>> Turn "you should not have this package" into "this package becomes
>>> useless". After all, I do what I want and I'm perfectly entitled to
>>> have a package that's useless..:-)
>>
>> I'd prefer something like "this pakages becomes not useful", instead
>> of "useless", the latter seems pretty strong. :)
>
> OK. Would seem fair. Justin, is "becomes not useful" the right way to
> write it in English ?
Try "this package will not be useful".
>>> Turn "file a bug" into "report a bug".
>>
>> Or "file a bug report"?
>
> My original intent was that "file a bug" is kind of jargonic. I think
> that "filing" something might also be hard to understand for someone
> not very savvy with usual jargon, but I might be wrong, here.
"File a bug" is verging on jargon, but "file a bug report" and
"report a bug" seem equally good to me.
>>> Use recommended itemization style and do not make it a separate paragraph.
>>
>> Please use '*'. I've always got the impression that was the most used
>> itemization style in Debian, the recent numbers posted on debian-devel
>> confirms that, and I'm guessing the Smith project in a way might have
>> slightly turned the balance on those numbers.
>
> I followed that discussion and I understand the argument.
>
> I would prefer an argument from a typographical reference here.
>
> I think that the best reference for this would be the Chicago Manual
> of Style. I suspect we might end up with asterisks, though.
In printed publications of course the standard is to use genuine
U+2022 bullet points, not asterisks. If we're sticking to things
we've got on our keyboards, asterisks make sense since after all
they're the most "bulletlike" character we've got and aren't useful
for much else. But minuses and pluses work too.
>>> - NOTE: You'll need the /dev/3dfx kernel driver to use this library.
>>> + You'll need the /dev/3dfx kernel driver to use this library.
>>>
>>> Do not yell..:-). Instead of "not the package you want", just use "not
>>> useful". Again, I could want a package even if it's useless...
>>
>> Same comment as the previous "useless" one.
(The wording in the text here is "not useful", so there's nothing
for us to argue about.)
>>> We generally recommend dropping "NOTE:" stuff.
>>
>> Why? I don't have a strong feeling about it, but it seems to make it
>> easier to visually mark this kind of out-of-band dependency information.
>
> In general, the reasoning is that separating in a paragraph is enough
> for the notice to be visible and we do our best to discourage the use
> of all-capitals letters (yelling, etc.). That also goes with a general
> stance where texts should be as neutral as possible and avoid carrying
> "emotional" charge...
What makes the kernel requirements "out-of-band" and the hardware
requirements "in-band"(?), anyway?
The real problem is that everything you say in a package description
_could_ be preceded by a "NOTE" prefix. This one was already a
prime example of note proliferation, since there's three successive
paragraphs start with "Note", "Also note", "NOTE:"!
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Reply to: