Linux-man Archive on lore.kernel.org
 help / color / Atom feed
From: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>
To: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Cc: mtk.manpages@gmail.com, linux-man <linux-man@vger.kernel.org>
Subject: Re: [PATCH] drop spurious t comment header
Date: Fri, 24 Jul 2020 14:30:05 +0200
Message-ID: <beb87fab-b925-fb57-541f-fe5c77ce5cbe@gmail.com> (raw)
In-Reply-To: <20200724121555.e4l2okob3x3fzk5z@localhost.localdomain>

Hi Branden, Mike,

On 7/24/20 2:15 PM, G. Branden Robinson wrote:
> At 2020-07-24T12:13:33+0200, Michael Kerrisk (man-pages) wrote:
>> On Fri, 24 Jul 2020 at 02:03, G. Branden Robinson
>> <g.branden.robinson@gmail.com> wrote:
>>> it is a hint to the man
>>> program to preprocess the man page text through tbl.
>>
>> Yes, that's my understanding. But I believe that these days it's no
>> longer needed(?). tbl(1) just gets used as needed, regardless of the
>> presence of the 't' comment, right?
> 
> [A few "strace -f -e execve"s later...]
> 
> Hmm, for the man-db man(1) in Debian bullseye (testing), at least, this
> is true!  And checking its own man page, it looks like it was true as
> far back as April 2001 (the horizon of its Git history).
> 
> I guess there are so many man pages that embed tables without including
> the hint that the man-db maintainers decided not to leave the comment to
> chance.  

That would be my guess.

> The only other man-like program I know if in anything like wide
> use on Linux systems is mandoc, which does all its own parsing and
> doesn't depend on a *roff at all.
> 
> Retaining an accurate comment would be a kindness to other man
> implementations I'm not aware of and to weirdos like me who run groff
> directly because we develop it (though admittedly, even for us, there is
> the crutch of grog(1)).  But I'll grant--these populations may be small.

Yes, and in any case, the man-pages pages are already widely omitting
this comment.

>> See my comments above. For 15 years or at least, I've not paid any
>> attention to adding the 't' comments when I added tables to pages, and
>> I do recall anyone reporting ill effects. So, I'm inclined to apply
>> Mike's patch, but will hold off a moment, in case there's other
>> feedback.
> 
> Sounds fair.

Branden, thanks for your detailed analysis.

Mike, I've applied the patch, but completely rewrote the commit
message, as below.

Cheers,

Michael

==

Various pages: Drop t comment header
  
Historically, a comment of the following form at the top of a
manual page was used to indicate too man(1) that the use of tbl(1)
was required in order to process tables:

    '\" t

However, at least as far back as 2001 (according to Branden),
man-db's man(1) automatically uses tbl(1) as needed, rendering
this comment unnecessary. And indeed many existing pages in
man-pages that have tables don't have this comment at the top of
the file.  So, drop the comment from those files where it is
present.


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

  reply index

Thread overview: 7+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-07-23 21:53 Mike Frysinger
2020-07-24  0:03 ` G. Branden Robinson
2020-07-24 10:13   ` Michael Kerrisk (man-pages)
2020-07-24 12:15     ` G. Branden Robinson
2020-07-24 12:30       ` Michael Kerrisk (man-pages) [this message]
2020-07-24 13:13         ` Stefan Puiu
2020-07-24 15:17           ` Michael Kerrisk (man-pages)

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=beb87fab-b925-fb57-541f-fe5c77ce5cbe@gmail.com \
    --to=mtk.manpages@gmail.com \
    --cc=g.branden.robinson@gmail.com \
    --cc=linux-man@vger.kernel.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Linux-man Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/linux-man/0 linux-man/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 linux-man linux-man/ https://lore.kernel.org/linux-man \
		linux-man@vger.kernel.org
	public-inbox-index linux-man

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.linux-man


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git