mandoc vs Xo in It argument

mandoc vs Xo in It argument

[Ulrich Spörlein]

Hey guys,

while further cleaning up the FreeBSD manpages, I'm now at a point where
I have to fix the Xo/Xc fallout. Why exactly is this allowed:

.Bl -tag -width indent -compact
.It Xo
.Ft void
.Xc
.It Xo
.Fn auth_destroy "AUTH *auth"
.Xc
.Pp
A macro that destroys the authentication information associated with

But not this

.Bl -column "CLSET_RETRY_TIMEOUT" "struct sockaddr_in"
.It Dv CLSET_TIMEOUT Ta Xo
.Vt "struct timeval" Ta "set total timeout"
.Xc
.It Dv CLGET_TIMEOUT Ta Xo
.Vt "struct timeval" Ta "get total timeout"
.Xc
.El

And is there a better way to rewrite this other than putting all the
arguments to .It on the same line (which quickly runs over 80 columns).

People really seem to like these three column tables ...

Regards,
Uli
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: mandoc vs Xo in It argument

[Jason McIntyre]

On Tue, May 25, 2010 at 05:58:38PM +0200, Ulrich Sp??rlein wrote:
> Hey guys,
> 
> while further cleaning up the FreeBSD manpages, I'm now at a point where
> I have to fix the Xo/Xc fallout. Why exactly is this allowed:
> 
> .Bl -tag -width indent -compact
> .It Xo
> .Ft void
> .Xc
> .It Xo
> .Fn auth_destroy "AUTH *auth"
> .Xc
> .Pp
> A macro that destroys the authentication information associated with
> 
> But not this
> 
> .Bl -column "CLSET_RETRY_TIMEOUT" "struct sockaddr_in"
> .It Dv CLSET_TIMEOUT Ta Xo
> .Vt "struct timeval" Ta "set total timeout"
> .Xc
> .It Dv CLGET_TIMEOUT Ta Xo
> .Vt "struct timeval" Ta "get total timeout"
> .Xc
> .El
> 
> And is there a better way to rewrite this other than putting all the
> arguments to .It on the same line (which quickly runs over 80 columns).
> 
> People really seem to like these three column tables ...
> 
> Regards,
> Uli

i'm not going to answer any questions here, just fuel the fire a bit ;)

Xo/Xc and -column are both steeped in dark magic. put them together, and
expect everything to break.

do yourself a favour: whenever you have something that makes you think
"that'll make a nice table", just paste it in, and wrap it in a literal
display. no one will be any the wiser, and the poor bastard who needs to
add column 4 will be forever grateful to you.

you could also try formatting your problem list in a way similar to the
first, simpler, example you gave. but if it works it will be trial and
error, and not because those macros follow any kind of logic.

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

Re: mandoc vs Xo in It argument

[Ingo Schwarze]

Hi Jason, hi Ulrich,

Jason McIntyre wrote on Tue, May 25, 2010 at 06:56:29PM +0100:
> On Tue, May 25, 2010 at 05:58:38PM +0200, Ulrich Spoerlein wrote:

>> while further cleaning up the FreeBSD manpages, I'm now at a point where
>> I have to fix the Xo/Xc fallout. Why exactly is this allowed:
>> 
>> .Bl -tag -width indent -compact
>> .It Xo
>> .Ft void
>> .Xc

Because i implemented plain .It Xo support long ago.  ;-)

>> .It Xo
>> .Fn auth_destroy "AUTH *auth"
>> .Xc
>> .Pp
>> A macro that destroys the authentication information associated with
>> 
>> But not this
>> 
>> .Bl -column "CLSET_RETRY_TIMEOUT" "struct sockaddr_in"
>> .It Dv CLSET_TIMEOUT Ta Xo
>> .Vt "struct timeval" Ta "set total timeout"
>> .Xc
>> .It Dv CLGET_TIMEOUT Ta Xo
>> .Vt "struct timeval" Ta "get total timeout"
>> .Xc
>> .El

Because Kristaps did not yet implement support for .Ta as a
full-blown macro, so you can't extend it yet with .Xo.
But, unless i'm quite mistaken, he is going to,
this will be the next step after the next release,
which is expected to happen very soon.

>> And is there a better way to rewrite this other than putting all the
>> arguments to .It on the same line (which quickly runs over 80 columns).

Hmmm, probably you will not need to rewrite that code at all.
On the other hand, the .Ta in the middle of the .Xo/.Xc does
look a bit ugly.  But i also have some code written that is
nearly finished, improving support for badly nested blocks, like

.Ao ao
.Bo bo
.Ac ac
.Bc bc

and 

.Aq aq Bo bo
.Bc bc

So, when Kristaps is finished with .Ta, let's see whether i can
put the pieces together and get

.It it Xo xo
.Ta ta
.Xc xc

supported too.
If you are lucky, it may take a week or two, if you are less lucky,
perhaps after the c2k10 hackathon, that is mid-July.

>> People really seem to like these three column tables ...

Sure, people are really creative, with .Bl -column in particular.

> i'm not going to answer any questions here, just fuel the fire a bit ;)
> 
> Xo/Xc and -column are both steeped in dark magic.

We are trying hard to make that obscurity go away.
Without .Xo, and since the m2k10 hackathon, mandoc is already
handling .Bl -column more gracefully than groff, i think.

Take block nesting (including .Xo/.Xc) alone, and expect the
remaining dark magic to be gone in about two week's time.

> put them together, and expect everything to break.

Still true, but the clear goal is to change that.

> do yourself a favour: whenever you have something that makes you think
> "that'll make a nice table", just paste it in, and wrap it in a literal
> display. no one will be any the wiser, and the poor bastard who needs to
> add column 4 will be forever grateful to you.

Still true, and .Bd -literal will of course remain a good option
for many cases, but we are trying hard to make .Bl -column
work reliably.

> you could also try formatting your problem list in a way similar to the
> first, simpler, example you gave. but if it works it will be trial and
> error, and not because those macros follow any kind of logic.

The hard part implementing them will be to make them do what you
want, reliably, even in cases that used to break for no obvious reason
in groff, and still remain compatible with existing usage in manuals.
But i suspect that is an achievable goal now, though certainly
non-trivial.

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

Re: mandoc vs Xo in It argument

[Ulrich Spörlein]

On Tue, 25.05.2010 at 20:27:06 +0200, Ingo Schwarze wrote:
> Hi Jason, hi Ulrich,
> 
> Jason McIntyre wrote on Tue, May 25, 2010 at 06:56:29PM +0100:
> > On Tue, May 25, 2010 at 05:58:38PM +0200, Ulrich Spoerlein wrote:
> 
> >> while further cleaning up the FreeBSD manpages, I'm now at a point where
> >> I have to fix the Xo/Xc fallout. Why exactly is this allowed:
> >> 
> >> .Bl -tag -width indent -compact
> >> .It Xo
> >> .Ft void
> >> .Xc
> 
> Because i implemented plain .It Xo support long ago.  ;-)

You bastard! ;]

> >> And is there a better way to rewrite this other than putting all the
> >> arguments to .It on the same line (which quickly runs over 80 columns).
> 
> Hmmm, probably you will not need to rewrite that code at all.
> On the other hand, the .Ta in the middle of the .Xo/.Xc does
> look a bit ugly.  But i also have some code written that is
> nearly finished, improving support for badly nested blocks, like
> 
> .Ao ao
> .Bo bo
> .Ac ac
> .Bc bc
> 
> and 
> 
> .Aq aq Bo bo
> .Bc bc
> 
> So, when Kristaps is finished with .Ta, let's see whether i can
> put the pieces together and get
> 
> .It it Xo xo
> .Ta ta
> .Xc xc
> 
> supported too.
> If you are lucky, it may take a week or two, if you are less lucky,
> perhaps after the c2k10 hackathon, that is mid-July.

Sounds good! So now I know that support may be coming eventually, I
don't need to rewrite these parts of the manpages. Yay!

> >> People really seem to like these three column tables ...
> 
> Sure, people are really creative, with .Bl -column in particular.

Or mdoc in general. They really want stuff to look a certain way, no
matter what the underlying structure is ...


Anyway, thanks for info and let's see what the upcoming release brings!

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