freebsd stable - Feb 2014 - RFC: deprecation of nve(4) in 10-STABLE and removal from 11-CURRENT

Yonghyeon PYUN wrote:
> On Mon, Feb 03, 2014 at 02:56:37PM +0100, Christian Brueffer wrote:
> > Hi,
> > 
> > for some time now we have had two drivers for NVIDIA NForce/MCP
network
> > chips, namely nve(4) and nfe(4).
> > 
> > The former came first and is based on a binary blob.  The latter was
> > later ported from OpenBSD and is blob-free.
> > 
> > nfe(4) supports all chips nve(4) supports, in addition to all the
newer
> > hardware.  In essence, nfe(4) has been the de-facto standard driver
for
> > a long time.  nve(4) has been commented out in GENERIC since 2007.
> > 
> > For this reason I propose deprecating nve(4) in 10-STABLE and removing
> > it from HEAD.
> > 
> > Does anyone see a reason not to do this?
> 
> A couple of users were still using nve(4) in the past. I guess
> the issue might be lack of code for waking up MAC/PHY from
> powerdown.  nfe(4) already has the needed code and should support
> all known NVIDIA ethernet controllers with full offloading support.
> So no objection from me.
It seems a good case to remove nve, no objection.

Please remove at a leisurely managed pace:
  (unless code conflicts press for urgency), ie at least one minor
  release on each major branch should contain a code revocation
  warning in the manual & preferably in a src/[A-Z]*, before the
  next minor release in same major release sequence might no longer
  contain old code.

  ( Not to suggest it wasn't planned similarly anyway, but some
  changes in other areas of FreeBSD have been rushed, & it's
  good to set an example of planning maturity. )  

  Some FreeBSD end users inc.  customers barely (if even) read
  announce@, let alone other lists such as these, but some do read
  manuals, & notice code withdrawal warnings.

I informed one old customer who was maybe still using nve, others
might take a similar opportunity, a subtle way to also invite people
to look at FreeBSD [again] ;-) , referring to eg:
  http://lists.freebsd.org/pipermail/freebsd-current/2014-February/048211.html
  http://svnweb.freebsd.org/base/release/10.0.0/share/man/man4/nve.4?view=markup
  http://svnweb.freebsd.org/base/release/10.0.0/share/man/man4/nfe.4?view=markup

It seems safe to add a removal warning in 
  http://svnweb.freebsd.org/base/head/share/man/man4/nve.4?view=markup
( there is not one yet at Rev 217468, I just checked. )

Best avoid the obscure word `Deprecated' in manuals:
  It's not common/ plain English.  Maybe a geek import, or USA
  dialect ?  It's not easily internationaly understood English.
  Best make manuals easier for non native English speakers (& native
  English too ;-).  I am British born & bred, whether in English
  speaking circles in UK or Germany I never hear or read 'deprecated'
  unless its in BSD context.  Few native English speakers I know will be
  immediately sure of the meaning, it's too obscure.
  
Cheers,
Julian
-- 
Julian Stacey, BSD Unix Linux C Sys Eng Consultant, Munich http://berklix.com
 Interleave replies below like a play script.  Indent old text with ">
".
 Send plain text, not quoted-printable, HTML, base64, or multipart/alternative.

On Thu, Feb 6, 2014 at 6:34 PM, Julian H. Stacey <jhs at berklix.com>
wrote:
> Best avoid the obscure word `Deprecated' in manuals:
>   It's not common/ plain English.  Maybe a geek import, or USA
>   dialect ?  It's not easily internationaly understood English.
>   Best make manuals easier for non native English speakers (& native
>   English too ;-).  I am British born & bred, whether in English
>   speaking circles in UK or Germany I never hear or read
'deprecated'
>   unless its in BSD context.  Few native English speakers I know will be
>   immediately sure of the meaning, it's too obscure.
As another Briton this surprises me:
The word "deprecate" has a clear and specific meaning in all
computing, especially in standards, release notes and documentation.
It is from latin and is the same base word in all romance languages.
It is definitely in common usage in the UK, I would not hesitate to
use it any conversation with anyone and expect them to understand its
meaning.

To my ear there is no clearer word to use for this purpose.

Cheers

Tom

On 6 Feb 2014, at 18:34, Julian H. Stacey <jhs at berklix.com> wrote:
> Best avoid the obscure word `Deprecated' in manuals:
>  It's not common/ plain English.  Maybe a geek import, or USA
>  dialect ?  It's not easily internationaly understood English.
>  Best make manuals easier for non native English speakers (& native
>  English too ;-).  I am British born & bred, whether in English
>  speaking circles in UK or Germany I never hear or read
'deprecated'
>  unless its in BSD context.  Few native English speakers I know will be
>  immediately sure of the meaning, it's too obscure.
I'd strongly disagree with this.  Deprecated is, perhaps, only in common use
as jargon, but it's very widespread within the tech field.  I don't
think I've ever read an API reference that doesn't include the word, for
example, and it's even a keyword in many code documentation tools.  For
example, JavaDoc supports @deprecated and gcc / clang include an
__attribute__((deprecated)) that generates a compile-time warning whenever
anyone tries to call a deprecated function.

I've not come across the word outside of tech uses, but I've also not
come across the term network interface outside of tech circles.  Deprecated, in
this use, may be jargon, but it's very widespread jargon, and requesting it
not be used sounds like asking for words like driver or processor also be
avoided.

David
(Also a native English speaker, although familiar with the unofficial fork from
Leftpondia)

Quoth Tom Evans <tevans.uk at googlemail.com>:
> On Thu, Feb 6, 2014 at 6:34 PM, Julian H. Stacey <jhs at berklix.com>
wrote:
> > Best avoid the obscure word `Deprecated' in manuals:
> >   It's not common/ plain English.  Maybe a geek import, or USA
> >   dialect ?  It's not easily internationaly understood English.
> >   Best make manuals easier for non native English speakers (&
native
> >   English too ;-).  I am British born & bred, whether in English
> >   speaking circles in UK or Germany I never hear or read
'deprecated'
> >   unless its in BSD context.  Few native English speakers I know will
be
> >   immediately sure of the meaning, it's too obscure.
> 
> As another Briton this surprises me:
> The word "deprecate" has a clear and specific meaning in all
> computing, especially in standards, release notes and documentation.
> It is from latin and is the same base word in all romance languages.
    Deprecate, v. 1624. [... f. L. /de-/ + /precari/ pray.]
    1. To pray against (evil); to seek to avert by prayer; to pray for
       deliverance from (/arch./) 1628.
    2. To plead earnestly against; to express earnest disapproval of
       1641.
    [...]

also

    Deprecation 1556.
    [...]
    3. Earnest desire that something may be averted or removed; earnest
       disapproval of 1612.

(To be clearly distinguished from 'depreciate', which means something
quite different.)

Ben

Hi, Reference:
> From:		David Chisnall <theraven@freebsd.org>
> Date:		Thu, 6 Feb 2014 18:52:43 +0000
David Chisnall wrote:
> On 6 Feb 2014, at 18:34, Julian H. Stacey <jhs@berklix.com> wrote:
> 
> > Best avoid the obscure word `Deprecated' in manuals:
> >  It's not common/ plain English.  Maybe a geek import, or USA
> >  dialect ?  It's not easily internationaly understood English.
> >  Best make manuals easier for non native English speakers (&
native
> >  English too ;-).  I am British born & bred, whether in English
> >  speaking circles in UK or Germany I never hear or read
'deprecated'
> >  unless its in BSD context.  Few native English speakers I know will
be
> >  immediately sure of the meaning, it's too obscure.
> 
> I'd strongly disagree with this.  Deprecated is, perhaps, only in
common use as jargon, but it's very widespread within the tech field.  I
don't think I've ever read an API reference that doesn't include the
word, for example, and it's even a keyword in many code documentation tools.
For example, JavaDoc supports @deprecated and gcc / clang include an
__attribute__((deprecated)) that generates a compile-time warning whenever
anyone tries to call a deprecated function.
> 
> I've not come across the word outside of tech uses, but I've also
not come across the term network interface outside of tech circles.  Deprecated,
in this use, may be jargon, but it's very widespread jargon, and requesting
it not be used sounds like asking for words like driver or processor also be
avoided.
> 
> David
> (Also a native English speaker, although familiar with the unofficial fork
from Leftpondia)
Uh Huh ;-)  http://en.wiktionary.org/wiki/Leftpondia
American 1620 fork of English deduced.
  1620: When a Mayflower butter maid Deprecated a milk maid giving 20 ounces
  to a pint, & confused USA liquids down to 16 ounces.  (Beware man units).

Amerian is not always best international English.  It's a big early
variant of English, but other native English speakers round the
globe well outnumber American I believe.  (Start with a map of the
Commonwealth), & many 2nd language people too will help define
international English, (as José Manuel Barroso, EU commission
president, said), not just natives, eg British or Americans etc,
will get to shape international English.

Americans often seem to find it harder to grasp what's internationaly
portable English, as opposed to American, perhaps because a large
country makes a higher percentage of language experience internal
national usage.

FreeBSD's manual writers, especially non native English manual
writers, should not copy Americanisms &/or bad nomenclature from
one manual to another, but ask themselves if they know better words,
to make it easier also for other non native English to read.  eg
Deprecated is not common English.

PS Light relief: http://www.bbc.com/future/story/20140206-can-drones-be-hacked

Cheers,
Julian
-- 
Julian Stacey, BSD Unix Linux C Sys Eng Consultant, Munich http://berklix.com
 Interleave replies below like a play script.  Indent old text with ">
".
 Send plain text, not quoted-printable, HTML, base64, or multipart/alternative.

--===============0519217857503668863=Content-Type: text/plain;
charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: inline

_______________________________________________
freebsd-stable@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-stable
To unsubscribe, send any mail to
"freebsd-stable-unsubscribe@freebsd.org"
--===============0519217857503668863==--