From 29252d1477dd224e88af915ff7e13cadd52838fb Mon Sep 17 00:00:00 2001 From: pennae Date: Wed, 1 Feb 2023 03:01:27 +0100 Subject: [PATCH] nixos-render-docs: add quotes to inline code in manpages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit other output types already have markings for inline code, manpages do not. this can be somewhat confusing, so we'll do the least intrusive thing: surrounding inline code blocks in ‘’. doing so separates inline code from the rest of the text and is unlikely to collide with the quoted contents. it's also what mdoc does with its Ql macro. --- .../nixos-render-docs/src/nixos_render_docs/manpage.py | 8 +++++++- .../nixos-render-docs/src/nixos_render_docs/options.py | 7 ++++++- .../tools/nix/nixos-render-docs/src/tests/test_manpage.py | 4 ++-- 3 files changed, 15 insertions(+), 4 deletions(-) diff --git a/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/manpage.py b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/manpage.py index 8adae2c8a0b0..5a16884a67df 100644 --- a/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/manpage.py +++ b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/manpage.py @@ -77,6 +77,11 @@ class List: class ManpageRenderer(Renderer): __output__ = "man" + # whether to emit mdoc .Ql equivalents for inline code or just the contents. this is + # mainly used by the options manpage converter to not emit extra quotes in defaults + # and examples where it's already clear from context that the following text is code. + inline_code_is_quoted: bool = True + _href_targets: dict[str, str] _do_parbreak_stack: list[bool] @@ -141,7 +146,8 @@ class ManpageRenderer(Renderer): return " " def code_inline(self, token: Token, tokens: Sequence[Token], i: int, options: OptionsDict, env: MutableMapping[str, Any]) -> str: - return _protect_spaces(man_escape(token.content)) + s = _protect_spaces(man_escape(token.content)) + return f"\\fR\\(oq{s}\\(cq\\fP" if self.inline_code_is_quoted else s def code_block(self, token: Token, tokens: Sequence[Token], i: int, options: OptionsDict, env: MutableMapping[str, Any]) -> str: return self.fence(token, tokens, i, options, env) diff --git a/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/options.py b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/options.py index 364fb6dc2c3a..a613ada1e68b 100644 --- a/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/options.py +++ b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/options.py @@ -291,7 +291,12 @@ class ManpageConverter(BaseConverter): if lit := option_is(option, key, 'literalDocBook'): raise RuntimeError("can't render manpages in the presence of docbook") else: - return super()._render_code(option, key) + assert isinstance(self._md.renderer, OptionsManpageRenderer) + try: + self._md.renderer.inline_code_is_quoted = False + return super()._render_code(option, key) + finally: + self._md.renderer.inline_code_is_quoted = True def _render_description(self, desc: str | dict[str, Any]) -> list[str]: if isinstance(desc, str) and not self._markdown_by_default: diff --git a/pkgs/tools/nix/nixos-render-docs/src/tests/test_manpage.py b/pkgs/tools/nix/nixos-render-docs/src/tests/test_manpage.py index 409c292fd5e4..5bd374dba406 100644 --- a/pkgs/tools/nix/nixos-render-docs/src/tests/test_manpage.py +++ b/pkgs/tools/nix/nixos-render-docs/src/tests/test_manpage.py @@ -16,12 +16,12 @@ class Converter(nixos_render_docs.md.Converter): def test_inline_code() -> None: c = Converter({}) - assert c._render("1 `x a x` 2") == "1 x a x 2" + assert c._render("1 `x a x` 2") == "1 \\fR\\(oqx a x\\(cq\\fP 2" def test_fonts() -> None: c = Converter({}) assert c._render("*a **b** c*") == "\\fIa \\fBb\\fI c\\fR" - assert c._render("*a [1 `2`](3) c*") == "\\fIa \\fB1 2\\fI c\\fR" + assert c._render("*a [1 `2`](3) c*") == "\\fIa \\fB1 \\fR\\(oq2\\(cq\\fP\\fI c\\fR" def test_expand_link_targets() -> None: c = Converter({}, { '#foo1': "bar", "#foo2": "bar" })