Deprecate .Tn and .Ux, and make it clearer that .Bt and .Ud are deprecated.

Do not use these macros in new documents, they provide no value.
Instead, usually no macro and no markup is needed at all.
Of course, they remain supported for compatibility with existing manuals.

Jason McIntyre (OpenBSD), Thomas Klausner (NetBSD) and
Franco Fichtner (DragonFly) are OK with this documentation change.

diff --git a/mdoc.7 b/mdoc.7
index 98c68c11ce03cb6fbafb346a1fd25ad08ac985c3..0706a19b7b01506fd3efa56cee7f160e94491b89 100644 (file)
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,4 +1,4 @@
-.\"    $Id: mdoc.7,v 1.229 2014/06/22 17:07:06 schwarze Exp $
+.\"    $Id: mdoc.7,v 1.230 2014/06/24 21:43:08 schwarze Exp $

 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010, 2011, 2013 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010, 2011, 2013 Ingo Schwarze <schwarze@openbsd.org>


@@ -15,7 +15,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"

-.Dd $Mdocdate: June 22 2014 $
+.Dd $Mdocdate: June 24 2014 $

 .Dt MDOC 7
 .Os
 .Sh NAME
 .Dt MDOC 7
 .Os
 .Sh NAME


@@ -513,7 +513,6 @@ in the alphabetical
 .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 \&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
 .El
 .Ss Physical markup
 .Bl -column "Brq, Bro, Brc" description


@@ -541,7 +540,6 @@ in the alphabetical
 .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 \&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
 .It Sx \&At Ta At
 .It Sx \&Bx Ta Bx
 .It Sx \&Bsx Ta Bsx


@@ -752,9 +750,8 @@ See also
 .Sx \&Dx ,
 .Sx \&Fx ,
 .Sx \&Nx ,
 .Sx \&Dx ,
 .Sx \&Fx ,
 .Sx \&Nx ,

-.Sx \&Ox ,

 and
 and

-.Sx \&Ux .
+.Sx \&Ox .

 .Ss \&Bc
 Close a
 .Sx \&Bo
 .Ss \&Bc
 Close a
 .Sx \&Bo


@@ -1118,10 +1115,10 @@ See also
 .Sx \&Dx ,
 .Sx \&Fx ,
 .Sx \&Nx ,
 .Sx \&Dx ,
 .Sx \&Fx ,
 .Sx \&Nx ,

-.Sx \&Ox ,

 and
 and

-.Sx \&Ux .
+.Sx \&Ox .

 .Ss \&Bt
 .Ss \&Bt

+Supported only for compatibility, do not use this in new manuals.

 Prints
 .Dq is currently in beta test.
 .Ss \&Bx
 Prints
 .Dq is currently in beta test.
 .Ss \&Bx


@@ -1141,9 +1138,8 @@ See also
 .Sx \&Dx ,
 .Sx \&Fx ,
 .Sx \&Nx ,
 .Sx \&Dx ,
 .Sx \&Fx ,
 .Sx \&Nx ,

-.Sx \&Ox ,

 and
 and

-.Sx \&Ux .
+.Sx \&Ox .

 .Ss \&Cd
 Kernel configuration declaration.
 This denotes strings accepted by
 .Ss \&Cd
 Kernel configuration declaration.
 This denotes strings accepted by


@@ -1441,9 +1437,8 @@ See also
 .Sx \&Bx ,
 .Sx \&Fx ,
 .Sx \&Nx ,
 .Sx \&Bx ,
 .Sx \&Fx ,
 .Sx \&Nx ,

-.Sx \&Ox ,

 and
 and

-.Sx \&Ux .
+.Sx \&Ox .

 .Ss \&Ec
 Close a scope started by
 .Sx \&Eo .
 .Ss \&Ec
 Close a scope started by
 .Sx \&Eo .


@@ -1492,7 +1487,7 @@ See also
 and
 .Sx \&Sy .
 .Ss \&En
 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.
 .Xr mandoc 1 .
 .Ss \&Eo
 An arbitrary enclosure.


@@ -1519,7 +1514,8 @@ See also
 .Sx \&Dv
 for general constants.
 .Ss \&Es
 .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 .
 .Ss \&Ev
 Environmental variables such as those specified in
 .Xr environ 7 .


@@ -1699,7 +1695,7 @@ See also
 and
 .Sx \&Ft .
 .Ss \&Fr
 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.
 .Xr mandoc 1 .
 .Pp
 It was used to show function return values.


@@ -1744,9 +1740,8 @@ See also
 .Sx \&Bx ,
 .Sx \&Dx ,
 .Sx \&Nx ,
 .Sx \&Bx ,
 .Sx \&Dx ,
 .Sx \&Nx ,

-.Sx \&Ox ,

 and
 and

-.Sx \&Ux .
+.Sx \&Ox .

 .Ss \&Hf
 This macro is not implemented in
 .Xr mandoc 1 .
 .Ss \&Hf
 This macro is not implemented in
 .Xr mandoc 1 .


@@ -2064,9 +2059,8 @@ See also
 .Sx \&Bx ,
 .Sx \&Dx ,
 .Sx \&Fx ,
 .Sx \&Bx ,
 .Sx \&Dx ,
 .Sx \&Fx ,

-.Sx \&Ox ,

 and
 and

-.Sx \&Ux .
+.Sx \&Ox .

 .Ss \&Oc
 Close multi-line
 .Sx \&Oo
 .Ss \&Oc
 Close multi-line
 .Sx \&Oo


@@ -2120,7 +2114,7 @@ See also
 and
 .Sx \&Dt .
 .Ss \&Ot
 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
 .Xr mandoc 1 .
 .Pp
 Historical


@@ -2143,9 +2137,8 @@ See also
 .Sx \&Bx ,
 .Sx \&Dx ,
 .Sx \&Fx ,
 .Sx \&Bx ,
 .Sx \&Dx ,
 .Sx \&Fx ,

-.Sx \&Nx ,

 and
 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
 .Ss \&Pa
 An absolute or relative file system path, or a file or directory name.
 If an argument is not provided, the character


@@ -2633,36 +2626,19 @@ Table cell separator in
 lists; can only be used below
 .Sx \&It .
 .Ss \&Tn
 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
 .Ss \&Ud

+Supported only for compatibility, do not use this in new manuals.

 Prints out
 .Dq currently under development.
 .Ss \&Ux
 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
 .Ss \&Va
 A variable name.
 .Pp