#166 manpage.py: move macro defs to head

[Willie]

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.

[engelbert gruber]

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

[engelbert gruber]

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

[engelbert gruber]

could you send me your (minimal) document please

[Willie]

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<tmac> option.</tmac>

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

[engelbert gruber]

sorry for the horrendous delay

[G. Branden Robinson]

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,

Hi there. I work on groff upstream. The reason for advising the definition of page-local versions of man(7) extension macros after the TH call is indeed to keep them from being clobbered when andoc.tmac (re-)sources the an.tmac file.

People might redefine a GNU an-ext.tmac macro to ensure the portability of their page to an environment that doesn't support the GNU extensions they use. For example, in 2009, the groff man extension macros MT, ME, UR, UE, SY, YS, and TQ were fairly new. Over time, other implementations, like Heirloom Doctools troff and mandoc(1), adopted them.

In July of this year, we released groff 1.23.0, which has a new man(7) macro, MR (pioneered by Plan 9 from User Space troff), for setting hyperlinkable man page cross references. groff 1.23.0's own man pages define a fallback version of MR (much less complex than the "official" one) so that the arguments to the macro can still be read as text in the page even if the page is formatted by an implementation that doesn't support MR, like groff 1.22.4 or earlier. (Normally, calls to undefined macros are discarded by the formatter along with their arguments.)

Here's an example. https://git.savannah.gnu.org/cgit/groff.git/tree/src/preproc/eqn/neqn.1.man?h=1.23.0

In the foregoing, MR is defined only if it isn't already; the fallback definition is used only if groff 1.23.0 isn't the formatter. It would indeed be harmless to put this definition before the TH call, and let it get clobbered, but (1) there still seemed to be a notional risk of feeble makewhatis implementations getting confused by such content at that location, and (2) I wanted to keep the advice to man page authors simple. Page-local macros should be defined only if necessary, and I didn't want to burden the groff_man(7) page with an exploration of the varying consequences of defining them (a) before the TH call; (b) after TH but before .SH Name; (c) after presenting the page's summary description with.SH Name; or (d) even later than that.

Let me know if I can further illuminate this issue.

Regards,
Branden