* deprecate .Tn and .Ux @ 2014-06-22 18:55 Ingo Schwarze [not found] ` <20140622210005.GA6196@harkle.home.gateway> 0 siblings, 1 reply; 5+ messages in thread From: Ingo Schwarze @ 2014-06-22 18:55 UTC (permalink / raw) To: jmc; +Cc: discuss 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 ^ permalink raw reply [flat|nested] 5+ messages in thread
[parent not found: <20140622210005.GA6196@harkle.home.gateway>]
* Re: deprecate .Tn and .Ux [not found] ` <20140622210005.GA6196@harkle.home.gateway> @ 2014-06-23 19:55 ` Ingo Schwarze 2014-06-23 20:15 ` Thomas Klausner 0 siblings, 1 reply; 5+ messages in thread From: Ingo Schwarze @ 2014-06-23 19:55 UTC (permalink / raw) To: Jason McIntyre; +Cc: discuss 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 ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: deprecate .Tn and .Ux 2014-06-23 19:55 ` Ingo Schwarze @ 2014-06-23 20:15 ` Thomas Klausner 2014-06-23 20:41 ` Ingo Schwarze 0 siblings, 1 reply; 5+ messages in thread From: Thomas Klausner @ 2014-06-23 20:15 UTC (permalink / raw) To: discuss; +Cc: Jason McIntyre 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 ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: deprecate .Tn and .Ux 2014-06-23 20:15 ` Thomas Klausner @ 2014-06-23 20:41 ` Ingo Schwarze 2014-07-30 11:56 ` Ulrich Spörlein 0 siblings, 1 reply; 5+ messages in thread From: Ingo Schwarze @ 2014-06-23 20:41 UTC (permalink / raw) To: Thomas Klausner; +Cc: discuss, Jason McIntyre 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 ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: deprecate .Tn and .Ux 2014-06-23 20:41 ` Ingo Schwarze @ 2014-07-30 11:56 ` Ulrich Spörlein 0 siblings, 0 replies; 5+ messages in thread From: Ulrich Spörlein @ 2014-07-30 11:56 UTC (permalink / raw) To: discuss; +Cc: Thomas Klausner, Jason McIntyre 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 ^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2014-07-30 11:56 UTC | newest] Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2014-06-22 18:55 deprecate .Tn and .Ux Ingo Schwarze [not found] ` <20140622210005.GA6196@harkle.home.gateway> 2014-06-23 19:55 ` Ingo Schwarze 2014-06-23 20:15 ` Thomas Klausner 2014-06-23 20:41 ` Ingo Schwarze 2014-07-30 11:56 ` Ulrich Spörlein
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).