#458 Two issues regarding manpage writer and .TH

[Dmitry Shachnev]

Dear docutils developers,

I received two bug reports in Debian regarding the content of .TH macro in man pages:

First bug — https://bugs.debian.org/1016527 — asks that the value of --date argument be used for the third argument of .TH, instead of putting it on a separate line (Generated on: YYYY-MM-DD).

Second bug — https://bugs.debian.org/1018737 — asks that docutils not set fifth argument of .TH to empty string, but omit it completely and rely on the default value.

Please see those bugs for more detailed descriptions (and some discussion, in the first bug).

[Günter Milde]

Thank you for forwarding the bug reports.

The "--date" command line argument (and "datestamp" configuration value) "Include a time/datestamp in the document footer." (https://docutils.sourceforge.io/docs/user/config.html#datestamp). They are generic Docutils options that should not be used with the
"manpage" writer.
The "date" value for the .th macro fetched from the "Date" field of the docinfo. See the test input "standalone_rst_manpage.txt" for an example.

Regarding the second bug: will omitting the fifth argument of .TH work with all troff/manpage processors?

[Dmitry Shachnev]

Regarding the second bug: will omitting the fifth argument of .TH work with all troff/manpage processors?

I asked the original reporter. He answered:

AFAIK, it will work. The behavior may differ, in that groff(1) and
mandoc(1) produce a default text, while others may not produce any text
at all, but it should work.

[engelbert gruber]

mqDmitry

AFAIK, it will work. The behavior may differ, in that groff(1) and
mandoc(1) produce a default text, while others may not produce any text
at all, but it should work.

I sometime test layout groff and try with mandoc what are the "others" ?

[Dmitry Shachnev]

Pandoc seems to have its own manpage reader: https://github.com/jgm/pandoc/blob/master/src/Text/Pandoc/Readers/Man.hs.

[engelbert gruber]

the values in the roff header .TH

.TH title section date source manual

are taken from title and the docinfo

:Date:   2009-06-22
:Version: 0.0.1
:Manual section: 1
:Manual group: text processing

the Version is put into "source" ... don't know why I did this ?
No one ever complained.

So there should be a "Manual source" instead.
"Manual manual" sounds ... silly doesn't it so it is "Manual group"

[engelbert gruber]

Revision 9200 Does not output empty "manual" in .TH
could be set via docinfo[Manual group]

[Adam Turner]

@grubert 9 tests are now failing in test_manpage.py -- I think the test expectations need to be updated.

A

[engelbert gruber]

sorry , fixed

[Günter Milde]

Is there still work to do or can we set this issue to "open-fixed" and close it once 0.20 is out?

[engelbert gruber]

set to open-fixed
commandline --date is not usable, but docinfo-date is used
noone complained about the value of source or answered so I will leave it
there

On Thu, 20 Apr 2023 at 18:47, "Günter Milde" milde@users.sourceforge.net
wrote:

Is there still work to do or can we set this issue to "open-fixed" and
close it once 0.20 is out?

---

• [bugs:#458] https://sourceforge.net/p/docutils/bugs/458/ Two issues
  regarding manpage writer and .TH*

Status: open
Labels: manpage writer
Created: Mon Sep 05, 2022 11:13 AM UTC by Dmitry Shachnev
Last Updated: Thu Nov 03, 2022 10:01 AM UTC
Owner: nobody

Dear docutils developers,

I received two bug reports in Debian regarding the content of .TH macro in
man pages:

First bug — https://bugs.debian.org/1016527 — asks that the value of
--date argument be used for the third argument of .TH, instead of putting
it on a separate line (Generated on: YYYY-MM-DD).

Second bug — https://bugs.debian.org/1018737 — asks that docutils not set
fifth argument of .TH to empty string, but omit it completely and rely on
the default value.

Please see those bugs for more detailed descriptions (and some discussion,
in the first bug).

---

Sent from sourceforge.net because you indicated interest in
https://sourceforge.net/p/docutils/bugs/458/

To unsubscribe from further messages, please visit
https://sourceforge.net/auth/subscriptions/

[Dmitry Shachnev]

One of the original bugs in Debian is fixed now. Regarding the other bug, I have forwarded your response to the original reporter, but he has not replied. So yes, I think you can close this bug.