From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on inbox.vuxu.org X-Spam-Level: X-Spam-Status: No, score=0.0 required=5.0 tests=T_FILL_THIS_FORM_SHORT autolearn=ham autolearn_force=no version=3.4.4 Received: (qmail 11748 invoked from network); 28 Mar 2021 18:46:10 -0000 Received: from bsd.lv (HELO mandoc.bsd.lv) (66.111.2.12) by inbox.vuxu.org with ESMTPUTF8; 28 Mar 2021 18:46:10 -0000 Received: from fantadrom.bsd.lv (localhost [127.0.0.1]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id 49644d70 for ; Sun, 28 Mar 2021 13:46:07 -0500 (EST) Received: from scc-mailout-kit-02.scc.kit.edu (scc-mailout-kit-02.scc.kit.edu [129.13.231.82]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id f9e3215c for ; Sun, 28 Mar 2021 13:46:06 -0500 (EST) Received: from hekate.asta.kit.edu ([141.3.145.153] helo=hekate.usta.de) by scc-mailout-kit-02.scc.kit.edu with esmtps (TLS1.2:ECDHE-RSA-AES256-GCM-SHA384:256) (envelope-from ) id 1lQaQG-0005G0-Oh; Sun, 28 Mar 2021 20:46:05 +0200 Received: from donnerwolke.asta.kit.edu ([141.3.145.61] helo=donnerwolke.usta.de) by hekate.usta.de with esmtp (Exim 4.92.2) (envelope-from ) id 1lQaQF-0003PU-It; Sun, 28 Mar 2021 20:46:03 +0200 Received: from login-1.asta.kit.edu ([141.3.145.72]) by donnerwolke.usta.de with esmtp (Exim 4.84_2) (envelope-from ) id 1lQaQF-0005vK-FU; Sun, 28 Mar 2021 20:46:03 +0200 Received: from schwarze by login-1.asta.kit.edu with local (Exim 4.92) (envelope-from ) id 1lQaQF-0002HO-Ek; Sun, 28 Mar 2021 20:46:03 +0200 Date: Sun, 28 Mar 2021 20:46:03 +0200 From: Ingo Schwarze To: Kristaps Dzonsons Cc: tech@mandoc.bsd.lv Subject: Re: ".TS H" macro Message-ID: References: X-Mailinglist: mandoc-tech Reply-To: tech@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: Hi Kristaps, Kristaps Dzonsons wrote on Sun, Mar 28, 2021 at 01:30:41PM +0200: > On second glance, this is only supported by the -ms parser in groff(1) > and tables with groff's -man don't support the `.TS H` invocation: > > % groff -tk -man -Tpdf foo.man >/dev/null > error: page 2: table will not fit on one page; use .TS H/.TH with a > supporting macro package Indeed, i agree with your assessment. ".TS H" is groff_ms(7) syntax and invalid in groff_man(7) and hence in man(7). Here is the result of running your sample file (without the "expand" table option that groff uses but mandoc ignores) through gmdiff: $ gmdiff tmp.man ========== tmp.man ========== mandoc: tmp.man:11:2: WARNING: missing manual title, using "": TH mandoc: tmp.man:11:2: WARNING: missing manual section, using "": TH mandoc: tmp.man:11:2: WARNING: missing date, using "": TH mandoc: tmp.man: STYLE: RCS id missing: (OpenBSD) mandoc: see above the output for WARNING messages --- /tmp/roff.out Sun Mar 28 20:09:57 2021 +++ /tmp/mandoc.out Sun Mar 28 20:09:57 2021 @@ -1,17 +1,11 @@ -UNTITLED(7) Miscellaneous Information Manual UNTITLED(7) +() () + +----+---------+ |app | quality | +----+---------+ -| | | -| | | -| | | -() | | () -| | | -| | | -| | | |foo | bar | +----+---------+ So the differences are as follows: 1. Groff prints the page header line as soon as it sees the first .TH. As you wisely decided, mandoc parses first and only starts rendering when the parsing is complete. Hence the difference in the first line of output. 2. *Both* groff and mandoc treat the second .TH as a man(7) .TH macro, not as a tbl(7) instruction (we probably shouldn't call tbl(7) features line "T{" and ".TH" "macros" because processing of tbl(7) and eqn(7) input differs substantially from normal roff(7) processing). But both treat this second man(7) .TH macro differently. Groff goes ahead an prints a second header, surrounded by the usual three blank lines, overlapping the table. Mandoc just collects the information, leaving the table undisturbed. > So this shouldn't affect mandoc because it doesn't accept -ms and thus > the `.TS H` shouldn't be used. Agreed. > Sorry for the noise! I don't deny your first shot went slightly astray, but it wasn't all noise. Consider the following test document: .TH ONE 1 2001-01-01 .TH TWO 2 2002-02-02 .SH NAME name \- name .SH DESCRIPTION text Groff prints both headers, which is hardly useful and not a worthy target for making mandoc(1) bug-compatible. But mandoc(1) silently ignores the first header and only prints the second header. Using the second rather than the first contradicts man(7) documentation: Each man document starts with the TH macro specifying the document's name and section, ... It also contadicts groff_man(7) documentation: A man page should contain exactly one .TH call at or near the beginning of the file, prior to any other macro calls. So both manuals prefer seeing the first .TH win, not the last one. Hence, your patch isn't completely wrong. But even more important than fixing which macro wins is emitting an ERROR level diagnostic when encountering more than one .TH macro in the same document. So i added a TODO entry: - report double .TH in man(7) as an ERROR and let the first win kristaps@ 28 Mar 2021 13:30:41 +0200 loc * exist * algo * size * imp * Thanks, Ingo -- To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv