Re: Implementing roff requests.

[Ingo Schwarze <schwarze@usta.de>]

Hi,

just a few brief comments...

Kristaps Dzonsons wrote on Thu, May 31, 2012 at 01:25:08PM +0200:

> As Ingo has mentioned, a few of these macros aren't possible given
> the layering of mandoc: roff.c is an opaque preprocessor and has
> limited functionality to cue the next processors (libmandoc.h), and
> no control at all over the front-ends (main.h).  `.ad', for example,
> is not possible given the current layering.

Well, if i had to do .ad, i'd probably use a roff register to save
the mode and put the actual alignment into term_flushln.  That won't
be straightforward and might need a few more smart ideas, but that
one seems certainly possible to me - and maybe even marginally useful
because so far we don't have alignment to the right margin at all.

> You'd need a separate
> <div> tag in HTML mode and it's uncertain how this would play with
> other implicit-margin-changing constructs (like lists).

In the HTML frontend, adding style attributes to some selected
tags - for example, <p> - might suffice.  Then again, it's not
a serious problem if some frontends ignore some macros.

> As you can see, roff.c itself is quite delicate---too delicate, if
> you ask me, bowing under conditionals and loops and so on.  roff and
> mandoc don't mix well: mandoc is [more or less] reflowable, while
> roff is line- and character-based.  If your focus is moving more and
> more into roff, you may want to revive Heirloom troff instead of
> using mandoc.

Well, as i see it, improving roff(7) request support in mandoc(1)
is useful purely for backward compatibility:  As Jesse says, make
people accept mandoc(1) as the default man(7) formatter.  Those
features are certainly not intended to be used in new documents.

> I actually prefer to move /away/ from roff unless
> explicitly demanded.

Indeed, in particular for any kind of new manuals, and for
improving existing manuals as well.  I heartily agree.

> Things like .ns, for example, already have
> -mdoc equivalents.
> 
> You might get partial coverage by re-writing `ns' as an appropriate
> -mdoc or -man no-space macro, but I'm not certain about behaviour.

I think you confuse apples and oranges here:  .ns partially
suppresses *vertical* spacing, while .Ns and .Sm and even stuff
like .BI is concerned with *horizontal* spacing.

Then again, .ns is mostly pointless without traps, which are not
likely to appear soon, and of little use in mdoc(7) and man(7)
documents in general.  The point about such macros isn't that
we want to use the functionality, but that we can process
historical, messily written manuals.

> Furthermore, this would pollute the layering even more with
> knowledge of the underlying parse type.  As written above, there's a
> well-defined point of diminishing returns here.

There is a point of diminishing return, indeed; the problem is,
it isn't well-defined at all.  You remeber your original stance
on roff(7) in mandoc(1) in general?  Wasn't it somewhat similar
to "over my dead body", if we go back enough before Rostock?  :)

At some point, i will possibly start to oppose low-level roff(7)
patches, maybe...  But i think Jesse is still safely away from that
point, whereever that point may actually lie, the patches he sent
so far weren't going over the top.  ;-)

And i'm going to warn him before he comes close to that point,
i think.  Right now, there is room for improvement of roff(7)
inside mandoc(1).  It's not the easiest corner of mandoc(1) nor
the most pressing, but if that's what he is interested in,
totally fine with me!

> I also note that tabs are a headache: I designed mandoc poorly in
> this regard.  I think an awesome coup would be to throw out all the
> tab-handling in -mdoc, consider tabbed `Bl -column' lists to be
> synonyms for `Bd', and use the standard argument-parser.  This has
> been in my TODO OF DEATH since forever.  It would throw out a lot of
> ugly, workaround code, and also accomodate for lots of tab-separated
> `Bl -column' syntax found in the wild.

Yes, the .Bl -column framework is complex and fragile and could
profit from refactoring (though i don't consider it completely
busted).  What you draft here is a bold plan!  In a way, it does
sound charming, but not as easy as that:  The crucial property
of .Bd -column is that the tabs are *not* at fixed positions, but
vary with the width of individual cell contents in individual rows.
Yes, it's probably feasible to design that one way or another
even in .Bd, but don't uproot everything while Jesse is trying
to find his way around the system!

> Meanwhile, if you've any implementations of macros, please send them
> to tech and we'll look them over!

Indeed.  Send often, send early - the smaller, less intrusive, and
more focussed a patch is, the easier and quicker to review and get
committed.

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