GNU bug report logs - #59631
29.0.50; [PATCH] New check-man target to check man pages for errors

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 59631 in the body.
You can then email your comments to 59631 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefankangas <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 29.0.50; [PATCH] New check-man target to check man pages for errors
Date: Sun, 27 Nov 2022 07:23:49 -0800

[Message part 1 (text/plain, inline)]

Severity: wishlist

The attached patch adds a new check-man target to check our man pages
for errors.  I know we prefer info over man, but why not.  It will catch
mistakes, like using unknown macros, etc.

To test this, change a macro like ".B" to ".BBB" in doc/man/emacs.1 and
run "make check-man".

[0001-Add-new-check-man-target.patch (text/x-diff, attachment)]

Message #8 received at 59631 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefankangas <at> gmail.com>
Cc: 59631 <at> debbugs.gnu.org
Subject: Re: bug#59631: 29.0.50;
 [PATCH] New check-man target to check man pages for errors
Date: Sun, 27 Nov 2022 17:44:40 +0200

> From: Stefan Kangas <stefankangas <at> gmail.com>
> Date: Sun, 27 Nov 2022 07:23:49 -0800
> 
> The attached patch adds a new check-man target to check our man pages
> for errors.  I know we prefer info over man, but why not.  It will catch
> mistakes, like using unknown macros, etc.
> 
> To test this, change a macro like ".B" to ".BBB" in doc/man/emacs.1 and
> run "make check-man".

Thanks, but I think it is better to have this as a script in admin/, not a
rule in the top-level Makefile.  Especially since it requires specialized
tools and setups.

Message #11 received at 59631 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 59631 <at> debbugs.gnu.org
Subject: Re: bug#59631: 29.0.50; [PATCH] New check-man target to check man
 pages for errors
Date: Sun, 27 Nov 2022 09:49:13 -0800

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> gnu.org> writes:

> Thanks, but I think it is better to have this as a script in admin/, not a
> rule in the top-level Makefile.  Especially since it requires specialized
> tools and setups.

OK, please find attached a new patch making this into a script instead.

[0001-New-script-admin-check-man-pages.patch (text/x-diff, attachment)]

Message #14 received at 59631 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefankangas <at> gmail.com>
Cc: 59631 <at> debbugs.gnu.org
Subject: Re: bug#59631: 29.0.50; [PATCH] New check-man target to check man
 pages for errors
Date: Sun, 27 Nov 2022 20:15:31 +0200

> From: Stefan Kangas <stefankangas <at> gmail.com>
> Date: Sun, 27 Nov 2022 09:49:13 -0800
> Cc: 59631 <at> debbugs.gnu.org
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> 
> > Thanks, but I think it is better to have this as a script in admin/, not a
> > rule in the top-level Makefile.  Especially since it requires specialized
> > tools and setups.
> 
> OK, please find attached a new patch making this into a script instead.

Thanks, LGTM.

Maybe this should be mentioned in some notes, like make-tarball or
something?  When do we want to run this?

Message #17 received at 59631 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 59631 <at> debbugs.gnu.org
Subject: Re: bug#59631: 29.0.50; [PATCH] New check-man target to check man
 pages for errors
Date: Sun, 27 Nov 2022 14:59:34 -0800

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> gnu.org> writes:

> Maybe this should be mentioned in some notes, like make-tarball or
> something?  When do we want to run this?

I think adding it to make-tarball is a good idea.  Perhaps we could do
it in the same step as checking the refcards?  I've attached a new patch
with a suggested wording, please let me know what you think.

I also enabled a few more groff warnings, and cleaned up the output to
enable automatically jumping to errors from *compilation* buffers.

[0001-New-script-admin-check-man-pages.patch (text/x-diff, attachment)]

Message #20 received at 59631 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefankangas <at> gmail.com>
Cc: 59631 <at> debbugs.gnu.org
Subject: Re: bug#59631: 29.0.50; [PATCH] New check-man target to check man
 pages for errors
Date: Mon, 28 Nov 2022 14:13:29 +0200

> From: Stefan Kangas <stefankangas <at> gmail.com>
> Date: Sun, 27 Nov 2022 14:59:34 -0800
> Cc: 59631 <at> debbugs.gnu.org
> 
> I think adding it to make-tarball is a good idea.  Perhaps we could do
> it in the same step as checking the refcards?  I've attached a new patch
> with a suggested wording, please let me know what you think.

SGTM.

> I also enabled a few more groff warnings, and cleaned up the output to
> enable automatically jumping to errors from *compilation* buffers.

Can this be done by running Groff directly instead of via 'man'?  If it's
possible, it's IMO better, since Groff installations are more widespread
than the particular variant of 'man' you used in the script.  E.g., I think
the requirement for C.UTF-8 locale being available can be dropped in that
case.

But if doing so requires too much effort or research, feel free to install
what you have.

Thanks.

Message #23 received at 59631 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 59631 <at> debbugs.gnu.org
Subject: Re: bug#59631: 29.0.50; [PATCH] New check-man target to check man
 pages for errors
Date: Thu, 1 Dec 2022 07:02:16 -0800

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> gnu.org> writes:

> Can this be done by running Groff directly instead of via 'man'?  If it's
> possible, it's IMO better, since Groff installations are more widespread
> than the particular variant of 'man' you used in the script.  E.g., I think
> the requirement for C.UTF-8 locale being available can be dropped in that
> case.

The version of man used is man-db, which AFAIK is used by all major
GNU/Linux distributions.

    https://man-db.gitlab.io/man-db/

Looking into this with PIPELINE_DEBUG=1, the processing done is
non-trivial, and depends on e.g. /usr/libexec/man-db/zsoelim from
man-db.  So I think trying to duplicate all of that for the purposes of
this script might not be the best use of our time.

For reference, I've attached the debug output from man.

[man-output.txt (text/plain, attachment)]

[Message part 3 (text/plain, attachment)]

Message #26 received at 59631 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefankangas <at> gmail.com>
Cc: 59631 <at> debbugs.gnu.org
Subject: Re: bug#59631: 29.0.50; [PATCH] New check-man target to check man
 pages for errors
Date: Thu, 01 Dec 2022 18:01:30 +0200

> From: Stefan Kangas <stefankangas <at> gmail.com>
> Date: Thu, 1 Dec 2022 07:02:16 -0800
> Cc: 59631 <at> debbugs.gnu.org
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> 
> > Can this be done by running Groff directly instead of via 'man'?  If it's
> > possible, it's IMO better, since Groff installations are more widespread
> > than the particular variant of 'man' you used in the script.  E.g., I think
> > the requirement for C.UTF-8 locale being available can be dropped in that
> > case.
> 
> The version of man used is man-db, which AFAIK is used by all major
> GNU/Linux distributions.

Exactly.  So anyone who doesn't have man-db or isn't on GNU/Linux is toast.
Groff is another matter: there's even a Windows port.

> Looking into this with PIPELINE_DEBUG=1, the processing done is
> non-trivial, and depends on e.g. /usr/libexec/man-db/zsoelim from
> man-db.  So I think trying to duplicate all of that for the purposes of
> this script might not be the best use of our time.

Fine with me, but just so you know: zsoelim is just a variant of soelim
which comes with Groff; it differs from soelim in that it knows about
compressed man pages (which are not the issue here).

AFAICT, the pipeline is simple:

 soelim FILE | preconv -e UTF-8 | groff -mandoc -Z -wall -wmac -Tutf8 > /dev/null

Message #29 received at 59631 <at> debbugs.gnu.org (full text, mbox):

From: Richard Stallman <rms <at> gnu.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 59631 <at> debbugs.gnu.org, stefankangas <at> gmail.com
Subject: Re: bug#59631: 29.0.50;
 [PATCH] New check-man target to check man pages for errors
Date: Fri, 02 Dec 2022 17:50:05 -0500

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > The version of man used is man-db, which AFAIK is used by all major
  > > GNU/Linux distributions.

  > Exactly.  So anyone who doesn't have man-db or isn't on GNU/Linux is toast.

Saying a user "is toast" means that the user is dead.  Even if that is
taken as a metaphor, it is a bit exaggeration.

A feature limited to GNU-Like systems is not a horrible thing.  Our
policy is that support for non-GNU-like systems is at best a secondary
goal -- something users can implement if they wish, but we don't
consider the lack of that support as a problem.

It's fine to make this call Groff directly, if it has no major
drawbacks.  But please don't imply that the absence of that support
would be horrible.


-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Message #32 received at 59631 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: rms <at> gnu.org
Cc: 59631 <at> debbugs.gnu.org, stefankangas <at> gmail.com
Subject: Re: bug#59631: 29.0.50;
 [PATCH] New check-man target to check man pages for errors
Date: Sat, 03 Dec 2022 09:06:35 +0200

> From: Richard Stallman <rms <at> gnu.org>
> Cc: stefankangas <at> gmail.com, 59631 <at> debbugs.gnu.org
> Date: Fri, 02 Dec 2022 17:50:05 -0500
> 
> A feature limited to GNU-Like systems is not a horrible thing.  Our
> policy is that support for non-GNU-like systems is at best a secondary
> goal -- something users can implement if they wish, but we don't
> consider the lack of that support as a problem.
> 
> It's fine to make this call Groff directly, if it has no major
> drawbacks.  But please don't imply that the absence of that support
> would be horrible.

This is not a user-level feature.  This is a feature for Emacs developers,
and only for those of them who routinely work on producing the release
tarballs.  From my POV, it is important to make this kind of features to
work on as many systems as possible, if only to allow me to do these jobs
from my local system.

The feature is implemented in Groff, btw, the man page of 'man' says that
explicitly.

And I didn't say the inability to use Groff directly would be "horrible",
quite the contrary.  Quote:

> Can this be done by running Groff directly instead of via 'man'?  If it's
> possible, it's IMO better, since Groff installations are more widespread
> than the particular variant of 'man' you used in the script.  E.g., I think
> the requirement for C.UTF-8 locale being available can be dropped in that
> case.
> 
> But if doing so requires too much effort or research, feel free to install
> what you have.

Note the last paragraph.

So I consider your reprimand gratuitous and even mildly insulting.  It
sounds like you reacted to a single sentence, taken out of context, and
either didn't read or forgot the other messages I wrote in this thread.

Message #35 received at 59631 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 59631 <at> debbugs.gnu.org
Subject: Re: bug#59631: 29.0.50; [PATCH] New check-man target to check man
 pages for errors
Date: Sat, 3 Dec 2022 06:20:50 -0800

Eli Zaretskii <eliz <at> gnu.org> writes:

> AFAICT, the pipeline is simple:
>
>  soelim FILE | preconv -e UTF-8 | groff -mandoc -Z -wall -wmac -Tutf8 > /dev/null

My concern is that the command is more brittle in the face of changes,
and also all the extra "echo" stuff that man-db is doing (probably
because I don't understand what it's doing).

I'm thinking that we could provide the above in case man-db isn't
available.  Is there any way to auto-detect that?  If not, how about
putting this behind a flag?

Message #38 received at 59631 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefankangas <at> gmail.com>
Cc: 59631 <at> debbugs.gnu.org
Subject: Re: bug#59631: 29.0.50; [PATCH] New check-man target to check man pages for errors
Date: Sat, 03 Dec 2022 16:39:02 +0200

On December 3, 2022 4:20:50 PM GMT+02:00, Stefan Kangas <stefankangas <at> gmail.com> wrote:
> Eli Zaretskii <eliz <at> gnu.org> writes:
> 
> > AFAICT, the pipeline is simple:
> >
> >  soelim FILE | preconv -e UTF-8 | groff -mandoc -Z -wall -wmac -Tutf8 > /dev/null
> 
> My concern is that the command is more brittle in the face of changes,
> and also all the extra "echo" stuff that man-db is doing (probably
> because I don't understand what it's doing).
> 
> I'm thinking that we could provide the above in case man-db isn't
> available.  Is there any way to auto-detect that?  If not, how about
> putting this behind a flag?
> 

Nah, just install your variant.  It isn't worth the hassle to do anything more complex.  I have the command in my notes and will use it if and when required.

Message #43 received at 59631-done <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 59631-done <at> debbugs.gnu.org
Subject: Re: bug#59631: 29.0.50; [PATCH] New check-man target to check man
 pages for errors
Date: Fri, 9 Dec 2022 02:25:43 -0800

Eli Zaretskii <eliz <at> gnu.org> writes:

> Nah, just install your variant.  It isn't worth the hassle to do
> anything more complex.  I have the command in my notes and will use it
> if and when required.

Thanks, pushed to emacs-29 (commit d3d9676bf8).  Closing.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.