Hi Hugh,
At 2023-08-17T07:54:03+1000, Hugh McMaster wrote:
> On Thu, 17 Aug 2023 at 03:39, Colin Watson wrote:
> > On Wed, Aug 16, 2023 at 09:29:45PM +1000, Hugh McMaster wrote:
> > > This all seems promising. Unfortunately, the man page is
> > > hand-crafted, not generated from another source, so groff is never
> > > invoked, and no other documents are referenced in the file.
> >
> > groff must be run somewhere, because you're seeing a warning from
> > groff.
>
> I meant that groff is never called by FreeType's build system, as the
> man page is hand-crafted.
Okay. But Lintian _is_ calling groff, to format man pages and sniff out
problems with them.
So whether the man page is hand-crafted or generated from some other
format at build time is not relevant. In fact, it's _meta_ irrelevant
(if that's even a thing) because the only reason (apart from the
validation Lintian's doing) for a source project to run groff at build
time on a man page is to generate a PDF, "cat page", or other
_formatted_ version of the man page.[1] Examples of these are rare, but
Bash and NetHack generate cat pages, and groff itself generates a PDF
compilation of all its man pages.[2]
> > What exact check is failing here (is it lintian, or something else)?
> > Could you please give us a pointer to the man page in question?
>
> Lintian issues the warning when checking for man-page issues using
> groff (via man). This particular warning has only appeared since the
> recent groff 1.23.0 upload.
The warning is new to groff 1.23.0.[3]
> The Lintian tag is 'groff-message'. The tag description helpfully
> provides the exact command used during the check:
>
> LC_ALL=C.UTF-8 MANROFFSEQ='' MANWIDTH=80 \
> man --warnings -E UTF-8 -l -Tutf8 -Z <file> >/dev/null
>
> The man page in question -- ftlint.1 -- is in the freetype2-demos
> package [1], or you can get an online copy from [2].
In the course of composing this message, I see that Colin covered this
point.[4]
I would also note that you can use the grog(1) command (new and improved
in groff 1.23.0![5]) to help you figure out which preprocessors (and
macro package) a *roff document needs.[6]
Let me know if this helps, or does not.
Regards,
Branden
[1] Another use case is to produce non-man-page manuals from *roff
sources using a macro package like "ms", "me", or "mm". groff
supports all of these and it was commonly done in pre-Web days, but
it's now sadly close to a lost art. The _Unix Time-Sharing System
Programmer's Manual Seventh Edition Volume 2_ (1979) remains
valuable reading and an example of high-quality technical writing
apply *roff to ends other than man pages.
https://archive.org/details/bitsavers_attunix7thersManualSeventhEditionVol21983_34117955/
It's particularly valuable for learning "classical Unix" tools in
their early and more easily grasped forms. I've found that GNU
manuals, in spite of the advantages touted for Texinfo for
preparation of book-length works over mere reference guides (a.k.a.
man pages), are nevertheless often written in the style of man pages
with little effort made to give the reader a perspective from which
to integrate knowledge of the (nearly always) larger interface and
feature list of GNU replacements for Unix tools. In other words,
they too often suffer from the same defects that the GNU Coding
Standards attribute to man pages.
https://web.archive.org/web/20041029120203/http://www.gnu.org/prep/standards/html_node/GNU-Manuals.html#GNU-Manuals
(To be fair, more recent versions of the GNU Coding Standards have
moved--slightly--in the direction of acknowledging that the
quality of the technical writing, not the formatting language used
to compose it, that is the predominant factor in production of
useful manuals.)
[2] https://www.gnu.org/software/groff/manual/groff-man-pages.pdf
[3] https://git.savannah.gnu.org/cgit/groff.git/commit/?id=80ee140eb0616b794b853bbad623263cbea06abc
[4] https://lists.debian.org/debian-devel/2023/08/msg00220.html
[5] Yes, I can feel my eternal soul tumbling down several rungs in Hell
for engaging in promotion.
[6] https://man.cx/grog
I was going to link to
https://manpages.debian.org/unstable/groff/grof.1.en.html here, but
the man page is missing! groff definitely ships it. Any advice?
Attachment:
signature.asc
Description: PGP signature