Re: groff warning: TE macro called with TW register undefined
Hi Branden,
On Thu, 17 Aug 2023 at 10:08, G. Branden Robinson wrote:
>
> Hi Hugh,
>
> [...]
> 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]
Thanks for the explanation. While my research indicated that tbl was
not being called, I couldn't find any way of calling it, short of
`groff -t`.
> > > 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]
Yes. I had no idea preprocessors could be invoked via man(1).
> 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.
It does help, yes. I ran grog(1) on the man page in question and the
output immediately indicated that `tbl` was needed.
Thank you for your help.
> 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?
Reply to: