Re: Mandoc Not Parsing Sy Macro (In some cases)

[Ingo Schwarze <schwarze@usta.de>]

Hi Abhinav,

Abhinav Upadhyay wrote on Mon, Jan 09, 2017 at 04:06:43PM +0530:

> In NetBSD's sysctl(7) man page, we noticed an issue where in some
> tables the Sy macro was not being parsed and being rendered literally
> as "Sy". While in other places it was being parsed correctly. On
> looking closely, we realized that in the cases where Sy was not being
> parsed, we were using <TAB> instead of Ta macro, like this:
> 
> .It Sy Second level name    Sy Type Sy Changeable
> 
> Which is being rendered as:
> Second level name  Sy Type    Sy Changeable

That is correct rendering.

Groff renders it the same way.

> Whereas in the places where it was being rendered correctly, we were
> using Ta, like this:
>
> It Sy Name  Ta Sy Constant     Ta Sy Next level names Ta Sy Description

Yes, that is exactly why you should preferably use Ta and not
literal tabs.  It's much easier to use correctly, and the mdoc(7)
source code is easier to read.

If you insist on using literal tabs, you need a blank character
between the tab and the following macro.

Yes, that is weird: a blank is syntactically significant after
a tab.  But that's just how roff traditionally behaves.

> I think this issue was not present in the previous version of mandoc,

Yes, 1.13.3 had a bug processing the first word after a tab
incorrectly.  It was fixed on October 17, 2015.

See

http://cvsweb.openbsd.org/cgi-bin/cvsweb/src/regress/usr.bin/mandoc/mdoc/Bl/column.in

in particular the commit message of revision 1.8, the test code
added by that commit, and the correct output in

http://cvsweb.openbsd.org/cgi-bin/cvsweb/src/regress/usr.bin/mandoc/mdoc/Bl/column.out_ascii?rev=HEAD&content-type=text/x-cvsweb-markup

> It has been noticed only with the latest release.

The proper response is to fix your manual pages.  You should do that
because as they are, they are not portable and won't work with groff.
Either insert the missing blanks or - much better for clarity
and robustness - use Ta rather than bare tabs.

I think i will also commit a clarification to the mdoc(7) manual
because this is indeed a nasty trap for the unwary.

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv