Giant .Bk magically doing the right thing?!

Giant .Bk magically doing the right thing?!

[Ingo Schwarze]

Hi,

Jason just pointed me to a couple of instances of very strange .Bk
usage that seem to magically do what you want - but i have no idea
why, or how to implement this in mandoc.  For example, from ifconfig(8):

.Sh TUNNEL
.Nm ifconfig
.Bk -words
.Ar tunnel-interface
.Op Cm deletetunnel Ar src_address dest_address
.Op Cm tunnel Ar src_address dest_address
.Op Cm tunneldomain Ar route-id
.Ek

This gives, with both old and new groff:

TUNNEL
     ifconfig tunnel-interface [deletetunnel src_address dest_address]
     [tunnel src_address dest_address] [tunneldomain route-id]

Without the .Bk, of course, groff gives:

TUNNEL
     ifconfig tunnel-interface [deletetunnel src_address dest_address] [tunnel
     src_address dest_address] [tunneldomain route-id]

Now, as far as i have understood and as i have documented in mdoc(7),
i think .Bk is supposed to keep the words in its block together.
How is groff telling the difference between the two spaces in the
string "dest_address] [tunnel src_address"?

If the markup were

.Sh TUNNEL
.Nm ifconfig
.Bk -words
.Ar tunnel-interface
.Op Cm deletetunnel Ar src_address dest_address
.Ek
.Bk -words
.Op Cm tunnel Ar src_address dest_address
.Ek
.Bk -words
.Op Cm tunneldomain Ar route-id
.Ek

i would understand.  But as it is, it looks like magic...

Any clues?

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

Re: Giant .Bk magically doing the right thing?!

[Kristaps Dzonsons]

> Jason just pointed me to a couple of instances of very strange .Bk
> usage that seem to magically do what you want - but i have no idea
> why, or how to implement this in mandoc.  For example, from ifconfig(8):
> 
> .Sh TUNNEL
> .Nm ifconfig
> .Bk -words
> .Ar tunnel-interface
> .Op Cm deletetunnel Ar src_address dest_address
> .Op Cm tunnel Ar src_address dest_address
> .Op Cm tunneldomain Ar route-id
> .Ek
> 
> This gives, with both old and new groff:
> 
> TUNNEL
>      ifconfig tunnel-interface [deletetunnel src_address dest_address]
>      [tunnel src_address dest_address] [tunneldomain route-id]
> 
> Without the .Bk, of course, groff gives:
> 
> TUNNEL
>      ifconfig tunnel-interface [deletetunnel src_address dest_address] [tunnel
>      src_address dest_address] [tunneldomain route-id]
> 
> Now, as far as i have understood and as i have documented in mdoc(7),
> i think .Bk is supposed to keep the words in its block together.
> How is groff telling the difference between the two spaces in the
> string "dest_address] [tunnel src_address"?
> 
> If the markup were
> 
> .Sh TUNNEL
> .Nm ifconfig
> .Bk -words
> .Ar tunnel-interface
> .Op Cm deletetunnel Ar src_address dest_address
> .Ek
> .Bk -words
> .Op Cm tunnel Ar src_address dest_address
> .Ek
> .Bk -words
> .Op Cm tunneldomain Ar route-id
> .Ek
> 
> i would understand.  But as it is, it looks like magic...

If you look at NetBSD's tmac file, which is easier to read than 
OpenBSD's (which reliably makes my eyes bleed), you may see that `Bk' 
defines "hard-space", which is only invoked within parsed /words/.

So in effect, hard-space is defined between words of the Op, but not 
between words and sub-expressions.

Which macros get "words" and which macros get parsed subexpressions is 
entirely on a macro-by-macro basis.

Note I say you "may see", because the tmacs themselves are mind-bending 
horrors without a single line of documentation.  I mean not a SINGLE 
line following the license.

You can always post this question to the groff mailing list. :-)

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

Re: Giant .Bk magically doing the right thing?!

[Joerg Sonnenberger]

On Sun, Jun 27, 2010 at 09:37:57PM +0200, Kristaps Dzonsons wrote:
> Note I say you "may see", because the tmacs themselves are
> mind-bending horrors without a single line of documentation.  I mean
> not a SINGLE line following the license.

Don't look at the installed version in /usr/share/tmac, but at the
source version in src/gnu/dist/groff/tmac.

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