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.
This commit is contained in:
pennae 2022-08-29 18:01:47 +02:00
parent 9bb82c35b7
commit 9c3c13b50d
3 changed files with 26 additions and 2 deletions

View file

@ -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

View file

@ -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.

View file

@ -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!