deprecate .Tn and .Ux

[Ingo Schwarze <schwarze@usta.de>]

Hi,

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).

OK?
  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