nixos/make-options-doc: deprecate \n\n parbreak

only whitespace changes to rendered outputs, all in the vicinity or body
of admonitions. previously admonitions would not receive paragraph
breaks even when they should have because the description postprocessing
did not match on their contents.

2 files changed, 16 insertions, 20 deletions

diff --git a/nixos/lib/make-options-doc/mergeJSON.py b/nixos/lib/make-options-doc/mergeJSON.py
index ef9f321e114..e78056f3f59 100644
--- a/nixos/lib/make-options-doc/mergeJSON.py
+++ b/nixos/lib/make-options-doc/mergeJSON.py
@@ -66,9 +66,9 @@ class Renderer(mistune.renderers.BaseRenderer):
     def text(self, text):
         return escape(text)
     def paragraph(self, text):
-        return text + "\n\n"
+        return f"<para>{text}</para>"
     def newline(self):
-        return "<literallayout>\n</literallayout>"
+        return "<para><literallayout>\n</literallayout></para>"
     def codespan(self, text):
         return f"<literal>{escape(text)}</literal>"
     def block_code(self, text, info=None):
@@ -91,11 +91,11 @@ class Renderer(mistune.renderers.BaseRenderer):
     def list(self, text, ordered, level, start=None):
         if ordered:
             raise NotImplementedError("ordered lists not supported yet")
-        return f"<itemizedlist>\n{text}\n</itemizedlist>"
+        return f"<para><itemizedlist>\n{text}\n</itemizedlist></para>"
     def list_item(self, text, level):
-        return f"<listitem><para>{text}</para></listitem>\n"
+        return f"<listitem>{text}</listitem>\n"
     def block_text(self, text):
-        return text
+        return self.paragraph(text)
     def emphasis(self, text):
         return f"<emphasis>{text}</emphasis>"
     def strong(self, text):
@@ -104,7 +104,7 @@ class Renderer(mistune.renderers.BaseRenderer):
         if kind not in admonitions:
             raise NotImplementedError(f"admonition {kind} not supported yet")
         tag = admonitions[kind]
-        return f"<{tag}><para>{text.rstrip()}</para></{tag}>"
+        return f"<para><{tag}>{text.rstrip()}</{tag}></para>"
     def block_quote(self, text):
         return f"<blockquote><para>{text}</para></blockquote>"
     def command(self, text):
@@ -192,7 +192,7 @@ def convertMD(options: Dict[str, Any]) -> str:
     def convertString(path: str, text: str) -> str:
         try:
             rendered = md(text)
-            return rendered.rstrip()
+            return rendered
         except:
             print(f"error in {path}")
             raise
@@ -206,8 +206,7 @@ def convertMD(options: Dict[str, Any]) -> str:
     def convertCode(name: str, option: Dict[str, Any], key: str):
         rendered = f"{key}-db"
         if optionIs(option, key, 'literalMD'):
-            docbook = convertString(name, f"*{key.capitalize()}:*\n{option[key]['text']}")
-            option[rendered] = f"<para>{docbook}</para>"
+            option[rendered] = convertString(name, f"*{key.capitalize()}:*\n{option[key]['text']}")
         elif optionIs(option, key, 'literalExpression'):
             code = option[key]['text']
             # for multi-line code blocks we only have to count ` runs at the beginning
@@ -220,11 +219,8 @@ def convertMD(options: Dict[str, Any]) -> str:
             # inline literals need a space to separate ticks from content, code blocks
             # need newlines. inline literals need one extra tick, code blocks need three.
             ticks, sep = ('`' * (longest + (3 if multiline else 1)), '\n' if multiline else ' ')
-            docbook = convertString(name, f"{ticks}{sep}{code}{sep}{ticks}")
-            if multiline:
-                option[rendered] = f"<para><emphasis>{key.capitalize()}:</emphasis></para> {docbook}"
-            else:
-                option[rendered] = f"<para><emphasis>{key.capitalize()}:</emphasis> {docbook}</para>"
+            code = f"{ticks}{sep}{code}{sep}{ticks}"
+            option[rendered] = convertString(name, f"*{key.capitalize()}:*\n{code}")
         elif optionIs(option, key, 'literalDocBook'):
             option[rendered] = f"<para><emphasis>{key.capitalize()}:</emphasis> {option[key]['text']}</para>"
         elif key in option:
@@ -236,6 +232,10 @@ def convertMD(options: Dict[str, Any]) -> str:
                 option['description'] = convertString(name, option['description']['text'])
             elif markdownByDefault:
                 option['description'] = convertString(name, option['description'])
+            else:
+                option['description'] = ("<nixos:option-description><para>" +
+                                         option['description'] +
+                                         "</para></nixos:option-description>")
 
             convertCode(name, option, 'example')
             convertCode(name, option, 'default')
diff --git a/nixos/lib/make-options-doc/options-to-docbook.xsl b/nixos/lib/make-options-doc/options-to-docbook.xsl
index a74429596b8..a2e88febdaf 100644
--- a/nixos/lib/make-options-doc/options-to-docbook.xsl
+++ b/nixos/lib/make-options-doc/options-to-docbook.xsl
@@ -53,12 +53,8 @@
 
             <listitem>
 
-              <nixos:option-description>
-                <para>
-                  <xsl:value-of disable-output-escaping="yes"
-                                select="attr[@name = 'description']/string/@value" />
-                </para>
-              </nixos:option-description>
+              <xsl:value-of disable-output-escaping="yes"
+                            select="attr[@name = 'description']/string/@value" />
 
               <xsl:if test="attr[@name = 'type']">
                 <para>