Re: -column issue

[Ingo Schwarze <schwarze@usta.de>]

Hi Jason and Kristaps,

Jason McIntyre wrote on Fri, Aug 06, 2010 at 06:51:36PM +0059:
> On Fri, Aug 06, 2010 at 07:08:11PM +0200, Kristaps Dzonsons wrote:
>> Jason wrote:

>>> hi. there's a formatting issue for -column lists. the best example
>>> i can find is in openbsd's sysctl.3 (it's riddled with these):
>>>
>>>	.Bl -column "Second level nameXXXXXX" integerXXX -offset indent
>>>	.It Sy Second level name	Type	Changeable
>>>	.It Dv FS_POSIX_SETUID No "	integer	yes"
>>>	.El

>> UGH.  This is gross.  Why why why didn't they do:
>> 
>>     46  .Bl -column "Second level nameXXXXXX" integerXXX -offset indent
>>     47  .It Sy Second level name        Type    Changeable
>>     48  .It Dv FS_POSIX_SETUID No       integer yes
>> 
>> (With tabs between columns.)  It renders just fine in both mandoc
>> and new/old groff.

[...]
> anyway, are you sure that your solution is correct?
> look carefully at how groff formats it:
> 
> Second level name          Type          Changeable
> FS_POSIX_SETUID No         integer       yes
> 
> i.e. it does not parse "No". mandoc does not display the "No".
> same if i move the "No" into the next column
> (which seems more logical).

I guess now i understand.
This has nothing to do with .Bl -column.
Rather, we are talking about tab characters.

The rules are:

1. Either a space or a tab delimit the initial macro on a line.
   If the delimiter is a tab, that tab is lost.

   Examples:
   .Fl<space>Fl       ->  Fl() Fl()  ->  "--"
   .Fl<tab>Fl         ->  Fl() Fl()  ->  "--"
   .Fl<tab><space>Fl  ->  Fl() Fl()  ->  "--"

   In this respect, there is a bug in mandoc.
   A tab character does not delimit the initial macro on a line,
   but .Fl<tab> gives you:
   ERROR: bad character  <-- that's the tab
   ERROR: unknown macro will be lost: unknown macro: Fl<tab>

2. Inside a macro line, from the point of view of the *parser*,
   the tab is a normal character and doesn't delimit anything.
   In the parser, it is preserved verbatim.
   Later on, the formatter will expand it.

   Examples:
   .Fl<space><tab>Fl         ->  Fl("<tab>Fl")     ->  "-    Fl"
   .Fl<space><tab><space>Fl  ->  Fl("<tab>") Fl()  ->  "-     -"
   .Op<space>Fl<tab>Fl       ->  Op("Fl<tab>Fl")   ->  "[Fl   Fl]"

   In this respect, mandoc actually seems to be correct.

Thus,

  .It<sp>Dv<sp>FS_POSIX_SETUID<sp>No<tab>integer<tab>yes  ->
  It(Dv(FS_POSIX_SETUID) "No<tab>integer<tab>yes")        ->
  "FS_POSIX_SETUID No         integer       yes"

In the line

  .It Dv FS_POSIX_SETUID No "     integer yes"

the space after the No is vital, whereas the quotes are not.
I guess the quotes were only put to make it plain that there is
a syntactically significant space preceding the tab.

Oh, and the reason why

  .It<sp>Dv<sp>FS_POSIX_SETUID<tab>No<sp>integer<tab>yes

cannot work is now plain too:  It gives

  It(Dv("FS_POSIX_SETUID<tab>No") "integer<tab>yes")  ->
  "FS_POSIX_SETUID            No integer    yes"

On the other hand, you cannot put a space after the tab
because it will mess up the alignment of the second column.
Hence the need to put the formatting macro for the second column
before the tab, and hence the idiom: macro, space, quote, tab.

Enjoy roff,
  Ingo


What remains is the quoted spacing issue in mandoc:

  .Bl -column "Second level nameXXXXXX" integerXXX -offset indent
  .It Sy Second level name	Type	Changeable
  .It Dv FS_POSIX_SETUID No 	integer	yes
  .It Dv FS_POSIX_SETUID No "	integer	yes"
  .El

gives

           Second level name          Type          Changeable
           FS_POSIX_SETUID            integer       yes
           FS_POSIX_SETUID            integer       yes

with groff (both old and new) but

           Second level name          Type          Changeable
           FS_POSIX_SETUID            integer       yes
           FS_POSIX_SETUID           integer       yes

with mandoc.
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv