Re: deprecate .Tn and .Ux

[Ingo Schwarze <schwarze@usta.de>]

Hi Jason,

Jason McIntyre wrote on Sun, Jun 22, 2014 at 09:59:40PM +0059:
> On Sun, Jun 22, 2014 at 08:55:28PM +0200, Ingo Schwarze wrote:

>> i'd like to more actively deprecate the mdoc(7) .Tn and .Ux macros.
>> Are there any objections?
>> 
>> The .Tn macro is useless as a semantic macro.  There is no need to
>> mark up tradenames in manual pages.  Existing usage is very
>> inconsistent, and trying to improve that would be a waste of time.
>> Even if existing usage were mostly accurate, nobody should rely on
>> manuals for legal advice regarding their company.
>> 
>> Historically, .Tn was mostly used as a presentation-level macro to
>> request a small caps font.  In that capacity, it is a horrible
>> misnomer and has caused confusion again and again.  Fortunately,
>> marking up stuff to be rendered as small caps is not important at
>> all.  On the terminal, it makes no difference whatsoever, and even
>> in PostScript, that's just typographical finesse beyond the scope
>> of manual pages.  We really shouldn't encourage manual page authors
>> to worry about such minor typographical details.
>> 
>> The .Ux macro is useless for current documentation, spelling out
>> UNIX is four characters just as well.  Besides, almost no manual
>> pages are talking about commercial UNIX certification, and when
>> used outside that context today, UNIX is a rather fuzzy term.  Using
>> a dedicated macro creates the wrong impression of something quite
>> specific being referred to.  If it ends up being typeset in a special
>> way on a high-quality output device, there is a risk that it might
>> be misconstrued as specifically referring to the UNIX trademark.
>> 
>> Interestingly, the .Ux macro is even more useless for HISTORY
>> sections.  It just isn't specific enough.  To discuss history, you
>> always need the more specific macros like .At, .Bx, .Nx and so on.
>> 
>> So this patch removes both macros from the MACRO OVERVIEW and from
>> all "see also" lists, shortens their descriptions, and removes the
>> examples showing their usage.  Besides, it uses standard wordings
>> for deprecated macros (Bt Tn Ud Ux) and for obsolete macros (En Es
>> Fr Ot).

> hmm. what are the benefits of marking it as deprecated?
> chiefly that we will discourage its use?

Yes.  Right now, many people dislike it, and there is oral
wisdom discouraging it.  I consider it unfortunate for the
official documentation to encourage its use.

> personally i pretty much zap Tn as i come across it.
> it's a mess that's always appalled me.

Yes, and the patch is about making our official recommendations
consistent with that good practice.

> Ux i encounter rarely.

Sure, it causes less pain.  It does occur now and then, though.
Somebody just sent patches to OpenBSD proposing to change ".Tn UNIX"
to ".Ux", which is only a very minor improvement, if any.

> maybe you should try and coordinate this with groff and/or other bsds.

That's why i Cc:ed discuss@mdocml, people from at least NetBSD, FreeBSD
and DragonFly lurk here.  I'd expect protest here if the issue were
contentious.

Traditionally, mdoc(7) came from the BSD side.  While the groff
folks did improve and does maintain it, they tend to not feel very
strongly about finer details, so i'd probably not bother them at
this point.

> i've no problem with them disappearing, but i don;t know how much
> it achieves if it's only mandoc marking it as deprecated.

Nowadays, mandoc has become somewhat authoritative regarding the
mdoc(7) language, given that all BSDs have it in base and mdoc(7)
usage is still most widespread in BSD systems.

It wasn't as authoritative three years ago, but i think that has
changed considerably.

> still, if we hate stuff, why promote it? ;)
> 
> so i guess i'm ok with this, but would prefer the discussion to
> at least be broadcast a bit further.

Hmm...  Any comments from other BSDs, or whom do you think
should we ask about this in your projects, in case you fear
people might get upset about it?

Yours,
  Ingo


