svn commit: r362191 - head/sbin/md5

[Warner Losh]

On Mon, Jun 15, 2020 at 7:34 AM Mateusz Piotrowski <0mp at freebsd.org> wrote:

> Hi,
>
> On 6/15/20 2:33 PM, Rodney W. Grimes wrote:
> > [ Charset UTF-8 unsupported, converting... ]
> >> Author: fernape (ports committer)
> >> Date: Mon Jun 15 10:08:02 2020
> >> New Revision: 362191
> >> URL: https://svnweb.freebsd.org/changeset/base/362191
> >>
> >> Log:
> >>   md5(1): fix style in man page
> >
> > Mandoc is fine to ignore this, but it is wrong to call it useless.
> >
> > I really wish that this stop.  .Tn might be useless to mandoc,
> > but it is a very usable thing if your formatting to something
> > other than txt, as in a ps or pdf.
>
> In that case I would consider patching our in-tree mandoc to not warn
> about Tn. Or request support for Tn or a well-defined replacement upstream.
>
> I can see the benefit of keeping Tn around, as it /might/ potentially
> create nice formatting for HTML. On the other hand, I don't like the
> idea of not following the linter.
>

I thought that Tn thing was the general consensus thing and added to the
linter because of that. The man page explains why it's problematic:

     Tn word ...
          Supported only for compatibility, do not use this in new manuals.
          Even though the macro name ("tradename") suggests a semantic
          function, historic usage is inconsistent, mostly using it as a
          presentation-level macro to request a small caps font.

It was useful for the Unix trademark, but was tailor towards AT&T's
preferred dressing for the Unix trademark, not for trademarks in general.

In this case, there were several instances of abuse:

-.Tn RSA .
+key under a public-key cryptosystem such as RSA.

Not a trademark in this context. RSA is a trademark for the RSA corporation
and it uses it in various other contexts.

-The
-.Tn MD5
-and
-.Tn SHA-1
-algorithms have been proven to be vulnerable to practical collision
-attacks and should not be relied upon to produce unique outputs,
+The MD5 and SHA-1 algorithms have been proven to be vulnerable to practical
+collision attacks and should not be relied upon to produce unique outputs,

MD5 and SHA-1 are not trade names in this context. The rest seem similar,
though I've not gone to the trouble to look them all up.

All in all, while I have some sympathy to Rod's view that we're losing
semantic information by these changes in general, this particular one
actually fixes the abuse talked about in the mdoc manual, IMHO.

Warner