From 9c3c13b50d02380cda1c834bc15cff3346956ea4 Mon Sep 17 00:00:00 2001
From: pennae <github@quasiparticle.net>
Date: Mon, 29 Aug 2022 18:01:47 +0200
Subject: [PATCH] nixos/make-options-doc: add inline roles for varname/envar

both of these render distinctly from plain literals in the manpage, and
manpages even semantically distinguish between the two.
---
 .../docbook-writer/rst-roles.lua              |  4 ++++
 .../contributing-to-documentation.chapter.md  |  4 +++-
 nixos/lib/make-options-doc/mergeJSON.py       | 20 ++++++++++++++++++-
 3 files changed, 26 insertions(+), 2 deletions(-)

diff --git a/doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua b/doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua
index 1c745393a04b..5c1b034d0792 100644
--- a/doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua
+++ b/doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua
@@ -31,6 +31,10 @@ function Code(elem)
       tag = 'command'
     elseif elem.attributes['role'] == 'option' then
       tag = 'option'
+    elseif elem.attributes['role'] == 'var' then
+      tag = 'varname'
+    elseif elem.attributes['role'] == 'env' then
+      tag = 'envar'
     end
 
     if tag ~= nil then
diff --git a/doc/contributing/contributing-to-documentation.chapter.md b/doc/contributing/contributing-to-documentation.chapter.md
index db16f13b474b..81482523cd0e 100644
--- a/doc/contributing/contributing-to-documentation.chapter.md
+++ b/doc/contributing/contributing-to-documentation.chapter.md
@@ -58,8 +58,10 @@ Additional syntax extensions are available, though not all extensions can be use
   A few markups for other kinds of literals are also available:
 
   - `` {command}`rm -rfi` `` turns into {command}`rm -rfi`
-  - `` {option}`networking.useDHCP` `` turns into {option}`networking.useDHCP`
+  - `` {env}`XDG_DATA_DIRS` `` turns into {env}`XDG_DATA_DIRS`
   - `` {file}`/etc/passwd` `` turns into {file}`/etc/passwd`
+  - `` {option}`networking.useDHCP` `` turns into {option}`networking.useDHCP`
+  - `` {var}`/etc/passwd` `` turns into {var}`/etc/passwd`
 
   These literal kinds are used mostly in NixOS option documentation.
 
diff --git a/nixos/lib/make-options-doc/mergeJSON.py b/nixos/lib/make-options-doc/mergeJSON.py
index c7577e41e2d2..1a1af11337e7 100644
--- a/nixos/lib/make-options-doc/mergeJSON.py
+++ b/nixos/lib/make-options-doc/mergeJSON.py
@@ -114,6 +114,10 @@ class Renderer(mistune.renderers.BaseRenderer):
         return f"<option>{escape(text)}</option>"
     def file(self, text):
         return f"<filename>{escape(text)}</filename>"
+    def var(self, text):
+        return f"<varname>{escape(text)}</varname>"
+    def env(self, text):
+        return f"<envar>{escape(text)}</envar>"
     def manpage(self, page, section):
         title = f"<refentrytitle>{escape(page)}</refentrytitle>"
         vol = f"<manvolnum>{escape(section)}</manvolnum>"
@@ -136,6 +140,20 @@ def p_file(md):
     md.inline.register_rule('file', FILE_PATTERN, parse)
     md.inline.rules.append('file')
 
+def p_var(md):
+    VAR_PATTERN = r'\{var\}`(.*?)`'
+    def parse(self, m, state):
+        return ('var', m.group(1))
+    md.inline.register_rule('var', VAR_PATTERN, parse)
+    md.inline.rules.append('var')
+
+def p_env(md):
+    ENV_PATTERN = r'\{env\}`(.*?)`'
+    def parse(self, m, state):
+        return ('env', m.group(1))
+    md.inline.register_rule('env', ENV_PATTERN, parse)
+    md.inline.rules.append('env')
+
 def p_option(md):
     OPTION_PATTERN = r'\{option\}`(.*?)`'
     def parse(self, m, state):
@@ -162,7 +180,7 @@ def p_admonition(md):
     md.block.rules.append('admonition')
 
 md = mistune.create_markdown(renderer=Renderer(), plugins=[
-    p_command, p_file, p_option, p_manpage, p_admonition
+    p_command, p_file, p_var, p_env, p_option, p_manpage, p_admonition
 ])
 
 # converts in-place!