From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from scc-mailout-kit-01.scc.kit.edu (scc-mailout-kit-01.scc.kit.edu [129.13.231.81]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id 850ca2ff for ; Mon, 16 Jul 2018 12:44:53 -0500 (EST) Received: from asta-nat.asta.uni-karlsruhe.de ([172.22.63.82] helo=hekate.usta.de) by scc-mailout-kit-01.scc.kit.edu with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (envelope-from ) id 1ff7YI-0008G6-Jw; Mon, 16 Jul 2018 19:44:52 +0200 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.77) (envelope-from ) id 1ff7YH-0000EC-BG; Mon, 16 Jul 2018 19:44:49 +0200 Received: from athene.usta.de ([172.24.96.10]) by donnerwolke.usta.de with esmtp (Exim 4.84_2) (envelope-from ) id 1ff7YI-00018j-Q8; Mon, 16 Jul 2018 19:44:50 +0200 Received: from localhost (athene.usta.de [local]) by athene.usta.de (OpenSMTPD) with ESMTPA id 4adba4f8; Mon, 16 Jul 2018 19:44:49 +0200 (CEST) Date: Mon, 16 Jul 2018 19:44:48 +0200 From: Ingo Schwarze To: Pali Rohar Cc: discuss@mandoc.bsd.lv Subject: Re: Broken tables in HTML output Message-ID: <20180716174448.GA93710@athene.usta.de> References: <20180716110335.uusqzhscwdgp5qaa@pali> <20180716152919.GB85992@athene.usta.de> <20180716163656.ttlmwsdtjvcsyadc@pali> X-Mailinglist: mandoc-discuss Reply-To: discuss@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20180716163656.ttlmwsdtjvcsyadc@pali> User-Agent: Mutt/1.8.0 (2017-02-23) 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