man generator does not insert correct preprocessor hint

[magicus]

For some obscure reason, pandoc outputs an initial "t" line comment for man pages if the source markdown file contains a table.

Steps to reproduce:

cat << EOF | pandoc -f markdown -t man --standalone   
Col1 Col2
---- ----
Val1 Val2
EOF

Actual output:

.\"t
.\" Automatically generated by Pandoc 2.11.0.4
.\"
.TH "" "" "" "" ""
.hy
.PP
.TS
tab(@);
l l.
T{
Col1
T}@T{
Col2
T}
_
T{
Val1
T}@T{
Val2
T}
.TE

Expected output:

.\" Automatically generated by Pandoc 2.11.0.4
.\"
.TH "" "" "" "" ""
.hy
.PP
.TS
tab(@);
l l.
T{
Col1
T}@T{
Col2
T}
_
T{
Val1
T}@T{
Val2
T}
.TE

(note the absence of the initial .\"t in the expected output)

This has been present from at least 2.3.1. to 2.11.0.4 (latest released binary).

[jgm]

There's a reason for this. Including a comment .\"t at the beginning forces groff to use the tbl preprocessor. Otherwise tables won't necessarily be processed. I suspect you'll find that man pages on your system that include the .TS and .TE macros have this comment at the start. On my system, I can see it in e.g. javadoc.1, reset.1, troff.1, and others.

Now, it may be that this is a holdover from earlier days, and that systems are now configured to run tbl by default. I'm really not sure. But I'm not sure I'd want to count on every system being configured this way.

[magicus]

Oh, ok, I. bow to your superior knowledge of ancient systems. :-)

[magicus]

(Just for clarity: javadoc.1 contains this since it is generated by pandoc, so it is a bit of a circular evidence of this behavior; I actually noticed this behavior when I was working on the OpenJDK documentation.)

[jgm]

I found the relevant documentation, in the groff_man(7) man page:

       When a preprocessor like tbl or eqn is needed, a hint can be  given  to
       the man page formatter by making the first line of a man page look like
       this:

              '\" word

       Note that the line starts with an apostrophe ('), not a dot, and that a
       single  space character follows the double quote.  The word consists of
       one letter for each needed preprocessor: `e' for eqn,  `r'  for  refer,
       and  `t'  for tbl.  Modern implementations of the man program interpret
       this first line and automatically call the right preprocessor(s).

[magicus]

Oh, but then pandoc is buggy anyway! ;-)

The pandoc output starts with a dot, not an apostrophe. And there is no space after the double quote.

So it should be '\" t instead of .\"t.