>> Index: mdoc.7
>> ===================================================================
>> RCS file: /cvs/src/share/man/man7/mdoc.7,v
>> retrieving revision 1.111
>> diff -u -r1.111 mdoc.7
>> --- mdoc.7	22 Jun 2014 17:06:50 -0000	1.111
>> +++ mdoc.7	22 Jun 2014 18:20:24 -0000
>> @@ -513,7 +513,6 @@
>>  .It Sx \&Cd Ta kernel configuration declaration (>0 arguments)
>>  .It Sx \&Ad Ta memory address (>0 arguments)
>>  .It Sx \&Ms Ta mathematical symbol (>0 arguments)
>> -.It Sx \&Tn Ta tradename (>0 arguments)
>>  .El
>>  .Ss Physical markup
>>  .Bl -column "Brq, Bro, Brc" description
>> @@ -541,7 +540,6 @@
>>  .It Sx \&Ex Fl std Ta standard command exit values: Op Ar utility ...
>>  .It Sx \&Rv Fl std Ta standard function return values: Op Ar function ...
>>  .It Sx \&St Ta reference to a standards document (one argument)
>> -.It Sx \&Ux Ta Ux
>>  .It Sx \&At Ta At
>>  .It Sx \&Bx Ta Bx
>>  .It Sx \&Bsx Ta Bsx
>> @@ -752,9 +750,8 @@
>>  .Sx \&Dx ,
>>  .Sx \&Fx ,
>>  .Sx \&Nx ,
>> -.Sx \&Ox ,
>>  and
>> -.Sx \&Ux .
>> +.Sx \&Ox .
>>  .Ss \&Bc
>>  Close a
>>  .Sx \&Bo
>> @@ -1118,10 +1115,10 @@
>>  .Sx \&Dx ,
>>  .Sx \&Fx ,
>>  .Sx \&Nx ,
>> -.Sx \&Ox ,
>>  and
>> -.Sx \&Ux .
>> +.Sx \&Ox .
>>  .Ss \&Bt
>> +Supported only for compatibility, do not use this in new manuals.
>>  Prints
>>  .Dq is currently in beta test.
>>  .Ss \&Bx
>> @@ -1141,9 +1138,8 @@
>>  .Sx \&Dx ,
>>  .Sx \&Fx ,
>>  .Sx \&Nx ,
>> -.Sx \&Ox ,
>>  and
>> -.Sx \&Ux .
>> +.Sx \&Ox .
>>  .Ss \&Cd
>>  Kernel configuration declaration.
>>  This denotes strings accepted by
>> @@ -1456,9 +1452,8 @@
>>  .Sx \&Bx ,
>>  .Sx \&Fx ,
>>  .Sx \&Nx ,
>> -.Sx \&Ox ,
>>  and
>> -.Sx \&Ux .
>> +.Sx \&Ox .
>>  .Ss \&Ec
>>  Close a scope started by
>>  .Sx \&Eo .
>> @@ -1507,7 +1502,7 @@
>>  and
>>  .Sx \&Sy .
>>  .Ss \&En
>> -This macro is obsolete and not implemented in
>> +This macro is obsolete and ignored by
>>  .Xr mandoc 1 .
>>  .Ss \&Eo
>>  An arbitrary enclosure.
>> @@ -1534,7 +1529,8 @@
>>  .Sx \&Dv
>>  for general constants.
>>  .Ss \&Es
>> -This macro is obsolete and not implemented.
>> +This macro is obsolete and ignored by
>> +.Xr mandoc 1 .
>>  .Ss \&Ev
>>  Environmental variables such as those specified in
>>  .Xr environ 7 .
>> @@ -1714,7 +1710,7 @@
>>  and
>>  .Sx \&Ft .
>>  .Ss \&Fr
>> -This macro is obsolete and not implemented in
>> +This macro is obsolete and ignored by
>>  .Xr mandoc 1 .
>>  .Pp
>>  It was used to show function return values.
>> @@ -1759,9 +1755,8 @@
>>  .Sx \&Bx ,
>>  .Sx \&Dx ,
>>  .Sx \&Nx ,
>> -.Sx \&Ox ,
>>  and
>> -.Sx \&Ux .
>> +.Sx \&Ox .
>>  .Ss \&Hf
>>  This macro is not implemented in
>>  .Xr mandoc 1 .
>> @@ -2079,9 +2074,8 @@
>>  .Sx \&Bx ,
>>  .Sx \&Dx ,
>>  .Sx \&Fx ,
>> -.Sx \&Ox ,
>>  and
>> -.Sx \&Ux .
>> +.Sx \&Ox .
>>  .Ss \&Oc
>>  Close multi-line
>>  .Sx \&Oo
>> @@ -2135,7 +2129,7 @@
>>  and
>>  .Sx \&Dt .
>>  .Ss \&Ot
>> -This macro is obsolete and not implemented in
>> +This macro is obsolete and ignored by
>>  .Xr mandoc 1 .
>>  .Pp
>>  Historical
>> @@ -2158,9 +2152,8 @@
>>  .Sx \&Bx ,
>>  .Sx \&Dx ,
>>  .Sx \&Fx ,
>> -.Sx \&Nx ,
>>  and
>> -.Sx \&Ux .
>> +.Sx \&Nx .
>>  .Ss \&Pa
>>  An absolute or relative file system path, or a file or directory name.
>>  If an argument is not provided, the character
>> @@ -2648,36 +2641,19 @@
>>  lists; can only be used below
>>  .Sx \&It .
>>  .Ss \&Tn
>> -Format a tradename.
>> -.Pp
>> -Since this macro is often implemented to use a small caps font,
>> -it has historically been used for acronyms (like ASCII) as well.
>> -Such usage is not recommended because it would use the same macro
>> -sometimes for semantical annotation, sometimes for physical formatting.
>> -.Pp
>> -Examples:
>> -.Dl \&.Tn IBM
>> +Supported only for compatibility, do not use this in new manuals.
>> +Even though the macro name
>> +.Pq Dq tradename
>> +suggests a semantic function, historic usage is inconsistent, mostly
>> +using it as a presentation-level macro to request a small caps font.
>>  .Ss \&Ud
>> +Supported only for compatibility, do not use this in new manuals.
>>  Prints out
>>  .Dq currently under development.
>>  .Ss \&Ux
>> -Format the
>> -.Ux
>> -name.
>> -Accepts no argument.
>> -.Pp
>> -Examples:
>> -.Dl \&.Ux
>> -.Pp
>> -See also
>> -.Sx \&At ,
>> -.Sx \&Bsx ,
>> -.Sx \&Bx ,
>> -.Sx \&Dx ,
>> -.Sx \&Fx ,
>> -.Sx \&Nx ,
>> -and
>> -.Sx \&Ox .
>> +Supported only for compatibility, do not use this in new manuals.
>> +Prints out
>> +.Dq Ux .
>>  .Ss \&Va
>>  A variable name.
>>  .Pp
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv