nixos-render-docs: add quotes to inline code in manpages

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.

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)

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:

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" })