Re: [Groff] Using real tables in groff_mdoc(7)

[Ingo Schwarze]

Hi Eric,

Eric S. Raymond wrote on Sat, Aug 11, 2012 at 12:33:29PM -0400:

> Sorry, that was a typo./thinko on my part; I meant .Bl/El.
> The trouble with that markup is that it works well at presentation
> level but would for various reasons be a very serious pain in the
> butt to parse into tables.

I feel your pain; the mandoc(1) .Bl -column parser isn't pretty
either, and probably was little fun to write, was it, Kristaps?

> In effect I'd have to write a new processing
> engine with the approximate complexity of my TBL interpreter, and that
> was quite hard to get right the first time.  I'm not willing to do it
> again, not for the small number of instances of pseudo-tables; there
> are only about a dozen of them, all on three particular groff pages.

I fear you are missing lots and lots of use cases (see the list at
the end of this message, too):

  address@hidden $ grep -R '^\.Bl.*-column' /usr/share/man | wc -l
     328
  address@hidden $ uname -a
  OpenBSD isnote.usta.de 5.2 GENERIC.MP#336 i386

So there are several hundred instances in the OpenBSD base system
alone, not counting ports land.  That's roughly 2% of the OpenBSD
base system documentation using .Bl -column.
Ugly or not, .Bl -column is a traditional mdoc(7) feature that has
been in common use for a long time, and not supporting it doesn't
remotely look like a viable option.

Besides, i wouldn't call .Bl -column "pseudo" tables.
They are just *native* mdoc(7) tables.  Pseudo tables would
be something like

.Bd -literal
col1<tab>col2<tab>col3
text1<tab>text2<tab>text3
.Ed

or

.Bd -literal
col1   col2   col3
text1  text2  text3
.Ed

which also works on the presentational level but is indeed
close to unparsable into HTML tables.

It's one thing to avoid low-level roff(7) requests in mdoc(7) code,
i fully agree that's a good idea.  But i doubt that deprecating
established high-level mdoc(7) functionality merely because it's
awkward to implement would be a wise move.

I worry that turning .Bl -column into tbl(7) might actually decrease
portability to some more traditional systems lacking both groff(1)
and mandoc(1).  Are you really sure all of those have usable tbl(7)?

In general, i prefer not having different tools (here, mdoc(7)
and tbl(7)) depend on each other if it can be avoided.  Also note
that traditionally, many man(7) pages rely on tbl(7), mostly
because man(7) indeed doesn't have any native support for tables,
whereas almost no mdoc(7) pages use tbl(7), so introducing tbl(7)
into mdoc(7) is more likely to cause portability issues because
i expect that combination to be close to untested on many systems.

Yours,
  Ingo


address@hidden $ grep -Rc '^\.Bl.*-column' /usr/share/man | grep -v :0
/usr/share/man/man1/bc.1:1
/usr/share/man/man1/cpio.1:1
/usr/share/man/man1/getent.1:1
/usr/share/man/man1/netstat.1:2
/usr/share/man/man1/oldrdist.1:1
/usr/share/man/man1/rdist.1:1
/usr/share/man/man1/stty.1:1
/usr/share/man/man1/tmux.1:5
/usr/share/man/man7/glob.7:1
/usr/share/man/man7/man.7:5
/usr/share/man/man7/mandoc.7:16
/usr/share/man/man7/mandoc_char.7:18
/usr/share/man/man7/mdoc.7:16
/usr/share/man/man7/operator.7:1
/usr/share/man/man8/ftpd.8:3
/usr/share/man/man8/login_krb5.8:1
/usr/share/man/man8/luna88k/boot_luna88k.8:2
/usr/share/man/man8/popa3d.8:2
/usr/share/man/man8/route.8:1
/usr/share/man/man8/sysctl.8:1
/usr/share/man/man8/tcpdump.8:1
/usr/share/man/man2/shutdown.2:1
/usr/share/man/man2/sigaction.2:1
/usr/share/man/man3/vax/infnan.3:1
/usr/share/man/man3/asprintf.3:3
/usr/share/man/man3/atan2.3:1
/usr/share/man/man3/atan2f.3:1
/usr/share/man/man3/atan2l.3:1
/usr/share/man/man3/cgetcap.3:3
/usr/share/man/man3/cgetclose.3:3
/usr/share/man/man3/cgetent.3:3
/usr/share/man/man3/cgetfirst.3:3
/usr/share/man/man3/cgetmatch.3:3
/usr/share/man/man3/cgetnext.3:3
/usr/share/man/man3/cgetnum.3:3
/usr/share/man/man3/cgetset.3:3
/usr/share/man/man3/cgetstr.3:3
/usr/share/man/man3/cgetusedb.3:3
/usr/share/man/man3/cgetustr.3:3
/usr/share/man/man3/fpgetmask.3:1
/usr/share/man/man3/fpgetround.3:1
/usr/share/man/man3/fpgetsticky.3:1
/usr/share/man/man3/fprintf.3:3
/usr/share/man/man3/fpsetmask.3:1
/usr/share/man/man3/fpsetround.3:1
/usr/share/man/man3/fpsetsticky.3:1
/usr/share/man/man3/fwprintf.3:3
/usr/share/man/man3/getcap.3:3
/usr/share/man/man3/printf.3:3
/usr/share/man/man3/signal.3:1
/usr/share/man/man3/sigvec.3:1
/usr/share/man/man3/snprintf.3:3
/usr/share/man/man3/sprintf.3:3
/usr/share/man/man3/stdio.3:1
/usr/share/man/man3/strtoimax.3:1
/usr/share/man/man3/strtol.3:1
/usr/share/man/man3/strtoll.3:1
/usr/share/man/man3/strtoq.3:1
/usr/share/man/man3/swprintf.3:3
/usr/share/man/man3/sysctl.3:31
/usr/share/man/man3/vasprintf.3:3
/usr/share/man/man3/vfprintf.3:3
/usr/share/man/man3/vfwprintf.3:3
/usr/share/man/man3/vprintf.3:3
/usr/share/man/man3/vsnprintf.3:3
/usr/share/man/man3/vsprintf.3:3
/usr/share/man/man3/vswprintf.3:3
/usr/share/man/man3/vwprintf.3:3
/usr/share/man/man3/wprintf.3:3
/usr/share/man/man4/acx.4:1
/usr/share/man/man4/adv.4:2
/usr/share/man/man4/advansys.4:2
/usr/share/man/man4/adw.4:2
/usr/share/man/man4/ahd.4:1
/usr/share/man/man4/alpha/tga.4:1
/usr/share/man/man4/aps.4:1
/usr/share/man/man4/ath.4:1
/usr/share/man/man4/athn.4:1
/usr/share/man/man4/bwi.4:1
/usr/share/man/man4/fins.4:1
/usr/share/man/man4/sgi/intro.4:1
/usr/share/man/man4/hp300/hyper.4:1
/usr/share/man/man4/hppa/intro.4:1
/usr/share/man/man4/hppa/io.4:1
/usr/share/man/man4/hppa/pdc.4:5
/usr/share/man/man4/i386/esm.4:1
/usr/share/man/man4/icmp.4:2
/usr/share/man/man4/icmp6.4:2
/usr/share/man/man4/ifmedia.4:1
/usr/share/man/man4/vax/rx.4:1
/usr/share/man/man4/vax/uda.4:6
/usr/share/man/man4/it.4:1
/usr/share/man/man4/itherm.4:1
/usr/share/man/man4/lm.4:1
/usr/share/man/man4/macppc/asms.4:1
/usr/share/man/man4/malo.4:1
/usr/share/man/man4/mvme68k/le.4:1
/usr/share/man/man4/mvme68k/vs.4:4
/usr/share/man/man4/mvme68k/vsbic.4:1
/usr/share/man/man4/mvme88k/le.4:1
/usr/share/man/man4/mvme88k/vs.4:4
/usr/share/man/man4/mvme88k/vsbic.4:1
/usr/share/man/man4/ne.4:1
/usr/share/man/man4/nsclpcsio.4:1
/usr/share/man/man4/pgt.4:1
/usr/share/man/man4/rtw.4:1
/usr/share/man/man4/safte.4:1
/usr/share/man/man4/schsio.4:1
/usr/share/man/man4/ses.4:1
/usr/share/man/man4/sparc/cgthree.4:1
/usr/share/man/man4/sparc/fga.4:1
/usr/share/man/man4/sparc/fvme.4:1
/usr/share/man/man4/sparc/mgx.4:1
/usr/share/man/man4/sparc/rfx.4:2
/usr/share/man/man4/sparc/tcx.4:3
/usr/share/man/man4/sparc/tvtwo.4:1
/usr/share/man/man4/sparc/vigra.4:3
/usr/share/man/man4/sparc/zx.4:2
/usr/share/man/man4/sparc64/ifb.4:1
/usr/share/man/man4/sparc64/mgx.4:1
/usr/share/man/man4/sparc64/rfx.4:2
/usr/share/man/man4/sparc64/tvtwo.4:1
/usr/share/man/man4/sparc64/vigra.4:3
/usr/share/man/man4/sparc64/zx.4:2
/usr/share/man/man4/speaker.4:1
/usr/share/man/man4/spkr.4:1
/usr/share/man/man4/sti.4:1
/usr/share/man/man4/termios.4:2
/usr/share/man/man4/uath.4:1
/usr/share/man/man4/ueagle.4:1
/usr/share/man/man4/ulpt.4:1
/usr/share/man/man4/umsm.4:2
/usr/share/man/man4/uthum.4:1
/usr/share/man/man4/viapm.4:1
/usr/share/man/man4/viasio.4:1
/usr/share/man/man5/disktab.5:1
/usr/share/man/man5/gettytab.5:2
/usr/share/man/man5/iked.conf.5:4
/usr/share/man/man5/ipsec.conf.5:3
/usr/share/man/man5/login.conf.5:1
/usr/share/man/man5/printcap.5:1
/usr/share/man/man5/termcap.5:2
/usr/share/man/man6/mille.6:1