nixos: nixos/doc/manual/development/meta-attributes.xml to CommonMark

3 files changed, 41 insertions, 64 deletions

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 00000000000..ca4ba007f7d
--- /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 c40be0a50c3..00000000000
--- 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 ac9617f4ea0..ff59dd074db 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" />