deprecate .Tn and .Ux

deprecate .Tn and .Ux

[Ingo Schwarze]

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

Re: deprecate .Tn and .Ux

[Ingo Schwarze]

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

Re: deprecate .Tn and .Ux

[Thomas Klausner]

On Mon, Jun 23, 2014 at 09:55:35PM +0200, Ingo Schwarze wrote:
> 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?

I don't have a problem with it as long as Tn/Ux still work for now
(too many occurrences in the NetBSD man pages). But that seems to be
what the patch does, so it's ok with me.
 Thomas
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: deprecate .Tn and .Ux

[Ingo Schwarze]

Hi Thomas,

Thomas Klausner wrote on Mon, Jun 23, 2014 at 10:15:31PM +0200:
> On Mon, Jun 23, 2014 at 09:55:35PM +0200, Ingo Schwarze wrote:

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

> I don't have a problem with it as long as Tn/Ux still work for now
> (too many occurrences in the NetBSD man pages). But that seems to be
> what the patch does,

Exactly.

I don't plan code changes to remove support for old stuff at all.  
I want to be able to use mandoc to view original Version 7 AT&T UNIX
and original 2BSD - 4.4BSD manuals out of the box (Version 6 and 1BSD
won't work, though, they use an older macro set).

This is exclusively about which usage we want to encourage or
discourage in modern manuals.

> so it's ok with me.

Thanks for taking a look!
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: deprecate .Tn and .Ux

[Ulrich Spörlein]

On Mon, 2014-06-23 at 22:41:44 +0200, Ingo Schwarze wrote:
> Hi Thomas,
> 
> Thomas Klausner wrote on Mon, Jun 23, 2014 at 10:15:31PM +0200:
> > On Mon, Jun 23, 2014 at 09:55:35PM +0200, Ingo Schwarze wrote:
> 
> >> 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?
> 
> > I don't have a problem with it as long as Tn/Ux still work for now
> > (too many occurrences in the NetBSD man pages). But that seems to be
> > what the patch does,
> 
> Exactly.
> 
> I don't plan code changes to remove support for old stuff at all.  
> I want to be able to use mandoc to view original Version 7 AT&T UNIX
> and original 2BSD - 4.4BSD manuals out of the box (Version 6 and 1BSD
> won't work, though, they use an older macro set).
> 
> This is exclusively about which usage we want to encourage or
> discourage in modern manuals.

Sorry for being late to the party, but the deprecation is also perfectly
fine with me. Just as long as we don't break the old manuals.

Thanks!
Uli
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv