Re: groff_mdoc(7): Document .Lk and .Mt macros.

[G. Branden Robinson]

Hi Ingo!

At 2020-12-20T17:08:22+0100, Ingo Schwarze wrote:
> G. Branden Robinson wrote on Sun, Dec 20, 2020 at 03:38:54AM -0500:
> >     groff_mdoc(7): Document .Lk and .Mt macros.
[...]
> >  .It Li .Lk
> > -To be written.
> > +Embed hyperlink.
> > +.
> > +.
> > +.Pp
> > +.Dl Usage: .Lk Ao url link-text Ac
> 
> I think this is incorrect.
> 
> Empty .Lk prints nothing and mandoc even warns about it:
> 
>   mandoc: tmp.mdoc:9:2: WARNING: skipping empty macro: Lk
> 
> So i think the first argument isn't optional.

Good!  I'm a fan of minimizing the number of ways to say "no operation"
in any language.  :D

> But the second argument definitely is optional.
> 
> Correct markup would be:
> 
>   .D1 Usage: Pf . Ic \&Lk Ar uri Op Ar link-text

Okay.  I'll try this out.

> I know the groff_mdoc(7) manual violates mdoc markup conventions
> throughout in very ugly ways, and at some point, that should be fixed.

It also violates the conventions of other groff man pages, the ones I've
spent the last 3+ years making more consistent.  Until recently I did
not touch the page at all, so its divergence has grown more obvious.

> The use of .Ao is disgusting in particular and clashes with the
> semantic markup paradigm that is fundamental to mdoc.

No serious argument here.  I'm also not a huge fan of using angle
brackets as parameter delimeters when whitespace already separates
parameters in the language being documented.

> But at least the manual should not mislead as to which arguments are
> mandatory and which are optional.

Agreed.

> >  .It Li .Mt
> > -To be written.
> > +Embed email address.
> > +.
> > +.
> > +.Pp
> > +.Dl Usage: .Mt email-address
> > +.
> 
> Except for the missing markup, the content of this part seems correct.

Thanks.  After looking up the meanings of several mandoc macros, I'll
try to make this one resemble your .Lk suggestion above.

Regards,
Branden

signature.asc
Description: PGP signature