manpage.py: move macro defs to head [SF:patches:166]

[chrisjsewell]

author: jwilliep
created: 2020-03-22 19:03:19.377000
assigned: grubert
SF_url: https://sourceforge.net/p/docutils/patches/166

attachments:

• https://sourceforge.net/p/docutils/patches/166/attachment/0001-manpage.py-move-macro-defs-to-head.patch

To be kind to 'whatis' database generators; move MACRO_DEF
out of the NAME section.

Every man page created by Perl Pod::Man has macro defs above
the .TH header. There are over 5000 of them on my system. So
it doesn't seem to be a problem to have them in the head.

---

commenter: grubert
posted: 2020-03-23 13:08:11.642000
title: #166 manpage.py: move macro defs to head

• assigned_to: engelbert gruber

---

commenter: grubert
posted: 2020-03-23 13:22:27.775000
title: #166 manpage.py: move macro defs to head

I am still unsure, please be patient with me

man 7 man says:

Title line
The first command in a man page (after comment lines, that is, lines that start with .") should be

          .TH title section date source manual

pod2man ignores this obviously, the whatis might be a perl program to begin with :-)

this seams important too

Sections
Sections are started with .SH followed by the heading name.

   The only mandatory heading is NAME, which should be the first section and be followed on the next line  by  a  one-
   line description of the program:

          .SH NAME
          item \- description

   It  is extremely important that this format is followed, and that there is a backslash before the single dash which
   follows the item name.  This syntax is used by the mandb(8) program to create a database of short descriptions  for
   the whatis(1) and apropos(1) commands.  (See lexgrog(1) for further details on the syntax of the NAME section.)

I am testing still

---

commenter: grubert
posted: 2020-03-23 14:04:57.482000
title: #166 manpage.py: move macro defs to head

lexgrog checking in sandbox/manpage-writer/expected

OK
expected/docinfo-deu-l_de.man: "deutsches_manpage_beispiel - manpage beschreibung"
expected/docinfo-deu-l_en.man: "deutsches_manpage_beispiel - manpage beschreibung"
expected/docinfo-deu.man: "deutsches_manpage_beispiel - manpage beschreibung"
expected/docinfo-eng-l_de.man: "english_manpage_sample - manpage description"
expected/docinfo-eng-l_en.man: "english_manpage_sample - manpage description"
expected/docinfo-eng.man: "english_manpage_sample - manpage description"
expected/man-de.1.man: "man - Programm zum Einsehen der Online-Manuale"
expected/optionslisttest.man: "OptionlistTest - Test for correct intention/detention of optionlists"
expected/test.man: "rst2man - generate unix manpages from reStructured text"

FAIL
expected/characters.man: parse failed
expected/compact_lists.man: parse failed
expected/dotted.man: parse failed
expected/indent.man: parse failed
expected/optionstoo.man: parse failed

but these fail because .SH NAME

• names with blanks are not allowed in
• empty descriptions are not allowed

---

commenter: grubert
posted: 2020-03-23 14:06:08.843000
title: #166 manpage.py: move macro defs to head

could you send me your (minimal) document please

---

commenter: jwilliep
posted: 2020-03-23 20:01:15.147000
title: #166 manpage.py: move macro defs to head

On Mon, 23 Mar 2020, engelbert gruber wrote:

man 7 man says:
Title line
The first command in a man page (after comment lines, that is, lines that
start with .") should be

          .TH title section date source manual

pod2man ignores this obviously, ...

Well, not exactly. IMO, Man(7) is written for a beginner man page author, and
the line you quote is intentionally over simplified.

Man pages are roff source files. In roff there is no such thing as a 'command'.
In roff terminology there are 'requests' and 'macros':

That line is referring to macros, specifically 'an macros'. So, the first
man macro called must be TH. There is no problem calling roff requests before
the TH macro. Custom macros should be included before the document, just as
they would when included with the roff -m option.

roff(7)

   Requests are the predefined basic formatting commands similar to the com‐
   mands at the shell prompt.  The user can define request-like elements us‐
   ing predefined roff elements.  These are then called macros.  A  document
   writer will not note any difference in usage for requests or macros; both
   are written on a line on their own starting with a dot.

I have an idea the reason the docutils macro definitions where originally added
in the NAME section is do to a misunderstanding of this comment:

groff_man(7):
If in doubt, copy the implementation into your page—after the .TH call and
the “Name” section

But that must be understood in the context it was written. It is referring to
the author redefining any of the GNU 'extension' an-ext.tmac man page macros,
which are included after the TH macro is processed. Meaning, if the author
tries to redefine them before the TH, they will get clobbered. I cannot imagine
why anyone would want to redefine a GNU an-ext.tmac macro, and manpage.py is
certainly not doing that.

could you send me your (minimal) document please

It looks like you are testing with lexgrog and trying to reproduce a failure.
That's fine, but there are at least 3 whatis parsers that I know of. I maintain
one of them. The macro defs did not cause a hard-fail for me, they just put
garbage in the index. So I cannot send you a manpage.py document that will
hard-fail lexgrog (if that is what you are asking for).

I have patched my parser to handle what manpage.py does, but it is still the
wrong location to be adding custom roff macro definitions. Polluting the
document space not only makes things harder for whatis parsers (and believe me
that is difficult enough with all the junk authors put in the NAME section),
but it also makes it harder for maintainers to review the source file.

I hope you will consider applying the patch and seeing if the results cause any
new failures for you. I'm confident that they will not.

Thank you Engelbert,

Willie