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?
