From c0853101833136590811a8c3cf30a989dd40a586 Mon Sep 17 00:00:00 2001
From: Bobby Rong <rjl931189261@126.com>
Date: Sat, 3 Jul 2021 22:18:11 +0800
Subject: [PATCH] nixos: nixos/doc/manual/development/meta-attributes.xml to
 CommonMark

---
 .../development/meta-attributes.section.md    | 40 ++++++++++++
 .../manual/development/meta-attributes.xml    | 63 -------------------
 .../manual/development/writing-modules.xml    |  2 +-
 .../development/meta-attributes.section.xml   | 55 ++++++++++++++++
 4 files changed, 96 insertions(+), 64 deletions(-)
 create mode 100644 nixos/doc/manual/development/meta-attributes.section.md
 delete mode 100644 nixos/doc/manual/development/meta-attributes.xml
 create mode 100644 nixos/doc/manual/from_md/development/meta-attributes.section.xml

diff --git a/nixos/doc/manual/development/meta-attributes.section.md b/nixos/doc/manual/development/meta-attributes.section.md
new file mode 100644
index 000000000000..ca4ba007f7dc
--- /dev/null
+++ b/nixos/doc/manual/development/meta-attributes.section.md
@@ -0,0 +1,40 @@
+# Meta Attributes {#sec-meta-attributes}
+
+Like Nix packages, NixOS modules can declare meta-attributes to provide
+extra information. Module meta attributes are defined in the `meta.nix`
+special module.
+
+`meta` is a top level attribute like `options` and `config`. Available
+meta-attributes are `maintainers` and `doc`.
+
+Each of the meta-attributes must be defined at most once per module
+file.
+
+```nix
+{ config, lib, pkgs, ... }:
+{
+  options = {
+    ...
+  };
+
+  config = {
+    ...
+  };
+
+  meta = {
+    maintainers = with lib.maintainers; [ ericsagnes ];
+    doc = ./default.xml;
+  };
+}
+```
+
+-   `maintainers` contains a list of the module maintainers.
+
+-   `doc` points to a valid DocBook file containing the module
+    documentation. Its contents is automatically added to
+    [](#ch-configuration). Changes to a module documentation have to
+    be checked to not break building the NixOS manual:
+
+    ```ShellSession
+    $ nix-build nixos/release.nix -A manual.x86_64-linux
+    ```
diff --git a/nixos/doc/manual/development/meta-attributes.xml b/nixos/doc/manual/development/meta-attributes.xml
deleted file mode 100644
index c40be0a50c36..000000000000
--- a/nixos/doc/manual/development/meta-attributes.xml
+++ /dev/null
@@ -1,63 +0,0 @@
-<section xmlns="http://docbook.org/ns/docbook"
-        xmlns:xlink="http://www.w3.org/1999/xlink"
-        xmlns:xi="http://www.w3.org/2001/XInclude"
-        version="5.0"
-        xml:id="sec-meta-attributes">
- <title>Meta Attributes</title>
-
- <para>
-  Like Nix packages, NixOS modules can declare meta-attributes to provide extra
-  information. Module meta attributes are defined in the
-  <filename
-    xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/misc/meta.nix">meta.nix</filename>
-  special module.
- </para>
-
- <para>
-  <literal>meta</literal> is a top level attribute like
-  <literal>options</literal> and <literal>config</literal>. Available
-  meta-attributes are <literal>maintainers</literal> and
-  <literal>doc</literal>.
- </para>
-
- <para>
-  Each of the meta-attributes must be defined at most once per module file.
- </para>
-
-<programlisting>
-{ config, lib, pkgs, ... }:
-{
-  options = {
-    ...
-  };
-
-  config = {
-    ...
-  };
-
-  meta = {
-    maintainers = with lib.maintainers; [ ericsagnes ]; <co
-      xml:id='modules-meta-1' />
-    doc = ./default.xml; <co xml:id='modules-meta-2' />
-  };
-}
-</programlisting>
-
- <calloutlist>
-  <callout arearefs='modules-meta-1'>
-   <para>
-    <varname>maintainers</varname> contains a list of the module maintainers.
-   </para>
-  </callout>
-  <callout arearefs='modules-meta-2'>
-   <para>
-    <varname>doc</varname> points to a valid DocBook file containing the module
-    documentation. Its contents is automatically added to
-    <xref
-      linkend="ch-configuration"/>. Changes to a module documentation
-    have to be checked to not break building the NixOS manual:
-   </para>
-<screen><prompt>$ </prompt>nix-build nixos/release.nix -A manual.x86_64-linux</screen>
-  </callout>
- </calloutlist>
-</section>
diff --git a/nixos/doc/manual/development/writing-modules.xml b/nixos/doc/manual/development/writing-modules.xml
index ac9617f4ea04..ff59dd074db7 100644
--- a/nixos/doc/manual/development/writing-modules.xml
+++ b/nixos/doc/manual/development/writing-modules.xml
@@ -183,7 +183,7 @@ in {
  <xi:include href="../from_md/development/option-types.section.xml" />
  <xi:include href="../from_md/development/option-def.section.xml" />
  <xi:include href="../from_md/development/assertions.section.xml" />
- <xi:include href="meta-attributes.xml" />
+ <xi:include href="../from_md/development/meta-attributes.section.xml" />
  <xi:include href="importing-modules.xml" />
  <xi:include href="replace-modules.xml" />
  <xi:include href="freeform-modules.xml" />
diff --git a/nixos/doc/manual/from_md/development/meta-attributes.section.xml b/nixos/doc/manual/from_md/development/meta-attributes.section.xml
new file mode 100644
index 000000000000..f535d94602bd
--- /dev/null
+++ b/nixos/doc/manual/from_md/development/meta-attributes.section.xml
@@ -0,0 +1,55 @@
+<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-meta-attributes">
+  <title>Meta Attributes</title>
+  <para>
+    Like Nix packages, NixOS modules can declare meta-attributes to
+    provide extra information. Module meta attributes are defined in the
+    <literal>meta.nix</literal> special module.
+  </para>
+  <para>
+    <literal>meta</literal> is a top level attribute like
+    <literal>options</literal> and <literal>config</literal>. Available
+    meta-attributes are <literal>maintainers</literal> and
+    <literal>doc</literal>.
+  </para>
+  <para>
+    Each of the meta-attributes must be defined at most once per module
+    file.
+  </para>
+  <programlisting language="bash">
+{ config, lib, pkgs, ... }:
+{
+  options = {
+    ...
+  };
+
+  config = {
+    ...
+  };
+
+  meta = {
+    maintainers = with lib.maintainers; [ ericsagnes ];
+    doc = ./default.xml;
+  };
+}
+</programlisting>
+  <itemizedlist>
+    <listitem>
+      <para>
+        <literal>maintainers</literal> contains a list of the module
+        maintainers.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        <literal>doc</literal> points to a valid DocBook file containing
+        the module documentation. Its contents is automatically added to
+        <xref linkend="ch-configuration" />. Changes to a module
+        documentation have to be checked to not break building the NixOS
+        manual:
+      </para>
+      <programlisting>
+$ nix-build nixos/release.nix -A manual.x86_64-linux
+</programlisting>
+    </listitem>
+  </itemizedlist>
+</section>