New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
manpage generator creates wrong markup if nested quotations are used #4430
Comments
The manpage converter is not a perfect solution. It's designed to be good enough. It handles common markup, but may mess up markup is combined. If you know what the solution is, you're welcome to send a PR to propose a fix. It's not something I have time to work on, nor do I understand how this is supposed to be supported in the groff syntax. |
roff formatters do not maintain a stack of font selections. Instead they maintain only a notion of the "current" font selection and the "previous" one. When you select a new font, the the current becomes the previous and the selection becomes current. When you restore the previous font, the previous and current swap. That's all there is to it. It is simple because that is what was tractable on a PDP-11 with an address space on the order of 16 bits. roff and Unix have a shared origin story. Macro languages can enable arbitrarily deep nesting of all sorts of things, but (A) the man package doesn't offer such a feature for font selections and (B) programs that generate man documents tend to eschew use of font selection macros in favor of font selection escape sequences ( |
I'll restate, if you know what the solution is, you're welcome to send a PR to propose a fix. It's not something I'm going to spend time on. |
My objective was to explain why unexpected output was generated, not to hector you for a fix. |
And I'm just stating my position so it's clear to anyone following the issue. |
Consider the adoc document that uses nested quotations, e.g.
asciidoctor `fails _to_ generate\` correct manpage in case of nested quotations.
If we convert it to manpage using
asciidoctor -o "t.1" -b "manpage" "t.adoc"
command then the following markup is generated:
asciidoctor \f(CRfails \fIto\fP generate\fP correct manpage in case of nested quotations.
.This manpage renders quite strange with
man
command:This is due to second
\fP
directive cancels previous\fP
directive, not\f(CR
.The right manpage markup should probably look like:
asciidoctor \f(CRfails \fP\fIto\fP\f(CR generate\fP correct manpage in case of nested quotations.
so this code should track quotations hierarchy by itself.
This issue was spotted in the wild by freebsd people (however it is not freebsd-specific) in ccache manual page ( adoc source, asciidoctor invocation ).
Reproduces with
Asciidoctor 2.0.18
,ruby 3.1.3
The text was updated successfully, but these errors were encountered: