How to set all arguments of the Title line in manpage written in reStructuredText, converted to groff with pandoc

Question

How can I get pandoc to properly set all of the arguments in the "Title line" (.TH) when converting from a .rst file to a man file?

According to the documentation man man-pages, the "Title line" takes positional arguments:

   Title line
       The first command in a man page should be a TH command:

              .TH title section date source manual

       The arguments of the command are as follows:

       title  The title of the man page, written in all caps (e.g., MAN-PAGES).

       section
              The section number in which the man page should be placed (e.g., 7).

       date   The date of the last nontrivial change that was made to the man page.  (Within the man-pages project, the necessary  up‐
              dates to these timestamps are handled automatically by scripts, so there is no need to manually update them as part of a
              patch.)  Dates should be written in the form YYYY-MM-DD.

       source The source of the command, function, or system call.

              For those few man-pages pages in Sections 1 and 8, probably you just want to write GNU.

              For system calls, just write Linux.  (An earlier practice was to write the version number of the kernel from  which  the
              manual  page  was  being written/checked.  However, this was never done consistently, and so was probably worse than in‐
              cluding no version number.  Henceforth, avoid including a version number.)

              For library calls that are part of glibc or one of the other common GNU libraries, just use GNU C Library,  GNU,  or  an
              empty string.

              For Section 4 pages, use Linux.

              In cases of doubt, just write Linux, or GNU.

       manual The title of the manual (e.g., for Section 2 and 3 pages in the man-pages package, use Linux Programmer's Manual).

I haven't found any documentation on how pandoc magically translates .rst files into groff files, but I've found that I can get it to spit-out a .TH line with a reStructuredText heading in the document like so:

user@buskill:~/tmp/groff$ cat source.rst 
==========
my-program
==========

Synopsis
========

**my-program**

Description
===========

**my-program** is magical. It does what you need!
user@buskill:~/tmp/groff$ 

user@buskill:~/tmp/groff$ pandoc -s source.rst -t man
.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "my-program" "" "" "" ""
.hy
.SH Synopsis
.PP
\f[B]my-program\f[R]
.SH Description
.PP
\f[B]my-program\f[R] is magical.
It does what you need!
user@buskill:~/tmp/groff$ 

The above execution shows that pandoc extracted the first argument to .TH from the reST heading (my-program), but the remaining arguments are all blank. If I try to specify them in the heading directly, it doesn't work.

user@buskill:~/tmp/groff$ head source.rst 
==============================
my-program "one" "two" "three"
==============================

Synopsis
========

**my-program**

Description
user@buskill:~/tmp/groff$ pandoc -s source.rst -t man
.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "my-program \[dq]one\[dq] \[dq]two\[dq] \[dq]three\[dq]" "" "" "" ""
.hy
.SH Synopsis
.PP
\f[B]my-program\f[R]
.SH Description
.PP
\f[B]my-program\f[R] is magical.
It does what you need!
user@buskill:~/tmp/groff$ 

What do I need to add to the source.rst file such that pandoc will populate the arguments in the destination file's .TH line? And, in general, where can I find reference documentation that describes this?

Answer 1

You can fix this by including the section in the title, defining the date in source.rst, and setting footer & header as variables.

Solution

Update your source.rst file as follows

========
one(two)
========

:date: three

Synopsis
========

**my-program**

Description
===========

**my-program** is magical. It does what you need!

And now re-render the manpage with the following command

user@buskill:~/tmp/groff$ pandoc -s source.rst --variable header=five --variable footer=four -t man
.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "one" "two" "three" "four" "five"
.hy
.SH Synopsis
.PP
\f[B]my-program\f[R]
.SH Description
.PP
\f[B]my-program\f[R] is magical.
It does what you need!
user@buskill:~/tmp/groff$ 

Why this works

I couldn't find great reference documentation from pandoc for the conversion between .rst and man, so I solved this with trial-and-error.

First I found in the pandoc documentation that you can see a default template for the destination format using the -D argument

• https://pandoc.org/MANUAL.html#templates

user@buskill:~$ pandoc -D man
$if(has-tables)$
.\"t
$endif$
$if(pandoc-version)$
.\" Automatically generated by Pandoc $pandoc-version$
.\"
$endif$
$if(adjusting)$
.ad $adjusting$
$endif$
.TH "$title/nowrap$" "$section/nowrap$" "$date/nowrap$" "$footer/nowrap$" "$header/nowrap$"
$if(hyphenate)$
.hy
$else$
.nh
$endif$
$for(header-includes)$
$header-includes$
$endfor$
$for(include-before)$
$include-before$
$endfor$
$body$
$for(include-after)$
$include-after$
$endfor$
$if(author)$
.SH AUTHORS
$for(author)$$author$$sep$; $endfor$.
$endif$
user@buskill:~$ 

I found that you can set the title and section by setting the main heading of the document to <title>(<section>).

And I found that you could set the date with a Field Name in source.rst

For some reason the formatting of the header and footer gets messed-up when defining them as field names, so I set those on the command line with

--variable header=five --variable footer=four