Re: Broken tables in HTML output

[Ingo Schwarze <schwarze@usta.de>]

Hi Pali,

Pali Rohar wrote on Mon, Jul 16, 2018 at 06:36:56PM +0200:
> On Monday 16 July 2018 17:29:19 Ingo Schwarze wrote:
>> Pali Rohar wrote on Mon, Jul 16, 2018 at 01:03:35PM +0200:

>>> It seems that mandoc is not able to format tables in HTML output
>>> correctly.  Output is rather ugly which makes it less readable.

>> You have designed a very complicated table for testing, exercising
>> many advanced features of the tbl(7) language:

> Complicated? This is just simplified version of real used table in man
> page. E.g.: https://github.com/pali/udftools/blob/master/doc/mkudffs.8

As i already said in my EuroBSDCon 2014 tutorial "Let's make manuals
more useful!" (slide 54, Handling manual pages in ports):

  The Law of Feature Creep
    If a software offers some feature,
    sooner or later somebody will use it.

  Porting corollary
    For every feature of the roff language (and for every groff
    extension), no matter how arcane and how obviously irrelevant
    for manual pages, sooner or later somebody will want to port a
    third-party software abusing that feature to format its manual
    pages.

In my recent BSDCan 2018 slides, you can see many of the recent
improvements in mandoc to cope with this awful effect.  They were
mostly related to low-level roff - and also to quite some tbl(7).

If a feature is used by a real-world manual page, that doesn't mean
much, in particular not that it is a feature normally used in manual
pages.  So yes, the features you are asking for are very unusual
in manual pages, and they are very advanced, complicated features.

Consequently, that manual page is totally non-portable.
Here is, for example, what Heirloom Roff does with it:

   $ export PATH="/usr/local/heirloom-doctools/bin:$PATH"
   $ tbl -Tutf8 tmp.man | nroff -man -Tutf8
[...]
       _________________________________________
        Very long text   Another very long text
       _________________________________________
         Short    shrt       val1         val2
       _________________________________________
                  1         value1
                  2         value3
ame
                  3         value4alue2

       _________________________________________
        Name2     1           v1           v2
       _________________________________________
                  1                       vv2
        Name3     2           vv1         vv4
       _________________________________________

All that said, ultimately, i do want to add these features, it just
can't happen overnight.  As opposed to many other non-standard
features that had to be implemented (many of which are used more
frequently), these are actually somewhat useful for unusually
complicated manual pages, as long as authors are aware that their
manual pages will not be portable.

>>> Because now ASCII version is better then what produce HTML.

>> Absolutely.  ASCII output is always better than HTML.  We consider
>> terminal output by far the most important output mode in OpenBSD.
>> But lately, HTML has also be improved in many respects, and that
>> work will continue.  The importance of HTML output is increasing.

> I was told that mandoc has support for formatting manpages to HTML
> and it is really good,

The correct statement is: mandoc HTML output is much better than
groff HTML output.

> therefore I tested it on some manpages (like above).
> And I had to say that no. ASCII of mandoc is better.

Absolutely.  I never said HTML output is better than ASCII output -
neither for mandoc nor for groff.

> And when I compared table ASCII table generated by mandoc and groff,
> groff output is better.

Yes, for complicated tables, groff terminal output is still better
than mandoc terminal output, though the gap is slowly narrowing.

> So based on your reply, all those reports are not supported by mandoc
> yet and marked as TODO...
> 
> I hope that they will be resolved, specially now when e.g. Arch Linux
> and Debian started to generate HTML versions of manpages by mandoc.
> Because otherwise it would be better to stick with UTF-8 output from
> groff and do some HTMLization of plain text output...

Sacrifice hyperlinking and semantic markup on all pages for some
arcane tbl(7) features used by very few pages?  I don't think that
would be an improvement.

Besides, Debian cannot easily switch back because groff is simply
too slow.

> About borders in html tables, I think that all is possible to describe
> via CSS properties like buttom-border, left-border, etc, ...

Very probably, yes.

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