Man output gives font warning with latest man and groff #9020
Comments
|
That's quite weird, but I can't see how it could be a bug in pandoc. You should report this to groff. Looking quickly at the changelog for 1.23, I didn't see anything relevant, but you might look more carefully before reporting. |
|
@jgm Thanks for taking a look. Reported to groff https://savannah.gnu.org/bugs/index.php?64594 |
|
Pandoc is obviously generating lots of bogus code.
Fiddling with such low-level implementation details guarantees that your output is not portable, neither between different formatters nor between subsequent releases of the same formatter. While not quite as dire as the above points, using the GNU escape syntax \f[...] is not a particularly good idea. While most modern formatters support that, it is less portable than using the standard syntax \fB and \f(BI. Finally, note that while the CB CI CR fonts will usually be available on most modern formatters, using them is more risky than using \fB \fI \fR only. The C fonts are notoriously error-prone. Whenever you can, use semantic markup like .EX/.EE. Yes, that is also slightly risky because a few very uncommon formatters might not provide it, but it is still significantly more robust than trying to manually fiddle with CX fonts. The discussion whether the particular regressions you see here are pandoc's fault or groff's fault is partially moot. As long as you poke so deeply into language internals and implementation details, you can bet that you will often see all kinds of misformatting and regressions. Maintainer of mandoc(1) and maintainer of the groff(1) port in OpenBSD speaking, see: https://mandoc.bsd.lv/ |
|
Perhaps there are ways to improve pandoc's man output, and we're happy to hear them. But this doesn't explain why this warning is suddenly popping up after this particular groff release. I'd like to understand that. My main resource in designing the current man and ms writers were the man pages themselves. I take the point that Regarding the conditional and low-level formatting you object to at the beginning: the motivation for this is described in #7506, in response to a request from @joeyh, who quite reasonably wanted a visible distinction between code The |
|
Using |
|
Experimented with using for a code block. Unfortunately, when you process it with |
|
Looking at some man pages on my system, I note that zipinfo.1 actually defines the .EX/.EE macros itself: The awk.1 man page also defines certtool.1 man page also defines The perl man pages start with huge conditional macros. For code blocks they use a custom macro Nobody seems to rely on |
|
I remembered why we use the |
|
Hello John, for the latest groff release, G. Branden Robinson, among other things, did lots of work improving warnings. For example, \f[C] never really worked reliably, but groff did not warn. Now, you get the warning because groff now warns about something that didn't work in the past, either. mandoc(1) has also been warning about that for some time: I'm not quite sure why you get a warning about CB. Then again, that's on the .ie line, and comparing strings with and without font escapes to find out anything about those font escapes is totally non-portable in the first place. For example, mandoc won't even consider "\fRtext\fP" equal to "text". So i don't think you should worry about that specific CB warning. Regarding following groff(7) documentation - obviously, GNU troff documentation documents GNU features, and those are portable to varying degrees, some more, some less. All the same, groff_man(7), in addition to documentating than man(7) language itself, also contains various bits of portability advice. For example, groff_man(7) talks about single-letter \fB \fI \fR \fP but not about \f[] for a reason. Also note that groff_man(7) does not even mention \f(CB, let alone \f[CB]. If you rely on groff(7) in addition to groff_man(7), it should not come as a surprise that your output will be GNU-specific and not portable. The groff HTML output device produces output of atrocious quality. That's due to technical limitations in the fundamental way roff works and very hard to improve. In particular, grohtml(1) cannot produce "pre"-tags or any other semantic HTML. The best ist can do it produce physical formatting tags like "B" and "I" tags. If you try to tweak low-level details of your output to work better with grohtml(1), that's guaranteed to ruin the quality of your code, but won't result in good HTML output either way. If you want good HTML output from manual pages, you really have to use mandoc(1) - for example, mandoc -Thtml produces "pre"-tags from .EX, leaving font selection to CSS (and browser defaults, which are usually reasonable). Trying to manually tweak fonts in the manual pages source code in order to get good HTML output is completely hopeless. Regarding .hy - just leave it out completely in all cases, no matter whether some "hyphenate" variable is set in your pandoc input or not. Maybe in your pandoc input language, it makes sense to give users a choice whether they want automatic hyphenation or not. But in man(7) code, any attempt to translate that choice will not be portable, most likely have no effect whatsoever, or possibly even cause trouble with some formatters. Not every feature can reasonably be translated from one language to another. The reason why you did not use .EX probably is (just guessing!) that twenty years ago, it was not particularly portable. Few people used AT&T Ninth Edition Unix which invented it, so around 1995-2000, it was mostly available via esr@'s man-ext package and in GNU troff. But nowadays, it is relatively widely supported - certainly less fragile than trying to manually manipulate fonts, in particular C fonts. Defining .EX in individual manual pages was what esr@ recommended twenty years ago. I never considered that particularly sustainable advice. Back than, you could perhaps argue that it helped some formatters some people used back then, but it always was a terrible kludge at best. Today, formatters that might profit in any way are extremely rare, but you risk trouble with modern formatters that include good implementations of .EX. Redefining something that is already part of the language risks clashes, and even worse, bundled implementations are almost never maintained, get outdated when the formatters are improved, so you end up with worse output on the most common formatters if your own bad implementation overrides the good implementation in the formatter. CW ("constant width") is a historical name for CR that was widely used before people started also using CB and CI. If all you want is one C font, than (CW could possibly be minimally more portable than (CR, but i don't really know whether any formatters still exist that understand (CW but not (CR. If you use (CB or (CI, than using (CW makes no sense because it is extremely unlikely that any formatter understands (CB but not (CR. Yes, the perl manual pages contain a huge preamble generated by the pod2man(1). According to what i said, it should not be there. However, that's the only instance of such a low-level roff preamble i have ever seen that causes relatively little trouble in practice. I'm unsure why that is. Probably a combination of that particular code being extremely stable - the pod2man(1) maintenance team almost never tinkers with it, certainly not in ways causing new compatibility issues - and Russ Allbery commanding exceptional roff skills. Certainly not everything in that preamble works on all formatters, but somehow, it seems very carefully crafted such that even if some parts of it don't work somewhere, the fallout is relatively harmless and the page still mostly readable. I have often seem other teams attempt similar feats, but none ever managed to. Certainly not the DocBook team, certainly not pandoc, certainly not rst2man, and i think there are several others the names of which i don't recall right now... |
I wouldn't be surprised if GNU troff is the only formatter supporting a CBI font. Regarding portability, that's significantly worse than even \f[CB]. For example, in mandoc(1), \f[CBI] is the same as \fR: Besides, for which semantic purpose would you want to use a font that is CW, bold and italic at the same time? Off the top of my head, i can't think of any reasonable use case. Probably, the reason why mandoc(1) does not support it is that i have never seen it used in practice, whereas CB, CI, CR (and CW) do occasionally occur in real-world manual pages. |
Hi jgm, I replied at some length at https://savannah.gnu.org/bugs/index.php?64594 . |
|
Thank you both for the detailed explanations and advice! I would very much like to use .EX/.EE, but when I try it on my system (macos), it doesn't seem to give me the formatting I want. It doesn't give me a blank line between it and surrounding content, or indentation, or (I think) a monospace font. (That's a bit hard to tell just from the terminal, but I tested with
I'm sure you can get by very well without this in man pages, but pandoc is charged with converting things, and these things might include bold italicized monospace content. So, I'm faced with the question what to do if the content I'm converting has all three properties. I can produce non-portable (Also, I should mention that I share some of the font handling code between the man and ms writers, in Text.Pandoc.Writers.Roff. Certainly in ms we want to support CBI.) |
|
As for V, it's still kind of nice to allow users to change the rendering of inline code by modifying something in the template, so I like the idea of this "font alias" if there's a way to make it work portably. The suggestion does not give us quite the same flexibility, because it will also affect code blocks (not just inline code). The current behavior boldfaces inline code but not code blocks -- aesthetically, bolding whole code blocks is pretty heavy and it's not necessary for distinguishing them from regular text, because they're indented and set off. |
regardless of setting of `hyphenate` variable. See #9020.
|
Hi John, I hope I can be of further assistance! Let's find out...
These are deliberate. Ninth Edition Unix For spacing, use
Long story short (I hope): keep track of whether your previous paragraph used I apologize for the weirdness of it; it's compatible with Doug McIlroy's design of the man package in 1979 (probably 1978, actually) for Seventh Edition Unix. There is another approach you might like (or be able to transform to) better discussed in the groff_man_style(7) page that would have you using
Yeah, on the terminal everything is monospaced, unless you hate your eyeballs. ;-)
You can find groff's in its an-ext.tmac file. It has some extra complexity involving register tests to (1) make it easy to run our automated test suite on it and (2) accept a proposal from Ingo that the
You can redefine them (except for groff_man_style(7) says:
I think you can go ahead with the
Yes indeed. Device-independent troff was a handful of years too early for the PostScript revolution, with its standardized families and styles, to impact its design. Regards, |
The question that we have to address is: how portable do you seek to be? AT&T troff didn't have any concept of document-defined fonts. The font repertoire was a property of specific output devices (driver programs), and it had no facility for querying that repertoire or even reporting what the currently selected font was by name. I think it was the Python Docutils maintainer who said recently that portability to the aforementioned trio (groff, Heirloom Doctools troff, and mandoc) was a comfortable horizon for him. If you want to reach Plan 9 and Solaris troff formatters, or Documenter's Workbench 3.3 troff, more work will be cut out for you. Maybe I can think of some tricks--but I fear they will look ugly, confusing, and unmotivated in the output. ('Course, you can always write roff comments to accompany the cleverness.) Let me know how ambitious you want to be and I'll offer the best advice I can.
That's true. I wince to suggest it, but I suppose you could stuff the above into a macro, write another to unwind it, and then call them in inverted order by appending to the existing
I agree. It would make for eye strain, or at least give typographically sensitive people the vapors. Regards, |
|
@jgm -- I never did answer this question with precision.
This is it. |
|
Thanks very much for all of that; it really clears up a lot of my questions! Am I understanding correctly that, if I just want to target the trio groff / mandoc / heirloom doctools troff, then defining a custom font (EDIT: Of course, another alternative would be for pandoc just to hardcode |
Didn't MacOS recently switch from using man-db+groff by default to using mandoc by default? Consequently, unless you tell me otherwise, i'll assume that all you are saying in the comment i'm replying to here refers to the behaviour of mandoc(1).
No, mandoc(1) does not produce vertical spacing or indentation around .EX because it strives for compatibility with groff, and Branden already explained groff's choices.
For terminal output, mandoc(1) discards the font family "C" and maps CB -> B, CI -> I, CR -> R.
In mandoc, there is no such concept as "default definition of a standard macro". Instead, and in utter contrast to what groff does, the standard high-level macros (like .EX) are represented as nodes in an abstract syntax tree (AST), which enables high-quality HTML output.
You can redefine standard macros in mandoc(1), but it's an absolutely terrible idea. The consequence is that instead of using the normal AST approach, the AST will contain low-level roff(7) nodes even in mandoc, resulting in atrocious HTML output even from mandoc.
If you are producing man(7) output, i think it's better to emit \f(BI, which will work on most modern formatters, rather than emitting \f[CBI], which is equivalent to \fR on some widely used formatters and likely to cause warnings on top of that.
I'm not sure what people use ms(7) for nowadays, and which software they use for that. Your argument that you want to support \f[CBI] in ms(7) output may be fair enough: i guess that most people using ms(7) are likely using groff, where that works. My first idea of a user group where \f[CBI] might cause trouble even in ms(7) output is Plan 9 users. There may be other examples, for example commercial UNIX systems like Solaris, HP-UX, or AIX. Then again, i know little about both ms(7) and Plan 9, and i stopped using commercial UNIX systems around 1998-2003, even before getting involved with free software documentation. Either way, using one feature in one output language doesn't imply that using the same feature in another output language is necessarily a good idea. I have a hard time thinking of any users who might profit from having \f[CBI] in manual pages, but i can easily think of lots of users who will be hurt by that. |
That's what grohtml does, and I am not sure of the wisdom of that choice; for things that aren't man pages, changing the semantics of input line breaks (meaning: in the HTML document) seems like a terrible idea.
Yes. I resort to it myself in groff man and in a very few cases in our man pages (the only example I can think of is in grotty(1), to illustrate that face's availability with that driver). It's not portable to Seventh Edition Unix or Unix System III. But those are 40+ year old systems. The PostScript revolution I mentioned above did have an impact, so I've never seen an instance of a missing The exception is formatting for TeX DVI; Knuth's Computer Modern faces have constant-width upright and italic forms, but not heavy (bold) variants thereof. We have bespoke logic in groff's an.tmac to cope with this, since it's the only output driver thus afflicted. So far, no one using alternative fonts with grodvi(1) has complained that we're cramping their style. Heck, if someone is using grodvi at all, I'd like to hear from them. EDIT: Actually there is another exception. The grolbp(1) output driver for Canon LBP-4 and LBP-8 laser printers also has a Courier family but, according to our man page, lacks the bold-italic style for it. I am inclined to simply leave this situation alone. I have no way to troubleshoot this output driver on real (or even emulated) hardware, the devices it supported would appear to have been out of production for decades, and I don't know if Canon or any other printer manufacturer still supports the data stream format. By contrast, grolj4(1), which is of similar vintage, continues to work fine, as I learned to my delight last year when I got my hands on a Brother laser printer for testing. If a grolbp user shows up complaining of these missing font diagnostic messages, I will be thrilled to hear from them.
I trust you mean that it produces equivalent output, because the font selection can't be honored.
And thus do we get squarely back on topic. ;-)
I expect ms document authors on Plan 9 use its troff, since groff's ms implementation is hopelessly entangled with GNU troff extensions. When updating Larry Kollar's ms.ms document, I was careful to document all extensions in the macro language itself. John, you might be interested in that document as well.
Interestingly all of these have come up on the groff list in the last few months. We know that Solaris dropped its troff for groff in Solaris 11, which was released...over a decade ago now? Solaris 10 is in hospice care; its date of execution has been postponed to January 2025--I think by the personal command of Larry Ellison specifically to spite my plans for designating a portable dialect of roff. >shakes fist impotently< I don't know if HP-UX still supports its Unix System V troff, but I can say that they got groff 1.23.0 ported really fast. Like, within a week. I once could say I had friends at HP, but I think they're all retired now. The more likely explanation is that they actually care about it, maybe because they use it. Mike Fulton of IBM has been in touch with us, too, and I don't remember if he said they still had their System V troff, too--I was too gobsmacked by the fact that we could get rid of CCSID ("code page") 1047 support.
It does seem like an unusual case. If one follows my recommendations in groff_man_style(7), one would need to have an I/O example that was parameterized in user input. Typically, man page examples are not that demanding of the reader's metacognition. John, please rein me in at any time--I know I have a tendency to ramble. |
No, you misunderstand: mandoc(1) does not support .ftr at all: Consequently, with mandoc, \fV is the same as \fR and also causes a warning message. The mdoc(7) macro package provides the .Ql macro exactly for this purpose: https://man.openbsd.org/mdoc.7#Ql But the older man(7) language does not provide any similar functionality, not even if you are willing to aggressively use all GNU extensions. Consequently, the best solution i can think of would look something like this: I expect that to be quite portable, even beyond the big three.
Indeed, defining your own macros in a manual page sets you up for a trip on the highway to hell (pod2man being the singular exception that confirms the rule rather than casting doubt on it, as discussed), and defining a custom macro to wrap standard ones sounds even worse. Even Branden, who usually tends be bolder and less timid with respect to compatibility questions than i am, was visibly shaking when reluctantly considering whether he should really provide such advice. :-o
I think enclosing in single quotes is less intrusive and less confusing than switching to CB, and will also feel familiar to people used to pages written in mdoc(7). |
I'd love to argue here, but I can't. The line of attack I have in mind is to give tbl direct HTML output support, use GNU eqn's long-standing MathML output mode, and add an SVG output mode to GNU pic. If I understand aright, these would eliminate all of the reasons for the pre-grohtml preprocessor. That, in turn, would make This is a long-term project.
There is the problem of the This one is a more superable problem (with string definitions in the man document, as Thomas Dickey does, or by trivial edits to font description files in troff implementations), however.
I'd be remiss if I didn't point out my ambition to add a quotation macro to man(7).
:-P
Double quotes will feel more familiar to North Americans. ;-) In any case, you want to be quoting multi-word inline literals, particularly in case formatting gets stripped, as happens when people forget to run mandoc(1)'s output through ul(1), or paste man page contents into emails. I would also add that I find inline family changes a bit uncomfortable to read. Worse than bold? I'm not sure. |
I'm not sure I like this as a general solution, because
|
|
Looks like the best solution might be using |
Well, you are writing a translation tool, so the tool can parse the content and decide accordingly. Of course, going for \f(CB for inline code is not out of the question either. I have occasionally seen printed books use bold face for sample code. Then again, manual pages usually do not use bold face for such purposes, so it might perhaps confuse some readers, and besides, it's also slightly confusing if inline code samples end up using a different font compared to displayed code samples - and displayed code samples should almost certainly use .EX without any manual font fiddling. |
The aim here (see #9020) is to produce more standard and more portable man pages. To that end: - We revert the fanciness introduced in #7506, which employs a custom font name V and a macro that makes this act like boldface in a terminal and monospace in other formats. Unfortunately, this code uses a mechanism that is not portable (and does not work in mandoc). - Instead of using V for inline code, we simply use CR. Note that `\f[CR]` is emitted instead of plain `\f[C]`, because there is no C font in man. (This produces warnings in recent versions of groff.) - For code blocks, we now use the `.EX` and `.EE` macros, together with `.IP` for spacing and indentation. This gives more standard code that can be better interpreted e.g. by mandoc.
This is at best a no-op (in groff man and mandoc) and at worst (in some formatters) may create extra whitespace. See #9020.
|
I've just push a couple changes that implement some of the suggestions made here. |
See #9031 and discussion in #9020. This will give us better accessibility; when tagging is enabled, the citation can be linked to the bibliography entry. This changes some of the details of the layout and the default template. We now use a special enumitem list for the bibliography items, instead of the old CSLReferences environment. Internal links to ids beginning in `ref-` are assumed to be links to bibliography items, and put inside a `\cite` instead of `\hyperref`. This may be a bit fragile, so we should probably add something to citeproc to more definitely identify citation links.
See #9031 and discussion in #9020. This will give us better accessibility; when tagging is enabled, the citation can be linked to the bibliography entry. This changes some of the details of the layout and the default template. We now use a special enumitem list for the bibliography items, instead of the old CSLReferences environment. Internal links to ids beginning in `ref-` are assumed to be links to bibliography items, and put inside a `\cite` instead of `\hyperref`. This may be a bit fragile, so we should probably add something to citeproc to more definitely identify citation links.
See #9031 and discussion in #9020. This will give us better accessibility; when tagging is enabled, the citation can be linked to the bibliography entry. This changes some of the details of the layout and the default template. We now use a special enumitem list for the bibliography items, instead of the old CSLReferences environment. Internal links to ids beginning in `ref-` are assumed to be links to bibliography items, and put inside a `\cite` instead of `\hyperref`. This may be a bit fragile, so we should probably add something to citeproc to more definitely identify citation links.
See #9031 and discussion in #9020. This will give us better accessibility; when tagging is enabled, the citation can be linked to the bibliography entry. This changes some of the details of the layout and the default template. We now make CSLReferences a special enumitem list that will contain `\bibitem`s. Internal links inside citations to ids beginning in `ref-` are put inside a `\cite` instead of `\hyperref`.
See #9031 and discussion in #9020. This will give us better accessibility; when tagging is enabled, the citation can be linked to the bibliography entry. This changes some of the details of the layout and the default template. We now make CSLReferences a special enumitem list that will contain `\bibitem`s. Internal links inside citations to ids beginning in `ref-` are put inside a `\cite` instead of `\hyperref`. Closes #9031.
|
@jgm @ischwarze @g-branden-robinson thank you for your thorough collaboration and prompt fix! I regenerated with my man page, fixing the warnings hickford/git-credential-oauth@99abc35 |
This has been many-times discussed online, e.g.: jgm/pandoc#9020 The issue at heart is that the "C" font for roff (mandoc, groff, etc.) is non-standard across output devices. Prior to this change, lowdown was emitting the "C" font for constant-width fonts (those `in backticks`). These were being discarded by mandoc and groff when on the terminal, where "C" is unnecessary because everything is "C". Mandoc warned about it, but groff just silently let it go by until a recent version displayed a warning message. This introduces some changes. First, "C" is retained by default for -tms, although output as "CR" instead of "C". The rationale is that -ms is mostly used for formatting PDF/PS, which have the "C" font. Second, "C" is no longer used for -tman: instead, a bold font is used. However, the user can override this behaviour. (This will be documented in subsequent checkins.) The --nroff-code-font (not yet finalised) accepts a 4-tuple describing the constant width fonts, specifically "regular,bold,italic,bold-italic". This lets the user override the font that will be coded into the output. Three aliases exist: "none", "bold", and "code". "None" does not render a constant-width font at all, and simply uses the regular font. "Bold" uses a bold font (obviously if it's a **`situation like this`**, the bold is kept as-is). Finally, "code" uses the constant-width variants. References #123
Indeed, the man(7) code generated by Pandoc 3.1.7 is massively better regarding style, reliability, and portability than what you got from Pandoc 3.1.2 in the past. Really glad that so much progress was made here, this will probably save other Pandoc users quite some grief as well. |
As pointed out by Noah in Azure#15, Debian packaging lints issues in the generated manpage due to formatting emitted by older versions of pandoc: jgm/pandoc#9020 While changes in recent versions of pandoc have improved the output, let's just take the generated output from pandoc 3.2 as a starting point and maintain it manually for the time being. This reduces friction for packaging and gives us flexibility if we wanted to do something in the manpage that pandoc doesn't support. Signed-off-by: Chris Patterson <[email protected]>
As pointed out by Noah in Azure#15, Debian packaging lints issues in the generated manpage due to formatting emitted by older versions of pandoc: jgm/pandoc#9020 While changes in recent versions of pandoc have improved the output, let's just take the generated output from pandoc 3.2 as a starting point and maintain it manually for the time being. This reduces friction for packaging and gives us flexibility if we wanted to do something in the manpage that pandoc doesn't support. Allow manpages to be generated at build-time with -DGENERATE_MANPAGES=1. Signed-off-by: Chris Patterson <[email protected]>
As pointed out by Noah in Azure#15, Debian packaging lints issues in the generated manpage due to formatting emitted by older versions of pandoc: jgm/pandoc#9020 While changes in recent versions of pandoc have improved the output, let's just take the generated output from pandoc 3.2 as a starting point and maintain it manually for the time being. This reduces friction for packaging and gives us flexibility if we wanted to do something in the manpage that pandoc doesn't support. Allow manpages to be generated at build-time with -DGENERATE_MANPAGES=1 which will make it easy to sync. Signed-off-by: Chris Patterson <[email protected]>
As pointed out by Noah in Azure#15, Debian packaging lints issues in the generated manpage due to formatting emitted by older versions of pandoc: jgm/pandoc#9020 While changes in recent versions of pandoc have improved the output, let's just take the generated output from pandoc 3.2 as a starting point and maintain it manually for the time being. This reduces friction for packaging and gives us flexibility if we wanted to do something in the manpage that pandoc doesn't support. Allow manpages to be generated at build-time with -DGENERATE_MANPAGES=1 which will make it easy to sync. Signed-off-by: Chris Patterson <[email protected]>
As pointed out by Noah in Azure#15, Debian packaging lints issues in the generated manpage due to formatting emitted by older versions of pandoc: jgm/pandoc#9020 While changes in recent versions of pandoc have improved the output, let's just take the generated output from pandoc 3.2 as a starting point and maintain it manually for the time being. This reduces friction for packaging and gives us flexibility if we wanted to do something in the manpage that pandoc doesn't support. Allow manpages to be generated at build-time with -DGENERATE_MANPAGES=1 which will make it easy to sync. Signed-off-by: Chris Patterson <[email protected]>
As pointed out by Noah in Azure#15, Debian packaging lints issues in the generated manpage due to formatting emitted by older versions of pandoc: jgm/pandoc#9020 While changes in recent versions of pandoc have improved the output, let's just take the generated output from pandoc 3.2 as a starting point and maintain it manually for the time being. This reduces friction for packaging and gives us flexibility if we wanted to do something in the manpage that pandoc doesn't support. Allow manpages to be generated at build-time with -DGENERATE_MANPAGES=1 which will make it easy to sync. Signed-off-by: Chris Patterson <[email protected]>
As pointed out by Noah in Azure#15, Debian packaging lints issues in the generated manpage due to formatting emitted by older versions of pandoc: jgm/pandoc#9020 While changes in recent versions of pandoc have improved the output, let's just take the generated output from pandoc 3.2 as a starting point and maintain it manually for the time being. This reduces friction for packaging and gives us flexibility if we wanted to do something in the manpage that pandoc doesn't support. Allow manpages to be generated at build-time with -DGENERATE_MANPAGES=1 which will make it easy to sync. Signed-off-by: Chris Patterson <[email protected]>
As pointed out by Noah in Azure#15, Debian packaging lints issues in the generated manpage due to formatting emitted by older versions of pandoc: jgm/pandoc#9020 While changes in recent versions of pandoc have improved the output, let's just take the generated output from pandoc 3.2 as a starting point and maintain it manually for the time being. This reduces friction for packaging and gives us flexibility if we wanted to do something in the manpage that pandoc doesn't support. Allow manpages to be generated at build-time with -DGENERATE_MANPAGES=1 which will make it easy to sync. Signed-off-by: Chris Patterson <[email protected]>
As pointed out by Noah in Azure#15, Debian packaging lints issues in the generated manpage due to formatting emitted by older versions of pandoc: jgm/pandoc#9020 While changes in recent versions of pandoc have improved the output, let's just take the generated output from pandoc 3.2 as a starting point and maintain it manually for the time being. This reduces friction for packaging and gives us flexibility if we wanted to do something in the manpage that pandoc doesn't support. Allow manpages to be generated at build-time with -DGENERATE_MANPAGES=1 which will make it easy to sync. Signed-off-by: Chris Patterson <[email protected]>
As pointed out by Noah in Azure#15, Debian packaging lints issues in the generated manpage due to formatting emitted by older versions of pandoc: jgm/pandoc#9020 While changes in recent versions of pandoc have improved the output, let's just take the generated output from pandoc 3.2 as a starting point and maintain it manually for the time being. This reduces friction for packaging and gives us flexibility if we wanted to do something in the manpage that pandoc doesn't support. Allow manpages to be generated at build-time with -DGENERATE_MANPAGES=1 which will make it easy to sync. Signed-off-by: Chris Patterson <[email protected]>
As pointed out by Noah in Azure#15, Debian packaging lints issues in the generated manpage due to formatting emitted by older versions of pandoc: jgm/pandoc#9020 While changes in recent versions of pandoc have improved the output, let's just take the generated output from pandoc 3.2 as a starting point and maintain it manually for the time being. This reduces friction for packaging and gives us flexibility if we wanted to do something in the manpage that pandoc doesn't support. Allow manpages to be generated at build-time with -DGENERATE_MANPAGES=1 which will make it easy to sync. Signed-off-by: Chris Patterson <[email protected]>
As pointed out by Noah in #15, Debian packaging lints issues in the generated manpage due to formatting emitted by older versions of pandoc: jgm/pandoc#9020 While changes in recent versions of pandoc have improved the output, let's just take the generated output from pandoc 3.2 as a starting point and maintain it manually for the time being. This reduces friction for packaging and gives us flexibility if we wanted to do something in the manpage that pandoc doesn't support. Allow manpages to be generated at build-time with -DGENERATE_MANPAGES=1 which will make it easy to sync. Signed-off-by: Chris Patterson <[email protected]>
In certain pandoc versions invalid fonts in groff output are generated[1]. Upstream seems to have fixed the issue[2], but as of now this issue is present in Debian testing+sid and Ubuntu 24.04. Besides the invalid fonts, the generated man-pages look fine. So ignore this warning as a workaround. [1] https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1062045 [2] jgm/pandoc#9020 Signed-off-by: Sascha Lucas <[email protected]>
In certain pandoc versions invalid fonts in groff output are generated[1]. Upstream seems to have fixed the issue[2], but as of now this issue is present in Debian testing+sid and Ubuntu 24.04. Besides the invalid fonts, the generated man-pages look fine. So ignore this warning as a workaround. [1] https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1062045 [2] jgm/pandoc#9020 Signed-off-by: Sascha Lucas <[email protected]>
Older versions of pandoc try to set the font to a font that doesn't actually exist. Older versions of groff don't care, but newer ones will catch the mistake. This has been fixed in pandoc 3 but we're not ready to declare a dependency on a newer version since installing the whole haskell toolchain is a lot for something that can be fixed with a trivial sed. jgm/pandoc#9020
Explain the problem.
Pandoc's man output for code blocks and inline code is incompatible with the latest man and groff, giving warnings about fonts such as "warning: cannot select font 'CB'" and "warning: cannot select font 'C'".
I am using GNU troff (groff) version 1.23.0. This issue did not occur with earlier versions of groff.
Pandoc command
pandoc example.1.md -t man -o example.1 --standaloneInput
example.1.md:Output
example.1:Run man command with warnings
man -l example.1 | grep warnThis warning is non-fatal. The man page looks okay to me.
Pandoc version?
pandoc 3.1.6.1 on Linux
The text was updated successfully, but these errors were encountered: