From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mailout.scc.kit.edu (mailout.scc.kit.edu [129.13.185.202]) by krisdoz.my.domain (8.14.5/8.14.5) with ESMTP id s5MItY8l010309 for ; Sun, 22 Jun 2014 14:55:35 -0400 (EDT) Received: from hekate.usta.de (asta-nat.asta.uni-karlsruhe.de [172.22.63.82]) by scc-mailout-02.scc.kit.edu with esmtp (Exim 4.72 #1) id 1WymvJ-0002Qj-BW; Sun, 22 Jun 2014 20:55:29 +0200 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.77) (envelope-from ) id 1WymvB-0003yI-0t; Sun, 22 Jun 2014 20:55:21 +0200 Received: from iris.usta.de ([172.24.96.5] helo=usta.de) by donnerwolke.usta.de with esmtp (Exim 4.72) (envelope-from ) id 1Wyn1F-0004AV-6C; Sun, 22 Jun 2014 21:01:37 +0200 Received: from schwarze by usta.de with local (Exim 4.77) (envelope-from ) id 1WymvI-000259-Ul; Sun, 22 Jun 2014 20:55:28 +0200 Date: Sun, 22 Jun 2014 20:55:28 +0200 From: Ingo Schwarze To: jmc@openbsd.org Cc: discuss@mdocml.bsd.lv Subject: deprecate .Tn and .Ux Message-ID: <20140622185528.GH15298@iris.usta.de> X-Mailinglist: mdocml-discuss Reply-To: discuss@mdocml.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.5.21 (2010-09-15) 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